5-phase-workflow 1.0.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.
Files changed (33) hide show
  1. package/README.md +332 -0
  2. package/bin/install.js +408 -0
  3. package/docs/workflow-guide.md +1024 -0
  4. package/package.json +34 -0
  5. package/src/agents/integration-agent.md +219 -0
  6. package/src/agents/review-processor.md +160 -0
  7. package/src/agents/step-executor.md +108 -0
  8. package/src/agents/step-fixer.md +132 -0
  9. package/src/agents/step-verifier.md +125 -0
  10. package/src/agents/verification-agent.md +411 -0
  11. package/src/commands/5/configure.md +309 -0
  12. package/src/commands/5/discuss-feature.md +393 -0
  13. package/src/commands/5/implement-feature.md +502 -0
  14. package/src/commands/5/plan-feature.md +285 -0
  15. package/src/commands/5/plan-implementation.md +376 -0
  16. package/src/commands/5/quick-implement.md +263 -0
  17. package/src/commands/5/review-code.md +583 -0
  18. package/src/commands/5/verify-implementation.md +277 -0
  19. package/src/hooks/statusline.js +53 -0
  20. package/src/settings.json +6 -0
  21. package/src/skills/build-project/SKILL.md +277 -0
  22. package/src/skills/configure-project/SKILL.md +355 -0
  23. package/src/skills/generate-readme/EXAMPLES.md +168 -0
  24. package/src/skills/generate-readme/SKILL.md +123 -0
  25. package/src/skills/generate-readme/TEMPLATE.md +141 -0
  26. package/src/skills/run-tests/SKILL.md +365 -0
  27. package/src/templates/ARCHITECTURE.md +64 -0
  28. package/src/templates/CONCERNS.md +75 -0
  29. package/src/templates/CONVENTIONS.md +75 -0
  30. package/src/templates/INTEGRATIONS.md +65 -0
  31. package/src/templates/STACK.md +60 -0
  32. package/src/templates/STRUCTURE.md +60 -0
  33. package/src/templates/TESTING.md +107 -0
@@ -0,0 +1,309 @@
1
+ ---
2
+ name: 5:configure
3
+ description: Phase 1 of project configuration. Analyzes project, gathers preferences, and creates a configuration feature spec. Follow up with /5:plan-implementation CONFIGURE.
4
+ allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
5
+ context: inherit
6
+ user-invocable: true
7
+ ---
8
+
9
+ # Configure (Phase 1 - Plan Feature for Project Configuration)
10
+
11
+ ## Overview
12
+
13
+ This command is **Phase 1** of the 5-phase workflow applied to project configuration itself. It analyzes the project, asks the user questions, and outputs a feature spec at `.5/CONFIGURE/feature.md`.
14
+
15
+ After running this command, proceed through the standard phases:
16
+ 1. **`/5:configure`** (this command) - Plan the configuration feature
17
+ 2. `/5:plan-implementation CONFIGURE` - Create implementation plan
18
+ 3. `/5:implement-feature CONFIGURE` - Execute configuration (uses `configure-project` skill)
19
+ 4. `/5:verify-implementation` - Verify configuration
20
+ 5. `/5:review-code` - Review generated files
21
+
22
+ ## Configuration Process
23
+
24
+ ### Step 1: Analyze Project (auto-detect, no user interaction)
25
+
26
+ Perform all detection silently, collecting results for Step 2.
27
+
28
+ **1a. Check for existing config:**
29
+ ```bash
30
+ if [ -f ".claude/.5/config.json" ]; then
31
+ # Config exists - will ask user in Step 2
32
+ fi
33
+ ```
34
+
35
+ **1b. Detect project type** by examining files:
36
+
37
+ ```javascript
38
+ // Node.js/JavaScript/TypeScript
39
+ if (exists('package.json')) {
40
+ const pkg = readJSON('package.json');
41
+
42
+ if (pkg.dependencies?.['next'] || pkg.devDependencies?.['next'])
43
+ return 'nextjs';
44
+ if (pkg.dependencies?.['@nestjs/core'])
45
+ return 'nestjs';
46
+ if (pkg.dependencies?.['express'])
47
+ return 'express';
48
+ if (pkg.dependencies?.['react'])
49
+ return 'react';
50
+ if (pkg.dependencies?.['vue'])
51
+ return 'vue';
52
+
53
+ return 'javascript';
54
+ }
55
+
56
+ // Java
57
+ if (exists('build.gradle') || exists('build.gradle.kts'))
58
+ return 'gradle-java';
59
+ if (exists('pom.xml'))
60
+ return 'maven-java';
61
+
62
+ // Python
63
+ if (exists('requirements.txt') || exists('pyproject.toml')) {
64
+ if (exists('manage.py')) return 'django';
65
+ if (exists('app.py') || exists('wsgi.py')) return 'flask';
66
+ return 'python';
67
+ }
68
+
69
+ // Rust
70
+ if (exists('Cargo.toml'))
71
+ return 'rust';
72
+
73
+ // Go
74
+ if (exists('go.mod'))
75
+ return 'go';
76
+
77
+ // Ruby
78
+ if (exists('Gemfile')) {
79
+ if (exists('config/routes.rb')) return 'rails';
80
+ return 'ruby';
81
+ }
82
+
83
+ return 'unknown';
84
+ ```
85
+
86
+ **1c. Detect build/test commands** based on project type:
87
+
88
+ | Type | Build Command | Test Command |
89
+ |------|--------------|--------------|
90
+ | javascript | `npm run build` | `npm test` |
91
+ | nextjs | `npm run build` | `npm test` |
92
+ | nestjs | `npm run build` | `npm test` |
93
+ | express | `npm run build \|\| tsc` | `npm test` |
94
+ | gradle-java | `./gradlew build -x test -x javadoc --offline` | `./gradlew test --offline` |
95
+ | maven-java | `mvn package -DskipTests` | `mvn test` |
96
+ | python | `python -m py_compile **/*.py` | `pytest` |
97
+ | django | `python manage.py check` | `python manage.py test` |
98
+ | rust | `cargo build` | `cargo test` |
99
+ | go | `go build ./...` | `go test ./...` |
100
+
101
+ **1d. Detect available tools:**
102
+
103
+ ```bash
104
+ # CodeRabbit CLI
105
+ if command -v coderabbit &> /dev/null; then
106
+ coderabbit_available=true
107
+ if coderabbit auth status | grep -q "authenticated"; then
108
+ coderabbit_authenticated=true
109
+ fi
110
+ fi
111
+
112
+ # IDE MCP (JetBrains) - check if MCP tools are available
113
+ ```
114
+
115
+ **1e. Check CLAUDE.md:**
116
+ - If `CLAUDE.md` exists, read its content
117
+
118
+ **1f. Scan existing skills:**
119
+ - Check `.claude/skills/` for existing project-specific skills
120
+
121
+ ### Step 2: Gather User Preferences (interactive via AskUserQuestion)
122
+
123
+ **2a. If config exists:**
124
+ - "Configuration already exists. What would you like to do?"
125
+ - Options: "Update existing", "Start fresh", "Cancel"
126
+ - If Cancel: stop here
127
+
128
+ **2b. Confirm project type:**
129
+ - "Detected project type: {detected-type}. Is this correct?"
130
+ - Options: "Yes (recommended)", "No, choose manually"
131
+ - If manual, present list: JavaScript/TypeScript, Next.js, NestJS, Express, React, Vue, Java (Gradle), Java (Maven), Python, Django, Flask, Rust, Go, Ruby on Rails, Other
132
+
133
+ **2c. Ticket ID pattern:**
134
+ - "How do you track work items in this project?"
135
+ - Options:
136
+ 1. "JIRA-style (e.g., PROJ-1234)" - Pattern: `[A-Z]+-\\d+`
137
+ 2. "GitHub Issues (e.g., #123)" - Pattern: `#\\d+`
138
+ 3. "Linear (e.g., ENG-1234)" - Pattern: `[A-Z]{3}-\\d+`
139
+ 4. "No tracking / skip" - Pattern: null
140
+ - Follow-up: "Extract ticket ID from branch name?" - Options: "Yes (recommended)", "No"
141
+
142
+ **2d. Branch naming convention:**
143
+ - "What branch naming convention do you use?"
144
+ - Options:
145
+ 1. "ticket-id/description (e.g., PROJ-1234/add-feature)"
146
+ 2. "feature/description (e.g., feature/add-login)"
147
+ 3. "Custom pattern"
148
+ 4. "No convention"
149
+
150
+ **2e. Confirm build/test commands:**
151
+ - "Suggested build command: `{command}`. Use this?"
152
+ - Options: "Yes (recommended)", "Customize", "None (no build step)"
153
+ - "Suggested test command: `{command}`. Use this?"
154
+ - Options: "Yes (recommended)", "Customize", "None (no test step)"
155
+
156
+ **2f. Confirm CLAUDE.md generation:**
157
+ - "Generate/update CLAUDE.md? This will analyze your codebase to document structure and conventions."
158
+ - Options: "Yes (recommended)", "Skip"
159
+
160
+ **2g. Confirm project-specific skills:**
161
+ - Present proposed skills based on detected project type (see skill table in configure-project/SKILL.md)
162
+ - "These project-specific skills were detected for your {project-type} project: {skill-list}. Confirm or customize?"
163
+ - Options: "Use these (recommended)", "Customize", "Skip skill generation"
164
+
165
+ ### Step 3: Create Feature Spec
166
+
167
+ Write `.5/CONFIGURE/feature.md` containing all gathered data:
168
+
169
+ ```markdown
170
+ # Feature: Project Configuration
171
+
172
+ ## Summary
173
+ Configure the 5-phase workflow for this {project-type} project. Creates config.json, generates CLAUDE.md with codebase analysis, and creates project-specific skills.
174
+
175
+ ## Requirements
176
+
177
+ ### Requirement 1: Create config.json
178
+ Create `.claude/.5/config.json` with the following values:
179
+ - Project type: {project-type}
180
+ - Ticket pattern: {pattern}
181
+ - Extract from branch: {yes/no}
182
+ - Branch convention: {convention}
183
+ - Build command: {build-command}
184
+ - Test command: {test-command}
185
+ - Build timeout: 120000ms
186
+ - Test timeout: 300000ms
187
+ - CodeRabbit: {available/not-available}, authenticated: {yes/no}
188
+ - IDE integration: {available/not-available}, type: {type}
189
+ - Review tool: {coderabbit/none}
190
+
191
+ ### Requirement 2: Generate Documentation Files
192
+ Analyze the codebase and generate modular documentation:
193
+
194
+ **Create separate documentation files in `.5/` folder:**
195
+ - `.5/ARCHITECTURE.md` - Architectural patterns and layers
196
+ - `.5/STACK.md` - Technology stack and dependencies
197
+ - `.5/STRUCTURE.md` - Directory layout and organization
198
+ - `.5/CONVENTIONS.md` - Coding standards and patterns
199
+ - `.5/TESTING.md` - Test framework and patterns
200
+ - `.5/INTEGRATIONS.md` - External services and APIs
201
+ - `.5/CONCERNS.md` - Tech debt, bugs, and risks
202
+
203
+ **Create CLAUDE.md as navigation hub:**
204
+ - Quick reference section with links to all `.5/*.md` files
205
+ - Project overview and build commands
206
+ - "Getting Started" guide with references to appropriate files
207
+ - Mandatory coding guidelines:
208
+ 1. Types should be clear and types should be available when possible
209
+ 2. Use doc (jsdoc, javadoc, pydoc, etc) concisely. No doc is better than meaningless doc
210
+ 3. Keep files short and structured
211
+ 4. Extract methods, classes
212
+ 5. Respect SRP and DRY
213
+ 6. Make code maintainable and modular
214
+
215
+ **Preserve existing content:**
216
+ - If CLAUDE.md already exists, preserve user-written custom sections
217
+
218
+ ### Requirement 3: Generate Project-Specific Skills
219
+ Generate the following skills in `.claude/skills/`:
220
+ {List of confirmed skills, e.g.:}
221
+ - create-component: Creates a React component following project conventions
222
+ - create-hook: Creates a custom React hook following project conventions
223
+ - create-context: Creates a React context provider following project conventions
224
+
225
+ Each skill should:
226
+ - Follow standard SKILL.md frontmatter pattern
227
+ - Derive patterns from existing code in the project
228
+ - Include file naming and location conventions
229
+ - Include template/pattern based on existing examples
230
+
231
+ ## Acceptance Criteria
232
+ - [ ] `.claude/.5/config.json` exists with correct values (no `steps` array)
233
+ - [ ] `.5/` directory created
234
+ - [ ] All 7 documentation files exist and are populated:
235
+ - [ ] `.5/ARCHITECTURE.md`
236
+ - [ ] `.5/STACK.md`
237
+ - [ ] `.5/STRUCTURE.md`
238
+ - [ ] `.5/CONVENTIONS.md`
239
+ - [ ] `.5/TESTING.md`
240
+ - [ ] `.5/INTEGRATIONS.md`
241
+ - [ ] `.5/CONCERNS.md`
242
+ - [ ] `CLAUDE.md` exists with references to `.5/` files
243
+ - [ ] CLAUDE.md contains 6 coding guidelines
244
+ - [ ] No placeholder text like `{YYYY-MM-DD}` remains unfilled
245
+ - [ ] All specified project-specific skills are generated in `.claude/skills/`
246
+ - [ ] Generated skills reference actual project conventions
247
+ - [ ] If CLAUDE.md existed before, user-written sections are preserved
248
+ ```
249
+
250
+ **Important:** Use `mkdir -p .5/CONFIGURE` before writing the feature spec.
251
+
252
+ ### Step 4: Guide User to Next Phase
253
+
254
+ Tell the user:
255
+
256
+ 1. "Configuration feature planned at `.5/CONFIGURE/feature.md`"
257
+ 2. "Next: Run `/5:plan-implementation CONFIGURE`"
258
+ 3. "Then: `/5:implement-feature CONFIGURE` -> `/5:verify-implementation` -> `/5:review-code`"
259
+
260
+ ## DO NOT
261
+
262
+ - DO NOT write config.json directly (that's Phase 3's job via the configure-project skill)
263
+ - DO NOT create CLAUDE.md directly (that's Phase 3's job)
264
+ - DO NOT generate skills directly (that's Phase 3's job)
265
+ - DO NOT skip user interaction - always confirm detected values
266
+ - DO NOT assume project structure - always detect or ask
267
+
268
+ ## Example Usage
269
+
270
+ ```
271
+ User: /5:configure
272
+
273
+ [Step 1: Auto-detection runs silently]
274
+
275
+ Claude: "Detected project type: Next.js. Is this correct?"
276
+ User: "Yes"
277
+
278
+ Claude: "How do you track work items?"
279
+ User: "GitHub Issues"
280
+
281
+ Claude: "Extract ticket ID from branch name?"
282
+ User: "Yes"
283
+
284
+ Claude: "Branch naming convention?"
285
+ User: "feature/description"
286
+
287
+ Claude: "Build command: `npm run build`. Use this?"
288
+ User: "Yes"
289
+
290
+ Claude: "Test command: `npm test`. Use this?"
291
+ User: "Yes"
292
+
293
+ Claude: "Generate CLAUDE.md with codebase analysis?"
294
+ User: "Yes"
295
+
296
+ Claude: "Proposed skills for Next.js: create-page, create-api-route, create-component. Confirm?"
297
+ User: "Use these"
298
+
299
+ Claude: [Writes .5/CONFIGURE/feature.md]
300
+ Claude: "Configuration feature planned at `.5/CONFIGURE/feature.md`"
301
+ Claude: "Next: Run `/5:plan-implementation CONFIGURE`"
302
+ ```
303
+
304
+ ## Related Documentation
305
+
306
+ - [5-Phase Workflow Guide](../../docs/workflow-guide.md)
307
+ - [configure-project skill](../../skills/configure-project/SKILL.md)
308
+ - [/5:plan-feature command](./plan-feature.md)
309
+ - [/5:plan-implementation command](./plan-implementation.md)
@@ -0,0 +1,393 @@
1
+ ---
2
+ name: 5:discuss-feature
3
+ description: Discusses and refines an existing feature specification through iterative Q&A. Use after /plan-feature when requirements need clarification or changes. Updates the feature spec based on discussion.
4
+ allowed-tools: Read, Write, Glob, Grep, Task, AskUserQuestion
5
+ context: inherit
6
+ user-invocable: true
7
+ ---
8
+
9
+ # Discuss Feature Specification (Phase 1 - Optional Iteration)
10
+
11
+ ## Overview
12
+
13
+ This skill is part of **Phase 1** (Feature Planning) of the 5-phase workflow:
14
+ 1. **Feature Planning** - Initial requirements gathering (`/plan-feature`), then optional iteration (`/discuss-feature`)
15
+ 2. **Implementation Planning** - Map to technical components
16
+ 3. **Orchestrated Implementation** - Execute with state tracking
17
+ 4. **Verify Implementation** - Check completeness and correctness
18
+ 5. **Code Review** - Apply automated quality improvements
19
+
20
+ This skill enables **optional iterative refinement** of feature specs after initial planning through discussion, clarification, and requirement changes. Use it when the initial spec needs adjustments before proceeding to implementation planning.
21
+
22
+ ## Use Cases
23
+
24
+ Use this skill when:
25
+ - Requirements need clarification after initial planning
26
+ - User wants to add/modify/remove requirements
27
+ - Scope needs adjustment
28
+ - Technical constraints discovered during exploration
29
+ - Alternative approaches need evaluation
30
+ - Feature complexity needs reduction
31
+ - Acceptance criteria need refinement
32
+
33
+ ## Prerequisites
34
+
35
+ Before invoking this skill, ensure:
36
+ 1. Feature spec exists at `.5/{feature-name}/feature.md`
37
+ 2. You have the feature name or ticket ID ready (e.g., "PROJ-1234-add-feature")
38
+
39
+ ## Discussion Process
40
+
41
+ ### Step 1: Extract Feature Name
42
+
43
+ If user provides only ticket ID (e.g., "PROJ-1234"), find the feature file:
44
+ - Use Glob: `.5/{TICKET-ID}-*-*/feature.md` (pattern from config)
45
+ - Match the ticket ID
46
+ - If multiple matches, ask user to specify
47
+ - If no match found, inform user and suggest running `/plan-feature` first
48
+
49
+ If user provides full feature name (e.g., "PROJ-1234-add-feature"), use directly.
50
+
51
+ ### Step 2: Read Feature Specification
52
+
53
+ Read the feature spec from `.5/{feature-name}/feature.md`.
54
+
55
+ Extract current state:
56
+ - Ticket ID
57
+ - Summary
58
+ - Requirements (functional and non-functional)
59
+ - Constraints
60
+ - Affected domains
61
+ - Entity definitions
62
+ - Business rules
63
+ - Acceptance criteria
64
+ - Alternatives considered
65
+ - Questions & Answers
66
+
67
+ ### Step 3: Initial Discussion Prompt
68
+
69
+ **FIRST ACTION:** Ask the user what they want to discuss using AskUserQuestion.
70
+
71
+ Prompt to use:
72
+
73
+ "What would you like to discuss or change about this feature?"
74
+
75
+ Provide context options for common scenarios:
76
+ - "Clarify existing requirements"
77
+ - "Add new requirements"
78
+ - "Remove or simplify requirements"
79
+ - "Change scope or approach"
80
+ - "Discuss technical constraints"
81
+ - "Review acceptance criteria"
82
+ - "Other (specify)"
83
+
84
+ Use `multiSelect: false` to get single focus area initially.
85
+
86
+ ### Step 4: Contextual Exploration (Optional)
87
+
88
+ Based on the user's focus area, explore the codebase if needed:
89
+
90
+ **For technical constraint discussions:**
91
+ - Search for similar implementations
92
+ - Check existing patterns
93
+ - Identify integration points
94
+
95
+ **For scope changes:**
96
+ - Verify affected modules
97
+ - Check dependencies
98
+ - Identify ripple effects
99
+
100
+ Use Task tool with subagent_type=Explore for complex exploration.
101
+
102
+ ### Step 5: Interactive Q&A
103
+
104
+ Based on the discussion topic, ask targeted follow-up questions using AskUserQuestion.
105
+
106
+ **Question types by topic:**
107
+
108
+ **Clarify Requirements:**
109
+ - "The current requirement says X. Should it also handle Y scenario?"
110
+ - "How should the system behave when Z happens?"
111
+ - "Are there edge cases we haven't considered?"
112
+
113
+ **Add Requirements:**
114
+ - "What is the expected behavior for this new requirement?"
115
+ - "How does this interact with existing requirement X?"
116
+ - "Should this be in scope or future work?"
117
+
118
+ **Simplify/Remove:**
119
+ - "If we remove X, what's the minimum viable version?"
120
+ - "Can we defer Y to a future iteration?"
121
+ - "Would simpler approach Z meet the core need?"
122
+
123
+ **Change Approach:**
124
+ - "What are the pros/cons of approach A vs B?"
125
+ - "Have you considered alternative C?"
126
+ - "What's the trade-off we're trying to optimize?"
127
+
128
+ **Technical Constraints:**
129
+ - "Is performance constraint X realistic?"
130
+ - "Should we use existing component Y instead?"
131
+ - "How will this integrate with system Z?"
132
+
133
+ **Acceptance Criteria:**
134
+ - "How will we verify requirement X is met?"
135
+ - "What does success look like for this feature?"
136
+ - "Are there specific test scenarios?"
137
+
138
+ ### Step 6: Iterative Refinement
139
+
140
+ After each round of Q&A:
141
+ 1. Summarize what you've learned
142
+ 2. Ask: "Would you like to discuss anything else about this feature?"
143
+ 3. Provide options:
144
+ - "Yes, discuss another aspect"
145
+ - "Yes, continue this topic"
146
+ - "No, update the spec"
147
+
148
+ Allow multiple rounds of discussion until user is satisfied.
149
+
150
+ ### Step 7: Update Feature Specification
151
+
152
+ When user indicates they're done discussing, update `.5/{feature-name}/feature.md`:
153
+
154
+ **Update these sections based on discussion:**
155
+
156
+ 1. **Summary** - If core understanding changed
157
+ 2. **Problem Statement** - If motivation clarified
158
+ 3. **Requirements** - Add/modify/remove based on discussion
159
+ 4. **Constraints** - Add new constraints discovered
160
+ 5. **Affected Domains** - If scope changed
161
+ 6. **Entity/Component Definitions** - If data model changed
162
+ 7. **Business Rules** - If logic clarified
163
+ 8. **Acceptance Criteria** - Add/refine verification criteria
164
+ 9. **Alternatives Considered** - Document discussed alternatives
165
+ 10. **Questions & Answers** - Append new Q&A from this session
166
+
167
+ **Preserve existing content** - Only update sections that changed during discussion.
168
+
169
+ **Track changes** - Add a "Discussion History" section if it doesn't exist:
170
+
171
+ ```markdown
172
+ ## Discussion History
173
+
174
+ ### Session 1: {Date} - {Topic}
175
+ **Changes made:**
176
+ - Added requirement: {X}
177
+ - Clarified: {Y}
178
+ - Removed: {Z}
179
+
180
+ **Rationale:** {Why these changes}
181
+ ```
182
+
183
+ ### Step 8: Inform Developer
184
+
185
+ After updating the spec, tell the developer:
186
+
187
+ 1. "Feature specification updated at `.5/{feature-name}/feature.md`"
188
+ 2. Summarize key changes:
189
+ - "Added: {X}"
190
+ - "Modified: {Y}"
191
+ - "Removed: {Z}"
192
+ 3. Ask: "Would you like to:"
193
+ - "Discuss more (run /discuss-feature again)"
194
+ - "Proceed to implementation planning (run /plan-implementation {feature-name})"
195
+ - "Review the updated spec first"
196
+
197
+ ## Instructions Summary
198
+
199
+ 1. **Extract feature name** - From user input or by matching ticket ID
200
+ 2. **Read feature spec** - Load current state from `.5/{feature-name}/feature.md`
201
+ 3. **Ask initial question** - What do they want to discuss?
202
+ 4. **Explore if needed** - Understand codebase context
203
+ 5. **Interactive Q&A** - Multiple rounds of clarifying questions
204
+ 6. **Iterate** - Allow continued discussion
205
+ 7. **Update feature spec** - Modify relevant sections
206
+ 8. **Track changes** - Document discussion history
207
+ 9. **Inform developer** - Summarize changes and next steps
208
+
209
+ ## Key Principles
210
+
211
+ 1. **User-driven** - Follow user's focus areas, don't prescribe
212
+ 2. **Iterative** - Allow multiple discussion rounds
213
+ 3. **Contextual** - Explore codebase when relevant
214
+ 4. **Challenge constructively** - Question complexity, suggest alternatives
215
+ 5. **Document evolution** - Track how requirements changed
216
+ 6. **Preserve history** - Keep previous Q&A, add new discussions
217
+ 7. **Clear next steps** - Guide user on what to do next
218
+
219
+ ## DO NOT in This Skill
220
+
221
+ - DO NOT rewrite the entire feature spec (only update changed sections)
222
+ - DO NOT skip asking what the user wants to discuss
223
+ - DO NOT create new feature specs (use /plan-feature for that)
224
+ - DO NOT proceed to technical planning (that's Phase 2's job)
225
+ - DO NOT start implementation
226
+ - DO NOT delete previous Q&A sections (append to them)
227
+
228
+ ## Discussion Patterns
229
+
230
+ ### Pattern 1: Scope Reduction
231
+ User: "This is too complex, can we simplify?"
232
+ Skill:
233
+ 1. Ask: "What's the minimum viable version?"
234
+ 2. Ask: "Which requirements are must-have vs nice-to-have?"
235
+ 3. Present options for phased approach
236
+ 4. Update spec with reduced scope
237
+
238
+ ### Pattern 2: Requirement Addition
239
+ User: "We need to also handle X scenario"
240
+ Skill:
241
+ 1. Ask: "How should X scenario work?"
242
+ 2. Ask: "How does X interact with existing requirement Y?"
243
+ 3. Ask: "Should X be in this feature or separate?"
244
+ 4. Update requirements section
245
+
246
+ ### Pattern 3: Technical Feasibility
247
+ User: "Can we reuse existing component Z?"
248
+ Skill:
249
+ 1. Explore: Find component Z implementation
250
+ 2. Ask: "Does Z fully meet the need or need extension?"
251
+ 3. Present trade-offs: reuse vs custom
252
+ 4. Update affected domains and approach
253
+
254
+ ### Pattern 4: Acceptance Criteria
255
+ User: "How do we verify this works?"
256
+ Skill:
257
+ 1. Ask: "What's the happy path test?"
258
+ 2. Ask: "What edge cases should we test?"
259
+ 3. Ask: "What does failure look like?"
260
+ 4. Update acceptance criteria section
261
+
262
+ ### Pattern 5: Alternative Evaluation
263
+ User: "Should we use approach A or B?"
264
+ Skill:
265
+ 1. Ask: "What's the goal: simplicity, performance, flexibility?"
266
+ 2. Present pros/cons of each approach
267
+ 3. Ask: "What constraints matter most?"
268
+ 4. Update alternatives considered section
269
+
270
+ ## Example Workflow
271
+
272
+ ### Example 1: Scope Clarification
273
+
274
+ ```
275
+ User: /discuss-feature PROJ-1234-add-feature
276
+
277
+ Skill: [Reads feature spec]
278
+ Skill: "What would you like to discuss or change about this feature?"
279
+
280
+ User: "Clarify existing requirements"
281
+
282
+ Skill: "The current spec mentions 'emergency schedule window'. Should this support:
283
+ - Single time window per product?
284
+ - Multiple overlapping windows?
285
+ - Recurring schedules?
286
+ What level of complexity do you need?"
287
+
288
+ User: "Just single window per product for now"
289
+
290
+ Skill: "Should we support updating/deleting the window after it's set?"
291
+
292
+ User: "Yes, full CRUD"
293
+
294
+ Skill: "Would you like to discuss anything else about this feature?"
295
+
296
+ User: "No, update the spec"
297
+
298
+ Skill: [Updates Requirements and Acceptance Criteria sections]
299
+ Skill: "Feature specification updated. Changes:
300
+ - Clarified: Single emergency window per product (not multiple)
301
+ - Added: Full CRUD operations for emergency windows
302
+ Would you like to proceed to implementation planning? Run: /plan-implementation PROJ-1234-add-feature"
303
+ ```
304
+
305
+ ### Example 2: Adding Requirements
306
+
307
+ ```
308
+ User: /discuss-feature PROJ-1234
309
+
310
+ Skill: [Finds PROJ-1234-add-feature.md]
311
+ Skill: "What would you like to discuss or change about this feature?"
312
+
313
+ User: "Add new requirements"
314
+
315
+ Skill: "What new requirement would you like to add?"
316
+
317
+ User: "We need to notify customers when emergency schedule is activated"
318
+
319
+ Skill: "How should notifications be delivered?
320
+ - Email only
321
+ - SMS only
322
+ - Both email and SMS
323
+ - Configurable per customer"
324
+
325
+ User: "Email only for now"
326
+
327
+ Skill: "Should notification be:
328
+ - Immediate when emergency schedule is created?
329
+ - When emergency window starts?
330
+ - Both?"
331
+
332
+ User: "When emergency window starts"
333
+
334
+ Skill: "Would you like to discuss anything else?"
335
+
336
+ User: "No, update the spec"
337
+
338
+ Skill: [Updates Requirements, adds email notification requirement]
339
+ Skill: [Updates Affected Domains, adds email service integration]
340
+ Skill: [Updates Acceptance Criteria, adds notification verification]
341
+ Skill: "Feature specification updated. Changes:
342
+ - Added: Email notification when emergency window starts
343
+ - Added: Integration with email service
344
+ Review the changes and run: /plan-implementation 12345-implement-your-new-feature when ready"
345
+ ```
346
+
347
+ ### Example 3: Simplification
348
+
349
+ ```
350
+ User: /discuss-feature PROJ-1234-add-feature
351
+
352
+ Skill: "What would you like to discuss or change about this feature?"
353
+
354
+ User: "Remove or simplify requirements"
355
+
356
+ Skill: "Current requirements include:
357
+ 1. Emergency schedule CRUD
358
+ 2. Email notifications
359
+ 3. Audit logging
360
+ 4. Analytics tracking
361
+ Which are critical for MVP?"
362
+
363
+ User: "Just #1 and #3. We can add notifications and analytics later"
364
+
365
+ Skill: "So we'll keep emergency schedule CRUD and audit logging, defer notifications and analytics to future work?"
366
+
367
+ User: "Correct"
368
+
369
+ Skill: [Updates Requirements, moves #2 and #4 to "Future Enhancements" section]
370
+ Skill: [Updates Affected Domains, removes email and analytics integrations]
371
+ Skill: "Feature specification updated. Changes:
372
+ - Removed: Email notifications (moved to future enhancements)
373
+ - Removed: Analytics tracking (moved to future enhancements)
374
+ - Kept: Core CRUD and audit logging
375
+ The simplified scope should reduce implementation complexity significantly."
376
+ ```
377
+
378
+ ## Tips for Effective Discussion
379
+
380
+ 1. **Read the spec first** - Understand current state before asking questions
381
+ 2. **Focus on one topic** - Don't try to discuss everything at once
382
+ 3. **Ask open questions** - Let user explain their thinking
383
+ 4. **Present options** - Give user choices with pros/cons
384
+ 5. **Challenge gently** - "Have you considered..." not "You should..."
385
+ 6. **Summarize often** - Confirm understanding before moving on
386
+ 7. **Track rationale** - Document WHY decisions were made
387
+ 8. **Be patient** - Allow multiple rounds until clarity emerges
388
+
389
+ ## Related Documentation
390
+
391
+ - [5-Phase Workflow Guide](../docs/workflow-guide.md)
392
+ - [plan-feature command](./plan-feature.md)
393
+ - [plan-implementation command](./plan-implementation.md)