Planning

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.

Goal Quality Gate

Run this gate before reaching for When to Plan below — a weak goal makes either path (full plan, flat list, or skip) waste tokens. Confirm the goal is measurable; a weak goal produces a weak plan and an unverifiable skip. Answer these five questions before proceeding:

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)

Repair weak goals before continuing. Reject pure-activity goals ("make progress", "keep investigating", "improve things") -- rewrite 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 -- e.g., "fix typo in README line 47", "rename oldFn to newFn across the repo", "bump lodash to 4.17.21". 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 needed -- write a numbered task list in the conversation or a single progress.md, skip .plan/ scaffolding

Skip planning only when ALL of these hold:

• The work is atomic — fits in one commit, no meaningful unit boundaries to break out independently
• There are no design choices that constrain implementation — no Key Technical Decisions worth recording. If the work needs the implementer to choose between two approaches, those are KTDs and a plan is warranted
• There are no scope boundaries worth pinning in writing — the work scope is self-evident from the user's request
• No upstream artifact (a brainstorm, an incident report, a deferred-follow-up item from a prior plan) needs traceability through this plan

Stress test the "looks atomic" case. Many requests look atomic at first glance 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.
• "Migrate from package A to package B" — sounds mechanical, but semantic differences between the packages create migration KTDs. Write the plan.
• "Add rate limiting" — sounds small, but algorithm, scope, and configurability are all KTDs. Write the plan.

vs. genuine skip cases:

• "Fix typo in README line 47" — atomic, no KTDs, skip the plan.
• "Rename `oldFn` to `newFn` across the repo" — mechanical, no design choices, skip.
• "Bump dependency X to v2.3.1" — mechanical, skip (unless breaking changes warrant unit-by-unit migration).

When skipping the plan doc, work proceeds directly to /ia-work 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:

bash init-plan.sh "Feature Name"

This creates .plan/ with task_plan.md, findings.md, and progress.md -- each pre-populated with the correct structure. Also adds .plan/ to .gitignore.

Planning files are ephemeral working state -- do not commit them. When starting a new feature, old .plan/ files are overwritten. Within a multi-phase feature, use numbered intermediate files (01-setup.md, 02-phase1-complete.md) to preserve state across phases.

Note: .plan/ is for ephemeral working state during implementation (scratch notes, progress tracking). docs/plans/ is for the formal plan document produced by a structured planning workflow (committed, living documents). Both coexist -- .plan/ supports the work session, docs/plans/ stores the committed plan.

Test Discovery (Existing Projects)

For projects with existing code (not greenfield), discover the test landscape before planning:

1. Search for test/spec files related to the feature area: Glob("**/*test*") and Grep("<feature-keyword>", glob="**/*.{ts,php,py}") 2. Check test config for the canonical test command (package.json scripts, pytest.ini, phpunit.xml, CI config) 3. Note which modules have coverage and which don't -- plan should extend existing test patterns, not introduce new frameworks

Skip for greenfield projects where no tests exist yet.

Plan Template

# Plan: [Feature/Task Name]

## Approach
[1-3 sentences: what and why]

## Scope
- **In**: [what's included]
- **Out**: [what's explicitly excluded]

## Global Constraints
[Spec-wide requirements that bind every phase -- version floors, naming/format rules, platform limits, security or compatibility invariants. Copy exact values verbatim from the spec; do not paraphrase. Omit the section only when the work has no project-wide constraint. Each task implicitly inherits these.]

## File Structure
[Map ALL files that will be created or modified, with one-line responsibility for each. Lock in decomposition decisions before defining tasks. Write for a zero-context engineer.]

| File | Action | Responsibility |
|------|--------|---------------|
| `path/to/file.ts` | Create | [what this file does] |
| `path/to/existing.ts` | Modify | [what changes and why] |

## Phase 1: [Name]
**Files**: [specific files, max 5-8 per phase]
**Posture**: [test-first | characterization-first | external-delegate]
**Tasks**:
- [ ] [Verb-first atomic task] -- `path/to/file.ts`
- [ ] [Next task]
**Verify**: [specific test: "POST /api/users → 201", not "test feature"]
**Exit**: [clear done definition]

## Phase 2: [Name]
...

## Execution Posture
- [Optional per-phase signals that shape implementation sequencing]
  - `test-first`: write failing test before implementation
  - `characterization-first`: capture existing behavior before changing it
  - `external-delegate`: mark units suitable for parallel/external execution

## Deferred to Implementation
- [Things intentionally left unspecified -- details that depend on what you find in the code]

## Open Questions
- [Max 3, only truly blocking unknowns]

Plan Quality Rules

No placeholders in tasks. Every task must contain actual code patterns, commands, or file paths -- not vague directives. Forbid: "TBD", "TODO", "handle errors appropriately", "add validation", "implement as needed", "similar to above", "Similar to Task N", "See above." Each task must be self-contained -- repeat the spec, code pattern, or file path in every task that needs it. The implementer may read tasks out of order, and vague tasks produce vague implementations. If a step cannot be specified concretely, it needs further breakdown before it belongs in a plan.

Type-consistency check. After writing all tasks, scan for naming drift. If Task 3 says clearLayers() but Task 7 says clearFullLayers(), that's a bug in the plan. Function names, variable names, and file paths must be consistent across all tasks.

Numbered outputs for long sessions. For multi-phase implementations, write numbered intermediate files to .plan/ (e.g., 01-setup.md, 02-phase1-complete.md) so state survives context compaction. Read from files, not conversation memory, when resuming work after compaction or across sessions.

Session continuity. At session start or after compaction: read .plan/progress.md → check which tasks are complete → review the current phase. At session end: update progress with what was done, note blockers, commit in-progress work. Mark interrupted tasks with a stopping-point note so the next session resumes without re-discovery.

SHA recording. When a task completes and is committed, note the commit SHA inline: - [x] Task 1.1 \abc1234\``. Creates traceability from plan to code.

Deviation documentation. When the implementation deviates from the plan, document why inline: **Deviation**: [what changed and why] under the affected task. Silent deviation breaks trust -- the orchestrator assumes the plan was followed.

No gold-plating. Build exactly what the spec requires. If a feature, enhancement, or "nice-to-have" isn't in the requirements, don't add it. Quote the exact spec requirements in the plan and flag any additions explicitly as scope expansion needing approval. Basic first implementations are acceptable -- most need 2-3 revision cycles anyway.

Phase Sizing Rules

Every phase must be context-safe:

• Max 5-8 files touched
• Max 2 dependencies on other phases
• No single task exceeds ~2 hours of focused work -- if it would, split further
• Fits in one focused session for a developer without external blockers
• If a phase violates these → split it
• Scope challenge: if the overall plan touches 8+ files or introduces 2+ new classes/services, challenge the scope. Ask: can this be split into smaller, independently shippable increments?

Task Decomposition

Vertical slicing

Decompose by user-visible capability, not by technical layer. "User can log in" is a vertical slice -- it touches UI, API, and DB, and delivers a working feature when done. "Build the auth database schema" is a horizontal slice that delivers zero value until other slices complete.

Vertical slices are independently demonstrable and testable. Each slice should produce something a stakeholder can see, try, or verify. When a phase in a plan delivers only one layer (all models, all controllers, all views), restructure it into slices that cut through all layers for one capability at a time.

Checkpoint system

After every 2-3 completed tasks, pause and verify: are the completed pieces actually working together? Run tests, check integration points, confirm that data flows end-to-end. This catches drift early instead of discovering at the end that pieces don't fit.

Checkpoints are lightweight -- run the test suite, hit the endpoint, render the component. Not a formal review. The goal is a fast feedback signal: "everything built so far integrates correctly." Document checkpoint results in .plan/progress.md.

Decision Authority

Not every decision needs user input. Apply this principle:

Claude decides (technical implementation): language, framework, architecture, libraries, file structure, naming conventions, test strategy, error handling approach, database schema details, API design patterns. Make the call, document the rationale in the plan.

User decides (experience-affecting): scope tradeoffs ("cut X to hit deadline?"), UX choices that change what users see or do, data model decisions that constrain future product options, anything where two valid paths lead to meaningfully different user outcomes.

Heuristic: If the decision changes what the user experiences, ask. If it changes how the code works, decide.

Clarifying Questions

Scale to complexity:

• Small task: 0-1 questions, assume reasonable defaults
• Medium feature: 1-2 questions on critical unknowns
• Large project: 3-5 questions (auth, data model, integrations, scope)

Only ask about decisions that fall in the "user decides" category above. Make reasonable assumptions for everything else.

Task Rules

Write every task as if the implementer has zero context and questionable taste. They cannot infer intent from conversation history -- everything must be in the plan.

• Atomic: one action, 2-5 minutes to complete. "Write the failing test" is a step. "Implement the feature" is not.
• Verb-first: "Add...", "Create...", "Refactor...", "Verify..."
• Concrete: name specific files, endpoints, components. Include exact commands with expected output, code snippets (not "add validation"), and file paths with line ranges for modifications.
• Ordered: respect dependencies, sequential when needed
• Verifiable: include at least one validation task per phase
• Complete: do not defer test coverage, skip edge cases, or omit error handling to save time. The marginal cost of completeness during initial implementation is near-zero compared to retrofitting later.

Operational Patterns

Context management rules, error protocol (3-attempt escalation), iterative plan refinement, and the 5-question context check are in operational-patterns.md. Read when starting a multi-phase plan or resuming after a gap.

Execution Posture Signals

Plans can carry lightweight metadata per phase that shapes how /ia-work sequences implementation. These are optional annotations, not requirements.

Default: tests-after — /ia-work writes tests alongside implementation for new features. No posture signal needed in this case.

Opt-in postures for phases that need different sequencing:

• test-first: Write failing tests before implementation. Use when behavior is well-defined and testable upfront (bug fixes always qualify; new features qualify when the contract is clear before coding).
• characterization-first: Capture existing behavior with tests before changing it. Use when modifying code without existing test coverage.
• external-delegate: Mark self-contained units suitable for parallel execution (separate worktree, separate agent). Use when a phase has no dependencies on other phases.

Add posture signals in the phase header: ## Phase 2: Auth middleware [test-first]. The executor inherits these silently without interrupting questions — they shape sequencing, not scope.

Plan Deepening

When asked to "deepen" or "strengthen" an existing plan, load plan-deepening.md — targeted research workflow (additive, not restructuring), per-section enhancement format, and Enhancement Summary block at the plan head. Orchestrated by the /ia-deepen-plan command.

Execution Handoff

When a plan is complete and ready to execute, offer the user an explicit choice rather than drifting into implementation. Present two options:

1. Subagent-driven (recommended for multi-phase plans, independent slices, or worktree-isolated work): dispatch each phase to a focused subagent with a self-contained task prompt (Objective / Owned Files / Interface Contracts / Acceptance Criteria / Out of Scope). Orchestrator integrates results and verifies between phases. See ia-orchestrating-swarms for dispatch discipline. Anchor each task prompt portably -- repo/package names, public symbols, command names, config keys, branch and PR/issue references, exact error text, and relative file paths (not absolute, which vary across working directories) -- so a fresh agent starting in a different working directory can resolve every reference. 2. Inline execution: main session runs the plan phase by phase. Use when phases are tightly coupled, require shared context that would be expensive to rehydrate, or the total work fits in one session without compaction risk.

State the recommendation with a one-sentence reason, then wait for the user to pick. Do not auto-start either path — drifting from "plan approved" to "plan in progress" without the user picking a handoff mode is how orchestration discipline silently decays.

Verify

• Plan file exists at .plan/task_plan.md (or docs/plans/ for formal plans)
• All tasks are verb-first and atomic (2-5 minutes each)
• File structure table is complete with action and responsibility columns
• Phase sizing respects 5-8 file limit
• No placeholder tasks ("implement feature", "add tests") -- every task names specific files and patterns
• Each phase delivers end-to-end functionality (not a single horizontal layer)
• Open questions limited to 3 or fewer genuinely blocking unknowns

Integration

• This skill is methodology (file persistence, phase sizing, context management). For full feature plans, the structured planning workflow handles research agents, issue templates, and formal output to docs/plans/. Apply this skill's principles whenever planning is required; reach for the full workflow when the task spans multiple files or requires architectural decisions.
• Architecture decisions: when the plan involves significant trade-offs (choosing between approaches, accepting constraints), use /ia-adr to document the decision and what was given up. ADRs outlive the plan.
• Threat modeling: when the plan introduces auth flows, payment handling, external API surfaces, or new trust boundaries, dispatch the ia-security-sentinel agent in threat-model mode before implementation. Architectural security gaps are cheaper to fix in the plan than in the code.
• Predecessor: ia-brainstorming -- use first when requirements are ambiguous. When a brainstorm spec exists (docs/brainstorms/), use it as input and skip idea refinement
• Prose quality: ia-writing -- use to humanize plan language and remove AI slop from plan documents
• Execution handoff: after the plan is approved, proceed to /ia-work or execute inline

Operational Patterns

Context Management Rules

Error Protocol

ATTEMPT 1: Diagnose root cause -> targeted fix
ATTEMPT 2: Different approach (different tool, library, method)
ATTEMPT 3: Question assumptions -> search for solutions -> update plan
AFTER 3 FAILURES: Escalate to user with what you tried

Never repeat the exact same failing action. Track attempts, mutate approach.

Iterative Refinement

For complex projects, iterate on the plan before implementing: 1. Draft initial plan 2. Dispatch a plan-reviewer subagent with the plan document and original spec (not session history) to evaluate completeness, feasibility, and gaps 3. Fix issues found, re-dispatch reviewer if needed (max 3 iterations) 4. Present to user for final approval before implementation

5-Question Context Check

If you can answer these, your planning is solid:

Plan Deepening

Load this reference when asked to "deepen" or "strengthen" an existing plan. The /ia-deepen-plan command orchestrates this workflow with parallel research agents per section.

Workflow

When asked to deepen a plan, don't re-run the full planning workflow. Instead:

1. Read the existing plan file 2. Identify phases or tasks that are vague, under-specified, or missing verification steps 3. For each weak area, run targeted research (read relevant code, check existing patterns, verify assumptions) 4. Expand the weak sections with concrete file paths, code patterns, and verification steps 5. Preserve everything that's already specific enough

Deepening is additive — it fills gaps without restructuring what already works.

Enhancement format per section

When a section is deepened by research agents, append the findings using this structure (preserve the original section content above it):

## [Original Section Title]

[Original content preserved verbatim]

### Research Insights

**Best Practices:**
- [Concrete recommendation with rationale]

**Performance Considerations:**
- [Optimization opportunity or benchmark to target]

**Implementation Details:**

// Concrete code example from research

**Edge Cases:**
- [Edge case and handling strategy]

**References:**
- [Documentation URL]

Enhancement summary block

At the top of the deepened plan, add a summary so reviewers can see what changed without diffing:

## Enhancement Summary

**Deepened on:** [Date]
**Sections enhanced:** [Count]
**Research agents used:** [List]

### Key Improvements
1. [Major improvement]

### New Considerations Discovered
- [Important finding]

Both blocks are owned by this skill — commands that orchestrate deepening (e.g., /ia-deepen-plan) delegate format decisions here rather than restating the templates.

ia-planning Specification

Intent

ia-planning is a workflow-class skill (a multi-step process producing concrete artifacts). Software implementation planning with file-based persistence (.plan/). Use when asked to plan, break down a feature, or when a task touches 3+ files, has ambiguous scope, or requires architectural decisions. Skip for typos, single-file fixes, and obvious one-shots.

Scope

In scope:

• Behaviors described in SKILL.md and routed via the should_trigger phrasings in distillery/tests/fixtures/triggers/ia-planning.jsonl.
• Updates to runtime behavior, structure, trigger precision, references, and validation.

Out of scope:

• Acting as the runtime instructions themselves (those live in SKILL.md).
• Trigger phrasings already covered by adjacent ia-* skills (validate-plugin flags >70% description overlap as DUPLICATE_TRIGGER).
• <!-- to fill in: domain-specific exclusions when the skill drifts -->

Trigger Context

• Class: workflow
• Hook regex: plugins/whetstone/hooks/skill-patterns.sh -> SKILL_PATTERNS[ia-planning]
• Common requests (from fixture should_trigger):
• "plan the implementation of the search feature"
• "break down this feature into tasks"
• "create a plan for the database migration"
• Should not trigger for (from fixture should_not_trigger):
• "debug why the tests are failing"
• "review the code in this PR"
• "add a new endpoint for user profiles"

Source And Evidence Model

Authoritative sources:

• SKILL.md -- runtime instructions and reference routing.
• references/*.md -- bundled supplementary content (2 file(s)).
• distillery/tests/fixtures/triggers/ia-planning.jsonl -- positive and negative trigger phrasings under regression test.
• plugins/whetstone/hooks/skill-patterns.sh -- regex pattern that fires this skill.
• distillery/.eval-data/ia-planning/ -- harvested session examples (when present).

Data that must not be stored in this skill or its references:

• Secrets, credentials, tokens.
• Machine-specific filesystem paths (/home/..., /Users/..., ~/ai/...). The validator (MACHINE_PATH_LEAK) flags these as HIGH.
• Private URLs, customer data, or unredacted personal information.

Coverage matrix

Evaluation

Lightweight (run on every change):

python3 distillery/scripts/distiller.py validate-plugin --component ia-planning
python3 distillery/scripts/distiller.py test-triggers --skill ia-planning

Deeper (when behavior risk warrants):

python3 distillery/scripts/distiller.py dspy-eval ia-planning
python3 distillery/scripts/distiller.py diagnose-negatives ia-planning

Acceptance gates:

• validate-plugin --component ia-planning returns 0 HIGH findings.
• test-triggers --skill ia-planning returns F1 = 1.0 with floors of 5 should_trigger and 5 should_not_trigger.
• For dspy-eval, the composite score does not regress against the most recent saved baseline (see distillery/.eval-data/ia-planning/history.json).

Known Limitations

<!-- to fill in over time as drift surfaces. Default rule: any time diagnose-negatives surfaces a recurring failure pattern, document it here so future maintainers understand the trade-off the current implementation accepts. -->

Maintenance Notes

• Update SKILL.md when the runtime workflow, branch conditions, or output contract changes.
• Update this SPEC.md when intent, scope, evidence model, evaluation gates, or maintenance expectations change.
• Update the trigger fixture when adding new positive phrasings, removing stale ones, or expanding scope (the 5/5 floor is a hard validator gate).
• Update the hook regex in skill-patterns.sh whenever fixture positives expose a missed phrasing; verify F1 = 1.0 with eval-triggers before committing.
• Run the full release pipeline via /release -- never bump versions or update CHANGELOG.md from a per-skill edit.