AGENT SKILL

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

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

  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

04 同仓库更多 Skills

apache
apache/cassandra

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.

测试与质量
★ 1.0w
apache
apache/cassandra

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".

★ 1.0w
apache
apache/cassandra

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.

代码审查
★ 1.0w
apache
apache/cassandra

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.

代码审查
★ 1.0w
apache
apache/cassandra

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.

代码审查
★ 1.0w
apache
apache/cassandra

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.

★ 1.0w