Debug and Verify the Result

A bug report should describe what was observed, where it happened, the input or action that triggered it, the expected behavior, and the evidence available. `Login is broken` invites guesses. An error message, timestamp, browser state, account condition, request identifier, and minimal reproduction let Claude search the right path.

Name the environment precisely. A failing production request with live data may not reproduce against local fixtures. A test failure on one operating system may depend on path or shell behavior. Before editing, ask Claude to restate the symptom and reproduce it in the safest environment that still preserves the relevant condition.

Debugging is a sequence of falsifiable questions, not a search for code that looks suspicious. Trace the failing path, identify the boundary where expected state becomes incorrect, and rank hypotheses by evidence. Then choose the smallest observation that distinguishes them: a targeted log, a single test, a request capture, a state query, or a diff against the last known-good version.

Ask Claude to report what each check would mean before running it. This prevents a large command dump from replacing reasoning. When a hypothesis fails, update the model rather than modifying another nearby file. Keep the investigation record concise so the final explanation shows why the fix addresses the root cause.

When practical, encode the bug as a test that fails for the right reason before implementation. This proves the test can see the problem and creates a durable guard against regression. A test that was written after the fix and only ever passed may accidentally confirm the implementation rather than the requirement.

Choose the lowest test layer that captures the broken contract without mocking away the cause. Unit tests are fast for pure logic. Integration tests verify boundaries such as a database or API contract. End-to-end tests and browser observation cover user paths but are slower and more sensitive to environment. Use a small number of complementary checks rather than making one giant test responsible for everything.

A targeted test proves one expectation. Typechecking proves selected structural consistency. Linting checks configured rules. A build proves the project can produce an artifact in that environment. A browser screenshot or interaction proves visible behavior. A deployment receipt proves a version was released. A public observation proves the named user-facing route serves that behavior.

Match the proof stack to the claim. If the request is a local refactor, source review and tests may be enough. If the request says `fix the live site`, the loop also needs versioned deployment and independent production verification. Report failed or skipped checks honestly; do not substitute one green layer for another required layer.

Sometimes the application is not the failing system. CLAUDE.md may not have loaded, a permission rule may match the wrong path, an MCP server may be disconnected, a hook may reject a command, or the installation may be unhealthy. Use the layer-specific diagnostics instead of changing application code to work around an agent configuration problem.

Anthropic's configuration debugging guide centers `/context`, `/doctor`, `/hooks`, and `/mcp`. Capture the exact warning, effective source, and session location. Reproduce from a clean session when context or reload behavior may be involved. Treat configuration changes with the same diff, test, and rollback discipline as application changes.