shallow-review

name	shallow-review
version	1.0.0
description	Shallow (quick) ensemble bug-finding review using 6 specialist agents in parallel. Each specialist reviews the same patch through a different lens: Logic & Types, Boundaries & I/O, Concurrency & State, Resources & Serialization, Absence Analysis, and API Completeness. Findings are merged and deduplicated. Best for: quick first-pass review of patches, triage of diffs, broad surface-level bug scan. For deeper file-focused review with full pattern catalogs and codebase investigation, use the deep-review skill instead.

Ensemble Code Review

Six specialist agents review the same patch in parallel. Each applies Phase 0 (understand the change, form hypotheses) then a focused checklist. Their findings are merged and deduplicated.

                    +------------------+
                    |   Input Patch    |
                    +--------+---------+
                             |
    +-------+------+---------+---------+-----------+
    |       |      |         |         |           |
+---v--+ +--v--+ +-v-----+ +-v------+ +v-----+ +---v-------+
|Logic | |Bound| |Concurr| |Resource| |Absenc| | Complete. |
|&Type | | &I/O| |&State | |& Serde | |(2-ph)| | & Contr.  |
+--+---+ +--+--+ +---+---+ +---+----+ +--+---+ +---+-------+
   |        |        |         |          |        |
   +--------+--------+---------+----------+--------+
                               |
                    +----------v----------+
                    |  Pass 3: Symmetry   |
                    |  (serial, optional) |
                    +----------+----------+
                               |
                    +----------v----------+
                    |   Merge & Dedup     |
                    |   (main agent)      |
                    +---------------------+

Quick Start

1. Identify target — patch, diff, file, or subsystem
2. Launch 6 specialists in parallel (see prompts below)
3. Run Pass 3 Symmetry check (serial, after specialists complete)
4. Merge findings: deduplicate, rank by confidence
5. Report in unified format

Phase 0: Understand Before Checking

Every specialist runs Phase 0 BEFORE touching the checklist:

1. Summarize the patch in 2–3 sentences (feature, fix, refactor, move?)
2. Hypothesize — list 3–5 things that could go wrong with this type of change
3. Note code shapes that warrant deeper investigation

This switches the review from bottom-up (checklist→code) to top-down (code→hypotheses→verification). The checklist then verifies and extends the hypotheses.

---

The Six Specialists

1. Logic & Types (52% of bugs)

Priority: wrong comparisons, missing returns, wrong constants, boolean polarity, sentinel ambiguity.

Reference: references/general/specialists/logic.md

Prompt:

You are a LOGIC specialist reviewing a patch for correctness bugs.

PHASE 0 — Understand the patch first (before reading checklist):
Read the patch: `{PATCH_PATH}`
1. Summarize what this patch does in 2-3 sentences.
2. List 3-5 things that could go wrong with this type of change.
3. Note any suspicious code shapes (control flow, comparisons, constants, sentinels).

PHASE 1 — Apply checklist:
Read your checklist: `{SKILL_DIR}/references/general/specialists/logic.md`
Apply questions that match your hypotheses and code shapes. Check all 30 items
against the patch but spend the most effort where your hypotheses pointed.

Report ALL findings above a noise floor. For each: Location, Confidence
(High/Medium/Low), What's wrong (1-2 sentences).
Or "No finding in my domain" if nothing applies.

2. Boundaries & I/O (17% of bugs)

Priority: off-by-one, integer overflow, null/bounds checks, buffer sizing, I/O completeness.

Reference: references/general/specialists/boundary.md

Prompt:

You are a BOUNDARY specialist reviewing a patch for correctness bugs.

PHASE 0 — Understand the patch first (before reading checklist):
Read the patch: `{PATCH_PATH}`
1. Summarize what this patch does in 2-3 sentences.
2. List 3-5 things that could go wrong with this type of change.
3. Note any arithmetic, indexing, range, or I/O operations.

PHASE 1 — Apply checklist:
Read your checklist: `{SKILL_DIR}/references/general/specialists/boundary.md`
Apply questions that match your hypotheses and code shapes. Check all 22 items
against the patch but spend the most effort where your hypotheses pointed.

Report ALL findings above a noise floor. For each: Location, Confidence
(High/Medium/Low), What's wrong (1-2 sentences).
Or "No finding in my domain" if nothing applies.

3. Concurrency & State (16% of bugs)

Priority: races, TOCTOU, live-view iteration, lock ordering, state cleanup.

Reference: references/general/specialists/concurrency.md

Prompt:

You are a CONCURRENCY specialist reviewing a patch for correctness bugs.

PHASE 0 — Understand the patch first (before reading checklist):
Read the patch: `{PATCH_PATH}`
1. Summarize what this patch does in 2-3 sentences.
2. List 3-5 things that could go wrong with this type of change.
3. Note any shared state, locks, collections, lifecycle operations.

PHASE 1 — Apply checklist:
Read your checklist: `{SKILL_DIR}/references/general/specialists/concurrency.md`
Apply questions that match your hypotheses and code shapes. Check all 24 items
against the patch but spend the most effort where your hypotheses pointed.

Report ALL findings above a noise floor. For each: Location, Confidence
(High/Medium/Low), What's wrong (1-2 sentences).
Or "No finding in my domain" if nothing applies.

4. Resources & Serialization (15% of bugs)

Priority: resource leaks, serialization mismatches, wrong metric types, background tasks, wrapper bypass.

Reference: references/general/specialists/resources.md

Prompt:

You are a RESOURCES specialist reviewing a patch for correctness bugs.

PHASE 0 — Understand the patch first (before reading checklist):
Read the patch: `{PATCH_PATH}`
1. Summarize what this patch does in 2-3 sentences.
2. List 3-5 things that could go wrong with this type of change.
3. Note any resource allocation, serialization methods, metrics, streams.

PHASE 1 — Apply checklist:
Read your checklist: `{SKILL_DIR}/references/general/specialists/resources.md`
Apply questions that match your hypotheses and code shapes. Check all 26 items
against the patch but spend the most effort where your hypotheses pointed.

Report ALL findings above a noise floor. For each: Location, Confidence
(High/Medium/Low), What's wrong (1-2 sentences).
Or "No finding in my domain" if nothing applies.

5. Absence Analysis (cross-cutting)

Priority: find what SHOULD be present but ISN'T — missing guards, cleanup, handlers, registrations.

Reference: references/general/specialists/absence.md

Prompt:

You are an ABSENCE specialist. Your job: find bugs that are purely absent — missing
guards, cleanup, handlers, or conditions that leave no signal in the diff.

PHASE 0 — Understand the patch first:
Read the patch: `{PATCH_PATH}`
1. Summarize what this patch does in 2-3 sentences.
2. List 3-5 things that SHOULD be present but might be missing.

PHASE 1 — Build the search list:
Read your checklist: `{SKILL_DIR}/references/general/specialists/absence.md`
For each event in the diff matching items (a)-(q), add to your search list.

PHASE 2 — Execute searches and report:
For each item in your search list:
  - Use Grep and Read tools to gather evidence from the codebase
  - If match found (remove/deregister exists): discard
  - If no match found: report as finding

Report ALL findings above a noise floor. For each: what's missing, where it should
be, what evidence you searched for, Confidence (High/Medium/Low).
Or "No absence finding" if nothing applies.

6. API Completeness & Contracts

Priority: missing fields, missing overrides, registration symmetry, visibility, event coverage.

Reference: references/general/specialists/completeness.md

Prompt:

You are an API COMPLETENESS specialist reviewing a patch for correctness bugs.

PHASE 0 — Understand the patch first (before reading checklist):
Read the patch: `{PATCH_PATH}`
1. Summarize what this patch does in 2-3 sentences.
2. List 3-5 things that could be incomplete about this change.
3. Note any new classes, new fields, new registrations, visibility changes.

PHASE 1 — Apply checklist:
Read your checklist: `{SKILL_DIR}/references/general/specialists/completeness.md`
Apply questions that match your hypotheses and code shapes. Check all 22 items
against the patch but spend the most effort where your hypotheses pointed.

Report ALL findings above a noise floor. For each: Location, Confidence
(High/Medium/Low), What's wrong (1-2 sentences).
Or "No finding in my domain" if nothing applies.

---

Pass 3: Cross-Path Symmetry (serial, after specialists complete)

Prompt:

You are a SYMMETRY specialist. For each code path modified in this patch, identify
whether a structurally parallel path (same class, interface, event family, version range)
was NOT modified. For each asymmetry:
- Where path A was changed
- Where parallel path B exists
- What was changed on A that is absent on B
- Whether the asymmetry is intentional or suspicious

Read the patch: `{PATCH_PATH}`
Search the codebase as needed using Grep and Read.
Report all asymmetries, Confidence High/Medium/Low.

---

Merge & Dedup

After all specialists report:

1. Collect all findings from 6 specialists + symmetry
2. Deduplicate — same code location + related reasons → combine
3. Rank by confidence — findings confirmed by multiple specialists rank highest
4. Cross-check reinforcement:
   • Logic + Absence at same location → boost to High
   • Concurrency + Resources on same lifecycle → boost to High
   • Any finding flagged by 3+ specialists → treat as confirmed
5. 3-point test each finding:
   • The code construct actually exists in the diff (not inferred)
   • The bug is possible given the visible context (not speculative)
   • The finding is actionable (what specifically should change)
6. Specialist Silence Rule: If Absence or Completeness reports nothing on a >100-line diff, note: "Consider verifying Phase 2 searches executed for registration symmetry, handler coverage, and field completeness."

---

Report Format

## Review: [target]

### Findings (ranked by confidence)

#### Finding 1: [title]
- **Location**: [file:line]
- **Confidence**: High / Medium / Low
- **Flagged by**: [specialists]
- **What's wrong**: [1-2 sentences]

### Specialist Coverage
- Logic: [N findings / no finding]
- Boundary: [N findings / no finding]
- Concurrency: [N findings / no finding]
- Resources: [N findings / no finding]
- Absence: [N findings / no finding]
- Completeness: [N findings / no finding]
- Symmetry: [N asymmetries / none]

Statistical Priors

Category	Share	Specialist
Logic error in condition	26%	Logic
Wrong constant / default	15%	Logic
Missing null / bounds check	13%	Boundary
Incorrect filtering / result	11%	Logic
Race condition	9%	Concurrency
Wrong serialization	8%	Resources
State not cleaned up	7%	Concurrency
Off-by-one	4%	Boundary
Resource leak	3%	Resources

Reference Files

Specialist checklists (trimmed, ensemble mode)

• references/general/specialists/logic.md — 30 items, Logic specialist
• references/general/specialists/boundary.md — 22 items, Boundary specialist
• references/general/specialists/concurrency.md — 24 items, Concurrency specialist
• references/general/specialists/resources.md — 26 items, Resources specialist
• references/general/specialists/absence.md — Phase 1/2 search patterns, Absence specialist
• references/general/specialists/completeness.md — 22 items, Completeness specialist