/ia-planning

name: ia-planning
class: workflow
description: >-
  Software implementation planning with file-based persistence (.plan/). Use
  when planning code changes touching 3+ files or with ambiguous scope. Skip
  for typos, single-file fixes, and research/scanning/audit work that
  produces reports rather than code.

Planning

Core Principle

Context window = RAM (volatile, limited)
Filesystem     = Disk (persistent, unlimited)
→ Anything important gets written to disk.

Planning tokens are cheaper than implementation tokens. Front-load thinking; scale effort to complexity.

Procedure

1. Run the *Goal Quality Gate* on the stated goal. 2. Pick the path per *When to Plan*: full plan, flat list, or skip. 3. For a full plan, scaffold `.plan/` via [init-plan.sh](./scripts/init-plan.sh). 4. Write the plan per the *Plan Template*, applying the quality, sizing, and task rules. 5. Run the *Verify* checklist against the finished plan. 6. Offer the *Execution Handoff* choice.

Goal Quality Gate

Run this gate before *When to Plan* below — a weak goal wastes tokens on any path and produces an unverifiable result. Answer these five questions first:

1. **What concrete thing will be true when this is done?** (named artifact, system state, or user-visible behavior — not "improve X" or "investigate Y") 2. **What evidence will prove it?** (specific test, command, screenshot, metric — not "looks right") 3. **What quantitative or binary threshold defines success?** (p95 < 250ms; `npm run test:checkout` passes; `gh pr view 123` shows no unresolved threads) 4. **What scope boundaries matter?** (which files/modules/environments are in scope; which are explicitly not) 5. **What should cause the agent to stop and ask?** (which decisions belong to the user, not Claude)

Reject pure-activity goals ("make progress", "keep investigating", "improve things") -- repair them into a verifiable outcome or ask one concise clarification before planning. Skip this gate only when the request already names a specific artifact AND a clear success signal in the user's own words -- the same choice-free cases listed under *When to Plan* below. Anything vaguer than that runs the gate.

When to Plan

**Bias toward producing a plan.** A thin plan for small work is mild ceremony; skipping a plan when one was warranted costs real time (reinvented decisions, lost unit boundaries, no IDed requirements to verify against). When unsure, write the plan.

• **Full plan** (.plan/ directory): multi-file changes, new features, refactors, >5 tool calls
• **Flat list** (inline checklist): 3-5 file changes, clear scope, no research -- a numbered task list in the conversation or a single progress.md, no .plan/ scaffolding

**Skip planning only when ALL of these hold:** the work is **atomic** (one commit, no unit boundaries worth breaking out); there are **no KTDs** (Key Technical Decisions: choices between approaches; each KTD becomes a *Key Decisions* entry in the plan -- if one exists, plan); the **scope is self-evident** from the request, with no boundaries worth pinning in writing; and **no upstream artifact** (brainstorm, incident report, deferred follow-up) needs traceability through this plan.

**Stress test the "looks atomic" case.** Many requests look atomic but hide design decisions. *"Add caching to this endpoint"* sounds atomic, but TTL, invalidation, cache-key shape, and backend selection are all KTDs -- write the plan. The same trap hides in "migrate package A to B" and "add rate limiting". Genuine skips are choice-free: *"fix typo in README line 47"*, *"rename `oldFn` to `newFn` across the repo"*, *"bump lodash to 4.17.21"* (unless breaking changes warrant a unit-by-unit migration).

When skipping the plan doc, work proceeds directly to execution (`/ia-work` in Claude Code) or to implementation, and any decisions made along the way land in the commit message or `docs/solutions/` if worth carrying forward.

Planning Files

Scaffold the `.plan/` directory with pre-populated templates using [init-plan.sh](./scripts/init-plan.sh):

SKILL_DIR="<absolute path of the directory containing this SKILL.md>"
bash "$SKILL_DIR/scripts/init-plan.sh" "Feature Name"

Substitute the real absolute path before running; never execute the command with the angle-bracket placeholder. Anchor the call to `SKILL_DIR` rather than a bare `init-plan.sh` — a relative path resolves against the caller's working directory, not the skill, and breaks from a subdirectory or under a non-Claude harness.

This creates `.plan/` with the three pre-populated files below and adds `.plan/` to `.gitignore`.

`.plan/` files are ephemeral working state -- do not commit them; old files are overwritten when starting a new feature. Within a multi-phase feature, use numbered intermediate files (`01-setup.md`, `02-phase1-complete.md`) to preserve state across phases. `docs/plans/` is the separate, committed home for a formal plan document; `.plan/` supports the work session.

| File | Purpose | Update When | |------|---------|-------------| | `.plan/task_plan.md` | Phases, tasks, decisions, errors | After each phase | | `.plan/findings.md` | Research, discoveries, code analysis | After any discovery | | `.plan/progress.md` | Session log, test results, files changed | Throughout session |

Test Discovery (Existing Projects)

For existing code, discover the test landscape before planning: find related test/spec files (`Glob("**/*test*")`, `Grep`), read the canonical test command from config (`package.json` scripts, `pytest.ini`, `phpunit.xml`, CI), and note coverage gaps -- the plan should extend existing test patterns, not introduce new frameworks. Skip for greenfield projects with no tests yet.

Reference Implementations

When target behavior is hard to describe but an existing implementation embodies it, cite that source as the spec and plan to reimplement its *semantics* -- source code is higher-fidelity than prose, docs, or screenshots. R