From 6b57102410baa721f74ccdae0641975d8780d3c3 Mon Sep 17 00:00:00 2001 From: Hugo Nijhuis Date: Sat, 10 Jan 2026 19:19:16 +0100 Subject: [PATCH] Add discovery phase to /plan-issues workflow The planning process previously jumped directly from understanding a feature to breaking it down into issues. This led to proposing issues without first understanding the user's actual workflow and where the gaps are. Added a discovery phase that requires walking through: - Who is the specific user - What is their goal - Step-by-step workflow to reach the goal - What exists today - Where the workflow breaks or has gaps - What's the MVP Issues are now derived from workflow gaps rather than guessing. Closes #29 Co-Authored-By: Claude Opus 4.5 --- commands/plan-issues.md | 27 +++++++++++++++++++++------ skills/roadmap-planning/SKILL.md | 32 +++++++++++++++++++++++++++++--- 2 files changed, 50 insertions(+), 9 deletions(-) diff --git a/commands/plan-issues.md b/commands/plan-issues.md index 994a335..85c7bce 100644 --- a/commands/plan-issues.md +++ b/commands/plan-issues.md @@ -16,12 +16,24 @@ context: fork 3. **Identify job**: Which job to be done does this enable? 4. **Understand the feature**: Analyze what "$1" involves 5. **Explore the codebase** if needed to understand context -6. **Break down** into discrete, actionable issues: + +6. **Discovery phase**: Before proposing issues, walk through the user workflow: + - Who is the specific user? + - What is their goal? + - What is their step-by-step workflow to reach that goal? + - What exists today? + - Where does the workflow break or have gaps? + - What's the MVP that delivers value? + + Present this as a workflow walkthrough before proposing any issues. + +7. **Break down** into discrete, actionable issues: + - Derive issues from the workflow gaps identified in discovery - Each issue should be independently completable - Clear dependencies between issues - Appropriate scope (not too big, not too small) -7. **Present the plan** (include vision alignment if vision exists): +8. **Present the plan** (include vision alignment if vision exists): ``` ## Proposed Issues for: $1 @@ -30,12 +42,15 @@ context: fork Supports: [Milestone/Goal name] 1. [Title] - Brief description + Addresses gap: [which workflow gap this solves] Dependencies: none 2. [Title] - Brief description + Addresses gap: [which workflow gap this solves] Dependencies: #1 3. [Title] - Brief description + Addresses gap: [which workflow gap this solves] Dependencies: #1, #2 ``` @@ -45,7 +60,7 @@ context: fork - This should be added as a non-goal - Proceed anyway (with justification) -8. **Ask for approval** before creating issues -9. **Create issues** in dependency order (blockers first) -10. **Link dependencies** using `tea issues deps add ` for each dependency -11. **Present summary** with links to created issues and dependency graph +9. **Ask for approval** before creating issues +10. **Create issues** in dependency order (blockers first) +11. **Link dependencies** using `tea issues deps add ` for each dependency +12. **Present summary** with links to created issues and dependency graph diff --git a/skills/roadmap-planning/SKILL.md b/skills/roadmap-planning/SKILL.md index cab87cc..6bd6512 100644 --- a/skills/roadmap-planning/SKILL.md +++ b/skills/roadmap-planning/SKILL.md @@ -15,7 +15,33 @@ How to plan features and create issues for implementation. - Who benefits and how? - What's the success criteria? -### 2. Break Down the Work +### 2. Discovery Phase + +Before breaking down work into issues, understand the user's workflow: + +| Question | Why It Matters | +|----------|----------------| +| **Who** is the user? | Specific persona, not "users" | +| **What's their goal?** | The job they're trying to accomplish | +| **What's their workflow?** | Step-by-step actions to reach the goal | +| **What exists today?** | Current state and gaps | +| **What's the MVP?** | Minimum to deliver value | + +**Walk through the workflow step by step:** +1. User starts at: [starting point] +2. User does: [action 1] +3. System responds: [what happens] +4. User does: [action 2] +5. ... continue until goal is reached + +**Identify the gaps:** +- Where does the workflow break today? +- Which steps are missing or painful? +- What's the smallest change that unblocks value? + +**Derive issues from workflow gaps** - not from guessing what might be needed. Each issue should address a specific gap in the user's workflow. + +### 3. Break Down the Work - Identify distinct components - Define boundaries between pieces - Aim for issues that are: @@ -23,12 +49,12 @@ How to plan features and create issues for implementation. - Independently testable - Clear in scope -### 3. Identify Dependencies +### 4. Identify Dependencies - Which pieces must come first? - What can be parallelized? - Are there external blockers? -### 4. Create Issues +### 5. Create Issues - Follow issue-writing patterns - Reference dependencies explicitly - Use consistent labeling -- 2.49.1