/writing-plans

name: ring:writing-plans
description: "Writing a rolling-wave phased implementation plan from a spec before coding: a phase-epic-task hierarchy where Phase 1 is detailed into dispatch-ready tasks and later phases stay epic-level for elaboration during execution. Use when a multi-file feature needs decomposition; runs after ring:exploring-codebases or pre-dev gates, hands off to ring:executing-plans or ring:running-dev-cycle. Skip for single-file changes or spikes."

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:planning-large-features (gates 0-6 artifacts) or ring:planning-small-features (gates 0-2 artifacts) — their 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.)

**Invoked from pre-dev:** when dispatched as the final gate of ring:planning-large-features or ring:planning-small-features, the spec inputs are the pre-dev artifacts — trd.md (plus feature-map.md, openapi.yaml, the schema file, and dependencies.md on the Large track). On Large, plan phases MUST mirror feature-map.md phases one-to-one. Output path is `docs/pre-dev/{feature}/plan.md`, overriding the default above; standalone invocations keep the default. plan.md is always a SINGLE document per feature: on multi-module topologies (monorepo fullstack / multi-repo), each epic carries one line `**Target:** backend | frontend | infra` (placed right before `**Status:**`); for multi-repo features the orchestrator copies plan.md into each repo and the local dev-cycle executes only epics whose Target matches that repo. No per-module plan splits.

Plan Language

Before authoring, ask which language the plan's **prose** should be written in — using the question/ask tool the harness provides (e.g. `AskUserQuestion` in Claude Code). Offer three options: **English** (default), **Brazilian Portuguese (pt-BR)**, **Spanish**. If the user skips or no question tool is available, default to English.

The choice covers narrative prose only — Goal, Architecture, Context, Implementation vision, and other descriptions. Everything a downstream skill or agent parses stays verbatim English regardless of choice: section headers and format keywords, `**Status:**` values (Pending/Doing/Done/Failed), Phase-Overview status cells (Detailed/Epic-level/Complete), `**Target:**` values, file paths, commands, code snippets, and identifiers. Translating those breaks ring:executing-plans and ring:running-dev-cycle status matching.

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 | A