# Writing Plans

> Create detailed implementation plans with bite-sized tasks for engineers with zero codebase context

- Skill: `bobmatnyc/writing-plans` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds add bobmatnyc/writing-plans`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bobmatnyc/writing-plans/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: bobmatnyc (https://skillmd.com/u/bobmatnyc)
- Updated: 2026-08-19
- Page: https://skillmd.com/skills/bobmatnyc/writing-plans

---


# Writing Plans

## Overview

Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.

Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.

**Announce at start:** "I'm using the Writing Plans skill to create the implementation plan."

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

**Save plans to:** `docs/plans/YYYY-MM-DD-<feature-name>.md`

## Quick Reference

**Plan header template:** See [Plan Structure & Templates](references/plan-structure-templates.md#standard-plan-document-header)

**Task template:** See [Plan Structure & Templates](references/plan-structure-templates.md#task-template-structure)

**Granularity guide:** Each step = 2-5 minutes. See [Best Practices](references/best-practices.md#bite-sized-task-granularity)

## Core Principles

- **Exact file paths always** - Not "in the user module" but "`src/models/user.py`"
- **Complete code in plan** - Not "add validation" but show the validation code
- **Exact commands with expected output** - "`pytest tests/file.py -v`" with what you'll see
- **Reference relevant skills** - Use @ syntax: `@skills/category/skill-name`
- **DRY, YAGNI, TDD, frequent commits** - Every task follows this pattern

For detailed guidance: [Best Practices & Guidelines](references/best-practices.md)

## Execution Handoff

After saving the plan, offer execution choice:

**"Plan complete and saved to `docs/plans/<filename>.md`. Two execution options:**

**1. Subagent-Driven (this session)** - I dispatch fresh subagent per task, review between tasks, fast iteration

**2. Parallel Session (separate)** - Open new session with executing-plans, batch execution with checkpoints

**Which approach?"**

**If Subagent-Driven chosen:**
- Use @skills/collaboration/subagent-driven-development
- Stay in this session
- Fresh subagent per task + code review

**If Parallel Session chosen:**
- Guide them to open new session in worktree
- New session uses @skills/collaboration/executing-plans

## Remember

- Write for zero-context engineers (specify everything)
- Complete code blocks, not instructions
- Exact commands with expected output
- Test first, then implement, then commit
- Reference existing patterns in codebase
- Keep tasks bite-sized (2-5 minutes each)

**Need examples?** See [Plan Structure & Templates](references/plan-structure-templates.md) for complete task examples.

**Need patterns?** See [Best Practices](references/best-practices.md) for error handling, logging, test design, and more.