/before

What it does

Before any non-trivial code change, Claude:

1. Reads CLAUDE.md and the docs relevant to your task
2. Greps the repo for prior art (similar code, helpers, patterns that exist)
3. Checks docs/DECISIONS.md for past decisions that apply
4. Checks docs/KNOWN-ISSUES.md for recurring bugs in this area
5. Reads the last entry in docs/SESSIONS.md for in-flight context
6. States a plan with files it expects to touch, risks, and steps
7. Waits for your approval before writing any code

Auto-skip on small tasks

/before is smart about when to run. It skips itself on:

• One-line changes or typo fixes
• Documentation-only edits
• Undoing / tweaking code from earlier in the same session
• Interactive debugging pivots (plans go stale fast)
• Tasks where you said “quick fix”, “small change”, “just”, “simple”

It always runs on:

• First touch of a module this session
• Tasks that will touch 3+ files or rename something used widely
• Tasks with “add”, “refactor”, “rename”, “rewrite”, “integrate”, “migrate” in the description
• After a long gap (first task of the day, first time in this repo this week)
• When you say “take your time” or “think about this”

First run in a project

If the project doesn’t have CLAUDE.md or the docs/ files yet, /before offers to scaffold them. Never overwrites existing files.

Output shape

## Plan — add rate limit to /api/invite

Read:
- CLAUDE.md: API routes must use thin handlers → service layer
- docs/api.md: rate-limit helper exists at lib/rate-limit.ts

Prior art:
- app/api/signup/route.ts:42 — applies rate-limit via withRateLimit()

Decisions that apply:
- ADR-004: Rate-limits use IP+userId composite key

Known issues:
- none

Plan:
1. Import withRateLimit from lib/rate-limit
2. Wrap the POST handler (5/min/user)
3. Add tests for the 429 path

Files I expect to touch:
- app/api/partner/[id]/doctors/route.ts
- __tests__/invite-rate-limit.test.ts

Risks:
- Existing callers may not handle 429 — grep for /invite callers.

Then it waits. No code written until you approve.

Why it matters

Claude without /before tends to:

• Rewrite files you didn’t ask it to touch
• Reinvent helpers that already exist
• Re-introduce bugs the team fixed months ago
• Skip past ADRs that constrain the solution

One pre-code plan catches all four.

Related

• /decision — log any design choice made during the task
• /ship — the post-code bookend