Comprehensive Writing Plans

A methodical skill for writing detailed implementation plans that enable any engineer to execute a feature or change without ambiguity. Covers plan structure, code location references, decision documentation, and edge case identification.

When to Use This Skill

Choose this skill when:

• Planning a feature that will be implemented by another engineer
• Documenting a complex implementation approach for team review
• Breaking down a large project into implementable phases
• Creating onboarding documentation for a new codebase area
• Writing RFC (Request for Comments) documents for architectural changes

Consider alternatives when:

• Implementing code directly → just implement it
• Writing user-facing documentation → use a docs skill
• Creating project timelines → use a project management tool
• Writing tests → use a testing skill

Quick Start

Copy
# Implementation Plan: [Feature Name]

## 1. Overview
One paragraph: what we're building, why, and the expected outcome.

## 2. Background
What exists today. Link to relevant code files with line numbers.
Explain current behavior the reader must understand.

## 3. Detailed Design
Step-by-step implementation instructions.
For each step:
- Which file to modify (exact path)
- What to add/change (with code snippets)
- Why this approach (brief justification)

## 4. Data Model Changes
Schema changes, migrations, new tables/fields.
Include before/after comparisons.

## 5. API Changes
New endpoints, modified payloads, breaking changes.
Include request/response examples.

## 6. Edge Cases
Specific scenarios that need handling.
For each: what happens, what should happen, how to handle.

## 7. Testing Strategy
What to test, how to test, expected coverage.

## 8. Rollout Plan
Feature flags, migration steps, rollback procedure.

Core Concepts

Plan Quality Criteria

Criterion	Good Plan	Bad Plan
Specificity	"Add field status to orders table, type VARCHAR(20)"	"Update the database"
File References	"src/services/OrderService.ts:45-67"	"the order service"
Code Samples	Actual code snippets for key changes	Prose descriptions of code
Edge Cases	"If order has 0 items, return 400 with message"	"Handle empty orders"
Dependencies	"Requires PR #123 merged first"	No dependency mentioned
Testing	"Add test: submit order with 0 items → expect 400"	"Add tests"

Implementation Step Template

Copy
### Step 3: Add order validation middleware

**File:** `src/middleware/validateOrder.ts` (NEW FILE)

**What:** Create a middleware that validates order requests before they reach the handler.

**Code:**
```typescript
import { z } from 'zod';

const orderSchema = z.object({
  items: z.array(z.object({
    productId: z.string().uuid(),
    quantity: z.number().int().min(1).max(999),
  })).min(1, 'Order must have at least one item'),
  shippingAddress: z.object({
    street: z.string().min(1),
    city: z.string().min(1),
    zip: z.string().regex(/^\d{5}(-\d{4})?$/),
  }),
});

export const validateOrder = validate(orderSchema);

Why: Validation at the middleware layer keeps the controller focused on business logic. Zod provides runtime type checking that TypeScript alone can't.

Depends on: Step 2 (validate middleware factory)

### Edge Case Documentation

```markdown
## Edge Cases

### EC-1: Concurrent order submission
**Scenario:** User double-clicks submit button
**Current behavior:** Two orders created
**Expected behavior:** Second request rejected
**Solution:** Add idempotency key header, check in middleware
**File:** `src/middleware/idempotency.ts`

### EC-2: Product out of stock between cart and checkout
**Scenario:** Last item reserved by another user during checkout
**Current behavior:** 500 error
**Expected behavior:** Clear error message, suggest alternatives
**Solution:** Check stock in transaction, return 409 with details
**File:** `src/services/OrderService.ts` → `createOrder()`

### EC-3: Payment succeeds but order creation fails
**Scenario:** Stripe charges card, database insert fails
**Current behavior:** Money charged, no order record
**Expected behavior:** Automatic refund, error logged
**Solution:** Create order record first (pending), capture payment after
**File:** `src/services/PaymentService.ts` → `processPayment()`

Configuration

Parameter	Type	Default	Description
planFormat	string	'markdown'	Format: markdown, notion, or confluence
codeSnippets	boolean	true	Include code samples in plan
fileReferences	boolean	true	Include exact file paths and line numbers
edgeCaseCount	number	5	Minimum edge cases to document
testingSection	boolean	true	Include testing strategy section
rolloutSection	boolean	true	Include rollout and rollback plan

Best Practices

1. Write plans for someone with zero context about your codebase — Don't assume the reader knows which files are important, how the system works, or what conventions exist. Include file paths, explain architectural decisions, and link to relevant existing code.

2. Include actual code snippets, not just descriptions — "Add a validation function" is ambiguous. A code snippet showing the exact validation schema, function signature, and error handling removes all ambiguity and speeds implementation.

3. Document every decision point and why — If you chose approach A over approach B, explain why. Future readers will question the decision and might switch to B without understanding the tradeoffs.

4. Enumerate edge cases with expected behavior — For each edge case, document: the scenario, the current behavior, the expected behavior, and the implementation approach. This prevents edge cases from becoming bugs discovered in production.

5. Order implementation steps by dependency — Steps should be implementable in order. If Step 5 depends on Step 3, make that dependency explicit. The implementer shouldn't have to read the entire plan to determine work order.

Common Issues

Plans become outdated before implementation starts — Long planning cycles produce stale plans. Keep plans focused on the next 1-2 weeks of work. Update plans when prerequisites change or new information emerges.

Plans too detailed, implementer follows blindly without understanding — Over-prescribed plans prevent implementers from making good local decisions. Specify the "what" and "why" completely, but leave room for the implementer to choose "how" for non-critical details.

Edge cases discovered during implementation that weren't in the plan — No plan catches everything. Establish a convention: when new edge cases are discovered, add them to the plan document before implementing. This maintains the plan as a living reference.