Targeted Review

Targeted Review

A meta-review skill. It does not encode bug patterns directly — it orchestrates other skills and a categorized findings catalog into a tight, evidence-driven review.

What it does

                +------------------+
                |   Input patch    |
                +--------+---------+
                         |
             +-----------+-----------+
             |                       |
   +---------v---------+   +---------v-----------+
   | patch-explainer   |   | codebase-analysis   |
   | (sub-skill)       |   | (sub-skill, scoped) |
   | what changed,     |   | invariants, callers,|
   | flow, assumptions |   | parallel paths      |
   +---------+---------+   +---------+-----------+
             |                       |
             +-----------+-----------+
                         |
         +---------------v----------------+
         | Pick categories + items        |
         | × 3-5 independent iterations  |
         | (each draw surfaces different  |
         |  items from the same catalog)  |
         +---------------+----------------+
                         |
                +--------v---------+
                | Pool & prioritize|
                | (items from 2+   |
                |  iterations →    |
                |  higher priority)|
                +--------+---------+
                         |
                +--------v---------+
                | Group items by   |
                | review focus     |
                | (file/func/feat) |
                +--------+---------+
                         |
            +------------+------------+
            |            |            |
    +-------v---+  +-----v-----+  +---v-------+
    | review    |  | review    |  | review    |
    | subagent  |  | subagent  |  | subagent  |
    | scope A   |  | scope B   |  | scope C   |
    +-------+---+  +-----+-----+  +---+-------+
            |            |            |
            +------------+------------+
                         |
                +--------v---------+
                | Merge & report   |
                +------------------+

When to use this skill

• A patch or diff is on the table for review (single commit, multi-commit branch, or staged changes)
• The user wants more focus than shallow-review provides (six fixed lenses on the whole patch) but doesn't want to commit to deep-review's file-by-file deep pass
• A *-findings/ corpus exists or the categorized catalog under references/categories/ is sufficient — the categories alone are usable; project corpora improve coverage
• Medium-to-large patches where dispatching focused subagents avoids overwhelming a single reviewer

When NOT to use this skill

• Trivial 1-3 line changes — direct review is faster
• Pure refactors with no behavior change — shallow-review symmetry pass is enough
• The user wants a single comprehensive write-up of one file — use deep-review instead

Workflow

You will go through seven phases. Phases 1a and 1b run in parallel. Phases 2-6 are sequential.

Phase 1a: Understand the patch — call the patch-explainer skill

Invoke the patch-explainer skill on the patch. Use the Skill tool. You want patch-explainer to produce its standard analysis (purpose, before/after diagrams, flow, assumptions, failure modes).

If the patch is already provided as a file path, point patch-explainer at it. If you only have a commit ref, ask for git show <ref> or read it from git diff. For multi-commit branches, it is fine to feed the cumulative diff.

Capture patch-explainer's full output. You will refer to it in Phases 3-5.

Phase 1b: Understand the surroundings — call the codebase-analysis skill

In parallel with 1a, invoke the codebase-analysis skill in targeted mode on the affected subsystem only — not the whole repo. Pass it:

• The list of files touched by the patch
• The subsystem name if obvious (e.g., "the journal replay subsystem")
• A directive to focus on: invariants, lifecycle, parallel implementations, and recent bug history in the affected area

You want codebase-analysis to produce a scoped analysis/system-analysis.md that gives you the context the patch sits inside — what the surrounding code expects, where parallel paths exist, what historical bugs touched this area.

If invoking the full skill is too heavy for a small patch, instead spawn a research subagent with this prompt: "Read these files: {touched files}. Summarize: (a) the invariants the surrounding code maintains, (b) any parallel implementations or sibling classes, (c) callers of the modified methods, (d) any recent bug-fix commits in this area. Under 400 words." This is a lighter alternative that retains the spirit of codebase-analysis. Prefer the full skill when the area is unfamiliar or large.

Phase 2: Pick categories — 3-5 independent iterations

Category selection and item picking are speculative: you're making probabilistic judgments about which patterns might apply, and a single pass will reliably miss some. Run 3-5 independent iterations of Phases 2+3, each starting from scratch with the same patch and context but without looking back at what prior iterations chose. Treat each iteration like a fresh read — you are more likely to notice different things each time.

For each iteration, read references/categories/INDEX.md — it lists all 11 categories with their descriptions and diff signals in one file (~200 lines). For each category, ask: does the patch contain ANY of the diff signals listed?

• If yes → mark as load
• If no → skip

Typically 3-7 categories load per iteration. If you would load more than 8, re-examine. If fewer than 2, the patch is probably too small for this skill.

Phase 3: Pick items within each loaded category (one pass per iteration)

Within each iteration, read the full content of each loaded category file. For each finding (### F-NN: title + body + **Look for:** {hint}), ask:

1. Does the "Look for" hint match a code shape that actually appears in this patch?
2. Does the patch context (from patch-explainer + codebase-analysis) make this finding plausibly applicable — not just a keyword match?

If yes to both → keep the item. If no → drop.

Be selective: a category typically has 25-40 findings; keep 3-12 per category per iteration. Repeat for all iterations before moving to Phase 3b.

Phase 3b: Pool and prioritize across iterations

After all iterations are complete, merge the item lists:

• An item selected in 2 or more iterations is a strong candidate — mark it priority.
• An item selected in only one iteration is still in scope — mark it speculative.
• Discard nothing yet; let the subagents decide.

The iteration count next to an item is a confidence signal for the subagents, not a gate. A speculative item can still turn into a real bug; a priority item can still be a false alarm.

Phase 4: Group items by review focus

Now you have a pooled list of selected items across categories and iterations. Group them by review focus — what part of the change a single reviewer should examine. A focus is one of:

• A specific function or method (MyClass.replay())
• A specific file or small group (FooSerializer.java and its sibling FooDeserializer.java)
• A feature, behavior, or concept ("the new fsync coordination", "the version-gated dispatch path")
• A specific cross-cutting concern in the patch ("any place we read the new dirty flag")

Aim for 2-5 foci per patch. Each focus should have 5-15 checklist items drawn from across the categories — not too few (subagent has nothing to do) and not too many (subagent gets overwhelmed). Include each item's priority annotation (priority / speculative) so the subagent knows where to focus first.

If multiple foci would receive the same checklist item, that's fine — the same pattern can apply at multiple sites. Tag each item with the category it came from so the subagent knows the rationale.

Phase 5: Spawn focused review subagents

For each focus, spawn one review subagent in parallel using the Agent tool. Use the template in references/subagent-prompt-template.md. The subagent prompt must contain:

• The patch (path, or pasted, or ref)
• A 100-word summary of patch-explainer's findings (relevant slice only — not the full output)
• A 100-word summary of codebase-analysis's findings (relevant slice only)
• The focus statement (what part of the change to review)
• The checklist items, each with: category, priority annotation, finding text, and look-for hint
• Instructions on how to gather evidence (read source, grep, check parallel paths) and what confidence to assign

Each subagent should produce: a list of findings, with location, confidence, and what evidence was checked.

Run all subagents in a single tool call (parallel). They are independent.

Phase 6: Merge and report

When all subagents return, merge findings:

1. Deduplicate — same code location + similar reasoning → one finding, both subagents credited
2. Rank by confidence — High first, then Medium, then Low
3. Cross-reinforce — if a finding was raised by multiple subagents, or if multiple findings cluster on the same lifecycle/state, boost confidence
4. Three-point check each surviving finding:
   • The code construct actually exists in the diff (not inferred from absence alone)
   • The bug is plausible given the visible context (not speculative)
   • The finding is actionable (the reader can tell what to change)

Use the format in references/report-format.md.

Reference files

The categories in references/categories/ are project-agnostic patterns mined from real bug fixes across distributed-systems projects (Cassandra, Kafka, Iceberg). They describe generalized code-level shapes, not project-specific issues.

How this differs from related skills

Use targeted-review when:

• The patch spans 50-1000 LOC
• You want to spend tokens on what matters for THIS patch, not on a fixed catalog
• You have a *-findings/ corpus or are reviewing systems-level code that benefits from the curated categories

Pitfalls and guardrails

• Don't skip Phase 1. Calling patch-explainer and codebase-analysis is what lets you pick categories and items intelligently. Without that grounding, you'll loose-match on keywords and overwhelm subagents.
• Don't look at prior iterations while picking. The whole value of multiple iterations is independent draws. If you anchor on the first iteration's selections, you get one draw repeated instead of several independent ones.
• Don't load every category "just in case". The whole value is selection. If you match more than 8 categories in an iteration, you've probably been too generous.
• Don't pass the full catalog to subagents. Each subagent gets only the items selected for its focus. Passing all items defeats the purpose.
• Don't substitute findings for understanding. A finding that "matches a code shape" is a hypothesis to verify — the subagent confirms or refutes by reading the code, not by trusting the pattern. Mark uncertain findings as Low confidence.
• The checklist is the menu, not the order. A subagent should also report bugs it notices that aren't on the checklist — the checklist primes attention, it doesn't cap it.