writing-plans

Use after brainstorming/design phase to create detailed implementation plans. Creates step-by-step plans clear enough for execution by any developer.

⭐2stars🔀0forks📁View on GitHub🕐Updated Dec 30, 2025⬇️1downloads

When & Why to Use This Skill

The Writing Plans skill is a high-performance Claude agent tool designed to bridge the gap between high-level brainstorming and technical execution. It generates comprehensive, step-by-step implementation plans that adhere to Test-Driven Development (TDD) principles, ensuring that complex software features are decomposed into verifiable, atomic tasks. By producing standardized documentation (markdown) with exact file paths, explicit code snippets, and robust rollback strategies, it eliminates ambiguity and maximizes the efficiency of both human developers and AI subagents in the software development lifecycle (SDLC).

Use Cases

  • Technical Roadmap Generation: Transform abstract design concepts into granular, executable task lists with specific file paths and implementation requirements.
  • TDD Workflow Standardization: Automatically generate 'Red-Green-Refactor' test cases and implementation stubs to ensure high code coverage and quality from the first line of code.
  • AI Agent Handoff & Orchestration: Create structured 'executing-plans' documents that allow subagents to perform complex coding tasks with zero context loss and minimal supervision.
  • Risk Management & Documentation: Develop detailed rollback plans and manual verification checklists for critical system updates to ensure production stability and easy recovery.
namewriting-plans
descriptionUse after brainstorming/design phase to create detailed implementation plans. Creates step-by-step plans clear enough for execution by any developer.

Writing Plans

Core Principle

Write plans clear enough for an enthusiastic junior engineer with poor taste, no judgement, no project context, and an aversion to testing to follow.

Plan Structure

Save plans to: docs/plans/YYYY-MM-DD-<feature-name>.md

# [Feature Name] Implementation Plan

> **For Claude:** Use executing-plans skill to implement this plan task-by-task.

## Overview
Brief description of what we're building and why.

## Prerequisites
- [ ] Dependency 1 installed
- [ ] Service 2 running
- [ ] Access to X configured

## Tasks

### Task 1: [Descriptive Name]
**File:** `path/to/file.ts`
**Test:** `path/to/file.test.ts`

#### Test First (RED)
```typescript
// Exact test code to write
describe('FeatureName', () => {
  it('should do specific thing', () => {
    // Arrange
    // Act  
    // Assert
  });
});

Implementation (GREEN)

// Exact implementation code
export function featureName() {
  // Implementation
}

Verification

npm test -- --grep "FeatureName"
# Expected: 1 passing

Task 2: [Next Task]

...

Integration Tests

After all tasks complete:

# Commands to run
npm run test:integration

Manual Verification

Steps to manually verify the feature works:

  1. Step 1
  2. Step 2
  3. Expected result

Rollback Plan

If something goes wrong:

  1. git revert HEAD
  2. ...

## Plan Quality Checklist

### Every Task Must Have:
- [ ] Exact file paths
- [ ] Complete code (not "add validation")
- [ ] Test written BEFORE implementation
- [ ] Verification command with expected output
- [ ] Clear success criteria

### Plan Must Include:
- [ ] Prerequisites listed
- [ ] Tasks in dependency order
- [ ] Integration test at end
- [ ] Rollback instructions

## Writing Guidelines

### Be Explicit
❌ "Add error handling"
✅ "Wrap the API call in try/catch, log errors with context, return null on failure"

### Be Complete
❌ "Update the config"
✅ ```json
{
  "setting": "value",
  "newSetting": "newValue"
}

Be Ordered

Tasks should be executable in sequence:

  1. No forward dependencies
  2. Each task builds on previous
  3. Tests pass after each task

Execution Handoff

After saving the plan, offer execution choice:

"Plan complete and saved. Two execution options:

1. Subagent-Driven (this session)

  • Fresh subagent per task
  • Review between tasks
  • Fast iteration

2. Parallel Session (separate)

  • Open new session with executing-plans skill
  • Batch execution with checkpoints

Which approach?"

DRY, YAGNI, TDD Reminders

Include at top of every plan:

## Remember
- Exact file paths always
- Complete code in plan (not "add validation")
- Exact commands with expected output
- DRY, YAGNI, TDD, frequent commits

Anti-Patterns

Don't Do This

  • Vague task descriptions
  • Missing file paths
  • Incomplete code snippets
  • Implementation before tests
  • No verification steps
  • Assuming context