writing-planslisted

# Writing Plans ## What a plan is for A plan is documentation for whoever implements it, and that implementer has zero context for this codebase. It might be a fresh session, a teammate, or you in a month. So everything they need goes on the page: which files to touch, the actual code, how to test it, and how to know it worked. If the plan says "add validation" instead of showing the validation, the plan has failed, because the executor now has to guess, and guessing is where plans go wrong. Assume the executor is a capable developer who knows almost nothing about this project's tools, conventions, or domain, and isn't a strong test designer. Write for that person. Spell out the boundaries; stay quiet about internals they can figure out. The habits that keep plans executable: DRY, YAGNI, test-first, small tasks, frequent commits. **Announce at start:** "I'm using the writing-plans skill to create the implementation plan." Think the approach through before you write, including the alternatives and edge cases, so the plan reflects a considered design rather than the first idea. ## Where the plan is saved `--output-dir <path>` (parse with `--output-dir\s+(\S+)`): - **Provided:** create the directory if missing, write to `{OUTPUT_DIR}/PLAN.md`. - **Standalone:** write to `docs/plans/YYYY-MM-DD-PLAN-<feature>.md`. ## Task size Each step is one action, roughly 2-5 minutes. That granularity is what lets an executor make steady, verifiable progress instead of taking a large