claude-code-plugins

Repository context. Gather first

Collect these with individual Bash calls, one command per call, never combined into a single
invocation:

• Current branch, git branch --show-current
• Recent commits, git log --oneline -10
• Shallow clone, git rev-parse --is-shallow-repository

Treat a failure (not a repository, git unavailable) as an unknown value and carry on. Keep these as
separate body Bash calls rather than pre-compute lines: the harness runs a skill's whole pre-compute
block as one shell invocation, and a worktree-isolated session refuses a compound command that
contains git.

Pre-computed context

Lane config: !ls "${CLAUDE_PROJECT_DIR:-.}/.claude/bugs.md" 2>/dev/null || echo "absent — bundled default lanes apply"

Consumer gotchas:
!bash "${CLAUDE_PLUGIN_ROOT}/scripts/concat-gotchas.sh"

Variables

Arguments: $ARGUMENTS

Purpose

/bugs:scan is the front of the bug lifecycle: it hunts defects nobody has observed yet, in
code that is resting. Every other finding-producer in reach needs an oracle first, a diff, a failing
test, a stack trace, a factual claim, a comment marker. This one needs none of them.

One invocation is one bounded pass: hunt a target (or a rotated lane), verify each candidate
through a separate fresh-context gate, report what survives in the plugin's five-field shape, stop.
That makes it equally usable interactively ("find a bug in the billing module"), from a /loop, or as
a daily operator routine, the same bounded unit either way.

The design premise, taken from published practice: per-run recall is low and the raw false-positive
rate is high, so recall and precision are separated into two stages. Hunters are told to be
generous; the verification gate is told to refute. A finding that reaches the report survived an agent
whose job was to kill it.

Verb contract. Read-only toward the repository

Bare invocation is read-only: it never edits code, never branches, never pushes, never files a
tracker item. Filing sits behind --track, and model auto-invocation never supplies --track on its
own. A user (or a standing lane rule) must ask for it.

Reconciliation: persisting the findings report and its cursor block under ${CLAUDE_PLUGIN_DATA}
is plugin-owned state, not target-repo mutation. The scanned repository's working tree, index, and
history are untouched by a bare run. --dry-run goes further: it emits the findings to stdout and
persists nothing. No report file, no cursor advance, no filing.

Durable cursor state never lives in .work/. Anything a wrapping session leaves under .work/ is a
checkout-local cache that a fresh clone or a git clean erases; the ladder below must re-derive the
cursor from rungs 1–3 without it, and never treats a cache note as authority.

Durability on a cloud or scheduled run. ${CLAUDE_PLUGIN_DATA} is ephemeral on a cloud session
and unreachable from the next scheduled run on another host, so the persisted report and its cursor
vanish with the container. On such a run pass --track: a filed item is the only output that
survives, and it is also what rung 1 of the cursor ladder reads back. Without --track a cloud run
is a one-off whose findings live only in the transcript.

Modes

Argument	Mode	Behavior
<path> / <feature> / <diff-ish ref>	Targeted	Hunt exactly that scope. No lane rotation, no cursor advance.
--lane <name>	Named lane	Hunt the named lane's globs. Advances the cursor to that lane.
(empty)	Rotation	Self-select the next lane via the cursor ladder, then hunt it.
--track	Filing	After reporting, file verified findings as raw intake (see below), subject to the team's filing_posture and the filing ladder in Step 7. Composable with any mode.
--dry-run	Plan-and-report only	Full hunt + verification, report to stdout, zero persistence and zero cursor advance. Composable with any mode; overrides --track.

Lane definitions (lanes, filing_posture) resolve from .claude/bugs.md per the cascade
contract. Keys, layers, and merge semantics live in
`${CLAUDE_PLUGIN_ROOT}/reference/config.md`, which is their single home.
When no layer declares lanes, use the bundled generic default lanes in
`context/lenses.md`.

Cursor ladder (rotation mode)

Which lane comes next is derived statelessly, first rung that answers wins:

1. Tracker history. When the work-items plugin is installed and a tracker binding resolves,
   search items (--state all) for the provenance line Filed by /bugs:scan (lane: <name>).
   The most recently filed lane is the previous lane; take the next one in declaration order. The
   search must be an exact match on that line (the seam's search verb, or the provider's literal
   body match with the string quoted): a semantic or fuzzy search cannot tell "no match" from
   "missed", so it is not an answer. When only a fuzzy search is available, or no search ran against
   a bound tracker, print why and fall through to rung 2; confirm the search actually ran against a
   bound tracker before trusting an empty result. An unbound tracker returns nothing, which is not
   the same answer as "no prior scan filings".
2. Persisted-report cursor. Otherwise resolve the report directory by the same precedence
   persistence uses. Step 5 below defers to /bugs:write's Step 4, and so does this rung;
   reading a directory reports no longer land in is how a configured output_dir silently strands the
   cursor. Then search backward from the newest report for the newest one carrying a valid
   rotation cursor block, one that names the rotation lane (see
   `context/findings-report.md`), and use it the same way. Reports
   without such a block are skipped, not read as a cursor: /bugs:write's reports share that
   directory and carry none, and a targeted scan's report must never advance rotation. If no report
   carries one, fall through to rung 3.
3. Date-derived floor. Otherwise pick deterministically: index the declared lane list by
   (days since 1970-01-01 UTC) mod (lane count). Zero state, no history, still rotates daily.

State the rung you used in the report. An operator reading a rotation run should be able to tell
tracker-derived rotation from the zero-state floor.

Reset semantics. Deleting the plugin-data reports (or scanning from a fresh machine) drops the run
to rung 3, which is a valid state, not an error. <project-slug> is the kebab-cased basename of the
project root, so two checkouts sharing a basename (~/work/api and ~/oss/api) share one cursor
directory. Name the absolute project root in the report so a reader can spot the collision. Two
sessions started the same day on a zero-state checkout will select the same lane; that is accepted
(the dedupe steps below absorb the duplicate findings) rather than jittered, because a
deterministic floor is what makes daily coverage predictable.

Budget

• Stop condition: 3 verified findings, or the lane's budget-bounded sample is complete.
• Candidate cap: at most 10 candidates per hunt wave reach the verification gate (5 on a small
  scope, per the sizing table). Rank by evidence strength and drop the tail rather than widening the
  wave; the dropped tail is reported, never discarded.
• Refill cap: if a whole wave is refuted, at most 2 refill waves. Then report the refuted set
  and stop. An unbounded refill loop is a token sink against a ~1:50 signal-to-noise base rate.
• "Lane exhausted" means the sample is complete, not that the lane is bug-free. The scan is
  budget-bounded sampling; never claim exhaustive coverage of a lane in the report.

Zero verified findings is a clean, successful outcome. Do not invent a finding to justify the run.

Sizing. Model by stage, breadth by scope, effort as the ceiling

Cost follows what is scanned, and precision never pays for it. Three rules, applied in this order:

Model by stage. Each stage runs on the tier its job needs, passed through the Agent tool's
per-invocation model parameter, never on the session's top model. The tiers below are the
fleet's ordered capability tiers; which alias each one binds today is the loop-lane convention's
to state, not this skill's. Resolve it from the marketplace's
docs/conventions/loop-lane/README.md "Capability tiers", whose alias binding is dated and
carries its own recheck trigger:

Stage	Tier	Why
Hunters (Step 2)	fast	The recall stage is generous by design and every output is refuted downstream, so a cheaper reader costs little precision and most of the run's tokens live here.
Gates (Step 4)	strong	The precision stage; the reproduction it runs is what makes a finding credible.
Main thread	the session's model, nothing passed	Orchestration and triage only.

Name the alias that actually resolved in the report's run metadata, so a reader can tell which
binding the run used. A dispatch the harness rejects means the binding moved: report it and
re-read the owner doc rather than substituting an alias here.

Breadth by scope. After Step 1 enumerates the files (test suites excluded), classify the scope
and size the recall stage from it:

Scope	Definition (files, or lines after hotspot ranking)	Lenses	Gate cap per wave
small	5 files or 1,000 lines or fewer	1 to 2, the highest-ranked for the surface	5
medium	20 files or 5,000 lines or fewer	2 to 3	10
large	above	4	10, refill waves allowed

A targeted run over one file is small; a full lane is usually large. The scope class, the lens
count, and the models used go in the report's run metadata.

Effort as the ceiling. The Effort row bounds lenses and refill waves; scope picks
within it, never above it. A low run over a large lane still dispatches one lens.

Effort

Caller effort for this run is ${CLAUDE_EFFORT}. If that reads as a literal placeholder rather than
one of low, medium, high, xhigh, or max, this body was read directly instead of
skill-loaded, so the substitution never ran: treat the run as high and use the full budget above.

Effort scales the recall stage only. The verification gate is the precision machinery and never
relaxes: every candidate still faces a separate fresh-context refuting subagent at every level, and
"if uncertain, it is NOT a finding" binds at low exactly as it does at max.

Effort	Lenses dispatched (step 2)	Refill waves	Stop condition
low	1, the highest-ranked lens for the scope	0	first verified finding
medium	2	1	2 verified findings
high, xhigh, max	up to 4, sized to the scope per the sizing table	2	3 verified findings

The gate cap per wave (10, or 5 on a small scope) holds at every level. Name the effort level and
the lens count in the report's run metadata, so a low run reads as the narrower sample it is
rather than as a clean lane.

The scan pipeline

Process one unit at a time. One target, or one lane. A unit is closed when its verified findings are
reported and deduped (and filed, under --track when the team's filing_posture allows it); only
then does the cursor advance.

Step 1. Resolve scope

Resolve the mode, the lane globs, and filing_posture from the config cascade. Enumerate the concrete
file list and drop test suites from it (*.test.*, test_*, *.Tests.ps1): hunters read a test to
learn a unit's contract and never hunt the test itself. If the enumeration exceeds ~40 files, narrow
to the highest-signal subset (recently changed, highest fan-in, most branch-dense) and say in the
report that you sampled. Then compute the hotspot reading order described in
`context/lenses.md`, one git command per Bash call; on a shallow clone, print the
skip notice and continue unranked. Classify the scope as small, medium, or large per the
sizing table.

Done when you can name the exact file list the hunters will read, the order they read it in, and
the scope class that sizes the rest of the run.

Step 2. Dispatch hunters (recall stage)

Dispatch one subagent per lens over the resolved scope, on the hunter tier the sizing table
names, each with the four-part contract: objective, output format, tool/source guidance, and task boundaries, spelled out
in `context/lenses.md`. The scope class picks the lens count and the
Effort row is the ceiling. Every hunter is read-only, must attach a verbatim evidence quote
to every candidate, may follow one hop outside the scope (a direct caller or callee of a scoped file)
and tags such a candidate out-of-lane, and is explicitly told that returning no candidate is a
valid and expected outcome.

Done when every dispatched lens has returned.

Step 3. Triage the candidate list (main thread, before any gate)

Seed, merge, and cut in the main thread, so no gate is spent on a duplicate or on a candidate whose
own hunter says nothing observable breaks:

1. Seed from the prior tail. On a rotation or named-lane run, read the newest persisted report
   for this lane (the directory rung 2 reads, resolved by the same precedence) and add its
   "Candidates not gated" rows to the list ahead of the hunters' output: each already carries a
   path:line, so at equal evidence strength it ranks first. A row whose quoted location no longer
   exists goes to the side observations. A targeted run has no lane and seeds nothing.
2. Merge same-cause candidates. Two lenses often reach one fault by different routes, and a
   seeded row often returns as a fresh candidate. Keep one candidate carrying both lens ids and the
   stronger evidence quote; the gate sees it once.
3. Drop cosmetic-impact candidates. A candidate whose stated impact is a comment, a log string,
   or a report field nothing consumes is a side observation, not a bug. Move it to the report's side
   observations rather than gating it.
4. Rank by evidence strength and cut to the gate cap. Done when the remaining list is at or
   under the cap. The tail above the cap is retained in the report's "Candidates not gated" section,
   which is what item 1 reads back on the next run over this lane.

Triage never confirms anything: it merges, drops, and orders. Every candidate that remains still
faces the gate.

Done when the list is at or under the gate cap and every merged or dropped candidate is accounted
for in the report.

Step 4. Verification gate (precision stage)

Dispatch a separate fresh-context subagent per candidate, on the gate tier the sizing table
names, using the prompt contract in `context/verification-gate.md`. The hunter that found a
candidate never grades it. A model re-checking its own work rubber-stamps it. The gate's default
stance is refute: it must try to construct the concrete input path that triggers the claimed
fault, and if it cannot, the candidate dies. If uncertain, it is NOT a finding.

Survivors are labeled reproduced (a check was actually run) or verified-by-reading (the fault is
established from the source, with the reproduction argument stated). Refuted candidates are retained
with their refuting argument. A high-kill gate catches some true positives, so they are never
silently dropped. A gate's one-line side observation (a stale comment, a weaker sibling check) goes to
the report's side observations.

Done when every candidate carries a verdict and a label or a refuting argument.

Step 5. Assemble and dedupe the report

Format per `context/findings-report.md`: the five fields per finding
(from /bugs:write's shape), plus the evidence label, the lens id, and the scope tag, then the refuted
tail, the candidates not gated, the side observations, and, on a rotation run, the cursor metadata
block with the sampled scope list; a targeted run emits the no-cursor line in its place. Before
persisting, run the same duplicate scan /bugs:write performs over the output directory. See Step 2
("Survey before you write") in `${CLAUDE_PLUGIN_ROOT}/skills/write/SKILL.md`,
and drop or merge findings that restate a prior report.

Persist to the path /bugs:write --file resolves (its Step 4 owns that precedence:
output_dir, then ${CLAUDE_PLUGIN_DATA}/bug-reports/<project-slug>/, then a project-local
fallback). Do not reinvent either mechanism here. Write the file with the Write tool: a shell
redirect or heredoc is what a repository's write guards block, and the plugin data directory is
outside any scratch exemption. Under --dry-run, skip persistence entirely.

Done when the report is emitted, and (outside --dry-run) persisted with its path stated.

Step 6. --track filing (explicit only)

Posture gate first. Resolve filing_posture from the config cascade. See
`${CLAUDE_PLUGIN_ROOT}/reference/config.md`, whose bundled default is
manual-only when no layer declares it. When it resolves to manual-only, file nothing: print one
notice, "filing skipped: filing_posture is manual-only (<layer, or bundled default>); report-only", and stop at the report, the same degrade shape as an absent work-items. Only allowed reaches the
beats below.

Then apply the filing ladder in Step 7: on an interactive run only the findings the ladder routes
to the tracker are filed; on an unattended run every verified finding is. Then, presence-gated on
work-items, follow the dogfood-filing beats by invoking /work-items:track add, never by pathing
into another plugin's files:

1. Dedupe. Search items over --state all first; sameness is judged by underlying cause, not
   wording. An open match gets a comment instead of a second item; a closed match is reopened or
   linked from a fresh item.
2. Categorize as raw intake. A scan filing records what was observed, not a verified diagnosis.
3. File through track add, which owns the body template and the argv-safe write. The body
   carries the five fields, and a provenance line, Filed by /bugs:scan (lane: <name>), which
   is what rung 1 of the cursor ladder later recognizes.
4. Mark needs-triage from the live label set. Apply that exact name when it exists. Create no labels. If it does not exist, say so and file without it.
   The filer does not self-triage.

Degrade: if work-items is absent, or no tracker binding resolves, do not improvise a filing path.
Print one notice, "filing skipped: ; report-only", and stop at the report.

Done when each verified finding is filed, matched to an existing item, or explicitly skipped with a
printed reason.

Step 7. Hand off through the filing ladder

The scan itself edits nothing. Where a verified finding goes next follows one ladder, so a small
fix does not become a tracker item and an unattended run never leaves work stranded in a transcript:

Run	Finding	Route
interactive	local: its fix stays inside one plugin or module, changes no documented contract, and has an existing test file to extend	fix it now, in this session and branch, through /implementation:implement (or the project's own fix lane)
interactive	non-local, or needs a design decision	file it with --track, or ask the operator
any	security-relevant	file it, and route to the /review:security-review lane, which owns that surface
unattended (a loop, a routine, a lane rule that passes --track)	any	file it; nobody is present to fix it, and the tracker is the only durable output

"Unattended" is declared by the caller, never inferred from the environment. Recommend the route,
do not auto-invoke it; a finding worth root-causing first goes to /debugging:debug. Nothing
verified: say so plainly and name the lane and rung, so the next run rotates on.

Next

• Verified local finding, interactive run: /implementation:implement.
• Verified non-local or security-relevant finding: /work-items:track add, then
  /review:security-review for the security-relevant ones.
• A finding that needs root-causing before a fix: /debugging:debug.

What this skill does NOT do

• Does not edit code itself. No patches, no PRs, from this skill. A verified finding leaves
  through the Step 7 ladder, which in an interactive session routes a local fix to the implement lane
  in the same session rather than to the tracker.
• Does not file on bare invocation. Filing needs --track.
• Does not review a diff. That is /review:code-review's lane; this reads resting code.
• Does not verify factual claims in docs or config against code. All four codebase-health:audit
  dimensions own that.
• Does not chase coverage gaps (testing:audit, mutation-testing:audit), structural drift
  (code-tidying:tidy), or comment markers (work-items:scan-todos).
• Does not emit type: review-findings frontmatter. That frontmatter alone routes a report into
  the /review:fanout fix relay; a scan report is intake, not a detector-findings artifact.

Gotchas

• The hunter never grades itself. If you collapse Steps 2 and 4 into one agent, precision collapses
  with them. The gate is a separate fresh-context dispatch, per candidate.
• A cheaper hunter is fine; a cheaper gate is not. The gate's reproduction is the whole precision
  claim, so it stays on the gate tier whatever the hunters ran on, and a scope class never lowers
  the gate's stance.
• The ungated tail is a queue, not an archive. Step 3 reads the prior report's "Candidates not
  gated" rows back before it merges; a run that skips the seed re-derives what the last run over
  the lane already paid for.
• Triage merges and drops, it never confirms. A candidate that survives triage still faces the
  gate; a candidate dropped as cosmetic is written to the side observations, not silently gone.
• No evidence quote, no finding. A candidate without a verbatim quote of the offending source is
  retracted at the gate, not "investigated further".
• Refuted is reported, not deleted. The refuted tail is a feature: it lets a human overturn a
  wrong kill, and it stops the same dead candidate resurfacing next run.
• --dry-run must not advance the cursor. A dry run that persists a cursor silently skips a lane
  on the next real run.
• --track is not --file. --file is /bugs:write's flag for persisting a report to
  disk; the same token here would mean tracker mutation. This skill uses --track for filing.
• Shallow clones degrade, they do not fail. The hotspot ranking is skipped with a printed notice
  when history is absent; the four lenses read the scope unranked.
• A lane with no verified findings is a result. Report it, advance the cursor, do not refill past
  the cap looking for something to say.
• Consumer ## Gotchas concatenate after these bullets. The pre-computed Consumer gotchas block
  is the cascade ## Gotchas from .claude/bugs.md layers (user-global, team, local overlay) in
  layer order. Treat those lines as additional gotchas for this invocation. Missing layers are
  absent, not an error. Generalizable lines belong in this shipped skill via an issue, not in the
  consumer file.

Reference index. Load on demand

File	Load when
`context/lenses.md`	Step 2, writing each hunter's dispatch prompt; also holds the bundled default lanes.
`context/verification-gate.md`	Step 4, before dispatching the refute gate on a candidate.
`context/findings-report.md`	Step 5, emitting the report, and the ladder's middle rung reading a prior cursor back.
`${CLAUDE_PLUGIN_ROOT}/reference/config.md`	A .claude/bugs.md key decides the run (lane, rotation, filing posture) and its layer is unclear.
`${CLAUDE_PLUGIN_ROOT}/skills/write/SKILL.md`	Emitting a finding in the five-field shape, running the duplicate scan, or resolving where --track persists.