skill-writing-plans git:20260906.89d2d35A

Immutable. This exact content is served forever at /api/v1/blob/cf593b813ad564ab.

---
name: skill-writing-plans
disable-model-invocation: true
description: Create zero-context implementation plans with bite-sized tasks — use for multi-step feature planning
trigger: |
  Invoke explicitly when you have a spec or requirements for a multi-step task.
  Example requests include "plan how to implement X", "create implementation plan",
  "break down this feature into tasks".
  Use BEFORE writing any implementation code.
execution_mode: enforced
pre_execution_contract:
  - visual_indicators_displayed
validation_gates:
  - orchestrate_sh_executed
  - output_artifact_exists
---

# Writing Plans

## MANDATORY COMPLIANCE — DO NOT SKIP

**When this skill is invoked, you MUST produce a full implementation plan following the structure below. You are PROHIBITED from:**
- Skipping the plan and jumping straight to implementation
- Producing a vague outline instead of the zero-context plan format
- Deciding the task is "simple enough" to not need a plan
- Omitting file paths, complete code, test instructions, or verification steps

**The user asked for a plan, not an implementation. Write the plan first.**

---

**Your first output line MUST be:** `🐙 **CLAUDE OCTOPUS ACTIVATED** - Implementation Planning`

## Overview

Write comprehensive implementation plans assuming the engineer has **zero context** for the codebase and **questionable taste**.

Document everything: which files to touch, complete code, how to test, how to verify.

**Principles:** DRY. YAGNI. TDD. Frequent commits.

## Decisions before tasks

Build a dependency graph for unresolved decisions before writing implementation
tasks. A decision record contains its question, evidence required, dependencies,
owner, resolution, and the implementation it unblocks. Use the repository's
configured tracker. Beads is not an end-user requirement.

Decision states are `open`, `claimed`, `resolved`, `superseded`, and `blocked`,
mapped to native tracker states or labels. Resolve only from evidence or a
recorded human decision. If new evidence invalidates a decision, reopen its
dependent work and explain why. A cycle means the work is not ready; recut the
decisions rather than marking tasks ready.

Claim through the tracker's atomic operation and read ownership back before
writing. If atomic claiming is unavailable, appoint one integrator. Never
overwrite another claim. When the tracker fails, save an explicitly unfiled
proposal in existing plan storage, stop tracker writes, and never fabricate IDs
or migrate a database.

---

## Plan Document Structure

### Header (Required)

```markdown
# [Feature Name] Implementation Plan

**Goal:** [One sentence describing what this builds]

**Architecture:** [2-3 sentences about approach]

**Tech Stack:** [Key technologies/libraries]

**Estimated Time:** [X tasks × 5 min = Y minutes]

---

## Prerequisites

- [ ] [Any setup needed before starting]
- [ ] [Dependencies to install]
- [ ] [Files that must exist]
```

---

## Task Granularity

**Each task is ONE action (2-5 minutes):**

| Good (Single Action) | Bad (Multiple Actions) |
|---------------------|------------------------|
| "Write the failing test" | "Write tests and implement" |
| "Run test to verify it fails" | "Make it work" |
| "Implement minimal code to pass" | "Add the feature" |
| "Commit with message" | "Finish the feature" |

---

## Task Template

```markdown
### Task N: [Component Name]

**Files:**
- Create: `exact/path/to/new-file.ts`
- Modify: `exact/path/to/existing.ts` (lines 45-67)
- Test: `tests/exact/path/to/test.spec.ts`

**Step 1: Write failing test**

```typescript
// tests/exact/path/to/test.spec.ts
describe('ComponentName', () => {
  it('should do specific thing', () => {
    const result = functionName(input);
    expect(result).toBe(expected);
  });
});
```

**Step 2: Run test to verify it fails**

```bash
npm test tests/exact/path/to/test.spec.ts
```

Expected output:
```
FAIL: expected 'expected' but got undefined
```

**Step 3: Implement minimal code**

```typescript
// exact/path/to/new-file.ts
export function functionName(input: InputType): OutputType {
  // Minimal implementation
  return expected;
}
```

**Step 4: Run test to verify it passes**

```bash
npm test tests/exact/path/to/test.spec.ts
```

Expected output:
```
PASS: 1/1 tests passed
```

**Step 5: Commit**

```bash
git add tests/exact/path/to/test.spec.ts exact/path/to/new-file.ts
git commit -m "feat(component): add specific functionality"
```

---
```

---

## Example: Complete Task

```markdown
### Task 3: Add Email Validation

**Files:**
- Create: `src/validators/email.ts`
- Test: `tests/validators/email.spec.ts`

**Step 1: Write failing test**

```typescript
// tests/validators/email.spec.ts
import { validateEmail } from '../src/validators/email';

describe('validateEmail', () => {
  it('returns error for empty email', () => {
    const result = validateEmail('');
    expect(result).toEqual({ valid: false, error: 'Email required' });
  });

  it('returns error for invalid format', () => {
    const result = validateEmail('not-an-email');
    expect(result).toEqual({ valid: false, error: 'Invalid email format' });
  });

  it('returns valid for correct email', () => {
    const result = validateEmail('user@example.com');
    expect(result).toEqual({ valid: true });
  });
});
```

**Step 2: Run test to verify it fails**

```bash
npm test tests/validators/email.spec.ts
```

Expected: `Cannot find module '../src/validators/email'`

**Step 3: Implement minimal code**

```typescript
// src/validators/email.ts
interface ValidationResult {
  valid: boolean;
  error?: string;
}

export function validateEmail(email: string): ValidationResult {
  if (!email || !email.trim()) {
    return { valid: false, error: 'Email required' };
  }

  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  if (!emailRegex.test(email)) {
    return { valid: false, error: 'Invalid email format' };
  }

  return { valid: true };
}
```

**Step 4: Run test to verify it passes**

```bash
npm test tests/validators/email.spec.ts
```

Expected: `PASS: 3/3 tests passed`

**Step 5: Commit**

```bash
git add src/validators/email.ts tests/validators/email.spec.ts
git commit -m "feat(validators): add email validation with tests"
```
```

---

## Integration with Claude Octopus

### Using Octopus for Plan Execution

After creating a plan, offer execution options:

```markdown
## Execution Options

**1. Sequential (this session)**
Execute tasks one by one with verification between each.

**2. Parallel (octopus tangle)**
Use Claude Octopus to parallelize independent tasks:
```bash
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh tangle "Execute implementation plan for [feature]"
```

**3. Full workflow (octopus embrace)**
Research → Define → Implement → Deliver:
```bash
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh embrace "Implement [feature] per plan"
```
```

### Plan Storage (Claude Code v2.1.10)

Claude Octopus uses session-aware plan storage. Plans are automatically saved to:

```
~/.claude-octopus/plans/${CLAUDE_SESSION_ID}/YYYY-MM-DD-feature-name.md
```

This integrates with Claude Code's `plansDirectory` setting. To customize:

```json
// settings.json
{
  "plansDirectory": "~/.claude-octopus/plans"
}
```

For project-local plans, save to `docs/plans/`:

```bash
mkdir -p docs/plans
# docs/plans/2026-01-17-user-authentication.md
```

---

## Checklist for Good Plans

- [ ] Each task is 2-5 minutes (single action)
- [ ] Exact file paths (not "in the utils folder")
- [ ] Complete code (not "add validation logic")
- [ ] Exact commands with expected output
- [ ] TDD: test before implementation
- [ ] Commit after each task

---

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| "Add the validation" | Show exact code |
| "Update the tests" | Show exact test code |
| "In the config file" | `config/app.config.ts` line 23 |
| "Run the tests" | `npm test path/to/specific.spec.ts` |
| Large tasks (30+ min) | Break into 2-5 min steps |
| No verification | Add "Run X, expect Y" |

---

## When to Create Plans

| Scenario | Use Plan? |
|----------|-----------|
| Multi-step feature (3+ tasks) | Yes |
| Simple bug fix (1 task) | No, just do it |
| Uncertain scope | Yes (clarifies thinking) |
| Delegation to subagent | Yes (zero-context execution) |
| Complex refactoring | Yes |
| Config change | No |

---

## Related Skills

- **test-driven-development** - Each task follows TDD cycle
- **verification-before-completion** - Verify each step
- **finishing-branch** - After all tasks complete

---

## The Bottom Line

```
Plan exists → Engineer with zero context can execute
Otherwise → Not a complete plan
```

**Exact paths. Complete code. Verification steps. No assumptions.**