2.4 KiB
name, description, argument-hint, disable-model-invocation
| name | description | argument-hint | disable-model-invocation |
|---|---|---|---|
| bug | Investigate a reported bug, find and explain its root cause, and propose a fix — without implementing anything | <description of the buggy behavior> | true |
A bug has been reported:
$ARGUMENTS
Investigate it and propose a solution. Do not implement anything — no edits, no new files, no fixes applied. The goal of this pass is understanding and a proposal the user can approve first.
Work through it like this:
-
Pin down expected vs. actual. Restate what the behavior should be and what it actually is. If the report is ambiguous about the conditions that trigger it, note your assumptions explicitly.
-
Find the relevant code. Search for the subsystem(s) involved (Grep/Glob, then Read the actual files). Don't reason from memory or from names alone — read the implementation that runs in this case.
-
Trace the real execution path. Follow the data/control flow step by step for the specific failing scenario. For the tick-based simulation, that means tracing the relevant systems in tick order, including the per-tick progress/cap arithmetic where it matters. Use the project's actual constants (tick rate, belt speed, etc.) rather than hand-waving.
-
State the root cause precisely. Name the exact mechanism, citing
file:line. Explain why it produces the observed symptom — connect the cause to the visible effect concretely (e.g. "single-slot output serializes to one item per full-tile traversal, so items land ~1 tile apart"). Confirm it explains the specific trigger conditions in the report. -
Propose a solution. Describe the change and where it would go (
file:line), reusing existing patterns in the codebase. If the symptom has more than one contributing path, say so. If the fix involves a design or balance trade-off (correctness vs. throughput, lossless vs. capped, a visual side effect, etc.), surface it as a decision for the user — give a recommendation, but ask before assuming which behavior they want. -
Stop and hand back. End with the proposal and any open questions. Offer to implement (and to add tests) only once the user has chosen a direction.
Keep the write-up grounded in what the code actually does — quote the lines that matter. Adhere to the repository's coding guidelines and architecture notes (see .claude/CLAUDE.md) when describing any proposed change.