Plan Writing

Plans that would satisfy a technical steering committee of distinguished engineers.

Context: Where Plan-Writing Fits

This skill operates within the Execute stage of RSID:

USER-DRIVEN:    Listen → Execute ← YOU ARE HERE → Reflect
AUTONOMOUS:     Ideate → Execute ← YOU ARE HERE → Reflect

After your plan is executed and merged, proceed to Reflect. See the rsid skill for the full model.

The Core Technique

When writing implementation plans, frame your audience as the most distinguished experts in the relevant domain. This isn't pretense—it's a forcing function for rigor.

The question to ask yourself:

Would this plan survive review by [distinguished expert] and their peers?

If you wouldn't present it at a design review with industry legends in the room, the plan isn't ready.

Domain-Specific Audiences

Match the expert panel to the technology:

Architectural Foundation

Every plan must address how the change fits the hexagonal architecture. This isn't optional—it's how we ensure recursive self-improvement.

The Contract-Port-Adapter Pattern

┌─────────────────────────────────────────────────────────────┐
│                     Application Core                        │
│  (Business logic - no platform dependencies)                │
└─────────────────────────────────────────────────────────────┘
            │                              │
            ▼                              ▼
┌───────────────────────┐      ┌───────────────────────┐
│   Contract Package    │      │   Contract Package    │
│  @scope/contract-X    │      │  @scope/contract-Y    │
│  (Pure interfaces)    │      │  (Pure interfaces)    │
└───────────────────────┘      └───────────────────────┘
            │                              │
            ▼                              ▼
┌───────────────────────┐      ┌───────────────────────┐
│     Port Package      │      │     Port Package      │
│    @scope/port-X      │      │    @scope/port-Y      │
│ (Production impl)     │      │ (Production impl)     │
└───────────────────────┘      └───────────────────────┘
            │                              │
            └──────────────┬───────────────┘
                           ▼
              ┌─────────────────────────┐
              │    Composition Root     │
              │  (Wires everything)     │
              │  Only place with        │
              │  platform globals       │
              └─────────────────────────┘

Plan Must Answer These Architecture Questions

Capability vs Data Contracts

Plans must distinguish between:

Key insight: If you're tempted to put methods on a data structure, those methods are operations—they belong in the port as pure functions.

Hermetic Primitive Ports

When wrapping platform primitives (Date, console, process, Math.random):

// Ports must accept optional environment overrides
export type ClockEnvironmentOverrides = {
  readonly performance?: PerformanceLike | null  // undefined = host default, null = disable
  readonly dateNow?: () => number
}

export function createSystemClock(options: ClockOptions = {}): Clock {
  const env = resolveEnvironment(options.environment)
  // ...
}

This ensures every package is testable in isolation.

What Distinguished Engineers Expect

1. Precise Problem Statement

They'd ask: "What exactly are we solving, and why does it matter?"

• State the problem in one paragraph
• Explain why existing solutions don't suffice
• Define success criteria upfront

Anti-pattern: Jumping to solution before establishing the problem.

2. Considered Alternatives

They'd ask: "What else did you consider, and why did you reject it?"

• List 2-3 alternative approaches
• Explain trade-offs of each
• Justify your chosen approach

Anti-pattern: Presenting one solution as if it's obviously correct.

3. Precise Technical Details

They'd ask: "Show me the types. Show me the interfaces."

• Define key data structures
• Specify function signatures
• Document contracts between components

Anti-pattern: Hand-waving with "we'll figure out the details during implementation."

4. Edge Cases and Failure Modes

They'd ask: "What happens when things go wrong?"

• List known edge cases
• Define error handling strategy
• Consider partial failure scenarios

Anti-pattern: Only describing the happy path.

5. Testability

They'd ask: "How will you know this works?"

• Describe testing strategy
• Identify what's mockable vs integration
• Define acceptance criteria

Anti-pattern: "We'll add tests after."

6. Migration and Rollout

They'd ask: "How do we get from here to there safely?"

• Describe incremental steps
• Identify breaking changes
• Plan for rollback if needed

Anti-pattern: Big-bang deployments with no incremental path.

Plan Structure Template

## Problem

[One paragraph describing the problem and why it matters]

## Success Criteria

- [ ] Criterion 1
- [ ] Criterion 2

## Alternatives Considered

### Option A: [Name]
[Description, pros, cons]

### Option B: [Name]
[Description, pros, cons]

### Chosen Approach: [Name]
[Why this option wins]

## Design

### Contracts (Pure Interfaces)

// @scope/contract-{name} // Only interfaces and types—no runtime code

export interface [CapabilityName] { [method](args): ReturnType }

// OR for data contracts: export interface [DataName] { readonly [field]: Type }

### Ports (Implementations)

// @scope/port-{name} // Factory with deps first, options second

export interface [Name]Dependencies { readonly [dep]: ContractType // Other contracts needed }

export interface [Name]Options { readonly [option]?: ConfigType // Optional configuration }

export function create[Name]( deps: [Name]Dependencies, options: [Name]Options = {} ): [Name] { // Implementation using deps, never globals }

### Composition Root

Where ports are wired together with real implementations:

// src/main.ts const clock = createSystemClock() const logger = createLogger({ clock, channel: createStderrChannel() }) const app = createApp({ logger })

### Component Breakdown

1. [Component 1]: [responsibility]
2. [Component 2]: [responsibility]

### Data Flow

[How data moves through the system—contracts at boundaries]

## Edge Cases

| Case | Handling |
|------|----------|
| [Edge case 1] | [How handled] |
| [Edge case 2] | [How handled] |

## Testing Strategy

- Unit: [what's unit tested]
- Integration: [what's integration tested]
- E2E: [acceptance scenarios]

## Implementation Steps

1. [ ] Step 1
2. [ ] Step 2
3. [ ] Step 3

## Open Questions

- [Question 1]
- [Question 2]

Rigor Calibration

Match detail level to scope:

Self-Check Questions

Before presenting a plan, verify:

Expert Review Readiness

• Could I defend this to Anders Hejlsberg (or domain equivalent)?
• Have I shown my work on alternatives?
• Are the types/interfaces concrete, not hand-wavy?
• Have I addressed "what could go wrong"?
• Is there a clear path from current state to done?
• Would a senior engineer be able to implement from this plan alone?

Architectural Compliance

• Are contracts pure (no runtime code, no JS emitted)?
• Do ports inject all dependencies (no direct globals)?
• Is there a clear composition root?
• Are packages hermetically sealed (testable without platform)?
• Can tests create inline mocks without shipping test code in ports?
• Do primitive ports accept environment overrides?
• Are capability vs data contracts clearly distinguished?

Anti-Patterns

The "Trust Me" Plan

Wrong:

"We'll refactor the auth system to be more modular."

Right:

"We'll extract AuthService into three components: TokenValidator, SessionManager, and PermissionChecker. Here are the interfaces..."

The "Happy Path Only" Plan

Wrong:

"User clicks button, API returns data, we display it."

Right:

"User clicks button. If network fails, show cached data with stale indicator. If API returns 429, back off exponentially. If response is malformed, log error and show fallback UI."

The "Implementation as Plan" Plan

Wrong:

"1. Create file. 2. Add function. 3. Call function."

Right:

"1. Define the CachePolicy interface. 2. Implement LRUCachePolicy with configurable max size. 3. Integrate into DataFetcher via dependency injection."

The "Kitchen Sink" Plan

Wrong:

47-step plan covering every micro-decision

Right:

Focused plan covering decisions that matter, leaving obvious details to implementation

The "Leaky Abstraction" Plan

Wrong:

// Port that uses globals directly
export function createLogger(): Logger {
  return {
    info(msg) {
      console.log(new Date().toISOString(), msg)  // NO! Direct globals
    }
  }
}

Right:

// Port with injected dependencies
export interface LoggerDeps {
  channel: OutChannel
  clock: Clock
}

export function createLogger(deps: LoggerDeps): Logger {
  return {
    info(msg) {
      deps.channel.write(`${deps.clock.timestamp()} ${msg}`)
    }
  }
}

The "Methods on Data" Plan

Wrong:

// Contract with operations baked in
export interface Dag<T> {
  nodes: Map<string, DagNode<T>>
  getTopologicalOrder(): string[]  // NO! This is an operation
  validate(): ValidationResult     // NO! This is an operation
}

Right:

// Contract: just the data
export type Dag<T> = readonly DagNode<T>[]

// Port: operations as pure functions
export function getTopologicalOrder<T>(dag: Dag<T>): string[]
export function validateDag<T>(dag: Dag<T>): ValidationResult

Integration with Claude Code

When entering plan mode (/plan or EnterPlanMode):

1. Identify the domain and select appropriate expert panel
2. Use the plan structure template
3. Apply rigor calibration based on scope
4. Verify architectural compliance (contract-port separation)
5. Run through self-check questions before presenting
6. Use ExitPlanMode only when plan meets distinguished engineer standards

Related Skills

Architectural Pattern Reference

The coding-patterns skill contains the authoritative reference for:

• Contract package structure (@scope/contract-{name})
• Port package structure (@scope/port-{name})
• Factory function argument order (deps first, options second)
• Hermetic primitive port patterns
• Composition root wiring
• Testing with inline mocks

When writing a plan, invoke coding-patterns if you need detailed guidance on any of these patterns.

The Standard

A good plan is one you'd be proud to present to the creators of the tools you're using.

If Anders Hejlsberg would raise an eyebrow at your TypeScript plan, it's not ready. If Dan Abramov would question your React component boundaries, rethink them. If Leslie Lamport would find holes in your distributed system design, fill them first.

The experts aren't actually reviewing your plan—but writing as if they were produces plans worth implementing.