Writing Plans

Skill Usage Announcement

MANDATORY: When using this skill, announce it at the start with:

🔧 Using Skill: writing-plans | [brief purpose based on context]

Example:

🔧 Using Skill: writing-plans | [Provide context-specific example of what you're doing]

This creates an audit trail showing which skills were applied during the session.

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

Optional Plan Document (Reference Only)

Plan files are OPTIONAL - use when architecture/design context needs documentation.

When to Create Plan File

Create optional 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:implement 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])

---

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, implement, 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

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

**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]"
  }
}

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 (architecture reference)

Execution options:

Ready to implement?

Use /wrangler:implement with one of these scopes:

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

The implement 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