shallow-review
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.
- License 许可
- Apache-2.0
- 所属仓库
- apache/cassandra
- 最近更新
- 2026-11-14
- Stars
- ★ 1.0w
- Forks
- 4.1k
01 前言 Front Matter
- 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.
02 资源文件 7
- 参考文档EVAL-PROMPT.md4.3 KB
- 参考文档references/general/specialists/absence.md5.7 KB
- 参考文档references/general/specialists/boundary.md4.9 KB
- 参考文档references/general/specialists/completeness.md5.5 KB
- 参考文档references/general/specialists/concurrency.md5.7 KB
- 参考文档references/general/specialists/logic.md8.0 KB
- 参考文档references/general/specialists/resources.md6.3 KB
03 SKILL.md 正文
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
- Identify target — patch, diff, file, or subsystem
- Launch 6 specialists in parallel (see prompts below)
- Run Pass 3 Symmetry check (serial, after specialists complete)
- Merge findings: deduplicate, rank by confidence
- Report in unified format
Phase 0: Understand Before Checking
Every specialist runs Phase 0 BEFORE touching the checklist:
- Summarize the patch in 2–3 sentences (feature, fix, refactor, move?)
- Hypothesize — list 3–5 things that could go wrong with this type of change
- 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:
- Collect all findings from 6 specialists + symmetry
- Deduplicate — same code location + related reasons → combine
- Rank by confidence — findings confirmed by multiple specialists rank highest
- 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
- 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)
- 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 specialistreferences/general/specialists/boundary.md— 22 items, Boundary specialistreferences/general/specialists/concurrency.md— 24 items, Concurrency specialistreferences/general/specialists/resources.md— 26 items, Resources specialistreferences/general/specialists/absence.md— Phase 1/2 search patterns, Absence specialistreferences/general/specialists/completeness.md— 22 items, Completeness specialist
04 同仓库更多 Skills
write-reproducer
Write minimal, reliable bug reproducers (repros) for any project. Use when: (1) a bug report or issue needs a test that reliably demonstrates the failure, (2) converting a described failure scenario into runnable code, (3) minimizing an existing complex test to its essential trigger conditions. Covers the full repro workflow: failure characterization, scope selection, writing the repro, verifying it fails for the right reason, and minimizing to the smallest possible trigger.
tla-plus
Create, run, and verify TLA+ and PlusCal formal specifications. Use for modeling distributed systems, protocols, concurrent algorithms, state machines. Can compose specs from code, find divergences between spec and implementation, spot concurrency bugs and invariant violations. Use when asked to "write a TLA+ spec", "model check", "verify protocol", "find race conditions", or "formal verification".
targeted-review
Findings-driven targeted code review. Understands the patch via patch-explainer and surrounding code via codebase-analysis, then consults a catalog of bug patterns (~11 categories under references/categories/). Picks only categories whose diff-signals match the patch and items whose "look for" hints match actual code shapes, groups them by review focus (function/file/feature), and spawns parallel subagents — each with a tight scope and selective checklist. Use for medium-to-large patches (50-1000 LOC) as a focused alternative to whole-patch ensemble or whole-file deep review. Triggers on: "review this patch/diff/change", "find bugs in this change", "scoped review", "what could go wrong here", "review using findings", or proactive PR review.
patch-explainer
Deep code analysis with ASCII visualizations showing structure, flow, and state transitions. Use when analyzing patches/diffs, explaining classes or subsystems, understanding code architecture, reviewing changes for inconsistencies, or when asked to visualize how code works. Provides before/after diagrams, data/control flow, concurrency analysis, assumptions, and failure modes. Triggers on explain this patch/code/class, how does X work, show me the flow, visualize this change, code review requests, or proactive analysis during PR reviews.
mega-review
Multi-pass deep code review for large patches (1000+ LOC) that maximizes real bug detection. Orchestrates targeted-review, shallow-review, and deep-review in parallel across all HIGH and MEDIUM risk files and commits: understands the feature holistically, splits by file and commit, runs deep review on every HIGH/MEDIUM file, targeted review across the same scope, and per-commit shallow review, followed by cross-cut consistency checks. Use when: reviewing a large patch (feature branch, multi-commit, or single large diff, 1000+ LOC), doing a thorough pre-merge review, or when shallower reviews miss bugs due to patch size. Triggers on: "review this branch", "review these commits", "review this feature", "mega review", "thorough review", "full review of X commits", or when the user specifies a commit range or feature for review.
heatmap
Use git heatmap analysis to identify high-churn files and lines as candidates for thorough review or bug hunting. Works for PR reviews, security audits, bug hunts, or any code analysis task.