Writing Plans

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

1. Read the specification file completely

2. Review existing codebase to understand:

   • What's already implemented
   • Existing patterns to follow
   • Where new code should live

3. Think deeply about best implementation approach

4. Consider architecture, design patterns, maintainability

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

1. Break specification into logical tasks
2. 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

3. Review and refine task breakdown

4. Ensure tasks are right-sized and ordered correctly

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

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

1. Use issues_list filtered by project: [specification filename] to verify all issues created
2. Review issue list to ensure:
   • All tasks from plan are present
   • Issues are in correct order
   • No duplicates or gaps
   • Task sizes are appropriate
3. 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

• Specification fully read and analyzed
• Existing codebase reviewed for patterns
• Task breakdown created and refined
• Every task has corresponding MCP issue with COMPLETE details
• All issues include exact file paths, code examples, commands
• All issues reference the specification
• Issue list reviewed and verified (using issues_list)
• Tasks are ordered correctly
• No gaps in implementation steps
• Optional plan file created (if architecture context needed)
• Plan covers entire specification without overscoping

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

Converted and distributed by TomeVault — claim your Tome and manage your conversions.