| New repo, no idea where anything is | Run it first, then trace one real request end to end; the call stack is the map | codebase.md |
| "Where do I make this change?" | Find the seam by following the data, not the folder names | codebase.md |
| Change touches code you did not write | Characterize current behavior with a test, then change; refactor and behavior in separate commits (Rule 4) | changes.md |
| Diff is getting big | Split at max_pr_lines: preparatory refactor, then behavior, then cleanup — three PRs (Rule 2) | changes.md |
| Bug report with no reproduction | Reproduce first, at the smallest scope that still fails; a fix you cannot see fail is a guess | bugs.md |
| Worked yesterday, broken today | git bisect — log₂(n) steps, 10 for 1,000 commits | bugs.md |
| Intermittent, only sometimes | Order, time, concurrency, shared state, or randomness — the five sources | bugs.md |
| Works locally, fails in CI | Diff the environment in a fixed order: version, deps, env vars, filesystem case, clock, parallelism | environments.md |
| No tests, or the tests do not catch anything | Test the behavior at the boundary you would not want to break; delete the rest | tests.md |
| A test fails once a week | Quarantine with an owner and a deadline, never a silent retry (Rule 6) | tests.md |
| PR sitting unreviewed, or review going in circles | Shrink it, state the risk, and separate blocking from preference | reviews.md |
| "How long will this take?" | Range from your own calibration log, not from the happy path (Rule 5) | estimation.md |
| Endpoint or job too slow | Measure first, name the target number, then find the dominant term | performance.md |
| Upgrade broke the build, or a new library is proposed | What it replaces, what it drags in, what it costs to remove | dependencies.md |
| Schema change, backfill, or data fix | Expand-migrate-contract, never a single destructive step (Rule 8) | migrations.md |
| Merged but not released, or needs a rollback plan | Name the rollback artifact before merging; flag it if the revert is slow | shipping.md |
| Paged, production is broken | Mitigate, then diagnose; the fix comes after the bleeding stops | oncall.md |
| Handling user input, secrets, or authorization in this diff | Run the developer's security pass on your own change | security.md |
| Starting a new service or project from zero | Decide the irreversible things deliberately, defer everything else | greenfield.md |
| Disagreement, scope creep, unclear requirement, handoff | Make the tradeoff explicit and put the decision in writing | collaboration.md |
| Anything else | Reproduce it, name the file and line that changes, state how you will know it worked, then do the smallest version of it | — |