agent-coding-playbook

Use when the user asks to fix a bug, investigate an error, debug a crash, explain a stack trace, or make a failing test pass. Enforces reproduce → isolate → smallest fix → verify, instead of guessing a cause and patching code.

Use when the user asks to review a pull request, review a diff, review changes on a branch, or audit code written by a teammate or AI agent. Reviews the diff (not the summary) for unrelated changes, missing verification, behavior risks, and over-engineering.

Use when the user asks to add a new feature, add a new API/endpoint/page/component, implement a new capability, or extend existing functionality with new behavior. Forces a plan-before-code loop, scoping non-goals, and verifying the new behavior end-to-end.

Use when the user asks to understand, explain, trace, audit, or explore code WITHOUT modifying it. Examples — "how does X work", "where is Y called", "why does this branch exist", "trace the request flow". Stays read-only and does not produce a fix.

Use when a request is large, ambiguous, or spans multiple files/components and the user has NOT yet approved an implementation approach. Produces a verifiable plan via Plan Mode and a TodoWrite breakdown, then hands off to a more specific skill (bug-fix, refactor, feature-add) for execution.

Use when the user asks to refactor, clean up, simplify, modularize, deduplicate, rename, or improve the structure of existing code WITHOUT changing behavior. If the user wants new behavior, do not use this skill. Enforces small reversible steps and behavior preservation.

Use before releasing, deploying, publishing, cutting a tag, or merging into a production-bound branch. Classifies risk level and audits verification evidence, rollback plan, and operational readiness — not just whether the code compiles.

Use when the user asks to fix a bug, add behavior, or change behavior in a project that has a test framework, AND the change can be expressed as an observable input/output contract. Writes a failing test first, then makes the smallest change to pass it.