Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions skills/writing-plans/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,23 @@ Before defining tasks, map out which files will be created or modified and what

This structure informs the task decomposition. Each task should produce self-contained changes that make sense independently.

## TDD Structure Is Mandatory

<HARD-GATE>
Every task that introduces or changes behavior MUST follow RED-GREEN-REFACTOR structure: write failing test → verify it fails → write minimal implementation → verify it passes → refactor → commit. No exceptions.
</HARD-GATE>

**This includes tasks that feel "untestable":**
- **Configuration/tooling setup** — write a smoke test that imports/runs the config and asserts expected values
- **Build pipeline changes** — write a test that runs the build and checks output
- **Scaffolding/boilerplate** — write a test that verifies the scaffold works (e.g., app starts, route responds)

If a task genuinely cannot have a test (e.g., "create .gitignore"), it must not contain any functional code. For tasks that only refactor, format, or make mechanically equivalent changes, rely on running the existing test suite rather than writing a new failing test. The moment a task introduces or changes logic, behavior, or integration — it needs a new or updated test first.

### Anti-Pattern: "Tests at the end"

Plans that put all tests in a final "Add tests" task are NOT TDD. Tests written after implementation prove nothing — they pass immediately and you never see them catch the bug. Each task must have its own test step BEFORE its implementation step.

## Bite-Sized Task Granularity

**Each step is one action (2-5 minutes):**
Expand Down
1 change: 1 addition & 0 deletions skills/writing-plans/plan-document-reviewer-prompt.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ Task tool (general-purpose):
| Completeness | TODOs, placeholders, incomplete tasks, missing steps |
| Spec Alignment | Plan covers spec requirements, no major scope creep |
| Task Decomposition | Tasks have clear boundaries, steps are actionable |
| TDD Structure | Every task that introduces or changes behavior follows RED-GREEN-REFACTOR: write failing test → verify fails → implement → verify passes → refactor → commit. Refactor-only tasks may rely on existing tests. Tests must NOT be deferred to a final task. Flag any task that has implementation before tests. |
| Buildability | Could an engineer follow this plan without getting stuck? |

## Calibration
Expand Down