Semantic Review

Semantic Review

Surface scanning ("this function takes X and returns Y") is not understanding. Without grasping why code is shaped the way it is, edits become guesses and introduce regressions. The user invoked this skill specifically because comprehension matters more than speed — do not optimize for token cost or response length.

This skill is portable across agent harnesses (Codex, Opencode, Claude Code). The procedure below does not depend on any particular tool surface — translate file/grep/blame steps to whatever your harness exposes.

When to use

• Full-file or full-module review where the user wants comprehension, not a checklist
• Exploring an unfamiliar codebase before implementing a feature that touches it
• Reading code where the author's intent is non-obvious (clever optimizations, workarounds, hidden invariants, unusual abstractions)
• Any task where "I don't understand what this does" would be a blocker for the next step

When NOT to use

• Single-line edits, typo fixes, formatting
• Code where naming alone makes the intent self-evident
• Quick lookups (locate a symbol, list files)
• Bulk mechanical refactors with no semantic risk

Depth control

Choose the lightest depth that still produces real understanding:

• Lightweight semantic pass: Use for a small file, a few symbols, or pre-implementation orientation. Analyze only the relevant meaningful units, but still consider all five fields for each selected unit.
• Standard semantic review: Use for full-file or focused module review. Cover each meaningful unit and group results by module, layer, or concern.
• Deep module review: Use when there are many files, more than about 30 meaningful units, or broad architectural uncertainty. First produce a module map and risk hotspots, then analyze the highest-risk or user-relevant units in detail. Continue in batches instead of dumping an unbounded review.

Do not let scale force shallow paraphrase. If the target is too large for a complete pass in one response, say which units were covered, which were deferred, and what order to continue in.

Core procedure

For each meaningful unit (function, type, branch, module boundary, non-trivial constant), produce these five fields. Do not skip Why. If you cannot determine why, write UNKNOWN plus the probe needed to resolve it — never fabricate a plausible-sounding reason.

1. What — the mechanical behavior, one sentence.
2. Why — the problem it solves, the constraint it satisfies, or the historical reason for its shape. If unclear, mark UNKNOWN — probe: .
3. Invariants — what must hold for this code to be correct. Examples: "input is validated upstream", "called only from the worker thread", "list is sorted ascending", "lock is held by caller".
4. Failure modes — what breaks the invariant, and what happens when it does (silent corruption, panic, wrong result, deadlock, etc.).
5. Connections — call sites, dependencies, what downstream code would break if this unit changed.

When the meaning is genuinely obvious from naming and shape, you may collapse What into one line — but Why, Invariants, and Failure must still be considered. If they are vacuous, say so explicitly ("Why: trivial accessor, no constraint to record") rather than omitting the field.

Output format

Per unit:

 @ :
  What:        
  Why:        
  Invariants:  
  Failure:     
  Connections: 

Group units by module / layer / concern. End the review with:

• Open questions — every UNKNOWN that still needs the user or further probing
• Risk hotspots — units where invariants are subtle, fragile, undocumented, or rely on caller discipline
• Implementation implications — only if the user asked for next steps; otherwise stop at understanding

Probes for Why

When the reason for code's shape is unclear, in this order:

1. Read nearby tests — they often encode the intended behavior and edge cases.
2. Read callers — the calling context reveals the contract.
3. Run git blame + read the commit message — original author rationale.
4. Search for related ADRs / docs — docs/adr/, CHANGELOG, RFC, README.
5. Search for the issue/PR number in the commit — surrounding discussion.
6. As a last resort, ask the user. Better one question than a fabricated explanation.

Anti-patterns

• Paraphrasing code as prose ("this function loops over items and checks each one"). That is What, not understanding. The skill fails if Why is missing.
• Inventing intent to fill the Why slot. If you don't know, say UNKNOWN.
• Skipping units that "look obvious". Obvious-looking code often carries the subtlest invariants — accessors that secretly mutate, "pure" functions that depend on global state, branches that exist only for a single legacy caller.
• Producing the analysis and then editing immediately. This skill ends at understanding. Implementation is a separate step the user must authorize.
• Compressing the output to seem efficient. The user accepted the cost. Verbosity here is the deliverable.

Handoff to implementation

If the user explicitly asked to understand first and then implement, do not edit during the semantic review itself. End with implementation implications and a handoff block:

Ready for implementation via execution-loop:
- Relevant units:
- Invariants to preserve:
- Risk hotspots:
- Suggested first implementation unit:

Then move into execution-loop only after the semantic review output is complete and implementation remains authorized by the user.

Stop condition

The skill is complete when:

• Every meaningful unit has all five fields filled, or marked UNKNOWN with a stated probe
• Open questions and risk hotspots are listed at the end
• The user has enough material to decide whether and how to proceed with implementation

Do not append a fix or refactor on top. Hand off to the user.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: haru0416-dev
• Source: haru0416-dev/agent-skills
• License: MIT
• Homepage: https://github.com/haru0416-dev/quaere

Install and usage instructions live in the source repository linked above.