@gitwhy-cli/whyspec 0.1.16 → 0.1.18

package/skills/whyspec-execute/SKILL.md

@@ -1,25 +1,38 @@
 ---
 name: whyspec-execute
-description: Implement a planned change using intent and design as context. Use when the user wants to start implementing, continue work, or execute tasks from a WhySpec plan.
+description: Use when starting implementation, continuing work, or executing tasks from a WhySpec plan.
+argument-hint: "[change-name]"
 ---
 
 Implement a change — read the plan, work through tasks, commit atomically.
 
-When all tasks are done, run `/whyspec-capture` to save your reasoning.
+When all tasks are done, run `/whyspec:capture` to save your reasoning.
 
 ---
 
 **Input**: Optionally specify a change name. If omitted, auto-detect or prompt for available changes.
 
-**Steps**
+## Iron Law
+
+**NEVER SKIP THE PLAN.** Read intent.md and design.md before writing a single line of code. The plan is the contract — if reality doesn't match the plan, update the plan first.
+
+## Red Flags — If You're Thinking This, STOP
+
+- "The plan is clear enough, I'll just start coding" → Read intent.md. Now. It takes 15 seconds.
+- "I'll batch all changes into one commit at the end" → One commit per task. That's the contract.
+- "This task seems unnecessary, I'll skip it" → Ask the user to remove it. Don't silently skip.
+- "The design says X but Y is clearly better" → Flag the contradiction. Don't silently override.
+- "I'm done, no need to run the verify step" → Run it. Evidence beats confidence.
+
+## Steps
 
 1. **Select the change**
 
-   If a name is provided, use it. Otherwise:
+   If ARGUMENTS provides a name, use it. Otherwise:
    - Auto-select if only one active change exists
-   - If multiple changes exist, run `whyspec list --json` and use **AskUserQuestion** to let the user select
+   - If multiple changes exist, run `whyspec list --json` and let the user select
 
-   Always announce: "Executing change: **<name>**"
+   Announce: "Executing change: **<name>**"
 
 2. **Load execution context**
 
@@ -37,7 +50,7 @@ When all tasks are done, run `/whyspec-capture` to save your reasoning.
 
 3. **Read plan files for context**
 
-   Read the full content of these files from the change folder:
+   Read the full content of:
    - `intent.md` — understand WHY this change exists, what constraints apply
    - `design.md` — understand HOW to approach it, what decisions are pending
    - `tasks.md` — understand WHAT to implement and how to verify
@@ -53,7 +66,6 @@ When all tasks are done, run `/whyspec-capture` to save your reasoning.
    Remaining:
    - [ ] Task description 1
    - [ ] Task description 2
-   ...
    ```
 
 5. **Implement tasks sequentially**
@@ -67,47 +79,127 @@ When all tasks are done, run `/whyspec-capture` to save your reasoning.
    e. Commit atomically — one commit per task or logical unit
    f. Continue to next task
 
-   **Pause if:**
-   - Task is unclear or ambiguous → use **AskUserQuestion** to clarify before implementing
-   - Implementation reveals a design issue → suggest updating design.md, ask user how to proceed
-   - Task contradicts the stated intent → flag the contradiction to the user
-   - Error or blocker encountered → report what happened and wait for guidance
-   - You're unsure about a "Decision to Make" from design.md → ask the user to resolve it
+   <examples>
+   <good>
+   Working on task 3/5: Add rate-limit middleware
+
+   Reading src/middleware/index.ts — current chain: cors → helmet → bodyParser → routes
+   Installing express-rate-limit@7.1.0 (compatible with Express 4.18)
+   Added rateLimiter middleware after helmet at src/middleware/index.ts:14
+   Config: 100 req/15min window, Redis store via existing src/lib/redis.ts client
+
+   verify: `npm test -- --grep "rate-limit"` → 4 tests pass
+   verify: `curl -I localhost:3000/api/users` → X-RateLimit-Limit: 100 header present
+
+   Committed: "feat(middleware): add rate-limit middleware with Redis backing"
+   Why good: References exact files/lines, shows what was done and why,
+   runs specific verification commands, commits atomically with clear message.
+   </good>
+
+   <bad>
+   Working on task 3/5: Add rate-limit middleware
+   Done! Moving to task 4.
+   Why bad: No detail about what was implemented. No verification.
+   No commit. The user can't tell if this was done correctly.
+   </bad>
+
+   <good>
+   Working on task 2/4: Refactor auth to use JWT
+   PAUSE — design.md says "cookie-based sessions" (design.md:12) but this task
+   says "JWT". This contradicts the design.
+   Options:
+   A) Update design.md to JWT and continue (Recommended — JWT aligns with the API-first intent)
+   B) Implement cookie-based sessions as designed
+   C) Discuss the trade-offs before deciding
+   Why good: Catches a contradiction between plan and task. Stops to resolve
+   with specific options instead of silently making a decision.
+   </good>
+
+   <bad>
+   Working on task 2/4: Refactor auth to use JWT
+   Design says cookies but I'll use JWT since the task says so.
+   Why bad: Silently overrides the design without flagging the contradiction.
+   </bad>
+   </examples>
 
 6. **On completion**
 
-   When all tasks are done:
+   Report status using completion codes:
+
+   | Status | When | What to show |
+   |--------|------|-------------|
+   | DONE | All tasks completed and verified | Full summary + `/whyspec:capture` prompt |
+   | DONE_WITH_CONCERNS | Tasks done but something feels off | Summary + concerns + `/whyspec:capture` |
+   | BLOCKED | Cannot proceed without input | Blocker details + resume command |
+   | NEEDS_CONTEXT | Missing information | Specific question about what's missing |
 
    ```
-   ## Implementation Complete
+   ## DONE
 
    Change: <name>
    Progress: M/M tasks complete
 
    Completed:
-   - [x] Task 1: description
-   - [x] Task 2: description
-   ...
+   - [x] Task 1: description — committed as "feat: ..."
+   - [x] Task 2: description — committed as "feat: ..."
 
-   Ready to capture reasoning? Run /whyspec-capture
+   Ready to capture reasoning? Run /whyspec:capture
    ```
 
-   If paused before completion:
+## Tools
 
-   ```
-   ## Implementation Paused
+| Tool | When to use | When NOT to use |
+|------|------------|-----------------|
+| **Read** | Read plan files (intent.md, design.md, tasks.md) BEFORE coding | Don't skip reading the plan |
+| **Grep** | Find affected code before editing (e.g., all usages of a function you're changing) | Don't grep after editing — grep BEFORE to understand impact |
+| **Edit** | Modify existing files — prefer Edit over Write for existing code | Don't rewrite entire files when a targeted edit suffices |
+| **Write** | Create new files only | Don't use Write to modify existing files |
+| **Bash** | Run tests (`npm test`), verify (`curl`, build commands), commit (`git commit`) | Don't run destructive git commands without asking |
+| **AskUserQuestion** | When a task is unclear, or design contradicts implementation (see format below) | Don't ask about things you can determine from the plan or code |
 
-   Change: <name>
-   Progress: N/M tasks complete
+### AskUserQuestion Format (use for contradictions and blockers)
 
-   Issue: <what caused the pause>
+1. **Re-ground**: "Executing task N/M of **<change>** — `<task description>`"
+2. **The contradiction/blocker**: What you found vs what the plan says
+3. **Options with recommendation**: Lettered choices with your pick
 
-   Resume with: /whyspec-execute <name>
-   ```
+<examples>
+<good>
+Executing task 2/4 of **add-rate-limiting** — "Configure Redis store"
+
+design.md says use the existing ioredis client (src/lib/redis.ts:8), but that
+client uses `db: 0` which is shared with session data. Rate limit keys could
+collide with session keys.
+
+A) Use db: 0 with a `ratelimit:` key prefix (simple, small collision risk)
+B) Create a separate client on db: 1 (isolated, adds ~2MB memory)
+C) Reuse db: 0 but with a Redis namespace library
+
+I'd recommend B — isolation is worth 2MB.
+Why good: Specific blocker with evidence from code. Options with trade-offs.
+</good>
+</examples>
+
+## Escalation Protocol
+
+| Situation | Attempts allowed | Action |
+|-----------|-----------------|--------|
+| Task is unclear or ambiguous | 0 — ask immediately | Ask ONE specific clarification question |
+| Implementation keeps failing | 3 attempts max | Report: what was tried, what failed, what error |
+| Design contradiction found | 0 — flag immediately | Present options, let user decide |
+| Unexpected dependency or constraint | 1 attempt to resolve | If can't resolve, present findings and ask |
+
+## Rationalization Table
 
-   **Always end with the capture prompt** — the reasoning is freshest right after implementation.
+| If you catch yourself thinking... | Reality |
+|----------------------------------|---------|
+| "I'll read the plan later, the task name is clear enough" | The plan has constraints you'll violate. Read it. 15 seconds. |
+| "One big commit is fine, I'll split it later" | You won't. Atomic commits are the contract. Do it now. |
+| "This test is probably passing, no need to run it" | "Probably" is not evidence. Run the test. |
+| "I'll skip the verify step for this trivial task" | Trivial tasks have trivial verifications. Run them anyway. |
+| "The design is slightly wrong but my way is better" | Flag it. The user made the design for a reason you might not see. |
 
-**Guardrails**
+## Guardrails
 
 - **Read intent.md before coding** — every implementation decision should align with the stated intent and constraints.
 - **Never skip tasks** — work through all tasks in order. If a task seems unnecessary, ask the user to remove it rather than silently skipping.
@@ -115,4 +207,4 @@ When all tasks are done, run `/whyspec-capture` to save your reasoning.
 - **Pause on unclear tasks** — don't guess at ambiguous requirements. Ask for clarification.
 - **Pause on design issues** — if reality doesn't match the plan, stop and suggest design.md updates before continuing.
 - **Mark checkboxes immediately** — update tasks.md after each task completion, not at the end.
-- **Always prompt capture** — end every execution session (complete or paused) with the `/whyspec-capture` suggestion.
+- **Always prompt capture** — end every execution session with the `/whyspec:capture` suggestion.

package/skills/whyspec-plan/SKILL.md

@@ -1,36 +1,72 @@
 ---
 name: whyspec-plan
-description: Plan a change by declaring intent, design, and tasks before coding. Use when the user wants to plan what to build, capture decisions that need to be made, or set up the Decision Bridge before implementation.
+description: Use when planning a code change, capturing decisions before coding, or setting up the Decision Bridge.
+argument-hint: "<change-name-or-description>"
 ---
 
 Plan a change — create intent.md, design.md, and tasks.md with the Decision Bridge.
 
-When ready to implement, run `/whyspec-execute`
+When ready to implement, run `/whyspec:execute`
 
 ---
 
-**Input**: A change name (kebab-case) or description of what to build.
+**Input**: A change name (kebab-case) or description of what to build via ARGUMENTS.
 
-**Steps**
+## Iron Law
 
-1. **Ask forcing questions before anything else**
+**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.
 
-   Do NOT create any files yet. Use the **AskUserQuestion tool** to ask these questions — they shape the entire plan:
+## Red Flags — If You're Thinking This, STOP
 
-   First ask:
-   > "What problem does this solve? Who feels this pain today?"
+- "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.
 
-   Then, building on their answer:
-   > "What constraints exist? (technical limits, timeline, dependencies, things that can't change)"
+## Steps
 
-   Finally:
-   > "How will you know it works? What does success look like?"
+1. **Parse ARGUMENTS and infer intent**
 
-   If the user provides a rich description upfront that already answers these, you may condense to one clarifying question. But never skip entirely.
+   Read what the user typed. Derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
 
-2. **Create the change folder**
+   **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.
+
+   <examples>
+   <good>
+   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.
+   </good>
+
+   <bad>
+   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.
+   </bad>
 
-   Derive a kebab-case name from the user's input (e.g., "add user authentication" → `add-user-auth`).
+   <good>
+   User: `/whyspec:plan`
+   Agent: "What change are you planning?"
+   Why good: ARGUMENTS is empty. ONE question to get started is justified.
+   </good>
+
+   <bad>
+   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.
+   </bad>
+   </examples>
+
+2. **Create the change folder**
 
    ```bash
    whyspec plan --json "<name>"
@@ -42,53 +78,105 @@ When ready to implement, run `/whyspec-execute`
    - `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, use **AskUserQuestion** to ask: continue the existing change, or create a new one with a different name?
+   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)
 
-3. **Create intent.md**
+   Before writing plan files, read relevant code to understand:
+   - Current architecture in the affected area
+   - Existing patterns and conventions
+   - Dependencies and constraints
 
-   Write to `<path>/intent.md`. Populate using the user's answers to the forcing questions:
+   <examples>
+   <good>
+   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.
+   </good>
+
+   <bad>
+   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.
+   </bad>
+   </examples>
+
+4. **Create intent.md**
+
+   Write to `<path>/intent.md`. Here's a concrete filled-in example:
 
    ```markdown
    ## Why This Change Exists
 
-   [Problem statement — from forcing question 1. Be specific about who feels the pain.]
+   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
 
-   [Capabilities this unlocks. What becomes possible that wasn't before?]
+   API stability under load. Prevents abuse without blocking legitimate traffic.
 
    ## Decisions to Make
 
-   - [ ] [Decision 1: option A vs option B?]
-   - [ ] [Decision 2: approach X vs approach Y?]
-   - [ ] [Decision 3: ...]
+   - [ ] 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.
+   They will be resolved during /whyspec:capture after implementation.
 
    ## Constraints
 
-   [From forcing question 2 — technical limits, non-negotiables, dependencies]
+   - 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
 
-   [From forcing question 3 — observable outcomes, acceptance criteria]
+   - `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
 
-   [What we're assuming is true but haven't verified]
+   - 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 design choice that isn't settled yet MUST be listed here. These get resolved in the context file after implementation.
+   **IMPORTANT**: The "Decisions to Make" checkboxes are the Decision Bridge. Every unsettled design choice MUST be listed here.
+
+   <examples>
+   <good>
+   ## 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.
+   </good>
+
+   <bad>
+   ## 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.
+   </bad>
+   </examples>
 
-4. **Create design.md**
+5. **Create design.md**
 
-   Write to `<path>/design.md`:
+   Write to `<path>/design.md`. Skip the trade-off matrix for simple changes:
 
    ```markdown
    ## Approach
 
-   [Chosen technical direction — 2-3 sentences on the high-level strategy]
+   [Chosen technical direction — 2-3 sentences grounded in the actual codebase]
 
    ## Trade-off Matrix
 
@@ -104,29 +192,27 @@ When ready to implement, run `/whyspec-execute`
    ## Questions to Resolve
 
    - [ ] [Open question needing an answer before or during coding]
-   - [ ] [Another open question]
 
    ## Risks & Unknowns
 
    - [What could go wrong]
-   - [What we don't know yet]
 
    ## Dependencies
 
-   - [External libraries, APIs, services, other teams' work]
+   - [External libraries, APIs, services]
    ```
 
-5. **Create tasks.md**
+6. **Create tasks.md**
 
-   Write to `<path>/tasks.md`. **Define verification FIRST** — goal-backward planning means you know what success looks like before listing tasks:
+   Write to `<path>/tasks.md`. Define verification FIRST — goal-backward planning:
 
    ```markdown
    ## Verification
 
    What proves this change works — defined BEFORE tasks:
 
-   - [ ] [Verification criterion 1 — e.g., "all auth tests pass"]
-   - [ ] [Verification criterion 2 — e.g., "login flow works end-to-end"]
+   - [ ] [Verification criterion 1]
+   - [ ] [Verification criterion 2]
 
    ## Tasks
 
@@ -134,15 +220,11 @@ When ready to implement, run `/whyspec-execute`
      verify: [how to verify this specific task]
    - [ ] Task 2: [description]
      verify: [verification step]
-   - [ ] Task 3: [description]
-     verify: [verification step]
    ```
 
-   Each task should be small enough for one atomic commit. Include a `verify:` line where meaningful.
+   Each task should be small enough for one atomic commit.
 
-6. **Show summary**
-
-   Display:
+7. **Show summary**
 
    ```
    ## Plan Created: <name>
@@ -153,18 +235,97 @@ When ready to implement, run `/whyspec-execute`
      tasks.md     — WHAT: verification criteria + implementation checklist
 
    Decisions to make: N pending
-   Questions to resolve: N open
    Tasks: N defined
 
-   Ready to implement? Run /whyspec-execute
+   Ready to implement? Run /whyspec:execute
    ```
 
-**Guardrails**
+## 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 **<change>** in `<project>` on `<branch>`"
+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"
+
+<examples>
+<good>
+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.
+</good>
+
+<bad>
+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.
+</bad>
+</examples>
+
+## 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
 
-- **Ask forcing questions FIRST** — never create files before asking. The questions shape the plan quality.
-- **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. These are the Decision Bridge. If the user hasn't mentioned trade-offs, ask: "What decisions haven't been made yet?"
+- **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 to do.
-- **Don't over-design** — if the user describes a small fix, create proportionally small plan files. Not every change needs a full trade-off matrix.
+- **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 |