[Issue #29] Add discovery step to /plan-issues skill #81

HugoNijhuis · 2026-01-10T18:19:27Z

HugoNijhuis commented

2026-01-10 18:19:27 +00:00

Summary

Added a discovery phase to the roadmap-planning skill and plan-issues command. The planning process previously jumped directly from understanding a feature to breaking it down into issues, which led to proposing issues without understanding user workflows.

Changes

Added discovery phase (step 2) to skills/roadmap-planning/SKILL.md with structured questions about user, goal, workflow, current state, and MVP
Updated commands/plan-issues.md to include discovery phase before proposing issues
Issues are now derived from identified workflow gaps, not guessed

Discovery Phase Questions

Question	Purpose
Who is the user?	Specific persona, not generic "users"
What's their goal?	The job they're trying to accomplish
What's the workflow?	Step-by-step actions to reach goal
What exists today?	Current state and gaps
What's the MVP?	Minimum to deliver value

Closes #29

## Summary Added a discovery phase to the roadmap-planning skill and plan-issues command. The planning process previously jumped directly from understanding a feature to breaking it down into issues, which led to proposing issues without understanding user workflows. ## Changes - Added discovery phase (step 2) to `skills/roadmap-planning/SKILL.md` with structured questions about user, goal, workflow, current state, and MVP - Updated `commands/plan-issues.md` to include discovery phase before proposing issues - Issues are now derived from identified workflow gaps, not guessed ## Discovery Phase Questions | Question | Purpose | |----------|---------| | Who is the user? | Specific persona, not generic "users" | | What's their goal? | The job they're trying to accomplish | | What's the workflow? | Step-by-step actions to reach goal | | What exists today? | Current state and gaps | | What's the MVP? | Minimum to deliver value | Closes #29

HugoNijhuis added 1 commit 2026-01-10 18:19:28 +00:00

Add discovery phase to /plan-issues workflow 6b57102410

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 <noreply@anthropic.com>

HugoNijhuis commented

2026-01-10 18:21:16 +00:00

AI Code Review

This is an automated review generated by the code-reviewer agent.

Summary

The PR adds a structured discovery phase to the plan-issues workflow, addressing the problem of jumping directly from feature understanding to issue creation without understanding user workflows. The changes are well-documented and provide clear guidance on workflow analysis before creating issues.

Findings

Code Quality

Clear structure with numbered steps that flow logically
Good use of tables to present discovery questions concisely
Instructions are actionable with specific examples
Consistent formatting between the command and skill files
The walkthrough template provides concrete guidance

Potential Bugs

No logic errors identified - these are documentation changes
The workflow steps are clear and complete

Security Concerns

No security concerns - documentation-only changes

Style Notes

Consistent with existing codebase conventions
Good use of markdown formatting (tables, bullet points, numbered lists)
Inline explanations enhance clarity

Test Coverage

Not applicable for documentation changes
The discovery phase questions are testable in practice through the workflow itself

Verdict

LGTM

This change directly addresses issue #29 by adding a crucial discovery step that will prevent poorly-scoped issues. The structured questions (Who, What, Workflow, Current State, MVP) provide clear guidance for understanding user needs before proposing solutions. The addition of "Addresses gap" fields in the issue plan template ensures traceability from workflow gaps to proposed issues.

## AI Code Review > This is an automated review generated by the code-reviewer agent. ### Summary The PR adds a structured discovery phase to the plan-issues workflow, addressing the problem of jumping directly from feature understanding to issue creation without understanding user workflows. The changes are well-documented and provide clear guidance on workflow analysis before creating issues. ### Findings #### Code Quality - Clear structure with numbered steps that flow logically - Good use of tables to present discovery questions concisely - Instructions are actionable with specific examples - Consistent formatting between the command and skill files - The walkthrough template provides concrete guidance #### Potential Bugs - No logic errors identified - these are documentation changes - The workflow steps are clear and complete #### Security Concerns - No security concerns - documentation-only changes #### Style Notes - Consistent with existing codebase conventions - Good use of markdown formatting (tables, bullet points, numbered lists) - Inline explanations enhance clarity #### Test Coverage - Not applicable for documentation changes - The discovery phase questions are testable in practice through the workflow itself ### Verdict **LGTM** This change directly addresses issue #29 by adding a crucial discovery step that will prevent poorly-scoped issues. The structured questions (Who, What, Workflow, Current State, MVP) provide clear guidance for understanding user needs before proposing solutions. The addition of "Addresses gap" fields in the issue plan template ensures traceability from workflow gaps to proposed issues.

HugoNijhuis merged commit 1a6c962f1d into main

2026-01-10 18:21:20 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: flowmade-one/architecture#81