From a6dcd2c95608d41e7b713842ad9963e41e9c590d Mon Sep 17 00:00:00 2001
From: Christian Nennemann <christian@nennemann.de>
Date: Sat, 4 Apr 2026 09:31:27 +0200
Subject: [PATCH] feat: add plan granularity constraint to plan-phase and
 creator

---
 agents/creator.md          | 11 ++++++++++-
 skills/plan-phase/SKILL.md | 40 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 50 insertions(+), 1 deletion(-)

diff --git a/agents/creator.md b/agents/creator.md
index 68e4ac0..b1080ca 100644
--- a/agents/creator.md
+++ b/agents/creator.md
@@ -46,8 +46,16 @@ For the full output format (including Mini-Reflect, Alternatives Considered, and
 | <option B> | <reason> |
 
 ### Changes
-1. **`path/file.ext`** — What changes and why
+1. **`path/file.ext:line`** — What changes and why
+   ```language
+   <target code state>
+   ```
+   **Verify:** `<command to confirm correctness>`
 2. **`path/test.ext`** — What tests to add
+   ```language
+   <test code>
+   ```
+   **Verify:** `<test command>`
 
 ### Test Strategy
 - <specific test cases>
@@ -72,6 +80,7 @@ For the full output format (including Mini-Reflect, Alternatives Considered, and
 - Name every file. The Maker needs exact paths.
 - Scope ruthlessly. Adjacent problems go under "Not Doing."
 - Include test strategy. No proposal is complete without it.
+- **Granularity:** Each change item must be a 2-5 minute task with exact file path, code block showing the target state, and a verify command. If an item would take >5 minutes, split it. If a non-trivial task has <2 items, you under-specified.
 - Any Confidence axis < 0.5? Flag it — the orchestrator may pause or escalate.
 
 ## Status Token
diff --git a/skills/plan-phase/SKILL.md b/skills/plan-phase/SKILL.md
index ea2e493..d8cabd2 100644
--- a/skills/plan-phase/SKILL.md
+++ b/skills/plan-phase/SKILL.md
@@ -118,6 +118,46 @@ When the Creator receives structured feedback from a prior cycle, the proposal m
 
 CRITICAL findings cannot be deferred or disputed — they must be fixed or the proposal will be rejected again.
 
+## Task Granularity
+
+Each change item in the Creator's proposal must be a **2-5 minute task** — specific enough that the Maker can implement it without interpretation.
+
+### Requirements per Change Item
+
+Every item in the `### Changes` section must include:
+
+1. **Exact file path** — `src/auth/handler.ts`, not "the auth module"
+2. **What to change** — a code block showing the target state or transformation
+3. **How to verify** — a command or check that confirms correctness
+
+### Good Example
+
+```markdown
+1. **`src/auth/handler.ts:48`** — Add input length validation before token processing
+   ```typescript
+   if (!token || token.trim().length === 0) {
+     throw new ValidationError('Token must not be empty');
+   }
+   ```
+   **Verify:** `npm test -- --grep "empty token"` passes
+```
+
+### Bad Example
+
+```markdown
+1. **Auth module** — Fix the validation logic
+```
+
+This is too vague. Which file? Which function? What does "fix" mean? The Maker will guess.
+
+### Granularity Check
+
+- If a single change item would take **>5 minutes**, split it into smaller items
+- If a non-trivial task has **<2 change items**, it is under-specified — the Creator missed something
+- Each item should touch **1-2 files** at most. Cross-cutting changes need separate items per file.
+
+---
+
 ## Explorer Skip Conditions
 
 Not every task needs Explorer research. Use this decision table: