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.

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:

Then apply the Means test to the answer to question 1: if the implementation changed, would this still be the goal? If not, what was named is a Means, not the Objective. A request that supplies only an approach ("move the retry logic out of the controller into a job") passes all five questions while anchoring the plan to a mechanism -- and when the mechanism turns out wrong there is nothing left to re-derive the plan from. Recover the Objective from why the approach was proposed, keep the approach as the current best route, and record it as a decision rather than as the goal.

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.

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.

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 ( in Claude Code) or to implementation, and any decisions made along the way land in the commit message or if worth carrying forward.

Scaffold the directory with pre-populated templates using 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 rather than a bare — 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 with the three pre-populated files below and adds to .

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 (, ) to preserve state across phases. is the separate, committed home for a formal plan document; supports the work session.

.plan/task_plan.md

.plan/findings.md

.plan/progress.md

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

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. Record a pointer in the plan so the implementer reads the source, not a summary. Full guidance in execution-and-methodology.md.

[1-3 sentences: what and why]

[Binds every phase: version floors; naming/format rules; platform limits; security/compatibility invariants. Exact spec values verbatim, never paraphrased. Every task inherits these. Omit if none.]

[Decisions likeliest to change on review: data model shapes; new type/interface contracts; user-facing or UX flows. Per decision: choice, discarded alternative, one-line why. Listed first so review redirects design before mechanical work is planned around it; mechanical refactoring stays in the phases. Omit if no non-obvious choice was made.]

[ALL files created or modified, one-line responsibility each; locks decomposition before tasks are defined. Write for a zero-context engineer.]

path/to/file.ts

path/to/existing.ts

[one line: the phase and task to resume on]

Status: pending | in_progress | complete Files: [specific files, max 5-8 per phase] Posture: [test-first | characterization-first | external-delegate] Tasks:

...

Keep phase state current. Changing a phase's also refreshes . That one line is what the resume protocol reads after a compaction or a new session, so a stale is worse than none -- it resumes work that already happened.

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

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

No gold-plating. Build exactly what the spec requires -- no features or "nice-to-haves" beyond 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.

Front-load high-variance decisions. Order the plan document by how likely each part is to change on review, not by execution order -- the template's Key Decisions bracket defines what goes there; execution order still governs the phases themselves.

Every phase must be context-safe:

Decompose by user-visible capability (vertical slices), not by technical layer, so each phase is independently demonstrable. Checkpoint every 2-3 tasks to catch integration drift early. Full guidance -- vertical slicing and the checkpoint system -- in execution-and-methodology.md.

Not every decision needs user input:

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.

Ask via AskUserQuestion (Claude Code; load with ToolSearch if not loaded) or request_user_input (Codex); fall back to numbered options in chat.

Scale to complexity:

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

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

Context management rules, error protocol (3-attempt escalation), iterative plan refinement, the 5-question context check, and session-continuity/traceability conventions (numbered outputs, resume protocol, SHA and deviation notes) are in operational-patterns.md. Read when starting a multi-phase plan or resuming after a gap.

Phases can carry optional metadata that shapes how sequences implementation. Default is tests-after; opt in per phase via the header (): (write failing test before implementation), (capture existing behavior before changing it), (mark units suitable for parallel/external execution). When to use each is in execution-and-methodology.md.

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 command.

When a plan is complete, offer the user an explicit choice -- subagent-driven (dispatch each phase to a focused agent) or inline execution -- rather than drifting into implementation. State a one-sentence recommendation, then present the choice via the same ask mechanism as Clarifying Questions and wait for the user to pick; do not auto-start either path. Dispatch discipline and portable task-prompt anchoring are in execution-and-methodology.md.