Writing Implementation Plans

Problem: the gap between intent and change

In real codebases, a short requirement often implies file edits, test coverage, tooling assumptions, and commit strategy. If a model or a new engineer starts coding directly, common failures include vague instructions like “add validation”, missing failure-to-pass test loops, and large tasks that are hard to review or revert. writing-plans treats an implementation plan as an executable artifact, not a product description.

How it works: plans as 2–5 minute actions

The skill expects the plan to be written for a competent developer who does not know the repository or domain. It should explicitly record:
- the exact file paths each task touches
- complete code, not summaries such as “add checks”
- runnable bash commands, including git add and git commit steps
- test cases, expected failures, and expected passing behavior
- engineering constraints such as DRY, YAGNI, TDD, and frequent commits

Plans are saved as docs/plans/YYYY-MM-DD-.md. After saving, the skill offers two execution paths: run tasks in the current session with a subagent for each task, or switch to a separate session to execute in batches with checkpoints.

Boundaries

It fits development work that needs reviewable, handoff-friendly, incremental implementation, especially when tests and file paths are explicit. It is not ideal for one-off scripts, purely verbal design options, or exploratory work without clear acceptance criteria.