WritingPlans

Write comprehensive implementation plans that break complex features into bite-sized, testable tasks.

Overview

Create detailed implementation plans that:

• Break work into 2-5 minute tasks
• Specify exact file paths and line numbers
• Include complete code examples (not just descriptions)
• Provide test commands with expected output
• Follow DRY, YAGNI, TDD, and frequent commits
• Assume engineer is skilled but unfamiliar with codebase

Announce at start: "I'm using the WritingPlans skill to create a detailed implementation plan."

Principles

DRY (Don't Repeat Yourself)

• Avoid duplicating code across the codebase
• Extract common logic into reusable functions
• Use existing utilities and patterns

YAGNI (You Aren't Gonna Need It)

• Only implement what's required for current use case
• Don't add features "just in case"
• Can always add more later

TDD (Test-Driven Development)

• Write tests before implementation
• Verify tests fail first
• Write minimal code to pass tests
• Integrate with TestDrivenDevelopment skill

Frequent Commits

• Commit after each completed task
• Small, focused commits
• Clear commit messages

Bite-Sized Task Granularity

Each step is ONE action taking 2-5 minutes:

Example task breakdown:

1. Write the failing test ← step
2. Run it to verify it fails ← step
3. Implement minimal code to pass ← step
4. Run tests to verify they pass ← step
5. Commit the changes ← step

Not this:

1. "Implement user authentication" ← Too large
2. "Add tests and implementation" ← Multiple actions

Plan Document Structure

Header Template

Every plan MUST start with this header:

# [Feature Name] Implementation Plan

**Status**: Draft | In Progress | Complete
**Created**: YYYY-MM-DD
**Goal**: [One sentence describing what this builds]
**Architecture**: [2-3 sentences about approach and key decisions]
**Tech Stack**: [Key technologies, libraries, tools used]

## Prerequisites

- [ ] [Any setup needed before starting]
- [ ] [Dependencies to install]
- [ ] [Documentation to review]

---

Task Template

### Task N: [Specific Component/Feature Name]

**Purpose**: [Why this task exists, what it accomplishes]

**Files:**
- Create: `exact/path/to/newfile.go`
- Modify: `exact/path/to/existing.go:123-145` (specify line ranges)
- Test: `tests/exact/path/to/test_file.go`
- Reference: `path/to/reference/pattern.go` (example to follow)

**Dependencies**: [What must be completed before this task]

---

#### Step 1: Write the failing test

```language
// Complete code, not pseudocode
func TestSpecificBehavior(t *testing.T) {
    input := "test input"
    result := FunctionUnderTest(input)
    expected := "expected output"
    if result != expected {
        t.Errorf("got %v, want %v", result, expected)
    }
}

Why this test: [Explain what behavior it verifies]

---

Step 2: Run test to verify it fails

Command:

go test ./path/to/package -v -run TestSpecificBehavior

Expected output:

FAIL: TestSpecificBehavior
    undefined: FunctionUnderTest

If different: [Troubleshooting guidance]

---

Step 3: Write minimal implementation

// Complete implementation, not "add code here"
func FunctionUnderTest(input string) string {
    // Minimal code to pass test
    return "expected output"
}

Implementation notes: [Explain key decisions]

---

Step 4: Run test to verify it passes

Command:

go test ./path/to/package -v -run TestSpecificBehavior

Expected output:

PASS: TestSpecificBehavior (0.00s)

---

Step 5: Refactor (if needed)

Optional improvements:

• Extract common logic
• Improve naming
• Add documentation

Run tests after each refactor

---

Step 6: Commit

git add tests/path/to/test_file.go path/to/newfile.go
git commit -m "feat: add specific feature

- Add FunctionUnderTest with test
- Handles [specific case]"

Commit message format: Follow repository conventions

---

## Complete Example

```markdown
# User Authentication Implementation Plan

**Status**: Draft
**Created**: 2025-12-25
**Goal**: Add JWT-based authentication to API endpoints
**Architecture**: Middleware-based auth using JWT tokens with refresh token rotation. Secrets stored via agenix.
**Tech Stack**: Go 1.21, golang-jwt/jwt/v5, agenix for secrets

## Prerequisites

- [ ] Review existing middleware patterns in `services/common/middleware/`
- [ ] Read JWT token structure in `docs/auth.md`
- [ ] Ensure agenix secret for JWT signing key exists

---

### Task 1: JWT Token Generation

**Purpose**: Create function to generate access and refresh tokens

**Files:**
- Create: `services/auth/jwt.go`
- Test: `services/auth/jwt_test.go`
- Reference: `services/common/crypto/signing.go` (signing pattern)

**Dependencies**: None

---

#### Step 1: Write the failing test

```go
package auth

import (
    "testing"
    "time"
)

func TestGenerateTokenPair_ValidUser(t *testing.T) {
    userID := "user-123"
    tokens, err := GenerateTokenPair(userID)

    if err != nil {
        t.Fatalf("unexpected error: %v", err)
    }

    if tokens.AccessToken == "" {
        t.Error("access token is empty")
    }

    if tokens.RefreshToken == "" {
        t.Error("refresh token is empty")
    }

    if tokens.ExpiresIn <= 0 {
        t.Error("expiration time is invalid")
    }
}

Why this test: Verifies token pair generation for authenticated user

---

Step 2: Run test to verify it fails

Command:

go test ./services/auth -v -run TestGenerateTokenPair_ValidUser

Expected output:

FAIL: TestGenerateTokenPair_ValidUser
    undefined: GenerateTokenPair

---

Step 3: Write minimal implementation

package auth

import (
    "time"

    "github.com/golang-jwt/jwt/v5"
)

type TokenPair struct {
    AccessToken  string
    RefreshToken string
    ExpiresIn    int64
}

func GenerateTokenPair(userID string) (*TokenPair, error) {
    // TODO: Load secret from agenix in future task
    secret := []byte("temp-secret-for-testing")

    // Access token (15 minutes)
    accessClaims := jwt.MapClaims{
        "sub": userID,
        "exp": time.Now().Add(15 * time.Minute).Unix(),
    }
    accessToken := jwt.NewWithClaims(jwt.SigningMethodHS256, accessClaims)
    accessStr, err := accessToken.SignedString(secret)
    if err != nil {
        return nil, err
    }

    // Refresh token (7 days)
    refreshClaims := jwt.MapClaims{
        "sub": userID,
        "exp": time.Now().Add(7 * 24 * time.Hour).Unix(),
    }
    refreshToken := jwt.NewWithClaims(jwt.SigningMethodHS256, refreshClaims)
    refreshStr, err := refreshToken.SignedString(secret)
    if err != nil {
        return nil, err
    }

    return &TokenPair{
        AccessToken:  accessStr,
        RefreshToken: refreshStr,
        ExpiresIn:    900, // 15 minutes in seconds
    }, nil
}

Implementation notes: Using temporary secret for testing; will integrate agenix in subsequent task

---

Step 4: Run test to verify it passes

Command:

go test ./services/auth -v -run TestGenerateTokenPair_ValidUser

Expected output:

PASS: TestGenerateTokenPair_ValidUser (0.01s)

---

Step 5: Commit

git add services/auth/jwt.go services/auth/jwt_test.go
git commit -m "feat: add JWT token pair generation

- Generate access token (15 min expiry)
- Generate refresh token (7 day expiry)
- Using temporary secret (agenix integration pending)"

---

Task 2: Agenix Secret Integration

[Continue with next task...]

---

## Plan Storage Location

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

Example:

docs/plans/2025-12-25-jwt-authentication.md

After writing plan:

git add docs/plans/2025-12-25-jwt-authentication.md
git commit -m "docs: add JWT authentication implementation plan"

What to Include in Plans

✅ Do Include

• Exact file paths with line numbers for modifications
• Complete code in examples (not "add validation here")
• Exact commands to run with expected output
• Why decisions were made (architecture choices)
• References to existing patterns in codebase
• Verification steps for each task
• Troubleshooting guidance for common issues
• Dependencies between tasks

❌ Don't Include

• Vague instructions like "add error handling"
• Pseudocode or incomplete examples
• Assumptions about what engineer knows
• Commands without expected output
• Tasks larger than 5 minutes
• Implementation details without tests

Integration with Other Skills

Before WritingPlans:

• Use Brainstorming skill to clarify design and requirements
• Ensure architecture decisions are made
• Identify all components needed

While WritingPlans:

• Reference TestDrivenDevelopment for test-first approach
• Check existing code patterns with Grep and Read
• Reference CORE principles for technology choices

After WritingPlans:

• Plan is ready for implementation
• Can be executed task-by-task
• Each task should take 2-5 minutes
• Progress can be tracked with TodoWrite

Examples

Example 1: Feature implementation plan

User: "I need a detailed plan for adding caching to the API"

→ Invoke WritingPlans skill
→ Announce: "I'm using the WritingPlans skill to create a detailed implementation plan"
→ Review existing API structure
→ Check for caching patterns in codebase
→ Break down into tasks:
  1. Add cache configuration
  2. Implement cache middleware
  3. Add cache key generation
  4. Implement cache invalidation
  5. Add metrics for cache hits/misses
→ Write complete plan with code examples
→ Save to docs/plans/2025-12-25-api-caching.md
→ Commit plan document
→ Ready for implementation

Example 2: Bug fix with test coverage

User: "Create a plan to fix the authentication bug and add comprehensive tests"

→ Invoke WritingPlans skill
→ Review bug report and reproduction steps
→ Identify root cause
→ Break down into tasks:
  1. Write test reproducing bug
  2. Verify test fails
  3. Fix bug with minimal change
  4. Add edge case tests
  5. Add integration tests
→ Write plan with exact code and commands
→ Save to docs/plans/2025-12-25-auth-bug-fix.md
→ Ready for systematic implementation

Example 3: Refactoring plan

User: "Plan out refactoring the database layer to use a repository pattern"

→ Invoke WritingPlans skill
→ Analyze current database usage
→ Design repository interfaces
→ Break down into tasks:
  1. Define repository interfaces
  2. Implement user repository
  3. Migrate user service to use repository
  4. Add repository tests
  5. Repeat for each entity
→ Each task includes before/after code
→ Includes migration strategy (incremental)
→ Save plan with 20+ small tasks
→ Can be implemented incrementally

Common Pitfalls

Don't:

• Write plans with vague tasks
• Skip exact file paths
• Provide incomplete code examples
• Forget test verification steps
• Make tasks too large (>5 minutes)
• Assume engineer knows codebase patterns

Do:

• Break work into bite-sized pieces
• Include complete, runnable code
• Specify expected output for commands
• Reference existing patterns
• Follow repository conventions
• Make each task independently committable