Review Oracle Code Evidence Semantics

Review one extracted Oracle module package as a connected body of evidence. Produce a colocated semantic-review overlay that explains relationships the extractor cannot establish by token or record continuity alone.

This skill is one post-extraction review step, not a new extraction pipeline. Keep the four-file evidence package immutable and write the review beside it.

Non-Negotiable Boundaries

1. Process exactly one tenant, one project, and one Oracle module package.
2. Accept only a linked package generated by leg-spec-from-code-oracle: master, operation details, decoded source, and database reference.
3. Review legacy evidence only. Do not generate target requirements, target UI, target tests, architecture, implementation choices, POC assumptions, or feasibility conclusions.
4. Do not silently rewrite any extraction file. If a raw fact is wrong or missing, register an extraction defect and recommend fixing the extractor or source bundle.
5. Treat historical specifications only as continuity or ambiguity prompts. Retain a historical claim only when the current package independently supports its underlying facts.
6. Separate observation, interpretation, proposed resolution, and human disposition.
7. Never convert missing runtime evidence into a confident explanation.
8. Preserve existing human dispositions and notes on rerun.

Scope And Output

Resolve the project repository as:

agentic-sdlc-data/tenants/<tenant>/projects/<project>/repo

Verify project.yaml exists and declares objective_type: legacy_modernization.

Resolve the selected master under:

evidence/features/<feature-name>/<module-id>-<screen-title>-specification.md

Write one review overlay in the same feature package:

evidence/features/<feature-name>/<module-id>-semantic-review.md

The review is colocated for association but must declare:

artifact_kind: legacy_evidence_semantic_review
authority: review_overlay_not_extracted_fact

Do not add findings to the extraction master. Do not modify its fingerprint or generated sections.

Identifier Economy

Use the module package ID and selective semantic local keys:

MOD-<MODULE-ID>#review.<semantic-slug>

Create a key only for a material relationship, ambiguity, conflict, or runtime-context gap that a human may need to review or downstream curation must consider. Do not create one key per field, trigger, message, SQL statement, or DDL object.

Keep keys stable across reruns. Prefer review.auto-query-contract-types over sequence numbers.

Required References

Read both references completely before writing a review:

• references/review-lenses.md
• references/semantic-review-template.md

Workflow

1. Resolve And Freeze The Package

Run the package preparation helper into a uniquely named operating-system temporary directory:

python <skill-dir>\scripts\oracle_semantic_review.py prepare `
  --spec <master-specification> `
  --output <temp-dir>\semantic-review-context.json

The helper must verify package links and shared metadata, hash every package file, count exhaustive records, and calculate the expected review path. Stop if a child is absent, mismatched, or outside the selected feature folder.

If the review file does not exist, scaffold it:

python <skill-dir>\scripts\oracle_semantic_review.py scaffold `
  --context <temp-dir>\semantic-review-context.json `
  --output <expected-review-path>

Never overwrite an existing review with scaffold. Read and reconcile it instead.

2. Review The Whole Package

Read the master first, then use its links and the prepared context to inspect relevant child records. Apply every lens in references/review-lenses.md.

Review relationships across facts, including:

• screen/module identity versus query discriminators and startup globals;
• UI fields versus Forms mappings, DDL types, and persistence ownership;
• design-time CRUD flags versus decoded triggers and runtime restrictions;
• branch conditions versus messages, stop effects, and outcomes;
• delete behavior versus inbound foreign keys and dependency checks;
• save/commit behavior versus transaction ownership and exception paths;
• navigation behavior versus caller, menu, parameter, and binary-library context;
• defaults and audit columns versus Forms and database ownership;
• screenshots versus Forms structural evidence;
• old ambiguity prompts versus current source-supported facts.

Do not read millions of repeated values indiscriminately. Start from concise master summaries, then inspect the exact operation, decoded-source, or DDL record required to prove or falsify a relationship.

3. Classify Findings

Use these types:

• ambiguity
• apparent_conflict
• cross_fact_dependency
• runtime_context_gap
• under_specified_behavior
• evidence_quality
• extraction_defect

Use these statuses:

• resolved_automatically
• proposed_for_human_review
• blocked_by_missing_evidence
• accepted_as_legacy_behavior
• superseded
• stale

Use high, medium, or low severity. Severity expresses downstream misunderstanding risk, not implementation priority.

4. Resolve Conservatively

Resolve automatically only when all of these are true:

1. The relevant facts are directly present in the current package.
2. Their source authority does not conflict.
3. The resolution requires no business-intent, policy, target-design, or runtime choice.
4. A skeptical reviewer can reproduce the conclusion from the cited locators.

Examples suitable for automatic resolution include two labels referring to the same hashed source body, an apparent type mismatch resolved by explicit Forms-to-DDL mapping, or a message/condition relationship proved by the active decoded branch.

Do not automatically resolve why a Standard Contract module retrieves N/U contract types merely because both facts exist. Without caller/startup semantics, record the relationship and leave the intent for human review.

5. Write The Review Overlay

Follow references/semantic-review-template.md. For every finding, record:

• facts in relationship or tension;
• precise relative source links and natural locators;
• semantic analysis;
• proposed resolution;
• applied interpretation, if safely resolved;
• missing evidence or human decision needed;
• downstream evidence-curation impact without proposing target behavior.

Keep a compact register plus one detail block per finding. Preserve human-authored dispositions from an existing review.

6. Handle Reruns And Staleness

• If the evidence fingerprint is unchanged, reconcile by stable local key and update only changed analysis.
• If the fingerprint changed, revalidate every finding. Mark unverified prior findings stale; do not delete them.
• Preserve accepted_as_legacy_behavior, human disposition text, reviewer names, and decision dates unless new explicit human evidence changes them.
• Add a review-history row for material changes.

7. Validate

Run:

python <skill-dir>\scripts\oracle_semantic_review.py validate `
  --spec <master-specification> `
  --review <semantic-review> `
  --context <temp-dir>\semantic-review-context.json
git diff --check -- <semantic-review>

Validation must fail when:

• an extraction file changed after preparation;
• module ID, module evidence ID, fingerprint, package hash, or parent link is inconsistent;
• the review is outside the selected feature folder;
• a finding key is duplicated or uses another module/package;
• a finding uses an unsupported type, severity, or status;
• a finding lacks source references, analysis, or proposed resolution;
• a local Markdown link is broken or escapes the project repository;
• extracted facts are presented as target requirements or approvals.

Open human-review findings are valid output; they do not make the review fail.

Completion Report

Report:

• module and feature reviewed;
• review artifact path;
• package fingerprint and whether extraction remained unchanged;
• counts by finding type, severity, and status;
• automatically resolved findings;
• findings requiring human review or missing evidence;
• validation result.

Do not create commits, tags, pushes, baselines, requirements, tests, or approvals unless explicitly requested.