writing-plans

Creates comprehensive implementation plans with exact file paths, complete codeexamples, and verification steps for engineers with zero codebase context.

⭐25stars🔀1forks📁View on GitHub🕐Updated Dec 31, 2025⬇️3downloads

When & Why to Use This Skill

This Claude skill automates the generation of highly detailed, executable implementation plans for software engineering projects. By providing exact file paths, complete code examples, and specific verification steps, it bridges the gap between high-level design and actual coding, allowing engineers—even those unfamiliar with the codebase—to begin development immediately with full context and precision.

Use Cases

  • Technical Task Breakdown: Transforming high-level design documents (PRDs/TRDs) into a series of bite-sized, 2-5 minute coding tasks with precise instructions and file paths.
  • Developer Onboarding: Generating comprehensive 'zero-context' implementation guides that allow new team members to contribute to complex features without extensive manual knowledge transfer.
  • AI-Driven Development: Creating structured, validated work plans that serve as a roadmap for specialized sub-agents to execute autonomous code generation and testing.
  • Complex Refactoring: Mapping out multi-file code changes with built-in verification checkpoints and failure recovery steps to ensure system stability during architectural shifts.
namering:writing-plans
description|
trigger|
skip_when|
- Requirements still unclear → use ringpre-dev-prd-creation first
- Already have a plan → use ringexecuting-plans
after[brainstorming, ring:pre-dev-trd-creation]
before[ring:executing-plans, ring:subagent-driven-development]
similar[brainstorming]

Writing Plans

Overview

This skill dispatches a specialized agent to write comprehensive implementation plans for engineers with zero codebase context.

Announce at start: "I'm using the ring:writing-plans skill to create the implementation plan."

Context: This should be run in a dedicated worktree (created by ring:brainstorming skill).

The Process

Step 1: Dispatch Write-Plan Agent

Dispatch via Task(subagent_type: "ring:write-plan", model: "opus") with:

  • Instructions to create bite-sized tasks (2-5 min each)
  • Include exact file paths, complete code, verification steps
  • Save to docs/plans/YYYY-MM-DD-<feature-name>.md

Step 2: Validate Plan

After the plan is saved, validate it:

python3 default/lib/validate-plan-precedent.py docs/plans/YYYY-MM-DD-<feature>.md

Interpretation:

  • PASS → Plan is safe to execute
  • WARNING → Plan has issues to address
    • Review the warnings in the output
    • Update plan to address the issues
    • Re-run validation until PASS

Step 3: Ask User About Execution

Ask via AskUserQuestion: "Execute now?" Options:

  1. Execute now → ring:subagent-driven-development
  2. Parallel session → user opens new session with ring:executing-plans
  3. Save for later → report location and end

Why Use an Agent?

Context preservation (reading many files keeps supervisor clean) | Model power (Opus for comprehensive planning) | Separation of concerns (supervisor orchestrates, agent plans)

What the Agent Does

Explore codebase → identify files → break into bite-sized tasks (2-5 min) → write complete code → include exact commands → add review checkpoints → verify Zero-Context Test → save to docs/plans/YYYY-MM-DD-<feature>.md → report back

Requirements for Plans

Every plan: Header (goal, architecture, tech stack) | Verification commands with expected output | Exact file paths (never "somewhere in src") | Complete code (never "add validation here") | Bite-sized steps with verification | Failure recovery | Review checkpoints | Zero-Context Test | Recommended agents per task

Agent Selection

Task Type Agent
Backend API/services backend-engineer-{golang,typescript}
Frontend/BFF frontend-bff-engineer-typescript
Infra/CI/CD ring:devops-engineer
Testing ring:qa-analyst
Reliability ring:sre
Fallback general-purpose (built-in, no prefix)

Execution Options Reference

Option Description
Execute now Fresh subagent per task, code review between tasks → ring:subagent-driven-development
Parallel session User opens new session, batch execution with human review → ring:executing-plans
Save for later Plan at docs/plans/YYYY-MM-DD-<feature>.md, manual review before execution

Required Patterns

This skill uses these universal patterns:

  • State Tracking: See skills/shared-patterns/state-tracking.md
  • Failure Recovery: See skills/shared-patterns/failure-recovery.md
  • Exit Criteria: See skills/shared-patterns/exit-criteria.md
  • TodoWrite: See skills/shared-patterns/todowrite-integration.md

Apply ALL patterns when using this skill.