Writing plans

Writing Plans

Overview

Write comprehensive implementation plans assuming the engineer has zero context for the codebase. Document everything: which files to touch, code, testing, how to verify. Give bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.

Assume the engineer is skilled but knows almost nothing about the project's toolset or problem domain.

Announce at start: "Using ecw:writing-plans to create the implementation plan."

Plan Mode — Do Not Use

Do NOT call EnterPlanMode or ExitPlanMode. This skill writes plans directly to .claude/plans/ via the Write tool. Claude Code's built-in plan mode is a separate mechanism not used by ECW. After writing the plan file, use AskUserQuestion to confirm with the user.

Risk-Aware Detail Level

Read .claude/ecw/session-data/{workflow-id}/session-state.json for risk level and affected domains. If unavailable (standalone invocation), default to P0 (full detail mode).

Risk Level	Plan Detail	Task Granularity
P0	Full steps with test code + verification commands + rollback notes	2-5 min per step, no merging
P1	Full steps with test code + verification commands	2-5 min per step, no merging
P2	Simplified steps, can merge single-file + no-branch-logic tasks	5-10 min per step
P3	Minimal outline (typically no formal plan needed)	—

Task merging rule (P2 only): See workflow-routes.yml impl_strategy section.

Domain Context Injection

Note: When Subagent Dispatch is active (≥ 2 domains or ≥ 3 knowledge files), these steps are executed inside the subagent, not by the coordinator. The coordinator only passes file paths.

Before writing the plan:

1. Read .claude/ecw/routing/path-mappings.md to understand code path → domain mappings
2. For each affected domain, read its business-rules.md to understand constraints (state machines, validation rules, concurrency controls)
3. If knowledge-summary.md exists (from domain-collab), read it for cross-domain dependency context

Knowledge file robustness: Verify each file exists before reading. If path-mappings.md is missing, skip domain context injection and note [Warning: path mappings not found, plan lacks domain-aware file grouping] in plan header. If a domain's business-rules.md is missing, note [Warning: {domain} business-rules.md not found, domain constraints may be incomplete] in the affected Tasks. Continue plan generation with available data.

Ensure design decisions respect domain rules. A plan that violates a state machine constraint or concurrency rule will fail at impl-verify.

Subagent Dispatch Architecture

When the Plan generation workload is significant, delegate to a subagent to keep the coordinator context lean.

Trigger Condition

Subagent dispatch activates when either condition is met:

• Affected domains ≥ 2 (cross-domain requirement)
• Knowledge files to read ≥ 3 (ecw-path-mappings + business-rules per domain + knowledge-summary, etc.)

When both conditions are false (single domain AND knowledge files < 3), use Direct mode — current behavior unchanged, no subagent overhead.

Coordinator Responsibilities (lightweight)

Coordinator constructs the subagent prompt with the following inputs — does not read knowledge file contents itself:

1. Requirement summary path: requirements-summary.md or domain-collab-report.md (subagent reads the file)
2. Knowledge file path list:
   • .claude/ecw/routing/path-mappings.md
   • .claude/knowledge/{domain}/business-rules.md (one per affected domain)
   • .claude/ecw/session-data/{workflow-id}/knowledge-summary.md (if exists)
3. Plan output target path: .claude/plans/{feature}.md
4. Risk level + Plan detail requirements: From session-state.json (P0/P1/P2 detail table in "Risk-Aware Detail Level" section)

Subagent Responsibilities

Source code reading limits (prevent timeout): Read at most 10 source files total. For each file, prefer Grep with limited context (-A 5) over full Read. Only Read full files for core interfaces or classes that directly participate in the change. Do NOT read complete implementations of large service classes — read class signatures and method signatures only.

The subagent executes the full Plan generation pipeline in its own context:

1. Read all knowledge files from the paths provided by coordinator
2. Execute Domain Context Injection (code path mappings, business rules, cross-domain dependencies)
3. Execute Scope Check (suggest splitting if multiple independent subsystems)
4. Execute Design Completeness Check (resolve open design questions via AskUserQuestion)
5. Execute Self-Review (spec coverage, placeholder scan, type consistency, TDD readiness)
6. Generate the complete Plan and Write it to .claude/plans/{feature}.md
7. Return to coordinator: Plan summary (≤ 500 tokens) containing:
   • Total Task count
   • One-sentence description per Task
   • Full list of files to create/modify
   • Implementation Strategy (see workflow-routes.yml impl_strategy section for full rules)

Coordinator Post-Processing

After receiving the subagent's summary:

1. Update session-state.json with Plan summary and implementation strategy (via update_status_fields)
2. Display summary to user for confirmation

Model

model: opus (default from models.defaults.planning; configurable via ecw.yml) — Plan quality drives all downstream implementation; a flawed plan causes cascading rework across TDD, implementation, and verification phases.

Timeout (dynamic): Scale timeout by estimated Task count — ≤5 Tasks: 180s, 6–10 Tasks: 300s, >10 Tasks: 420s. Estimate Task count before dispatch from requirement scope: single-domain focused change → ≤5; multi-domain (2–3 domains) or medium complexity → 6–10; large cross-domain (4+ domains) or high complexity → >10. If estimate is unavailable, default to 300s. On timeout, fall back to Direct mode immediately — do NOT retry (empirically, a timed-out Plan subagent retried under the same conditions times out again, wasting another full timeout window).

Budget cap: Single subagent, one attempt. No retry loop for timeout — fall back to Direct mode. Retry only on format/incomplete plan failure (once), then fall back to Direct mode if retry also fails.

Scope Check

If the spec covers multiple independent subsystems, suggest breaking into separate plans — one per subsystem. Each plan should produce working, testable software on its own.

File Structure

Before defining tasks, map out which files will be created or modified and what each one is responsible for.

• Design units with clear boundaries and well-defined interfaces
• Prefer smaller, focused files over large ones that do too much
• Files that change together should live together. Split by responsibility, not by layer
• In existing codebases, follow established patterns

This structure informs the task decomposition.

Bite-Sized Task Granularity

Each step is one action (2-5 minutes):

• "Write the failing test" - step
• "Run it to make sure it fails" - step
• "Implement the minimal code to make the test pass" - step
• "Run the tests and make sure they pass" - step
• "Commit" - step

Plan Document Header

Read ./plan-header-template.md for the exact header format. Every plan MUST start with this header. Save plans to .claude/plans/<feature-name>.md.

Task Structure

Read ./task-structure-template.md for the full task format with TDD step-by-step cycle, file paths, and test context. Each task follows this structure.

Plan Quality

Read ./prompts/plan-quality-checks.md for no-placeholder rules, design completeness checklist, self-review protocol, and common rationalizations.

Context management: The Plan file contains all necessary context for downstream skills. After the Plan is written and self-review is complete:

1. If spec-challenge follows (P0 any domain mode): Skip context-health check entirely. The session split decision belongs to spec-challenge's Post-Review phase — triggering compact here would preempt that split point and cause the implementation phase to run in an already-bloated session.
2. Otherwise (no spec-challenge downstream): Check .claude/ecw/state/context-health.txt — if the file exists and starts with HIGH, use AskUserQuestion to offer compaction (follow project.output_language). If user picks compact, output the /compact instruction then STOP. Otherwise (file missing, LOW, MEDIUM, or user picks continue), proceed immediately.

Error Handling

Scenario	Handling
Subagent dispatch fails or returns incomplete plan	Log FAILED to trace (ecw_trace.jsonl) → retry once → still fails: fall back to Direct mode (coordinator generates plan itself). If Direct mode also fails, escalate via AskUserQuestion: "Plan generation failed. Options: (1) retry Direct mode, (2) abort."
Subagent timeout (dynamic limit exceeded)	Log TIMEOUT to trace (ecw_trace.jsonl) → fall back to Direct mode immediately (no retry — empirically, retry under same conditions times out again, wasting another full timeout window). Coordinator generates plan itself in Direct mode
Knowledge file missing (path-mappings.md, business-rules.md, knowledge-summary.md)	Log [Warning: {file} not found, plan may lack domain constraints] → continue plan generation with available data. Missing path-mappings: skip domain context injection. Missing business-rules: note in plan header as risk
Plan file write failure	Retry once → still fails: output full plan content in conversation. User can manually save to .claude/plans/
session-state.json unavailable (risk level unknown)	Default to P0 (full detail mode) and proceed

Supplementary Files

• plan-header-template.md — Plan document header format
• task-structure-template.md — Task format with TDD step-by-step cycle
• prompts/plan-quality-checks.md — No-placeholder rules, design completeness, self-review, rationalizations