# Execution & Decomposition Patterns

Load when decomposing a plan into slices, annotating phases with execution postures, handing an approved plan off to implementation, or specifying behavior against an existing reference implementation.

## Reference Implementations

When an authorized reference implementation embodies target behavior, cite its source to preserve exact semantics and edge cases that a summary may omit. Treat it as evidence subordinate to governing requirements, not a replacement specification; existing bugs do not become requirements merely because the source contains them. Name the file or module and the behavior to match, resolve conflicts against user requirements, and plan to reimplement the *semantics* rather than copy code verbatim, including across languages. Record the pointer so the implementer reads the source: `ref: legacy/pricing.py -> reimplement the specified pricing semantics in src/pricing.ts`.

## 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

Pause and verify when completed pieces first cross an integration boundary, before an irreversible transition, and before phase closure. Run the narrowest test or user path that proves the pieces work together. This catches drift without turning task count into a ceremony trigger.

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." Record a result in `task_plan.md` only when it changes phase state or matters for recovery.

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

## Execution Handoff

When a plan-only request is complete, deliver the plan and stop. When implementation is already authorized, choose the simpler of these execution modes unless the choice materially changes cost, risk, isolation, or review quality:

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 / Validation Assignment). 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.

Ask the user to choose only when the execution-mode trade-off is material. Otherwise continue with the selected mode and keep the plan's `## Next Step` current.

# execution handoff

## Operational Patterns

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](./operational-patterns.md). Read when starting a multi-phase plan or resuming after a gap.

## Execution Posture Signals

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

## Plan Deepening

When asked to "deepen" or "strengthen" an existing plan, load [plan-deepening.md](./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 the user requested a plan only, stop after delivering the plan. When the request already authorizes implementation, continue with the simplest execution mode that fits the work. Do not infer execution approval from a prior conversation; approval carries across a session restart only when the durable plan artifact records it. Ask the user to choose between inline and delegated execution only when the choice materially changes cost, risk, isolation, or review quality. Dispatch discipline and portable task-prompt anchoring are in [execution-and-methodology.md](./execution-and-methodology.md).

## Verify

- Plan file exists at `.plan/task_plan.md` (or `docs/plans/` for formal plans)
- All tasks are verb-first and independently verifiable
- File structure and ownership are explicit where they affect integration
- Phase boundaries follow runnable capability and context safety rather than file or task counts
- 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)
- Every process item names the capability or observed defect class it gates
- Open questions contain only genuinely blocking unknowns

## Integration

- **Predecessor:** `ia-brainstorming` when requirements are ambiguous -- use an existing brainstorm spec (`docs/brainstorms/`) as input and skip idea refinement.
- **Architecture decisions:** record significant trade-offs (chosen approach, what was given up) as an ADR (`/ia-adr` in Claude Code); ADRs outlive the plan.
- **Threat modeling:** dispatch `ia-security-sentinel` in threat-model mode before implementation when the plan adds auth flows, payment handling, external API surfaces, or new trust boundaries -- architectural gaps are cheaper to fix in the plan than the code.
- **Prose quality:** `ia-writing` to humanize plan language and strip AI slop.
- **Execution handoff:** continue authorized work or ask only when the execution-mode choice is material, per *Execution Handoff* above.

# goal definition

## Core Principle

```
Context window = RAM (volatile, limited)
Filesystem     = Disk (persistent, unlimited)
→ Persist only state that would be costly to reconstruct.
```

Planning exists to reduce implementation risk and preserve necessary state. Scale it to unresolved decisions, dependency depth, and continuity needs rather than file count or tool activity alone.

## 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](./plan-format.md#plan-template), applying the quality, sizing, and task rules.
5. Run the [Verify checklist](../SKILL.md#authority-and-verification) against the finished plan.
6. Continue authorized implementation unless [Execution handoff](./execution-handoff.md#execution-handoff) identifies a material 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 verifiable without knowing the changed component's internals, 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)

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. An outcome-shaped Objective can still be a disguised mechanism -- apply the altitude test: could a reader who does not know the changed component's internals tell whether it was met? "X no longer holds the request open while it waits" fails that test; the real Objective is whatever depended on it ("checkout p95 under 300ms").

Apply a standalone-readability test as well: could a colleague who was not in this conversation state the goal from the Objective alone, without reading Scope, Key Decisions, or any later section? If the Objective only makes sense alongside later context, fold that context back into the Objective rather than leaving it to be reconstructed downstream.

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

Create a plan when it lowers implementation risk or preserves state that the current context cannot safely carry. A plan is a support artifact, not progress toward the requested capability.

- **Full plan** (`.plan/` directory): multi-phase work that crosses sessions or context limits, has interdependent decisions, or needs durable recovery state
- **Flat list** (inline checklist): clear multi-step work that fits in one session and has no durable decision record to preserve
- **Skip the plan artifact**: direct implementation with clear scope, known acceptance criteria, and no material unresolved choice

Treat file count, tool-call count, and new-feature status as signals, not triggers. Several mechanical files may need no plan, while one concurrency-sensitive file may need a written decision and verification strategy.

Stress-test apparently simple requests for hidden Key Technical Decisions (KTDs). *"Add caching to this endpoint"* hides TTL, invalidation, cache-key shape, and backend selection; record those decisions before implementation. A repository-wide rename can remain direct when it is mechanical and has an exhaustive verification command.

When skipping the plan artifact, proceed directly to implementation. Record only decisions that future work cannot re-derive cheaply, using the repository's existing decision-record convention.

# Operational Patterns

## Context Management Rules

| Situation | Action |
|-----------|--------|
| Starting new phase | Read .plan/task_plan.md (refresh goals in attention window) |
| Discovery changes the plan | Record it under the affected phase or decision in .plan/task_plan.md |
| After completing phase | Update status, verification result, and `## Next Step` in .plan/task_plan.md |
| Image/PDF evidence must survive the turn | Record only the deciding observation under the affected phase |
| Resuming after gap | Read .plan/task_plan.md, run `git diff --stat`, and reconcile actual vs planned state |
| Just wrote a file | Don't re-read it (still in context) |
| Error occurred | Log to .plan/task_plan.md, read relevant files for state |

**Cut first vs protect.**

| Cut first | Protect |
|-----------|---------|
| Failed attempts and their output, once the conclusion is recorded | The task definition and acceptance criteria |
| Verbose tool output already summarized | The active error text under investigation |
| Superseded drafts, once the current version is written | The file currently being edited |
| Exploratory reads that produced nothing | Decisions, with their reasons |

Place task-critical content last in a brief or handoff. Models attend most reliably to the start and end of a context window and least to the middle (Liu et al., 2023, "Lost in the Middle") -- keep stable rules and specs early, the active task material last.

## 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 high-risk or genuinely ambiguous plans, run one independent review against the original request and the plan. Revise only findings that expose a concrete gap. Run another review only after a material redesign. Seek approval only for unresolved choices that belong to the user.

## 5-Question Context Check

If you can answer these, your planning is solid:

| Question | Source |
|----------|--------|
| Where am I? | `## Next Step` in .plan/task_plan.md, confirmed against per-phase `Status:` |
| Where am I going? | Remaining phases |
| What's the goal? | Approach section |
| What have I learned? | Decisions and affected phase notes in .plan/task_plan.md |
| What have I done? | Phase status and verification results in .plan/task_plan.md |

## Session Continuity & Traceability

**Intermediate outputs for long sessions.** Add a numbered file under `.plan/` only when a phase produces recovery state that does not fit clearly in `task_plan.md` or the working-tree diff. Read durable state, not conversation memory, when resuming after compaction or across sessions.

**Session continuity.** At session start or after compaction: read `## Next Step` at the head of `.plan/task_plan.md`, confirm it against the per-phase `Status:` fields and the working-tree diff, then resume there. Refresh `Next Step` whenever a phase `Status` changes. Before an interruption, record the stopping point, completed verification, and any blocker that changes the next action.

**SHA recording.** When an external tracker, review boundary, or multi-session handoff needs commit traceability, note the commit SHA inline: `- [x] Task 1.1 \`abc1234\``. Skip it when version control already makes the relationship obvious.

**Deviation documentation.** Record a deviation only when it changes a preserved decision, acceptance criterion, dependency, or next action. Do not log harmless implementation discoveries that the current diff already explains.

# Plan Deepening

Load this reference when asked to deepen or strengthen an existing plan. In Claude Code, `/ia-deepen-plan` orchestrates targeted research for this workflow.

## 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 supported decisions; replace instructions contradicted by verified evidence. Keep useful superseded rationale in a separate decision-history note, not in the active execution steps.

Maintain one internally consistent current plan. Restructure only where needed to resolve a gap or contradiction, and report material decision changes.

## Enhancement format per section

When research changes a section, update its active instructions and add the relevant evidence using this structure:

```markdown
## [Original Section Title]

[Current supported instructions, with superseded steps replaced]

### Research Insights

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

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

**Implementation Details:**
```[language]
// 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:

```markdown
## 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.

# plan format

## Planning Files

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

```bash
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. The script refuses to overwrite a `task_plan.md` that still has unchecked tasks -- that is the never-overwrite gate below; pass `--force` only after deciding which plan wins. 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/task_plan.md` and adds `.plan/` to `.gitignore`.

`.plan/` files are ephemeral working state -- do not commit them; old files are overwritten when starting a new feature. Before overwriting, check the existing `task_plan.md` for unchecked tasks: same work continuing means update in place, different work over an incomplete plan means stop and ask which plan wins -- never bulk-close or silently discard another plan's open items (the same rule applies to items mirrored into an external tracker). 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` | Goal, decisions, next step, phases, discoveries that affect the plan, and errors that affect recovery | When a decision, phase state, or recovery point changes |

Do not create secondary findings or progress logs solely to prove activity. Add another planning artifact only when it carries state that `task_plan.md` cannot express clearly or when the user requested it as a deliverable.

## 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 an authorized reference implementation embodies target behavior, cite the source and plan to reimplement its *semantics*. Source reveals behavior more precisely than a summary, but does not override the user's specification or establish that existing bugs are requirements. Record a `ref:` pointer so the implementer reads the source; resolve conflicts against the governing requirements. Full guidance in [execution-and-methodology.md](./execution-and-methodology.md).

## Plan Template

```markdown
# Plan: [Feature/Task Name]

**Spec:** [optional -- path or URL to the spec/design doc this plan implements; distinct from a `ref:` pointer, which names a reference implementation to reimplement, not a spec to satisfy]

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

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

## Global Constraints
[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.]

## Key Decisions (review first)
[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.]

## File Structure
[ALL files created or modified, one-line responsibility each; locks decomposition before tasks are defined. 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] |

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

## Phase 1: [Name]
**Status**: pending | in_progress | complete
**Files**: [specific files owned by this phase]
**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]
...

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

## Open Questions
- [Only genuinely blocking unknowns]
```

### Plan Quality Rules

**Keep phase state current.** Changing a phase's `Status` also refreshes `## Next Step`. That one line is what the resume protocol reads after a compaction or a new session, so a stale `Next Step` 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 `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.

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

**Keep the deliverable ahead of the apparatus.** Every process or operations item names the capability or observed defect class it gates. Stop adding checks, matrices, or plan structure when the existing machinery is sufficient to keep implementation honest. Record deferred rigor as debt rather than building it speculatively.

**Do not edit the target down to the implementation.** A plan or specification change needs independent product or technical justification. A weaker acceptance criterion is not a fix for code that fails the original one.

**Keep closures vertical.** Internal plan steps may isolate one action, but a closable phase or external work item includes its implementation and tests and ends in runnable behavior. Do not turn types, implementation, tests, and documentation for one capability into separate completion credits.

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

# task design

## Phase Sizing Rules

Every phase must be **context-safe**:

- End in one coherent, independently verifiable capability or integration state.
- Fit in the available context, or record a clear recovery boundary before compaction or handoff.
- Name dependencies whose failure would block the phase.
- Split only when each part has a meaningful verification boundary; do not split to meet a file, task, or duration target.
- Never state hour, day, or week estimates in a plan; an agent has no wall-clock experience, so such figures are confabulated. Size by dependency count, verification steps, and a relative Small/Medium/Large label instead.
- Challenge scope when nonlocal invariants, ownership overlap, or integration dependencies make independent delivery unlikely.

## Task Decomposition

Decompose by user-visible capability (vertical slices), not by technical layer, so each phase is independently demonstrable. Checkpoint where components first integrate, before an irreversible transition, and before phase closure. Full guidance -- vertical slicing and the checkpoint system -- in [execution-and-methodology.md](./execution-and-methodology.md).

## Decision Authority

Not every decision needs user input. Apply the following division within existing user choices, repository constraints, and authorized scope; technical work can still require a material user decision:

**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

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

Ask only about decisions that fall in the "user decides" category above. Batch the material unknowns, and make reasonable assumptions for everything else. Do not manufacture a question count from task size.

## Task Rules

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.

- **Atomic**: one independently verifiable action. Internal steps may separate test setup from implementation, but they do not become separately closable work items.
- **Verb-first**: "Add...", "Create...", "Refactor...", "Verify..."
- **Concrete**: name specific files, endpoints, components, and verification. Include code patterns or line-level anchors only when they preserve a decision the implementer could not recover cheaply.
- **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.

#!/usr/bin/env bash
# init-plan.sh — Scaffold a durable task plan
# Usage: bash init-plan.sh [task-name] [--force]
#
# Creates .plan/task_plan.md
# Adds .plan/ to .gitignore if not present
# Refuses to overwrite a task_plan.md that still has unchecked tasks
# unless --force is given.

set -euo pipefail

PLAN_DIR=".plan"
FORCE=0
TASK_NAME="Unnamed Task"
for arg in "$@"; do
    case "$arg" in
        --force) FORCE=1 ;;
        *) TASK_NAME="$arg" ;;
    esac
done
DATE=$(date +%Y-%m-%d)

# Guard: an existing plan with unchecked tasks is live work in progress.
if [ "$FORCE" -ne 1 ] && [ -f "$PLAN_DIR/task_plan.md" ] && grep -q '^\s*- \[ \]' "$PLAN_DIR/task_plan.md"; then
    echo "ERROR: $PLAN_DIR/task_plan.md has unchecked tasks." >&2
    echo "Same work continuing: update it in place. Different work: confirm which plan wins, then re-run with --force." >&2
    exit 1
fi

# Create directory
mkdir -p "$PLAN_DIR"

# Add to .gitignore if not present
if [ -f .gitignore ]; then
    grep -qxF '.plan/' .gitignore 2>/dev/null || echo '.plan/' >> .gitignore
else
    echo '.plan/' > .gitignore
fi

# task_plan.md
cat > "$PLAN_DIR/task_plan.md" << EOF
# Plan: ${TASK_NAME}

**Created:** ${DATE}

## Approach

[1-3 sentences: what and why]

## Scope

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

## Next Step

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

## Phase 1: [Name]

**Status**: pending
**Files**: [specific files owned by this phase]

**Tasks**:
- [ ] [Verb-first atomic task]

**Verify**: [specific test command or assertion]
**Exit**: [clear done definition]

## Open Questions

- [Only genuinely blocking unknowns]

## Error Log

| Attempt | What Failed | Why | Next Action |
|---------|-------------|-----|-------------|
EOF

echo "Created ${PLAN_DIR}/ with:"
echo "  - task_plan.md"
echo "Added .plan/ to .gitignore"