Writing Plans

Overview

Write comprehensive implementation plans assuming the engineer has zero context for our codebase. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.

MCP issues are the source of truth - each tracked task contains complete implementation details.

Optionally create:

Plan file (.wrangler/plans/YYYY-MM-DD-PLAN_<spec>.md) - Architecture overview and design decisions (reference only)

Works in main branch OR worktree (no preference)

Headless mode: If run as subagent, do not stop to ask for feedback during execution.

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 (Reference Only)

Plan files are required when architecture/design context needs documentation, an implementation involves multiple interconnected steps/issues that require planning around ordering and potential parallelism.

Create Plan File

Create plan file when ANY of these are true:

✅ 10+ issues/tasks - Need architectural overview to understand big picture ✅ Multiple interconnected components - Need system diagram and component relationships ✅ Significant design decisions - Need to document rationale and alternatives considered ✅ Complex patterns/conventions - Need reference material that applies across multiple tasks ✅ Onboarding context needed - Future agents/sessions would struggle understanding issues in isolation

Skip plan file when:

❌ < 5 simple tasks - Straightforward implementation, issues are sufficient ❌ No architectural complexity - Changes are localized and self-explanatory ❌ Obvious approach - No design decisions requiring rationale

Plan File Content (If Created)

Plan file should contain:

Architecture overview and design decisions
Technology choices and rationale
Cross-cutting concerns and patterns
Component relationships and system diagram
Design alternatives considered and why rejected
References to MCP issues (NOT duplicate content)

# [Feature Name] Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use /wrangler:implementing-issue to implement this plan task-by-task.

**Goal:** [One sentence describing what this builds]

**Architecture:** [2-3 sentences about approach]

**Tech Stack:** [Key technologies/libraries]

**Implementation tracking:** See MCP issues (project: [specification filename])

---

## Acceptance Criteria Coverage (Auto-generated)

### Spec Acceptance Criteria

- AC-001: [description]
- AC-002: [description]
  ...

### Task-to-AC Mapping

| Task ID | Satisfies AC   | Estimated Compliance Contribution |
| ------- | -------------- | --------------------------------- |
| ISS-001 | AC-001, AC-003 | 15%                               |
| ISS-002 | AC-002         | 10%                               |

...

### Coverage Summary

- Total AC: 15
- AC covered by tasks: 14 (93%)
- AC with no implementing tasks: AC-012 ⚠️
- Estimated post-execution compliance: 93%

### Risk Areas

- [List any AC with no tasks or partial coverage]

---

MCP Issue Content Requirements

Each issue MUST contain:

Exact file paths (create/modify/test)
Complete code examples (not "add validation")
Exact commands with expected output
All 5 TDD steps (write test, verify fails, implementing-issue, verify passes, commit)
Clear acceptance criteria
Dependencies on other tasks

NOT in issues:

Architecture rationale (goes in optional plan file)
Design alternatives considered (goes in optional plan file)
Cross-cutting concerns (goes in optional plan file)

Remember

MCP issues are source of truth
Include complete implementation details in each issue
Optional plan file for architecture/design context only
No duplication between issues and plan file
Reference relevant skills with @ syntax
DRY, YAGNI, TDD, frequent commits

Planning Process

Phase 1: Read and Analyze Specification

Read the specification file completely
Review existing codebase to understand:
- What's already implemented
- Existing patterns to follow
- Where new code should live
Think deeply about best implementation approach
Consider architecture, design patterns, maintainability
Extract acceptance criteria from specification

Use LLM to identify all acceptance criteria:
- AC explicitly labeled (AC-001, AC-002, etc.)
- Requirements from "Acceptance Criteria" sections
- Test requirements from "Testing" sections
- Manual verification steps
- E2E test requirements
Store as structured list for task mapping in Phase 2.

Note: If spec has no explicit acceptance criteria, note this for later phases.

Phase 2: Plan Task Breakdown

Break specification into logical tasks
For each task, prepare complete details:
- Exact files to create/modify
- Complete code examples for all 5 TDD steps
- Test requirements
- Exact commands and expected output
- Commit message

Think deeply about task ordering:

Tasks should build on each other incrementally
Each task should be small (<250 LOC when implemented)
No gaps - every step builds on earlier work

Review and refine task breakdown
Ensure tasks are right-sized and ordered correctly
Map tasks to acceptance criteria

For each task, determine which acceptance criteria it satisfies:
- Analyze task description and implementation scope
- Identify which AC are fully/partially addressed
- Calculate estimated compliance contribution per task
- Flag any AC with no implementing tasks
This mapping will be used to:
- Add satisfiesAcceptanceCriteria metadata to each MCP issue
- Generate coverage report in plan file (if created)
- Enable REVIEW phase validation in implementing-specs workflow
Optionally draft plan file for architecture overview (if needed)

Phase 3: Create MCP Issues (Source of Truth)

MCP issues contain ALL implementation details. For each task, call issues_create with complete information:

{
  title: "Task N: [Short action-oriented title]",
  description: `## Description
[What this task implements - refer to specification]

## Context
Reference: [specification filename]
[Relevant architectural context and design decisions]

## Files
- Create: \`path/to/new/file.ts\`
- Modify: \`path/to/existing.ts:45-67\`
- Test: \`path/to/test.ts\`

## Implementation

**Step 1: Write the failing test**

\`\`\`typescript
// Complete test code
describe('feature', () => {
  it('should behave correctly', () => {
    // Exact test implementation
  });
});
\`\`\`

**Step 2: Run test to verify it fails**

Run: \`npm test -- path/to/test.ts\`
Expected: FAIL with "[expected error message]"

**Step 3: Write minimal implementation**

\`\`\`typescript
// Complete implementation code
export function feature() {
  // Exact minimal implementation
}
\`\`\`

**Step 4: Run test to verify it passes**

Run: \`npm test -- path/to/test.ts\`
Expected: PASS

**Step 5: Commit**

\`\`\`bash
git add path/to/test.ts path/to/file.ts
git commit -m "feat: add specific feature"
\`\`\`

## Acceptance Criteria
- [ ] Test written and failing (RED)
- [ ] Implementation passes test (GREEN)
- [ ] Code refactored if needed (REFACTOR)
- [ ] All tests passing
- [ ] Committed with clear message

## Dependencies
- Requires completion of: Task [N-1]
`,
  type: "issue",
  status: "open",
  priority: "medium", // or high/low based on criticality
  labels: ["plan-step", "implementation"],
  project: "[specification filename]",
  wranglerContext: {
    agentId: "plan-executor",
    parentTaskId: "", // if breaking down larger issue
    estimatedEffort: "[time estimate if known]",
    satisfiesAcceptanceCriteria: ["AC-001", "AC-003"] // Which AC this task implements
  }
}

Important:

Issues are the single source of truth - include complete code examples and exact commands
Use issues_update if you need to refine an issue after creation (don't create duplicates)
If creating optional plan file, it should reference issues, NOT duplicate their content

Phase 4: Verify and Report

Use issues_list filtered by project: [specification filename] to verify all issues created
Review issue list to ensure:
- All tasks from plan are present
- Issues are in correct order
- No duplicates or gaps
- Task sizes are appropriate
Make any necessary adjustments using issues_update

Execution Handoff

After creating issues, offer execution choice:

"Plan complete:

Issues created: [N] tasks in issue tracker (project: [spec])
Plan file (if created): .wrangler/plans/YYYY-MM-DD-PLAN_<spec>.md (includes AC coverage analysis)
Estimated compliance: [X]% (based on task-to-AC mapping)

Execution options:

Ready to implementing-issue?

Use /wrangler:implementing-issue with one of these scopes:

/wrangler:implementing-issue (auto-infers from plan file in context)
/wrangler:implementing-issue issues 1-N (specific issue range)
/wrangler:implementing-issue plan-filename.md (explicit plan file)

The implementing-issue skill will:

Execute all tasks autonomously via subagents
Run code review after each task with automatic fixes
Only stop for genuine blockers (unclear requirements, flummoxed agents)
Present completion summary when done

Issue Update Pattern

If you discover during planning that a task needs refinement:

// Instead of creating new issue
issues_update({
  id: "[issueId]",
  priority: "high", // change priority
  description: "[updated description]", // add more detail
  labels: ["plan-step", "implementation", "complex"], // add label
});

Checklist Before Completion

Integration with Specifications

When working from a specification created with writing-specifications skill:

Reference spec filename in all issues
Follow any implementation notes in spec
Honor constraints documented in spec
Use architecture decisions from spec
Create issues that map to spec's acceptance criteria

writing-plans