writing-plans
Creates comprehensive implementation plans with exact file paths, complete codeexamples, and verification steps for engineers with zero codebase context.
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.
| name | ring:writing-plans |
|---|---|
| description | | |
| trigger | | |
| skip_when | | |
| - Requirements still unclear → use ring | pre-dev-prd-creation first |
| - Already have a plan → use ring | executing-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 executeWARNING→ 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:
- Execute now →
ring:subagent-driven-development - Parallel session → user opens new session with
ring:executing-plans - 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.