writing-plans_skill

Overview

This skill generates detailed, test-first implementation plans from a spec or requirements document before any coding begins. It produces step-by-step, bite-sized tasks that assume the engineer has no repository context and limited test design skill. Plans include exact file paths, full code snippets, commands with expected output, and a clear save location so work can be executed or handed off reliably.

How this skill works

I inspect the spec or feature description and decompose it into atomic actions (2–5 minute steps) that follow TDD: write a failing test, run it, implement minimal code, run tests, commit. The plan always includes a required markdown header, exact file create/modify instructions, complete code examples, test commands with expected results, and explicit commit commands. At the end I save the plan to docs/plans/YYYY-MM-DD-<feature-name>.md and present execution handoff options.

When to use it

• Before writing any code for a multi-step feature or refactor
• When the implementer has little to no context about the codebase
• When you need reproducible, reviewable work units for parallel development
• When enforcing TDD and frequent, small commits is required
• When handing work to remote contributors or junior engineers

Best practices

• Start the plan with: "I'm using the writing-plans skill to create the implementation plan."
• Keep each step a single, verifiable action (2–5 minutes) following TDD
• Use exact file paths and complete code listings, not vague instructions
• Prefer minimal implementations to satisfy tests; avoid speculative features (YAGNI)
• Make frequent commits with clear messages and include expected test output in the plan

Example use cases

• Add a new API endpoint with request validation and tests, with exact files and test cases
• Implement a core algorithm change by first defining failing unit tests and minimal fixes
• Split a large feature into parallel tasks for multiple contributors, each with its own commitable steps
• Onboard a new engineer by giving them a complete, executable plan for their first contribution
• Convert an informal spec into a repeatable worktree saved plan for automated execution