--- name: whyspec-plan description: Use when planning a code change, capturing decisions before coding, or setting up the Decision Bridge. argument-hint: "" --- Plan a change — create intent.md, design.md, and tasks.md with the Decision Bridge. When ready to implement, run `/whyspec-execute` --- **Input**: A change name (kebab-case) or description of what to build via ARGUMENTS. ## Iron Law **ACT FIRST, ASK ONLY WHEN STUCK.** The user invoked `/whyspec-plan` with a description of what they want. Your job is to structure their intent into plan files — not to interview them. ## Red Flags — If You're Thinking This, STOP - "I should ask what problem this solves" → The user TOLD you. Read ARGUMENTS. - "Let me ask about constraints first" → Explore the codebase. Find them yourself. - "I need more context before I can plan" → You have a codebase. Read it. - "This is too vague to plan" → Even "fix auth" is enough. Read the auth code, find the issues, plan the fix. - "I'll create a generic template and ask the user to fill it in" → That's not planning. That's homework assignment. ## Steps 1. **Parse ARGUMENTS and infer intent** Read what the user typed. Derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`). **If ARGUMENTS is empty or a single ambiguous word** (e.g., just "plan" or "help"): Ask ONE question: "What change are you planning?" — then proceed. **If ARGUMENTS has any meaningful description** (even brief): Proceed immediately. Do NOT ask forcing questions. The user told you what they want. User: `/whyspec-plan add dark mode support` Agent: Creates change folder, writes intent.md capturing dark mode as the goal, design.md with CSS custom properties vs class-based approach trade-off, tasks.md with implementation steps. Why good: User stated what they want. Agent structured it into plan files without interrogation. User: `/whyspec-plan add dark mode support` Agent: "What problem does this solve? Who feels this pain today?" Why bad: The user literally just told you — they want dark mode. Asking "what problem does this solve" is patronizing checklist-walking. The answer is obvious from the input. User: `/whyspec-plan` Agent: "What change are you planning?" Why good: ARGUMENTS is empty. ONE question to get started is justified. User: `/whyspec-plan refactor auth middleware` Agent: "What constraints exist? What does success look like? How will you know it works?" Why bad: Three rounds of corporate interview questions. The user wants to refactor auth middleware — explore the codebase to understand constraints, don't ask generic questions. 2. **Create the change folder** ```bash whyspec plan --json "" ``` Parse the JSON response: - `path`: The change directory (e.g., `whyspec/changes/add-auth/`) - `templates`: Template content for intent.md, design.md, tasks.md - `context`: Project context from config.yaml (constraints for you — do NOT copy into files) - `rules`: Project-specific rules (constraints for you — do NOT copy into files) If a change with that name already exists, ask: continue the existing change, or create a new one with a different name? 3. **Explore codebase for context** (if the change touches existing code) Before writing plan files, read relevant code to understand: - Current architecture in the affected area - Existing patterns and conventions - Dependencies and constraints User wants to add rate limiting. Agent reads src/middleware/index.ts, finds Express + helmet at line 12, sees the middleware chain: cors → helmet → bodyParser → routes. Writes design.md: "Insert express-rate-limit after helmet in the existing chain at src/middleware/index.ts:14. Use sliding window algorithm. Redis backing via existing ioredis client at src/lib/redis.ts." Why good: References exact files, line numbers, existing dependencies. Plan is grounded in code the agent actually read. User wants to add rate limiting. Agent writes design.md: "Consider using express-rate-limit or a custom middleware solution. Evaluate Redis vs in-memory storage." Why bad: Generic advice from training data. Ignores the actual codebase. Could have been written without reading a single file. 4. **Create intent.md** Write to `/intent.md`. Here's a concrete filled-in example: ```markdown ## Why This Change Exists POST /api/users returns 500 under load because we have no rate limiting. Production logs show 12k requests/min from a single IP during the March 28 incident. ## What It Enables API stability under load. Prevents abuse without blocking legitimate traffic. ## Decisions to Make - [ ] Rate limit storage: Redis (shared across 3 instances) vs in-memory (simpler, single-instance only)? - [ ] Limit granularity: per-IP vs per-user-token vs both? - [ ] Response on limit: 429 with Retry-After header vs 429 with custom error body? These checkboxes form the "before" side of the Decision Bridge. They will be resolved during /whyspec-capture after implementation. ## Constraints - Must work with existing Express middleware chain (cors → helmet → bodyParser → routes) - Redis (ioredis) already available at src/lib/redis.ts — prefer reuse over new dependency - P99 latency budget: <5ms per request for rate limit check ## Success Looks Like - `npm test` passes with rate limit integration tests - Siege test: 1000 req/s returns 429 after threshold, Retry-After header present - No latency regression visible in existing API benchmark ## Assumptions - Redis is available in all environments (need to verify staging) - Current ioredis client supports the rate limiting pattern we choose ``` **IMPORTANT**: The "Decisions to Make" checkboxes are the Decision Bridge. Every unsettled design choice MUST be listed here. ## Decisions to Make - [ ] Rate limit storage: Redis (shared across instances) vs in-memory (simpler, single-instance only)? - [ ] Limit granularity: per-IP vs per-user-token vs both? - [ ] Response on limit: 429 with Retry-After header vs 429 with custom error body? Why good: Specific, actionable decisions with concrete options derived from the codebase. ## Decisions to Make - [ ] What technology to use? - [ ] How to implement it? - [ ] What approach is best? Why bad: Vague decisions that could apply to literally any change. Not useful. 5. **Create design.md** Write to `/design.md`. Skip the trade-off matrix for simple changes: ```markdown ## Approach [Chosen technical direction — 2-3 sentences grounded in the actual codebase] ## Trade-off Matrix | Option | [Criterion 1] | [Criterion 2] | [Criterion 3] | |--------|---------------|---------------|---------------| | Option A | ... | ... | ... | | Option B | ... | ... | ... | ## Architecture [ASCII diagram showing the design — components, data flow, boundaries] ## Questions to Resolve - [ ] [Open question needing an answer before or during coding] ## Risks & Unknowns - [What could go wrong] ## Dependencies - [External libraries, APIs, services] ``` 6. **Create tasks.md** Write to `/tasks.md`. Define verification FIRST — goal-backward planning: ```markdown ## Verification What proves this change works — defined BEFORE tasks: - [ ] [Verification criterion 1] - [ ] [Verification criterion 2] ## Tasks - [ ] Task 1: [description] verify: [how to verify this specific task] - [ ] Task 2: [description] verify: [verification step] ``` Each task should be small enough for one atomic commit. 7. **Show summary** ``` ## Plan Created: / intent.md — WHY: problem, constraints, success criteria design.md — HOW: approach, trade-offs, decisions to make tasks.md — WHAT: verification criteria + implementation checklist Decisions to make: N pending Tasks: N defined Ready to implement? Run /whyspec-execute ``` ## Tools | Tool | When to use | When NOT to use | |------|------------|-----------------| | **Glob** | Find files by pattern before writing plan (e.g., `src/middleware/**/*.ts`) | Don't glob blindly — know what area you're looking for | | **Grep** | Search for patterns in code (e.g., existing rate limit logic, auth middleware) | Don't grep the whole repo — scope to relevant dirs | | **Read** | Read specific files to understand architecture before planning | Don't read files unrelated to the change | | **Bash** | Run `whyspec plan --json` (CLI-as-oracle). Run `git log` to understand recent changes | Don't run destructive commands | | **AskUserQuestion** | ONLY when ARGUMENTS is empty or genuinely ambiguous (see format below) | Don't ask questions answerable by reading code | ### Codebase First, Web Never-First Read the codebase BEFORE considering web search. Web search is justified ONLY when: - The change involves a library/framework not present in the codebase - You need version-specific migration docs - Security advisory lookup (CVEs) Never search the web for: architecture decisions, "best practices", or how to use a library already in the codebase. ### AskUserQuestion Format (use sparingly) When you MUST ask (ARGUMENTS empty, or genuinely stuck after codebase exploration): 1. **Re-ground**: "Planning **** in `` on ``" 2. **What you found**: Show what you already discovered in the codebase 3. **One specific question**: Not a checklist. One thing you need. 4. **Recommendation**: "I'd suggest X because Y — your call" Planning **add-rate-limiting** in `my-api` on `main` I found Express 4.18 with helmet middleware at src/middleware/index.ts, and an existing ioredis client at src/lib/redis.ts. Should the rate limit apply globally (all routes) or only to /api/* routes? I'd suggest /api/* only — internal health checks shouldn't be rate-limited. Why good: Shows what was already found. Asks ONE specific question with a recommendation. What problem does this solve? What constraints exist? How will you know it works? Why bad: Three generic questions. No codebase context. Classic checklist-walking. ## Escalation Protocol If you hit any of these, STOP and ask the user (max 3 attempts before escalating): | Situation | Action | |-----------|--------| | ARGUMENTS is genuinely ambiguous after codebase exploration | Ask ONE specific question, not a checklist | | Multiple valid architectures with no clear winner | Present the trade-off matrix, ask user to pick | | Change requires access or knowledge you don't have | State what you know, what you need, and ask | | After 3 failed attempts to infer intent | Escalate: "I need more context. Here's what I've found so far: [findings]" | ## Guardrails - **Don't interrogate the user** — if ARGUMENTS contains a meaningful description, proceed. Only ask when ARGUMENTS is empty or genuinely ambiguous. - **Ground plans in the codebase** — read relevant code before writing. Plans that ignore the actual architecture are useless. - **Don't implement code** — this skill creates plan files only. Implementation happens in `/whyspec-execute`. - **Don't skip "Decisions to Make"** — every unsettled design choice must be a checkbox. If you can't find any decisions, you haven't thought hard enough about the change. - **Use CLI-as-oracle** — always call `whyspec plan --json` to create the folder. Don't create paths or generate IDs manually. - **Apply `context` and `rules` as constraints** — they guide your writing but must NOT appear in the output files. - **Verification before tasks** — in tasks.md, define what "done" looks like before listing the work. - **Scale to the change** — a typo fix gets a 3-line intent and 1 task. A major refactor gets the full treatment. ## Rationalization Table | If you catch yourself thinking... | Reality | |----------------------------------|---------| | "I should ask the user some clarifying questions first" | Read the codebase. Most "clarifying questions" can be answered by reading code. | | "The user's description is too vague to plan" | Even "fix auth" is plannable — read the auth code, find the issues, plan the fix. | | "I need to understand the full architecture before planning" | Plan the change, not the universe. Read what's relevant, skip what's not. | | "I should create a comprehensive plan with all sections" | Scale to the change. A 1-line fix gets a 3-line plan. Don't over-engineer. | | "Let me ask about success criteria" | Infer from the change. "Success = tests pass + the thing works." Write it yourself. | | "I'll write generic placeholder text and the user can fill it in" | That's not planning. Populate every field with specific, codebase-grounded content. | ## Anti-Patterns | If you're about to... | STOP — do this instead | |----------------------|----------------------| | Ask "What problem does this solve?" | Read ARGUMENTS — the user just told you | | Ask "What constraints exist?" | Explore the codebase — find the constraints yourself | | Ask "Who is this for?" | This is a code change, not a product pitch | | Write a generic plan without reading code | Read the affected files first | | Create a massive plan for a small fix | Scale the plan to match the change size | | Skip Decisions to Make because "it's obvious" | If it's obvious, write it down — it takes 10 seconds |