sdlc-framework 1.0.2 → 2.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +41 -16
- package/bin/install.js +6 -5
- package/package.json +2 -2
- package/src/commands/close.md +21 -7
- package/src/commands/debug.md +2 -2
- package/src/commands/discuss.md +81 -0
- package/src/commands/fast.md +50 -5
- package/src/commands/help.md +15 -10
- package/src/commands/impl.md +2 -2
- package/src/commands/init.md +21 -5
- package/src/commands/review.md +2 -2
- package/src/commands/spec.md +2 -2
- package/src/commands/status.md +57 -91
- package/src/commands/transition.md +99 -0
- package/src/commands/verify.md +2 -2
- package/src/references/prompt-detection.md +1 -1
- package/src/templates/PRD.md +89 -0
- package/src/workflows/close-phase.md +1 -1
- package/src/workflows/discuss-phase.md +195 -0
- package/src/workflows/fast-forward.md +58 -7
- package/src/workflows/init-project.md +1 -1
- package/src/workflows/status-session.md +206 -0
- package/src/workflows/transition-phase.md +3 -3
- package/src/commands/hotfix.md +0 -99
- package/src/commands/milestone.md +0 -136
- package/src/commands/pause.md +0 -115
- package/src/commands/resume.md +0 -103
- package/src/workflows/hotfix-flow.md +0 -190
- package/src/workflows/milestone-management.md +0 -169
- package/src/workflows/pause-work.md +0 -153
- package/src/workflows/resume-project.md +0 -159
package/src/commands/status.md
CHANGED
|
@@ -1,118 +1,84 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: sdlc:status
|
|
3
|
-
description: "Show loop position and
|
|
4
|
-
|
|
3
|
+
description: "Show loop position, pause/resume sessions, and force next action"
|
|
4
|
+
argument-hint: "[pause [reason] | resume [handoff-path]]"
|
|
5
|
+
allowed-tools: [Read, Write, Bash, Glob, Grep, AskUserQuestion]
|
|
5
6
|
---
|
|
6
7
|
|
|
7
8
|
<objective>
|
|
8
|
-
Show exactly where you are in the SDLC loop
|
|
9
|
+
Show exactly where you are in the SDLC loop. Optionally pause (save context) or resume (restore context). One command for all session awareness.
|
|
9
10
|
|
|
10
|
-
**When to use:**
|
|
11
|
+
**When to use:**
|
|
12
|
+
- No argument: see loop position, progress, and forced next action.
|
|
13
|
+
- `pause`: save session context before a break. Creates HANDOFF.md.
|
|
14
|
+
- `resume`: restore session context after a break. Reads HANDOFF.md.
|
|
11
15
|
|
|
12
16
|
**What it does:**
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
4. Force exactly ONE next action with an explanation of what it does and why.
|
|
17
|
+
- **No argument:** Read STATE.md, display visual loop diagram, progress bar, blockers, and force ONE next action.
|
|
18
|
+
- **pause:** Gather session context, create HANDOFF.md, optionally WIP commit. Tell user to run `/sdlc:status resume` when they return.
|
|
19
|
+
- **resume:** Read HANDOFF.md, display restored context, verify git state, archive handoff, force ONE next action.
|
|
17
20
|
|
|
18
|
-
**What happens next:** The forced next action. No choices.
|
|
21
|
+
**What happens next:** The forced next action. No choices — the state machine decides.
|
|
19
22
|
</objective>
|
|
20
23
|
|
|
21
24
|
<execution_context>
|
|
25
|
+
@~/.claude/sdlc-framework/workflows/status-session.md
|
|
22
26
|
@.sdlc/STATE.md
|
|
23
27
|
@.sdlc/ROADMAP.md
|
|
24
28
|
</execution_context>
|
|
25
29
|
|
|
26
30
|
<context>
|
|
27
|
-
|
|
31
|
+
$ARGUMENTS — empty, "pause [reason]", or "resume [handoff-path]".
|
|
28
32
|
|
|
29
|
-
Read .sdlc/STATE.md for current loop position
|
|
30
|
-
Read .sdlc/ROADMAP.md for milestone
|
|
33
|
+
Read .sdlc/STATE.md for current loop position.
|
|
34
|
+
Read .sdlc/ROADMAP.md for milestone progress.
|
|
31
35
|
</context>
|
|
32
36
|
|
|
33
37
|
<process>
|
|
38
|
+
Follow workflow: @~/.claude/sdlc-framework/workflows/status-session.md
|
|
39
|
+
|
|
34
40
|
Step-by-step:
|
|
35
41
|
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
3. **Display project context**
|
|
65
|
-
- Show:
|
|
66
|
-
```
|
|
67
|
-
Milestone: {name} ({completed_phases}/{total_phases} phases)
|
|
68
|
-
Phase: {name}
|
|
69
|
-
Plan: {name or "none — run /sdlc:spec"}
|
|
70
|
-
```
|
|
71
|
-
|
|
72
|
-
4. **Show progress bar**
|
|
73
|
-
- Calculate completion percentage from ROADMAP.md.
|
|
74
|
-
- Display:
|
|
75
|
-
```
|
|
76
|
-
Progress: [████████░░░░░░░░░░░░] 40% (4/10 plans completed)
|
|
77
|
-
```
|
|
78
|
-
|
|
79
|
-
5. **Show blockers and deferred issues**
|
|
80
|
-
- If blockers exist in STATE.md:
|
|
81
|
-
```
|
|
82
|
-
BLOCKERS:
|
|
83
|
-
- {blocker 1}
|
|
84
|
-
- {blocker 2}
|
|
85
|
-
```
|
|
86
|
-
- If deferred issues exist:
|
|
87
|
-
```
|
|
88
|
-
DEFERRED:
|
|
89
|
-
- {issue 1}
|
|
90
|
-
- {issue 2}
|
|
91
|
-
```
|
|
92
|
-
- If none: "No blockers. No deferred issues."
|
|
93
|
-
|
|
94
|
-
6. **Force ONE next action with explanation**
|
|
95
|
-
- Determine the next action from loop_position (same logic as /sdlc:resume).
|
|
96
|
-
- Explain what that action DOES and WHY it is next:
|
|
97
|
-
|
|
98
|
-
```
|
|
99
|
-
NEXT ACTION REQUIRED: /sdlc:impl
|
|
100
|
-
|
|
101
|
-
What it does: Implements the current plan by writing code with subagent workers.
|
|
102
|
-
Why it is next: The spec phase is complete. The plan has been approved.
|
|
103
|
-
Your implementation will be verified in the next step.
|
|
104
|
-
```
|
|
105
|
-
|
|
106
|
-
- Junior-friendly: use plain language. Assume the reader has never used the framework.
|
|
42
|
+
### If no argument: SHOW STATUS
|
|
43
|
+
|
|
44
|
+
1. Read .sdlc/STATE.md. If missing: "Run /sdlc:init first." Stop.
|
|
45
|
+
2. Display visual loop diagram with current position highlighted using `[PHASE]` brackets.
|
|
46
|
+
3. Display project context: milestone, phase, plan, progress bar.
|
|
47
|
+
4. Display blockers and deferred issues (or "None").
|
|
48
|
+
5. Force ONE next action from loop_position with plain-language explanation.
|
|
49
|
+
|
|
50
|
+
### If "pause": SAVE SESSION
|
|
51
|
+
|
|
52
|
+
1. Read .sdlc/STATE.md to get current loop position and active work.
|
|
53
|
+
2. Gather session context: git status, recent commits, in-progress tasks, decisions, blockers.
|
|
54
|
+
3. Ask user: "Anything to remember for next session not already in files?"
|
|
55
|
+
4. Create .sdlc/HANDOFF.md with full session context.
|
|
56
|
+
5. Offer WIP commit if uncommitted changes exist.
|
|
57
|
+
6. Update STATE.md: add paused_at timestamp, history entry. Do NOT change loop_position.
|
|
58
|
+
7. Output: "Session saved. Run /sdlc:status resume when you return."
|
|
59
|
+
|
|
60
|
+
### If "resume": RESTORE SESSION
|
|
61
|
+
|
|
62
|
+
1. Locate handoff: from $ARGUMENTS path, STATE.md handoff_file field, or .sdlc/HANDOFF.md.
|
|
63
|
+
2. If no handoff: fall back to STATE.md only. Display: "No handoff found. Resuming from state."
|
|
64
|
+
3. Display restored context: loop position, work in progress, decisions, blockers.
|
|
65
|
+
4. Verify git state matches handoff (warn on mismatch). Pop stash if applicable.
|
|
66
|
+
5. Archive consumed handoff to .sdlc/HANDOFF-{timestamp}.md.archived.
|
|
67
|
+
6. Clean up STATE.md session fields (remove paused_at).
|
|
68
|
+
7. Force ONE next action. Output ends with NEXT ACTION REQUIRED.
|
|
107
69
|
</process>
|
|
108
70
|
|
|
109
71
|
<success_criteria>
|
|
110
|
-
- [ ]
|
|
111
|
-
- [ ]
|
|
112
|
-
- [ ]
|
|
113
|
-
- [ ]
|
|
114
|
-
- [ ]
|
|
115
|
-
- [ ]
|
|
116
|
-
- [ ]
|
|
117
|
-
- [ ]
|
|
72
|
+
- [ ] No-arg: visual loop diagram displayed with current position
|
|
73
|
+
- [ ] No-arg: progress bar and blockers shown
|
|
74
|
+
- [ ] No-arg: exactly ONE next action forced with explanation
|
|
75
|
+
- [ ] Pause: session context gathered (git, tasks, decisions, blockers)
|
|
76
|
+
- [ ] Pause: HANDOFF.md created with complete context
|
|
77
|
+
- [ ] Pause: WIP commit offered if uncommitted changes exist
|
|
78
|
+
- [ ] Pause: output states "Run /sdlc:status resume when you return"
|
|
79
|
+
- [ ] Resume: handoff located and context restored
|
|
80
|
+
- [ ] Resume: git state verified against handoff
|
|
81
|
+
- [ ] Resume: handoff archived after consumption
|
|
82
|
+
- [ ] Resume: output ends with NEXT ACTION REQUIRED: /sdlc:{action}
|
|
83
|
+
- [ ] No menus, no options — one clear path forward
|
|
118
84
|
</success_criteria>
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: sdlc:transition
|
|
3
|
+
description: Transition to the next phase after all plans in a phase complete
|
|
4
|
+
argument-hint: "[phase-name]"
|
|
5
|
+
allowed-tools: [Read, Write, Bash, Glob, Grep, Edit, AskUserQuestion]
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
<objective>
|
|
9
|
+
Transition from the current phase to the next phase within a milestone. Verify phase completeness, update project state, commit the phase, and advance to the next phase.
|
|
10
|
+
|
|
11
|
+
**When to use:** After /sdlc:close detects the last plan in a phase is done. Can also be run manually to force a phase transition.
|
|
12
|
+
|
|
13
|
+
**What it does:**
|
|
14
|
+
1. Verify all plans in the current phase are complete (every SPEC has a SUMMARY, all ACs passed).
|
|
15
|
+
2. Cross-check STATE.md, PROJECT.md, and ROADMAP.md for consistency.
|
|
16
|
+
3. Update PROJECT.md with implemented, superseded, and newly discovered requirements.
|
|
17
|
+
4. Advance state to the next phase (or trigger milestone completion if this was the last phase).
|
|
18
|
+
5. Update ROADMAP.md with phase completion details.
|
|
19
|
+
6. Create a git commit marking the phase boundary.
|
|
20
|
+
|
|
21
|
+
**What happens next:**
|
|
22
|
+
- Next phase exists: Framework directs you to /sdlc:spec for the first plan of the new phase.
|
|
23
|
+
- Last phase in milestone: Framework directs you to /sdlc:close for milestone finalization.
|
|
24
|
+
|
|
25
|
+
**Critical rule:** No phase transitions without completeness verification. Every plan must have a summary. Every AC must pass. State inconsistencies are surfaced and resolved before advancing.
|
|
26
|
+
</objective>
|
|
27
|
+
|
|
28
|
+
<execution_context>
|
|
29
|
+
@~/.claude/sdlc-framework/workflows/transition-phase.md
|
|
30
|
+
@.sdlc/STATE.md
|
|
31
|
+
@.sdlc/ROADMAP.md
|
|
32
|
+
@.sdlc/PROJECT.md
|
|
33
|
+
</execution_context>
|
|
34
|
+
|
|
35
|
+
<context>
|
|
36
|
+
$ARGUMENTS — optional phase name to transition from. If not provided, read from .sdlc/STATE.md current_phase field.
|
|
37
|
+
|
|
38
|
+
Read these files:
|
|
39
|
+
- .sdlc/STATE.md — current phase, milestone, loop position.
|
|
40
|
+
- .sdlc/ROADMAP.md — phase list, plan counts, next phase identification.
|
|
41
|
+
- .sdlc/PROJECT.md — requirements to update based on completed work.
|
|
42
|
+
- All SUMMARY.md files in the completing phase's directory.
|
|
43
|
+
</context>
|
|
44
|
+
|
|
45
|
+
<process>
|
|
46
|
+
Follow workflow: @~/.claude/sdlc-framework/workflows/transition-phase.md
|
|
47
|
+
|
|
48
|
+
Step-by-step:
|
|
49
|
+
|
|
50
|
+
1. **Verify phase completeness**
|
|
51
|
+
- Read .sdlc/STATE.md. Confirm loop_position is CLOSE ✓. If not, warn: "Loop not closed. Run /sdlc:close first."
|
|
52
|
+
- List all SPEC and SUMMARY files in .sdlc/phases/{current_phase}/.
|
|
53
|
+
- Every SPEC must have a corresponding SUMMARY. If not, block: "Phase transition blocked. Plan {N} has a spec but no summary."
|
|
54
|
+
- Every SUMMARY must show all ACs passed. If not, block: "Phase transition blocked. Plan {N} has failing ACs."
|
|
55
|
+
|
|
56
|
+
2. **Verify state consistency**
|
|
57
|
+
- Cross-check STATE.md, PROJECT.md, and ROADMAP.md:
|
|
58
|
+
- STATE.md current_milestone matches ROADMAP.md in-progress milestone.
|
|
59
|
+
- STATE.md current_phase matches the phase being completed.
|
|
60
|
+
- Prior phases in this milestone are all COMPLETE.
|
|
61
|
+
- If inconsistency found: display details, offer to auto-fix, ask for confirmation.
|
|
62
|
+
|
|
63
|
+
3. **Update PROJECT.md**
|
|
64
|
+
- Read all SUMMARY.md files from the completing phase.
|
|
65
|
+
- Mark addressed requirements as IMPLEMENTED.
|
|
66
|
+
- Mark contradicted requirements as SUPERSEDED.
|
|
67
|
+
- Add newly discovered requirements as NOT STARTED.
|
|
68
|
+
- Display proposed changes and ask user to confirm before writing.
|
|
69
|
+
|
|
70
|
+
4. **Advance state to next phase**
|
|
71
|
+
- Read ROADMAP.md to identify the next phase.
|
|
72
|
+
- If next phase exists:
|
|
73
|
+
- Update STATE.md: current_phase, clear current_plan, set loop_position: TRANSITION ✓, set next_required_action: /sdlc:spec.
|
|
74
|
+
- Update ROADMAP.md: mark completed phase as COMPLETE, set next phase to IN PROGRESS.
|
|
75
|
+
- If no next phase (last phase in milestone):
|
|
76
|
+
- Update STATE.md: set next_required_action: /sdlc:close (milestone completion).
|
|
77
|
+
|
|
78
|
+
5. **Update ROADMAP.md with phase summary**
|
|
79
|
+
- Add completion date, plan count, hotfix count, key deliverables, and duration.
|
|
80
|
+
|
|
81
|
+
6. **Create git commit** (if in a git repository)
|
|
82
|
+
- Stage .sdlc/ files and source files from the phase.
|
|
83
|
+
- Commit with message: "feat({phase-name}): complete phase {number}"
|
|
84
|
+
|
|
85
|
+
7. **Output next action**
|
|
86
|
+
- If next phase exists: end with NEXT ACTION REQUIRED: /sdlc:spec
|
|
87
|
+
- If milestone complete: end with NEXT ACTION REQUIRED: /sdlc:close
|
|
88
|
+
</process>
|
|
89
|
+
|
|
90
|
+
<success_criteria>
|
|
91
|
+
- [ ] Phase completeness verified: every SPEC has a SUMMARY, all ACs passed
|
|
92
|
+
- [ ] State consistency checked across STATE.md, PROJECT.md, ROADMAP.md
|
|
93
|
+
- [ ] PROJECT.md updated with implemented, superseded, and new requirements
|
|
94
|
+
- [ ] STATE.md advanced to next phase (or milestone completion)
|
|
95
|
+
- [ ] ROADMAP.md updated with phase completion details and summary
|
|
96
|
+
- [ ] Git commit created at phase boundary (if in a git repo)
|
|
97
|
+
- [ ] If next phase exists: output ends with NEXT ACTION REQUIRED: /sdlc:spec
|
|
98
|
+
- [ ] If milestone complete: output ends with NEXT ACTION REQUIRED: /sdlc:close
|
|
99
|
+
</success_criteria>
|
package/src/commands/verify.md
CHANGED
|
@@ -25,7 +25,7 @@ Verify the implementation against every acceptance criterion in the SPEC.md. Use
|
|
|
25
25
|
</objective>
|
|
26
26
|
|
|
27
27
|
<execution_context>
|
|
28
|
-
@~/.claude/sdlc-framework/workflows/
|
|
28
|
+
@~/.claude/sdlc-framework/workflows/verify-phase.md
|
|
29
29
|
@.sdlc/STATE.md
|
|
30
30
|
The SPEC.md path is read from STATE.md or provided via $ARGUMENTS.
|
|
31
31
|
</execution_context>
|
|
@@ -40,7 +40,7 @@ Read these files:
|
|
|
40
40
|
</context>
|
|
41
41
|
|
|
42
42
|
<process>
|
|
43
|
-
Follow workflow: @~/.claude/sdlc-framework/workflows/
|
|
43
|
+
Follow workflow: @~/.claude/sdlc-framework/workflows/verify-phase.md
|
|
44
44
|
|
|
45
45
|
Step-by-step:
|
|
46
46
|
|
|
@@ -10,7 +10,7 @@ When a developer types `/sdlc:fast "add a login page"`, the framework must deter
|
|
|
10
10
|
|
|
11
11
|
1. **What type of work is this?** (feature, bug, critical, research, test, refactor, docs)
|
|
12
12
|
2. **How complex is it?** (simple, medium, complex)
|
|
13
|
-
3. **Where should it route?** (inline execution, /sdlc:spec, /sdlc:debug, /sdlc:
|
|
13
|
+
3. **Where should it route?** (inline execution, /sdlc:spec, /sdlc:debug, /sdlc:research, /sdlc:discuss, or inline hotfix)
|
|
14
14
|
|
|
15
15
|
`/sdlc:fast` is the **default entry point** for all work — not just small tasks. It is a universal router that classifies intent and complexity, then either handles work inline (simple) or routes to the appropriate specialized command (complex, bugs, research, emergencies).
|
|
16
16
|
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
# PRD: {title}
|
|
2
|
+
|
|
3
|
+
## Meta
|
|
4
|
+
|
|
5
|
+
| Field | Value |
|
|
6
|
+
|-------|-------|
|
|
7
|
+
| Created | {date} |
|
|
8
|
+
| Status | DRAFT / APPROVED |
|
|
9
|
+
| Author | {user} + AI |
|
|
10
|
+
| Source | /sdlc:discuss |
|
|
11
|
+
|
|
12
|
+
## Problem Statement
|
|
13
|
+
|
|
14
|
+
{2-3 sentences describing the problem being solved. Focus on the pain, not the solution.}
|
|
15
|
+
|
|
16
|
+
### Who Has This Problem
|
|
17
|
+
|
|
18
|
+
- **Primary user:** {role/persona} — {how they encounter the problem}
|
|
19
|
+
- **Secondary user:** {role/persona} — {how they are affected}
|
|
20
|
+
|
|
21
|
+
### Current Workarounds
|
|
22
|
+
|
|
23
|
+
- {How users solve this today, and why it is insufficient}
|
|
24
|
+
|
|
25
|
+
### Impact
|
|
26
|
+
|
|
27
|
+
- {What happens if this problem is not solved}
|
|
28
|
+
- {Quantifiable impact if available: time wasted, errors caused, revenue lost}
|
|
29
|
+
|
|
30
|
+
## Proposed Solution
|
|
31
|
+
|
|
32
|
+
{2-3 sentences describing the solution at a high level. What changes for the user.}
|
|
33
|
+
|
|
34
|
+
### Approach
|
|
35
|
+
|
|
36
|
+
{Technical approach chosen during discussion, with rationale for why this approach over alternatives.}
|
|
37
|
+
|
|
38
|
+
### Alternatives Considered
|
|
39
|
+
|
|
40
|
+
| Approach | Pros | Cons | Why Not |
|
|
41
|
+
|----------|------|------|---------|
|
|
42
|
+
| {alternative 1} | {pros} | {cons} | {reason rejected} |
|
|
43
|
+
| {alternative 2} | {pros} | {cons} | {reason rejected} |
|
|
44
|
+
|
|
45
|
+
## Requirements
|
|
46
|
+
|
|
47
|
+
### Functional Requirements
|
|
48
|
+
|
|
49
|
+
- **FR-1:** {requirement} — Priority: {must/should/could}
|
|
50
|
+
- **FR-2:** {requirement} — Priority: {must/should/could}
|
|
51
|
+
|
|
52
|
+
### Non-Functional Requirements
|
|
53
|
+
|
|
54
|
+
- **NFR-1:** {performance, security, scalability, accessibility requirement}
|
|
55
|
+
|
|
56
|
+
### User Flows
|
|
57
|
+
|
|
58
|
+
#### Flow 1: {flow name}
|
|
59
|
+
|
|
60
|
+
1. User {action}
|
|
61
|
+
2. System {response}
|
|
62
|
+
3. User {action}
|
|
63
|
+
4. System {response}
|
|
64
|
+
|
|
65
|
+
## Constraints
|
|
66
|
+
|
|
67
|
+
- **Technical:** {tech stack limitations, existing architecture constraints}
|
|
68
|
+
- **Timeline:** {deadline or time budget}
|
|
69
|
+
- **Scope:** {explicit boundaries — what is NOT included}
|
|
70
|
+
|
|
71
|
+
## Edge Cases
|
|
72
|
+
|
|
73
|
+
- {edge case 1} — Expected behavior: {behavior}
|
|
74
|
+
- {edge case 2} — Expected behavior: {behavior}
|
|
75
|
+
|
|
76
|
+
## Success Metrics
|
|
77
|
+
|
|
78
|
+
- {How to measure whether this solution works}
|
|
79
|
+
- {Concrete, measurable criteria}
|
|
80
|
+
|
|
81
|
+
## Open Questions
|
|
82
|
+
|
|
83
|
+
- {Unresolved questions deferred to spec phase}
|
|
84
|
+
|
|
85
|
+
## Decisions Log
|
|
86
|
+
|
|
87
|
+
| # | Question | Decision | Rationale |
|
|
88
|
+
|---|----------|----------|-----------|
|
|
89
|
+
| 1 | {question asked during discussion} | {answer} | {why} |
|
|
@@ -188,7 +188,7 @@
|
|
|
188
188
|
Phase {phase} COMPLETE.
|
|
189
189
|
MILESTONE {milestone} COMPLETE.
|
|
190
190
|
|
|
191
|
-
|
|
191
|
+
Milestone completion is handled automatically by /sdlc:close.
|
|
192
192
|
```
|
|
193
193
|
|
|
194
194
|
WHY: The display tells the user exactly where they are in the bigger picture. Completing a phase or milestone is a significant moment — acknowledge it.
|
|
@@ -0,0 +1,195 @@
|
|
|
1
|
+
<purpose>Drive AI-led brainstorming to transform a raw idea into a structured PRD. The discuss phase sits upstream of spec — it explores the problem space, validates approaches, and builds requirements through targeted questioning. Without this phase, specs are built on assumptions instead of explored decisions.</purpose>
|
|
2
|
+
<when_to_use>Run when the user has an idea but has not yet defined what to build. This is pre-loop discovery — it feeds into /sdlc:spec. Can run at any point: before init, between loops, or when pivoting direction.</when_to_use>
|
|
3
|
+
<required_reading>.sdlc/PROJECT.md (if exists), .sdlc/ROADMAP.md (if exists), codebase structure for technical context</required_reading>
|
|
4
|
+
<loop_context>
|
|
5
|
+
expected_phase: DISCUSS (pre-loop activity)
|
|
6
|
+
prior_phase: any (entry point or between loops)
|
|
7
|
+
next_phase: SPEC (discuss always leads to spec)
|
|
8
|
+
</loop_context>
|
|
9
|
+
<process>
|
|
10
|
+
|
|
11
|
+
<step name="seed_idea" priority="first">
|
|
12
|
+
The discussion needs a starting point — without one, questions are unfocused.
|
|
13
|
+
|
|
14
|
+
IF $ARGUMENTS provided:
|
|
15
|
+
Restate the idea in one sentence to confirm understanding.
|
|
16
|
+
Ask: "Is this what you want to explore, or should I adjust the framing?"
|
|
17
|
+
|
|
18
|
+
IF $ARGUMENTS empty:
|
|
19
|
+
Ask: "What idea, feature, or problem do you want to explore?"
|
|
20
|
+
Wait for response before proceeding.
|
|
21
|
+
|
|
22
|
+
IF .sdlc/PROJECT.md exists:
|
|
23
|
+
Read it. Note the tech stack, architecture, and constraints.
|
|
24
|
+
These inform all downstream questions — do not ask about things the project context already answers.
|
|
25
|
+
|
|
26
|
+
Record the seed idea for the decisions log.
|
|
27
|
+
</step>
|
|
28
|
+
|
|
29
|
+
<step name="explore_problem" priority="second">
|
|
30
|
+
Understanding the problem prevents building solutions to the wrong thing. Most failed features solve real problems badly because the problem was never properly defined.
|
|
31
|
+
|
|
32
|
+
Ask 2-4 questions from this category. Include a recommendation with each. Use AskUserQuestion.
|
|
33
|
+
|
|
34
|
+
PROBLEM QUESTIONS (pick the most relevant):
|
|
35
|
+
- "What specific problem does this solve? Who encounters it and how often?"
|
|
36
|
+
Recommendation: Frame the problem from the user's perspective, not the system's.
|
|
37
|
+
- "How do users solve this today? What makes current workarounds insufficient?"
|
|
38
|
+
Recommendation: Based on codebase scan, suggest what exists and what gaps you see.
|
|
39
|
+
- "What happens if this is not built? What is the cost of inaction?"
|
|
40
|
+
Recommendation: Assess severity based on what you know about the project.
|
|
41
|
+
- "Is this a new capability, an improvement to something existing, or a fix?"
|
|
42
|
+
Recommendation: Based on codebase, state whether related functionality already exists.
|
|
43
|
+
|
|
44
|
+
DO NOT ask questions whose answers are already in PROJECT.md or the codebase.
|
|
45
|
+
DO NOT ask questions that do not affect the technical solution.
|
|
46
|
+
|
|
47
|
+
Record all answers in the decisions log.
|
|
48
|
+
</step>
|
|
49
|
+
|
|
50
|
+
<step name="define_scope" priority="third">
|
|
51
|
+
Scope prevents building too much or too little. Without explicit scope, features creep and deadlines slip.
|
|
52
|
+
|
|
53
|
+
Ask 2-4 questions from this category. Include a recommendation with each.
|
|
54
|
+
|
|
55
|
+
SCOPE QUESTIONS (pick the most relevant):
|
|
56
|
+
- "What is the smallest version of this that delivers value? What is the full vision?"
|
|
57
|
+
Recommendation: Propose an MVP scope based on the problem definition.
|
|
58
|
+
- "What is explicitly NOT included? What should be deferred to later?"
|
|
59
|
+
Recommendation: Suggest boundaries based on complexity and dependencies.
|
|
60
|
+
- "Are there timeline or resource constraints that affect scope?"
|
|
61
|
+
Recommendation: If constraints exist, suggest what to cut first.
|
|
62
|
+
- "Does this interact with existing features? Which ones?"
|
|
63
|
+
Recommendation: Based on codebase scan, identify integration points.
|
|
64
|
+
|
|
65
|
+
After this round, you should be able to state the scope in one sentence.
|
|
66
|
+
Display: "Scope summary: {one sentence}. Does this match your intent?"
|
|
67
|
+
|
|
68
|
+
Record all answers in the decisions log.
|
|
69
|
+
</step>
|
|
70
|
+
|
|
71
|
+
<step name="validate_approach" priority="fourth">
|
|
72
|
+
Choosing the wrong approach is the most expensive mistake — it compounds through every downstream phase. Presenting options with trade-offs prevents blind commitment to the first idea.
|
|
73
|
+
|
|
74
|
+
Based on the problem and scope, identify 2-3 viable technical approaches.
|
|
75
|
+
|
|
76
|
+
Present each approach:
|
|
77
|
+
```
|
|
78
|
+
Approach A (recommended): {description}
|
|
79
|
+
- Effort: {low/medium/high}
|
|
80
|
+
- Risk: {what could go wrong}
|
|
81
|
+
- Maintenance: {ongoing burden}
|
|
82
|
+
- Fits existing patterns: {yes/no — reference specific codebase patterns}
|
|
83
|
+
|
|
84
|
+
Approach B: {description}
|
|
85
|
+
- Effort: {low/medium/high}
|
|
86
|
+
- Risk: {what could go wrong}
|
|
87
|
+
- Maintenance: {ongoing burden}
|
|
88
|
+
- Fits existing patterns: {yes/no}
|
|
89
|
+
|
|
90
|
+
Approach C (do nothing / defer): {description}
|
|
91
|
+
- Risk of deferring: {what happens}
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Ask: "Which approach do you prefer? I recommend Approach A because {concrete reason}."
|
|
95
|
+
|
|
96
|
+
IF the user picks a non-recommended approach:
|
|
97
|
+
Acknowledge the choice. Do not argue. Record the rationale.
|
|
98
|
+
|
|
99
|
+
IF the user is unsure:
|
|
100
|
+
Ask one targeted follow-up to resolve the uncertainty.
|
|
101
|
+
|
|
102
|
+
Record the chosen approach and rationale in the decisions log.
|
|
103
|
+
</step>
|
|
104
|
+
|
|
105
|
+
<step name="detail_requirements" priority="fifth">
|
|
106
|
+
Requirements bridge the gap between "what to build" and "how to spec it." Missing requirements surface as bugs during implementation.
|
|
107
|
+
|
|
108
|
+
Ask 2-4 questions from this category. Include a recommendation with each.
|
|
109
|
+
|
|
110
|
+
REQUIREMENTS QUESTIONS (pick the most relevant):
|
|
111
|
+
- "Walk me through the primary user flow. What does the user do step by step?"
|
|
112
|
+
Recommendation: Propose a flow based on the chosen approach.
|
|
113
|
+
- "What are the edge cases? What happens when {unlikely but possible scenario}?"
|
|
114
|
+
Recommendation: List 2-3 edge cases you identified and propose handling.
|
|
115
|
+
- "Are there security, performance, or accessibility requirements?"
|
|
116
|
+
Recommendation: Based on project context, suggest relevant NFRs.
|
|
117
|
+
- "How will you know this works? What does success look like?"
|
|
118
|
+
Recommendation: Propose measurable success criteria.
|
|
119
|
+
- "What data does this feature need? New models, fields, or API endpoints?"
|
|
120
|
+
Recommendation: Based on codebase, suggest data model approach.
|
|
121
|
+
|
|
122
|
+
STOP ASKING SIGNAL:
|
|
123
|
+
- You can write functional requirements for the core flow.
|
|
124
|
+
- You can list at least 3 edge cases with expected behavior.
|
|
125
|
+
- You know the primary user flow end to end.
|
|
126
|
+
- Remaining unknowns are implementation details, not requirements.
|
|
127
|
+
|
|
128
|
+
IF clarity is sufficient after round 2 or 3, skip this round and proceed to compile.
|
|
129
|
+
|
|
130
|
+
Record all answers in the decisions log.
|
|
131
|
+
</step>
|
|
132
|
+
|
|
133
|
+
<step name="compile_prd" priority="sixth">
|
|
134
|
+
The PRD is the deliverable — it captures every decision made during discussion. Without it, the discussion is just a conversation that evaporates.
|
|
135
|
+
|
|
136
|
+
Create .sdlc/discuss/ directory if it does not exist.
|
|
137
|
+
|
|
138
|
+
Generate a topic slug from the seed idea: lowercase, hyphens, no special characters, max 40 chars.
|
|
139
|
+
|
|
140
|
+
Write .sdlc/discuss/{topic-slug}-PRD.md using the PRD template structure:
|
|
141
|
+
- Problem Statement: from explore_problem answers
|
|
142
|
+
- Proposed Solution: from validate_approach chosen approach
|
|
143
|
+
- Alternatives Considered: from validate_approach rejected approaches
|
|
144
|
+
- Requirements: from detail_requirements answers
|
|
145
|
+
- Constraints: from define_scope answers
|
|
146
|
+
- Edge Cases: from detail_requirements answers
|
|
147
|
+
- Success Metrics: from detail_requirements answers
|
|
148
|
+
- Decisions Log: every question asked and answer received, numbered
|
|
149
|
+
|
|
150
|
+
Display a compact summary of the PRD (30-50 lines):
|
|
151
|
+
- Problem (2 lines)
|
|
152
|
+
- Solution (2 lines)
|
|
153
|
+
- Requirements (numbered list)
|
|
154
|
+
- Constraints (list)
|
|
155
|
+
- Edge cases (list)
|
|
156
|
+
- Open questions (list)
|
|
157
|
+
</step>
|
|
158
|
+
|
|
159
|
+
<step name="approve_and_route" priority="seventh">
|
|
160
|
+
The user must approve the PRD before it feeds into spec. An unapproved PRD is just notes.
|
|
161
|
+
|
|
162
|
+
Ask: "PRD complete. Review the summary above."
|
|
163
|
+
Present options:
|
|
164
|
+
- APPROVE: Lock the PRD and proceed to /sdlc:spec
|
|
165
|
+
- REVISE: Tell me what to change (re-compile after changes)
|
|
166
|
+
- REJECT: Discard the PRD and stop
|
|
167
|
+
|
|
168
|
+
IF APPROVE:
|
|
169
|
+
Set PRD status to APPROVED.
|
|
170
|
+
Update .sdlc/STATE.md:
|
|
171
|
+
- Add history entry: "{timestamp} | discuss | Topic: {topic}. PRD saved."
|
|
172
|
+
- Set next_required_action: /sdlc:spec
|
|
173
|
+
- Add prd_path: .sdlc/discuss/{topic-slug}-PRD.md
|
|
174
|
+
|
|
175
|
+
Display:
|
|
176
|
+
```
|
|
177
|
+
PRD approved.
|
|
178
|
+
|
|
179
|
+
Saved: .sdlc/discuss/{topic-slug}-PRD.md
|
|
180
|
+
|
|
181
|
+
The spec phase will use this PRD to create a detailed specification with
|
|
182
|
+
acceptance criteria and task dependencies.
|
|
183
|
+
|
|
184
|
+
NEXT ACTION REQUIRED: /sdlc:spec
|
|
185
|
+
Run /sdlc:spec to formalize this PRD into an implementation-ready specification.
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
IF REVISE:
|
|
189
|
+
Apply changes. Re-display summary. Re-ask for approval.
|
|
190
|
+
|
|
191
|
+
IF REJECT:
|
|
192
|
+
Delete the PRD file. Display: "PRD discarded." Stop.
|
|
193
|
+
</step>
|
|
194
|
+
|
|
195
|
+
</process>
|