Diagnosing Bugs

A discipline for hard bugs. Skip phases only when explicitly justified.

When exploring the codebase, read CONTEXT.md (if it exists) to get a clear mental model of the relevant modules, and check ADRs in the area you're touching.

Intent and capability boundary

Classify the requested action before beginning the loop:

• Remediation mode applies only when the user explicitly requests a fix, repair, modification, or restoration (including an unambiguous equivalent). It permits persistent product and regression-test changes. Follow every phase below.
• Diagnosis-only mode applies to diagnose, debug, investigate, and root-cause-only requests, and is the default for an ambiguous request. Do not infer remediation from a bug report, urgency, or a request to continue.

Diagnosis-only mode stays inside the capability boundary: it permits read-only source, configuration, and history inspection plus read-only runtime observation, but no persistent product, test, configuration, or artifact changes.

If diagnosis-only work needs temporary instrumentation, a throwaway repro, prototype, or harness, or a failing test:

1. Before writing, preview the exact changes to make in an isolated workspace: paths plus a diff or complete contents, their purpose, and a cleanup plan that names every artifact to remove.
2. Ask for explicit approval and wait. A general diagnosis request, silence, or rejection is not approval.
3. Only after approval, make those temporary writes in an isolated workspace, never the user's checkout. A throwaway repro, prototype, or harness—and all of its local source, dependency manifests/lockfiles, fixtures, scratch data, route configuration, run metadata, and run instructions—must live under .agents/prototype/<name>/ inside that approved isolated workspace. It may inspect production source read-only for context, but must not import or modify production source or edit the project's root manifests, task runners, routes, configs, or shared components. This location rule applies only to prototype-like artifacts; ordinary permanent regression tests and generic debug scripts retain their existing locations. Remove every approved artifact before reporting; do not retain it as a product or test change.