ring:writing-plans

What this skill does

# Writing Plans

## When to use
- Spec or requirements exist for a multi-step task and no implementation has started
- Feature spans multiple files/layers and needs decomposition before coding
- Handing off implementation to a separate session, agent, or human

## Skip when
- Single-file change with obvious shape (just do it)
- Exploratory spike — phased plans assume known requirements
- Spec is still in brainstorming; the plan would lock premature decisions

## Sequence
**Runs after:** ring:exploring-codebases, ring:pre-dev-* skills (Gates 0-9 outputs feed the spec)
**Runs before:** ring:executing-plans (rolling-wave execution) or ring:running-dev-cycle (gated subagent workflow)

## Related
**Companion:** [plan-document-reviewer-prompt.md](plan-document-reviewer-prompt.md) — subagent dispatch template for thorough plan review

---

Write the plan assuming the implementer is skilled but has zero context for this codebase, toolset, or problem domain.

The plan is a **rolling-wave document**. Only the first phase is detailed to task level at plan time; later phases stay at epic level until execution reaches them. Detail decays: code written in Phase 1 invalidates assumptions baked into Phase 3 tasks, so do not write Phase 3 tasks yet. ring:executing-plans elaborates each subsequent phase against the codebase as it actually exists.

**Announce at start:** "Using ring:writing-plans to author the implementation plan."

**Default save path:** `docs/plans/YYYY-MM-DD-<feature-name>.md`
(User preferences override.)

## Standards

Do NOT fetch standards documents while planning — standards compliance is enforced by the implementation agents and reviewers downstream. Plans reference DRY, YAGNI, and TDD generically.

## Blocker — STOP and Report

Do not write a plan on a shaky foundation. STOP and ask when:

| Situation | Action |
|-----------|--------|
| Vague requirements ("make it better", "add feature") | STOP. Ask: "What specific behavior should change?" |
| Missing success criteria | STOP. Ask: "How do we verify this works?" |
| Unknown codebase structure (can't locate files) | STOP. Run ring:exploring-codebases first, then plan |
| Conflicting constraints | STOP. Ask: "Which constraint takes priority?" |
| Multiple valid architectures without guidance | STOP. Ask: "Which pattern should we use?" |

## Scope Check

If the spec covers multiple independent subsystems, suggest breaking it into separate plans — one per subsystem. Each plan must produce working, testable software on its own.

If brainstorming already split the spec into sub-project specs, write one plan per sub-spec.

## Plan Hierarchy

| Level | Granularity | When detailed |
|-------|-------------|---------------|
| **Phase** | Independently verifiable milestone — software works at the end of every phase | At plan time |
| **Epic** | Cohesive unit of work inside a phase (one capability, one subsystem) | At plan time |
| **Task** | Dispatch-ready unit: context + implementation vision + verification | Phase 1 at plan time; later phases during execution (rolling wave) |

Rules:
- Every phase ends with working, testable software. No phase ends mid-refactor.
- 2–5 epics per phase. An epic that needs more than a paragraph to describe is two epics.
- Order phases by dependency first, then by risk — front-load whatever invalidates the design if it turns out wrong.

## Code Snippet Policy

Default is **prose, not code**. Describe intent, decisions, and shape; the implementer writes the code at execution time with the real codebase in front of them.

Include a snippet ONLY when prose cannot pin down the decision:

| Justified | Example |
|-----------|---------|
| Public contract other epics depend on | API signature, event schema, migration DDL |
| Non-obvious algorithm where the approach IS the decision | Custom balancing logic, conflict-resolution rule |
| Exact artifact where approximation breaks behavior | Config block, regex, SQL query |

If the snippet exists to "save the implementer time", delete it. If it exists because two epics would otherwise disagree about a contract, keep it.

## Plan Document Header

**Every plan MUST start with this header:**

```markdown
# [Feature Name] Implementation Plan

> **For implementers:** Use ring:executing-plans (rolling wave: implement the
> detailed phase → user checkpoint → detail the next phase → implement → repeat),
> or ring:running-dev-cycle for the full subagent-orchestrated workflow.
> This document is the living source of truth — task elaboration for later
> phases is written back into it during execution.

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

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

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

## Phase Overview

| Phase | Milestone | Epics | Status |
|-------|-----------|-------|--------|
| 1 | [what works at the end] | 1.1, 1.2 | Detailed |
| 2 | [what works at the end] | 2.1, 2.2 | Epic-level |
| 3 | [what works at the end] | 3.1 | Epic-level |

---
```

## Epic Format (all phases)

```markdown
### Epic N.M: [Name]

**Goal:** [what exists and works when this epic is done]
**Scope:** [subsystems/directories touched — coarse-grained for later phases]
**Dependencies:** [epics or phases that must land first, or "none"]
**Done when:** [observable acceptance criteria]
```

For Phase 1 epics, tasks follow immediately below the epic block. For later phases, the epic block is the whole entry — tasks are added during execution.

## Task Format (detailed wave only)

Each task is close to a ready-to-dispatch prompt: an implementer with zero context should be able to start within a minute of reading it.

```markdown
#### Task N.M.T: [Action-oriented name]

- [ ] Done

**Context:** [why this task exists; what already exists, with `file.go:42`-style
references into the current codebase]

**Implementation vision:** [the approach; key decisions already made; patterns
to follow or avoid; named edge cases and how each is handled]

**Files:**
- Create: `exact/path/to/file.go`
- Modify: `exact/path/to/existing.go:123-145`
- Test: `path/to/file_test.go`

**Verification:** [command to run + expected outcome]

**Done when:** [acceptance criteria]
```

Use `file:line` references when pointing into existing code. Paths are always exact for every file touched.

## ⛔ No Vague Tasks

The plan's deliverable is **decisions**, not code. A task without decisions is a plan failure:

| Pattern | Why it fails |
|---------|--------------|
| "Add appropriate error handling" | WHICH errors, handled HOW? Decide in the plan. |
| "Handle edge cases" | Name them, one by one. |
| "TBD" / "TODO" / "figure out during implementation" in detailed-wave tasks | The detailed wave admits no deferrals — that's what makes it dispatch-ready |
| Implementation vision that restates the task name | Vision = approach + decisions, not a paraphrase |
| Task referencing a contract no epic defines | Plan is internally inconsistent |

Deferrals ARE allowed in later-phase epics — that is the point of rolling wave. They are NOT allowed inside the detailed wave.

## Self-Review

After writing the complete plan, look at the spec with fresh eyes and check the plan against it. This is a checklist you run yourself — not a subagent dispatch.

| Check | What to verify |
|-------|----------------|
| **Spec coverage** | Skim each requirement in the spec. Point to an epic that covers it. List gaps. |
| **Vagueness scan** | Search detailed-wave tasks for the red flags in "No Vague Tasks". Fix any matches. |
| **Contract consistency** | Names, signatures, and schemas referenced across epics agree. A contract defined nowhere but used somewhere is a bug. |
| **Phase boundaries** | Every phase ends with working, verifiable software. |
| **Verification plausibility** | Detailed-wave verification commands target real paths and plausible outcomes. |

If you find issues, fix them inline. No need to re-review — just fix and move on.

**For high-stakes plans** (large sur