AGENT SKILL

bug-archaeology

Mine bug patterns from any git repository. Discovers bug-fix commits via git log heuristics, analyzes each in parallel with subagents, writes individual analysis files, and synthesizes a generalized PATTERNS.md with repo-specific details stripped. Invoke explicitly with /bug-archaeology.

License 许可
Apache-2.0
所属仓库
apache/cassandra
最近更新
2026-11-14
Stars
★ 1.0w
Forks
4.1k

01 前言 Front Matter

name
bug-archaeology
version
1.0.0
description
Mine bug patterns from any git repository. Discovers bug-fix commits via git log heuristics, analyzes each in parallel with subagents, writes individual analysis files, and synthesizes a generalized PATTERNS.md with repo-specific details stripped. Invoke explicitly with /bug-archaeology.

02 资源文件 3

03 SKILL.md 正文

Bug Archaeology

Systematic extraction of reusable bug-detection heuristics from a repository's commit history.

Arguments

All optional. Parse from the user's invocation string.

Arg Default Description
--range HEAD~200..HEAD Git revision range
--path (all files) Restrict to commits touching this path glob
--since / --until (none) Date filter for git log
--limit 200 Max bug-fix commits to analyze
--batch-size 10 Commits per subagent
--output ./bug-archaeology/ Output directory

Workflow

Three sequential phases. Each phase completes fully before the next starts.

Phase 1: Discovery

Find bug-fix commits via git log heuristics.

git log --no-merges --pretty=format:"%H %s" [--since=X] [--until=X] <range> [-- <path>] \
  | grep -iE '(fix|bug|patch|resolve|repair|correct|workaround|hotfix|regression|#[0-9]+|[A-Z]+-[0-9]+)'

Filter out commits whose message matches ONLY cosmetic keywords (typo, whitespace, import, format, style, cleanup, rename) with no bug keywords.

Truncate to --limit.

Write QUEUE.txt to the output directory:

0001 abc123def First line of commit message
0002 def456abc Another commit message

Resumption: If PROGRESS.md exists, read it and exclude commits already marked done or skipped. Re-include pending and error entries.

Phase 2: Analysis (parallelized)

Spawn subagents to analyze commits in batches. Each commit is independent.

Subagent prompt template — adapt as needed:

Read the file at references/per-bug-format.md for the output format specification.

Analyze these commits from the repository at <REPO_PATH>:
<list of "NNNN hash message" lines>

For each commit:
1. Run: git show <hash>
2. If the commit is cosmetic, test-only, refactor-only, or a merge with no
   original changes — mark it as skipped with a one-word reason.
3. Otherwise, write the analysis to <OUTPUT>/bug-<NNNN>-<slug>.md
   following the format in per-bug-format.md exactly.

Return a status line per commit: NNNN <hash> done|skipped [reason-or-filename]

Parallelism: Launch up to 5 subagent batches concurrently. Wait for all to complete before the next wave.

Progress tracking: After each wave, append results to PROGRESS.md:

| # | Commit | Status | File / Reason |
|---|--------|--------|---------------|
| 0001 | abc123d | done | bug-0001-null-after-lookup.md |
| 0002 | def456a | skipped | cosmetic |

Errors: Mark as error with a one-line reason. Don't retry — the user re-invokes with --resume.

Phase 3: Synthesis

After all analysis is complete, produce PATTERNS.md. Read references/synthesis-format.md for the full specification.

Process:

  1. Read all bug-*.md files in the output directory
  2. Parse the Tags section from each — extract category and code-pattern
  3. Group bugs by code-pattern tag
  4. For each group of 2+ bugs with the same code-pattern:
    • Extract the shared Detection Rule (generalize if they differ across instances)
    • Pick the most representative Example
  5. Generalize — strip repo-specific details:
    • Replace specific class/method names with structural descriptions
    • Remove ticket IDs, author names, project-specific subsystem labels
    • Keep language-specific API names only if scope is that language or broader
  6. Group patterns by category and write PATTERNS.md
  7. Patterns with only 1 instance go in a "Singletons" section at the end

Reference Files

File Loaded by Purpose
references/per-bug-format.md Subagents (Phase 2) Per-bug output template and field guidelines
references/synthesis-format.md Orchestrator (Phase 3) PATTERNS.md structure and generalization rules

Evaluating the Skill

Full instructions are in references/EVAL-PROMPT.md. Summary:

  1. Pick a bug from the archaeology output and trace its introducing commit via git blame.
  2. Extract the patch with git diff ${INTRO}~1 $INTRO.
  3. Choose a review skill — the user must specify one:
    • /shallow-review — quick 6-specialist parallel scan, any patch size
    • /deep-review — focused on specific files, complex logic
    • /targeted-review — findings-driven, medium-to-large patches
    • /mega-review — large feature branches or 1000+ LOC diffs
  4. Run the chosen skill against the extracted patch.
  5. Score the output: Exact / Partial / Different bug / Miss.
  6. Prod misses — tell the skill what it missed and ask which checklist item would have caught it; use the answer to improve that skill's reference files.

Target: >90% hit rate (exact + partial), <5% miss rate across a batch of N bugs.

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

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.

开发工程师后端与接口
★ 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