Ring:writing Plans

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 — 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:

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

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:

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:

# [Feature Name] Implementation Plan

> **For implementers:** Use ring:executing-plans (rolling wave: dispatch each
> wave — a phase or one epic, your choice — as a workflow → review → user
> checkpoint → detail the next phase against the real code → repeat),
> ring:dispatching-workflows to run each phase as a reviewed multi-agent
> workflow (review + contrarian baked in), 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)

### 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]
**Status:** Pending

**Status:** lifecycle: Pending → Doing → Done | Failed. It is the write target for ring:running-dev-cycle epic checkpoints; ring:executing-plans may ignore it.

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.

#### 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:

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.

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

For high-stakes plans (large surface, multiple authors, critical path): also dispatch a plan-document reviewer subagent using the template in plan-document-reviewer-prompt.md.

Execution Handoff

After saving the plan, announce the save, then collect the execution choice using the question/ask tool the harness provides (e.g. AskUserQuestion in Claude Code). If no question tool is available, present the options as a prose prompt and ask which to use. The three options:

Plan complete and saved to docs/plans/<filename>.md. Pick how to execute it:

1. Rolling-Wave Execution (this session) — Use ring:executing-plans: you supervise while one workflow per wave-unit (a whole phase, or one epic at a time — you choose at start) implements its tasks; you review what returns, checkpoint, then elaborate the next phase into tasks against the real landed code, and repeat. Lightest: one supervised subagent per wave, reviewed after it returns. Best for iterative delivery with course-correction between waves.

2. Reviewed Multi-Agent Workflows (this session) — Use ring:dispatching-workflows: the same rolling wave, but each phase runs as a multi-agent workflow harness that implements, reviews, and runs an adversarial contrarian pass internally before returning verified work. Best when you want review and a contrarian baked into every wave, without the full gated cycle.

3. Subagent-Orchestrated (ring:running-dev-cycle) — lean backend cycle (Gate 0/8/9) with parallel specialist dispatch. Heaviest: full review pool per epic. Best for production work that must pass through the full review pool.

If Rolling-Wave chosen: Continue with ring:executing-plans in this session.

If Reviewed Multi-Agent Workflows chosen: Continue with ring:dispatching-workflows in this session.

If Subagent-Orchestrated chosen: Hand off to ring:running-dev-cycle, which owns implementation across the lean cycle (Gate 0 per task, Gates 8/9 per epic, phase boundaries per phase).

Verification Checklist

Before marking the plan complete:

• Plan language confirmed with user (prose only; structural tokens, paths, and code stay English)
• Plan header present (Goal, Architecture, Tech Stack, Phase Overview)
• Every phase ends in working, testable software
• Every epic has Goal, Scope, Dependencies, Done-when, Status
• Phase 1 epics fully broken into dispatch-ready tasks; later phases epic-level only
• No vague tasks in the detailed wave (no "appropriate", "TBD", unnamed edge cases)
• Code snippets only where the Code Snippet Policy justifies them
• Contract consistency across epics
• Self-review checklist applied
• Plan saved to docs/plans/YYYY-MM-DD-<feature-name>.md (or docs/pre-dev/{feature}/plan.md when invoked from pre-dev)
• Execution handoff offered

Worked Example

Goal: GET /transactions/:id returns a persisted transaction end-to-end Scope: internal/service/, internal/handler/ Dependencies: none Done when: integration test fetches a seeded transaction by ID; unknown ID returns 404 Status: Pending

Task 1.1.1: Implement GetTransactionByID service method

• Done

Context: TransactionRepository interface already exposes GetByID at internal/domain/repository.go:15. The service layer (internal/service/transaction_service.go) has no read path yet — only Create.

Implementation vision: Add GetByID(ctx, id) to transactionService, delegating to the repository. Follow the observability pattern used by Create (transaction_service.go:31-38): tracking from context, span around the call, HandleSpanError on failure. Propagate domain.ErrNotFound untouched — the handler layer maps it to 404; do not wrap it. No input validation here: ID format is validated at the handler.

Files:

• Modify: internal/service/transaction_service.go
• Test: internal/service/transaction_service_test.go

Verification: go test ./internal/service/... -run TestTransactionService_GetByID -v — found and not-found cases both pass; not-found asserts errors.Is(err, domain.ErrNotFound).

Done when: service returns the transaction for a known ID and domain.ErrNotFound for an unknown one, with span + log coverage matching the Create pattern.

Epic 2.1: Transaction list endpoint with cursor pagination

Goal: GET /transactions returns tenant-scoped pages of transactions Scope: internal/service/, internal/handler/, repository query layer Dependencies: Epic 1.1 (read path patterns established there) Done when: paginated listing works against seeded data; cursor round-trips; page size capped at 100 Status: Pending

(No tasks yet — elaborated by ring:executing-plans after Phase 1 lands, against the read-path patterns Phase 1 actually established.)