| name | bug-catcher |
| description | Audit a Go package in this repository for subtle correctness bugs, including both bugs inside the package and bugs in how the rest of the repository uses it. Optimized for Pebble- and CockroachDB-style code where invariants, iterator semantics, ownership, and API contracts matter more than style issues. |
| disable-model-invocation | true |
You are running a multi-stage audit of a Go package.
The user will provide exactly one argument: a repo-relative path to a Go package directory.
Your goal is to produce a final report containing confirmed bugs only, ordered by severity, with no fix suggestions.
This skill is optimized for large Go storage/database codebases like Pebble and CockroachDB. Favor semantic correctness, invariants, and contract violations over stylistic critique.
Primary objective
Find bugs that are likely to pass unnoticed by a human reviewer, especially:
- typos that still compile but alter behavior
- wrong field / constant / comparer / option / bound / level / sequence number chosen
- subtle API misuse by callers
- semantic mismatches between comments, names, and implementation
- edge cases around iterator validity, bounds, exhaustion, and positioning
- ownership / aliasing / lifetime mistakes
- incorrect assumptions around zero values or sentinel values
- ordering mistakes
- concurrency / locking / callback / reentrancy mistakes
- stale invariants after refactors
- test coverage that appears convincing but fails to pin down the actual contract
Non-goals
- no style review
- no formatting nits
- no speculative “maybe” issues in the final report
- no patch suggestions
- no performance-only observations unless they imply a correctness bug
Required workflow
Stage 1: build package understanding
Start the package-understander subagent on the target package path.
Its output must be written to a durable artifact, not only held in conversational state.
Write to:
$TMPDIR/bug-catcher/<sanitized-package-path>/understanding.md
The understanding must capture:
- package purpose
- exported API
- key internal helpers and state transitions
- invariants and hidden assumptions
- important data representations
- ownership / lifetime expectations
- concurrency / synchronization expectations
- important tests and what they appear to specify
- key dependencies
- major callers in the repo
- what those callers appear to assume about this package
- bug-prone surfaces
Stage 2: generate candidate bugs
Start the candidate-generator subagent on the target package.
Pass it:
- package path
- understanding artifact path (
$TMPDIR/bug-catcher/<sanitized-package-path>/understanding.md)
- output path:
$TMPDIR/bug-catcher/<sanitized-package-path>/candidates.md
Stage 3: confirm each candidate independently
For each candidate, start a fresh bug-confirmer subagent.
Pass it:
- package path
- understanding artifact
- candidate description
- relevant files / symbols
Each confirmer must independently determine whether the issue is real, trying first to disprove it.
A candidate should only be confirmed if the evidence supports a specific semantic failure mode, not merely surprising or ambiguous code.
When in doubt, mark it not-confirmed.
Each confirmation must return:
- verdict: confirmed / not-confirmed
- severity: critical / high / medium / low
- confidence: high / medium / low
- concise justification
- exact code references
Write one confirmation per file:
$TMPDIR/bug-catcher/<sanitized-package-path>/confirmations/<NNN>.md
Stage 4: final report
Produce a final report containing only confirmed bugs, sorted by severity, then confidence.
When ordering confirmed bugs, rank by:
- semantic correctness impact, especially corruption or persistent wrong behavior
- breadth of affected call paths
- likelihood in realistic usage
- confidence
For each confirmed bug include:
- severity
- short title
- category
- package path
- affected files / symbols
- concise explanation
- why it could slip past review
- evidence
Do not include fix suggestions.
Do not include rejected candidates.
Do not dilute the report with general observations.
Pebble / CRDB-specific hunting guidance
When auditing these kinds of codebases, pay extra attention to:
- iterator positioning, validity, lower/upper bounds, and exhaustion semantics
- ownership of byte slices, keys, values, buffers, and backing storage
- sequence-number visibility rules
- tombstone / range-key / masking / shadowing semantics
- comparer / split / separator / successor assumptions
- format-major-version or feature-gating assumptions
- state machines with implicit ordering requirements
- zero-value structs that are valid in some contexts but not others
- interaction between options structs and defaults
- cross-level or cross-batch assumptions
- internal iterators vs external iterator contract mismatches
- correctness assumptions encoded only in tests or comments
- call sites that accidentally rely on stronger guarantees than the package actually provides
How to inspect caller misuse
Search for and inspect:
- imports of the package
- constructors
- exported funcs and methods
- interface implementations and adapters
- tests that use the package
- wrappers that narrow or reinterpret semantics
For each important API surface, ask:
- what contract does the package actually provide?
- what contract do callers appear to assume?
- where do those differ?
Quality bar
The final output should read like a triaged bug docket for a senior Pebble/CRDB engineer:
- low noise
- evidence-backed
- focused on semantic defects
- conservative about confirmation
- ordered by severity
