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
- 参考文档references/EVAL-PROMPT.md3.7 KB
- 参考文档references/per-bug-format.md3.9 KB
- 参考文档references/synthesis-format.md2.9 KB
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:
- Read all
bug-*.mdfiles in the output directory - Parse the
Tagssection from each — extractcategoryandcode-pattern - Group bugs by
code-patterntag - 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
- 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
- Group patterns by
categoryand writePATTERNS.md - 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:
- Pick a bug from the archaeology output and trace its introducing commit via
git blame. - Extract the patch with
git diff ${INTRO}~1 $INTRO. - 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
- Run the chosen skill against the extracted patch.
- Score the output: Exact / Partial / Different bug / Miss.
- 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
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.
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.
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.