Initial commit
This commit is contained in:
Zhongwei Li
998
commands/plan.md
Normal file
998
commands/plan.md
Normal file
@@ -0,0 +1,998 @@
|
||||
---
|
||||
description: Generate implementation specification from problem analysis with flexible input sources
|
||||
argument-hint: [jira-id|github-issue-url|--input path|--from-scratch description] [--work-dir PATH]
|
||||
allowed-tools: ["Read", "Grep", "Glob", "Task", "mcp__jira__*", "mcp__jetbrains__*", "Bash", "AskUserQuestion", "Write"]
|
||||
---
|
||||
|
||||
# Create Specification Workflow
|
||||
|
||||
You are **creating an implementation specification** that bridges problem analysis and implementation. This spec transforms exploratory analysis into actionable, clear implementation guidance.
|
||||
|
||||
---
|
||||
|
||||
## ARGUMENT PARSING
|
||||
|
||||
Parse command arguments using lib/argument-parser.md:
|
||||
|
||||
```
|
||||
Configuration:
|
||||
command_name: "plan"
|
||||
command_label: "Create-Spec"
|
||||
|
||||
positional:
|
||||
- name: "input"
|
||||
description: "Jira ID, GitHub URL, analysis file path, or description"
|
||||
required: false
|
||||
|
||||
flags:
|
||||
- name: "--input"
|
||||
type: "path"
|
||||
description: "Analysis file path"
|
||||
- name: "--output"
|
||||
type: "path"
|
||||
description: "Custom output file path"
|
||||
- name: "--from-scratch"
|
||||
type: "string"
|
||||
description: "Create spec without analysis"
|
||||
- name: "--work-dir"
|
||||
type: "path"
|
||||
description: "Custom work directory"
|
||||
- name: "--no-file"
|
||||
type: "boolean"
|
||||
description: "Skip file creation, terminal only"
|
||||
- name: "--quiet"
|
||||
type: "boolean"
|
||||
description: "Suppress terminal output"
|
||||
- name: "--post-to-jira"
|
||||
type: "boolean"
|
||||
description: "Post spec as Jira comment"
|
||||
|
||||
validation:
|
||||
- Check for conflicting flags (--input with --from-scratch)
|
||||
- Ensure at least one input source provided
|
||||
```
|
||||
|
||||
**Store parsed values:**
|
||||
- `input_value`: Positional argument or --input value or --from-scratch value
|
||||
- `output_path`: --output value or null
|
||||
- `work_dir`: --work-dir value or null
|
||||
- `file_output`: true (unless --no-file)
|
||||
- `terminal_output`: true (unless --quiet)
|
||||
- `jira_posting`: true if --post-to-jira, else false
|
||||
- `from_scratch_mode`: true if --from-scratch flag present
|
||||
|
||||
---
|
||||
|
||||
## PHASE 1: INPUT VALIDATION & ANALYSIS EXTRACTION
|
||||
|
||||
### Step 1.1: Classify and Validate Input Type
|
||||
|
||||
**Input classification:**
|
||||
|
||||
1. **Research File** (✅ VALID - --input flag)
|
||||
- Pattern: `--input ./research-*.md`
|
||||
- Has deep technical analysis with file:line references
|
||||
- Action: Read and extract research analysis
|
||||
|
||||
2. **Analysis File (Legacy)** (✅ VALID - --input flag)
|
||||
- Pattern: `--input ./analysis-*.md`
|
||||
- Has technical analysis with file:line references (from old analyze command)
|
||||
- Action: Read and extract analysis
|
||||
- Note: Legacy support, use research command for new workflows
|
||||
|
||||
3. **From Scratch** (✅ VALID - --from-scratch flag)
|
||||
- Pattern: `--from-scratch "description"`
|
||||
- Bypass research requirement
|
||||
- Action: Interactive minimal spec creation
|
||||
|
||||
4. **Conversation Analysis** (✅ VALID - no args, research/analysis in conversation)
|
||||
- Pattern: No arguments
|
||||
- Recent `/schovi:research` or `/schovi:analyze` output in conversation
|
||||
- Action: Extract from conversation history
|
||||
|
||||
5. **Brainstorm File** (❌ INVALID - requires research first)
|
||||
- Pattern: `--input ./brainstorm-*.md`
|
||||
- Has multiple solution options, lacks deep technical analysis
|
||||
- Action: STOP with guidance to run research first
|
||||
|
||||
6. **Raw Input** (❌ INVALID - Jira ID, GitHub URL, text description)
|
||||
- Patterns: `EC-1234`, `#123`, `owner/repo#123`, free text without --from-scratch
|
||||
- Requires research first
|
||||
- Action: STOP with guidance message
|
||||
|
||||
**If input type is INVALID (Raw inputs or brainstorm without research):**
|
||||
|
||||
Determine specific error type and display appropriate message:
|
||||
|
||||
#### Error Type A: Raw Input (Jira, GitHub, text without flags)
|
||||
|
||||
```markdown
|
||||
╭─────────────────────────────────────────────────────────────────╮
|
||||
│ ❌ RESEARCH REQUIRED BEFORE SPECIFICATION GENERATION │
|
||||
╰─────────────────────────────────────────────────────────────────╯
|
||||
|
||||
**Problem**: Cannot generate actionable specification without deep technical research.
|
||||
|
||||
**Input Detected**: [Describe what was provided - Jira ID, GitHub URL, description]
|
||||
|
||||
**Why Research is Required**:
|
||||
Specifications need specific file locations, affected components, and technical context
|
||||
to generate actionable implementation tasks. Without research:
|
||||
|
||||
❌ Tasks will be vague: "Fix the bug" instead of "Update validation in Validator.ts:67"
|
||||
❌ No clear entry points: Which files to change?
|
||||
❌ Missing context: How do components interact?
|
||||
❌ Unclear scope: What else might be affected?
|
||||
|
||||
**Required Workflow**:
|
||||
|
||||
🧠 **Step 1: Brainstorm Options** (optional, recommended)
|
||||
Explore 2-3 solution approaches:
|
||||
/schovi:brainstorm [your-input]
|
||||
|
||||
🔬 **Step 2: Deep Research** (required)
|
||||
Analyze ONE specific approach:
|
||||
/schovi:research --input brainstorm-[id].md --option [N]
|
||||
OR directly: /schovi:research --input [your-input]
|
||||
|
||||
📋 **Step 3: Create Spec** (this command)
|
||||
Generate implementation plan:
|
||||
/schovi:plan --input research-[id].md
|
||||
|
||||
**Quick Path** (skip brainstorm):
|
||||
|
||||
# Direct deep research
|
||||
/schovi:research --input [jira-id|github-url|file]
|
||||
/schovi:plan --input research-[id].md
|
||||
|
||||
**Simple Tasks** (skip research):
|
||||
|
||||
# Create minimal spec without research
|
||||
/schovi:plan --from-scratch "Task description"
|
||||
|
||||
**Examples**:
|
||||
|
||||
# Wrong: Raw input
|
||||
/schovi:plan EC-1234 ❌
|
||||
|
||||
# Right: Research first
|
||||
/schovi:research --input EC-1234
|
||||
/schovi:plan --input research-EC-1234.md ✅
|
||||
|
||||
# Or full workflow
|
||||
/schovi:brainstorm EC-1234
|
||||
/schovi:research --input brainstorm-EC-1234.md --option 2
|
||||
/schovi:plan --input research-EC-1234-option2.md ✅
|
||||
```
|
||||
|
||||
#### Error Type B: Brainstorm File (--input brainstorm-*.md)
|
||||
|
||||
```markdown
|
||||
╭─────────────────────────────────────────────────────────────────╮
|
||||
│ ❌ BRAINSTORM CANNOT BE USED DIRECTLY FOR SPECIFICATION │
|
||||
╰─────────────────────────────────────────────────────────────────╯
|
||||
|
||||
**Problem**: Brainstorm files contain multiple solution options without deep technical analysis.
|
||||
|
||||
**Input Detected**: [brainstorm file path]
|
||||
|
||||
**Why Research is Required**:
|
||||
Brainstorm provides 2-3 high-level solution options with broad feasibility analysis.
|
||||
To create actionable implementation tasks, you must:
|
||||
|
||||
1. Choose ONE option from brainstorm
|
||||
2. Perform deep technical research on that option
|
||||
3. Then create specification from research
|
||||
|
||||
Brainstorm → Research → Plan
|
||||
(2-3 opts) (1 deep) (spec)
|
||||
|
||||
**Required Actions**:
|
||||
|
||||
🔬 **Run research on chosen option**:
|
||||
|
||||
# Research option 2 from brainstorm
|
||||
/schovi:research --input [brainstorm-file] --option 2
|
||||
|
||||
# Then create spec from research
|
||||
/schovi:plan --input research-[id]-option2.md
|
||||
|
||||
**Available Options** (from your brainstorm):
|
||||
[List options from brainstorm file if readable]
|
||||
|
||||
**Example**:
|
||||
|
||||
# Wrong: Use brainstorm directly
|
||||
/schovi:plan --input brainstorm-EC-1234.md ❌
|
||||
|
||||
# Right: Research first, then plan
|
||||
/schovi:research --input brainstorm-EC-1234.md --option 2
|
||||
/schovi:plan --input research-EC-1234-option2.md ✅
|
||||
```
|
||||
|
||||
**Workflow**:
|
||||
┌─────────────┐ ┌──────────────┐ ┌──────────────┐ ┌─────────────┐
|
||||
│ Problem │ → │ Brainstorm │ → │ Research │ → │ Plan │
|
||||
│ (Jira, GH) │ │ (2-3 opts) │ │ (1 deep) │ │ (Spec Gen) │
|
||||
└─────────────┘ └──────────────┘ └──────────────┘ └─────────────┘
|
||||
↓ optional ↑ required
|
||||
└─────────────────────────┘
|
||||
|
||||
╭─────────────────────────────────────────────────────────────────────────────╮
|
||||
│ 💡 TIP: Run /schovi:research --input [input] to perform deep analysis first │
|
||||
╰─────────────────────────────────────────────────────────────────────────────╯
|
||||
```
|
||||
|
||||
**HALT EXECUTION** - Do not proceed.
|
||||
|
||||
---
|
||||
|
||||
### Step 1.2: Extract Analysis Content
|
||||
|
||||
**Based on validated input type:**
|
||||
|
||||
#### Option A: Research/Analysis File (--input flag provided)
|
||||
|
||||
```
|
||||
1. Acknowledge file read:
|
||||
📄 **[Create-Spec]** Reading research from file: [PATH]
|
||||
|
||||
2. Use Read tool to load file contents:
|
||||
file_path: [PATH from --input flag]
|
||||
|
||||
3. If file doesn't exist or read fails:
|
||||
❌ **[Create-Spec]** File not found: [PATH]
|
||||
|
||||
Ask user for correct path or alternative input source.
|
||||
HALT EXECUTION
|
||||
|
||||
4. If file loads successfully:
|
||||
✅ **[Create-Spec]** File loaded ([X] lines)
|
||||
|
||||
5. Extract key content based on file type:
|
||||
|
||||
**For Research Files (research-*.md)**:
|
||||
- Problem/topic summary (from 📋 Problem/Topic Summary section)
|
||||
- Research focus and specific approach
|
||||
- Current state analysis with file:line references
|
||||
- Architecture overview with components
|
||||
- Technical deep dive (data flow, dependencies, code quality)
|
||||
- Implementation considerations (complexity, testing, risks)
|
||||
- Performance and security implications
|
||||
|
||||
**For Analysis Files (analysis-*.md - legacy)**:
|
||||
- Problem summary (core issue, impact, severity)
|
||||
- Affected components with file:line references
|
||||
- User flow and data flow (if present)
|
||||
- Solution proposals with pros/cons
|
||||
- Technical details and dependencies
|
||||
|
||||
6. Verify content quality:
|
||||
- Check: Has file:line references? (Critical for actionable spec)
|
||||
- Check: Has affected components identified?
|
||||
- Check: Has problem description?
|
||||
- Check: Has technical context (architecture, dependencies)?
|
||||
|
||||
If missing critical elements → Flag for enrichment in Step 1.3
|
||||
```
|
||||
|
||||
#### Option B: Conversation Analysis (no arguments, search conversation)
|
||||
|
||||
```
|
||||
1. Acknowledge search:
|
||||
🔍 **[Create-Spec]** Searching conversation for research output...
|
||||
|
||||
2. Search conversation history (last 100 messages) for:
|
||||
- Messages containing "/schovi:research" command (priority)
|
||||
- Messages containing "/schovi:analyze" command (legacy)
|
||||
- Messages with research sections ("## 🔬 Research:", "## 📋 Problem/Topic Summary", etc.)
|
||||
- Messages with analysis sections ("## 🎯 1. PROBLEM SUMMARY", etc.)
|
||||
- File:line references in recent messages
|
||||
|
||||
3. If research/analysis found:
|
||||
✅ **[Create-Spec]** Found research from [N messages ago]
|
||||
|
||||
Extract same content as Option A (research or analysis format)
|
||||
|
||||
4. If NOT found:
|
||||
⚠️ **[Create-Spec]** No research found in recent conversation
|
||||
|
||||
Ask user to:
|
||||
1. Run: /schovi:research --input [input] first
|
||||
2. Provide research file: /schovi:plan --input ./research-[id].md
|
||||
3. Create simple spec: /schovi:plan --from-scratch "description"
|
||||
|
||||
HALT EXECUTION
|
||||
|
||||
5. Verify content quality (same checks as Option A)
|
||||
```
|
||||
|
||||
#### Option C: From Scratch (--from-scratch flag provided)
|
||||
|
||||
```
|
||||
1. Acknowledge mode:
|
||||
✨ **[Create-Spec]** Creating spec from scratch...
|
||||
|
||||
2. Parse provided description from --from-scratch argument
|
||||
|
||||
3. Use AskUserQuestion tool for interactive requirements gathering:
|
||||
|
||||
Q1: "What is the primary goal of this task?"
|
||||
Options: "Bug fix", "New feature", "Refactoring", "Technical debt", "Other"
|
||||
|
||||
Q2: "Which components or areas will be affected?"
|
||||
Free text input
|
||||
|
||||
Q3: "What are the key requirements or acceptance criteria?"
|
||||
Free text input (bullet points encouraged)
|
||||
|
||||
Q4: "Any known constraints or risks?" (Optional)
|
||||
Free text input
|
||||
|
||||
4. Acknowledge collected info:
|
||||
✅ **[Create-Spec]** Requirements collected
|
||||
|
||||
5. Prepare minimal spec data:
|
||||
- Title: From description
|
||||
- Goal: From Q1
|
||||
- Affected areas: From Q2 (high-level, no file:line refs)
|
||||
- Acceptance criteria: From Q3
|
||||
- Constraints/risks: From Q4
|
||||
|
||||
6. Template type: "minimal" (no flows, no solution comparisons)
|
||||
|
||||
7. Skip enrichment step (from-scratch intentionally lacks technical detail)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 1.3: Optional Context Enrichment (If Analysis Lacks File:Line References)
|
||||
|
||||
**Skip this step if:**
|
||||
- From-scratch mode is active
|
||||
- Analysis already has sufficient file:line references
|
||||
|
||||
**If analysis is vague (missing specific file locations):**
|
||||
|
||||
```
|
||||
1. Detect gaps:
|
||||
- Count file:line references in analysis
|
||||
- If < 3 references found → Analysis may be too vague
|
||||
|
||||
2. Ask user for permission:
|
||||
⚠️ **[Create-Spec]** The analysis appears to lack specific file locations.
|
||||
|
||||
Options:
|
||||
1. Enrich via quick codebase search (20-40 seconds, finds exact files)
|
||||
2. Skip enrichment (spec will have high-level tasks)
|
||||
3. Manually provide file locations
|
||||
|
||||
Which would you prefer? [1/2/3]
|
||||
|
||||
3. If user chooses option 1 (Enrich):
|
||||
⏳ **[Create-Spec]** Enriching analysis with file locations...
|
||||
|
||||
Use Task tool with Explore subagent (quick mode):
|
||||
- Search for components mentioned in analysis
|
||||
- Find file locations for affected areas
|
||||
- Add file:line references to analysis
|
||||
|
||||
✅ **[Create-Spec]** Enrichment complete ([N] file references added)
|
||||
|
||||
4. If user chooses option 2 (Skip):
|
||||
⚠️ **[Create-Spec]** Proceeding without enrichment (spec will be high-level)
|
||||
|
||||
5. If user chooses option 3 (Manual):
|
||||
Ask user to provide file locations, then merge with analysis
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 1.4: Detect User's Chosen Approach (If Multiple Solutions in Analysis)
|
||||
|
||||
**If analysis contains multiple solution options:**
|
||||
|
||||
```
|
||||
1. Search for user preference in:
|
||||
- User messages after analysis
|
||||
- Jira comments (if from Jira)
|
||||
- File content (if from file)
|
||||
|
||||
2. Look for patterns:
|
||||
- "Let's go with Option [N]"
|
||||
- "I prefer Option [N]"
|
||||
- "Option [N] makes most sense"
|
||||
|
||||
3. If preference found:
|
||||
✅ **[Create-Spec]** Detected preference: Option [N] - [Solution Name]
|
||||
|
||||
4. If preference NOT found:
|
||||
⚠️ **[Create-Spec]** Multiple options available, no clear preference
|
||||
|
||||
Use AskUserQuestion tool:
|
||||
"Which approach should I use for the spec?"
|
||||
|
||||
Options (from analysis):
|
||||
- Option 1: [Name] - [Brief description]
|
||||
- Option 2: [Name] - [Brief description]
|
||||
- Option 3: [Name] - [Brief description]
|
||||
|
||||
Wait for user selection
|
||||
|
||||
5. Confirm selection:
|
||||
🎯 **[Create-Spec]** Selected approach: Option [N] - [Solution Name]
|
||||
```
|
||||
|
||||
**If single approach or from-scratch mode:**
|
||||
- Skip selection step
|
||||
- Use the single approach or minimal template
|
||||
|
||||
---
|
||||
|
||||
### Step 1.5: Work Folder Resolution
|
||||
|
||||
Use lib/work-folder.md:
|
||||
|
||||
```
|
||||
Configuration:
|
||||
mode: "auto-detect"
|
||||
|
||||
identifier: [Jira ID from analysis, or null]
|
||||
description: [Problem title from analysis]
|
||||
|
||||
workflow_type: "full"
|
||||
current_step: "plan"
|
||||
|
||||
custom_work_dir: [work_dir from arguments, or null]
|
||||
|
||||
Output (store for later phases):
|
||||
work_folder: [path from library, e.g., ".WIP/EC-1234-feature"]
|
||||
metadata_file: [path from library, e.g., ".WIP/EC-1234-feature/.metadata.json"]
|
||||
output_file: [path from library, e.g., ".WIP/EC-1234-feature/plan-EC-1234.md"]
|
||||
identifier: [identifier from library]
|
||||
is_new: [true/false from library]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Phase 1 Validation Checkpoint:**
|
||||
```
|
||||
- [ ] Input type validated (analysis file / conversation / from-scratch)
|
||||
- [ ] If raw input: STOPPED with guidance (not proceeded)
|
||||
- [ ] If valid: Analysis content extracted
|
||||
- [ ] Analysis quality checked (file:line refs present or enriched)
|
||||
- [ ] Enrichment decision made (yes/no/manual/skipped)
|
||||
- [ ] Chosen approach identified (if multiple options)
|
||||
- [ ] Work folder resolved (if applicable)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## PHASE 1.5: LOAD FRAGMENT CONTEXT (if fragments exist)
|
||||
|
||||
**Objective**: Load existing fragment registry and details to pass to spec-generator for acceptance criteria traceability.
|
||||
|
||||
**Use lib/fragment-loader.md**:
|
||||
|
||||
### Step 1.5.1: Check if fragments exist (Operation 1)
|
||||
|
||||
```
|
||||
work_folder: [work_folder from Phase 1]
|
||||
```
|
||||
|
||||
**If fragments don't exist**:
|
||||
- Skip this phase, proceed to Phase 2
|
||||
- Spec generation works without fragment context
|
||||
|
||||
**If fragments exist**:
|
||||
- Continue to next steps
|
||||
|
||||
### Step 1.5.2: Load fragment registry (Operation 2)
|
||||
|
||||
```
|
||||
work_folder: [work_folder path]
|
||||
```
|
||||
|
||||
**Parse registry for**:
|
||||
- Count of assumptions (A-#)
|
||||
- Count of risks (R-#)
|
||||
- Count of metrics (M-#)
|
||||
|
||||
**Store**:
|
||||
- `fragments_exist`: true
|
||||
- `assumption_count`: N
|
||||
- `risk_count`: N
|
||||
- `metric_count`: N
|
||||
|
||||
### Step 1.5.3: Load all assumptions (Operation 4)
|
||||
|
||||
```
|
||||
work_folder: [work_folder]
|
||||
fragment_type: "A"
|
||||
```
|
||||
|
||||
**For each assumption**:
|
||||
- Extract ID (A-1, A-2, ...)
|
||||
- Extract statement
|
||||
- Extract current status (pending, validated, failed)
|
||||
|
||||
**Store**:
|
||||
- `assumptions_list`: [
|
||||
{id: "A-1", statement: "...", status: "validated"},
|
||||
{id: "A-2", statement: "...", status: "pending"}
|
||||
]
|
||||
|
||||
### Step 1.5.4: Load all risks (Operation 4)
|
||||
|
||||
```
|
||||
work_folder: [work_folder]
|
||||
fragment_type: "R"
|
||||
```
|
||||
|
||||
**For each risk**:
|
||||
- Extract ID (R-1, R-2, ...)
|
||||
- Extract description
|
||||
- Extract impact/probability
|
||||
|
||||
**Store**:
|
||||
- `risks_list`: [
|
||||
{id: "R-1", description: "...", impact: "High", probability: "Medium"},
|
||||
{id: "R-2", description: "...", impact: "Medium", probability: "Low"}
|
||||
]
|
||||
|
||||
### Step 1.5.5: Load all metrics (Operation 4)
|
||||
|
||||
```
|
||||
work_folder: [work_folder]
|
||||
fragment_type: "M"
|
||||
```
|
||||
|
||||
**For each metric**:
|
||||
- Extract ID (M-1, M-2, ...)
|
||||
- Extract description
|
||||
- Extract target
|
||||
|
||||
**Store**:
|
||||
- `metrics_list`: [
|
||||
{id: "M-1", description: "...", target: "p95 < 200ms"},
|
||||
{id: "M-2", description: "...", target: "< 0.1% error rate"}
|
||||
]
|
||||
|
||||
**After Phase 1.5**:
|
||||
- Fragment context loaded (if exists)
|
||||
- Ready to pass summaries to spec-generator
|
||||
|
||||
---
|
||||
|
||||
## PHASE 2: SPEC GENERATION
|
||||
|
||||
### Step 2.1: Prepare Input Context for Spec Generator
|
||||
|
||||
Build structured input context from analysis extraction:
|
||||
|
||||
```markdown
|
||||
## Input Context
|
||||
|
||||
### Problem Summary
|
||||
[Problem description from analysis - 2-4 sentences]
|
||||
|
||||
### Chosen Approach
|
||||
[If multiple options existed: "Option [N]: [Name]"]
|
||||
[Detailed approach description from analysis]
|
||||
|
||||
### Technical Details
|
||||
- Affected files: [List with file:line references from analysis]
|
||||
- User flow: [Flow description if present]
|
||||
- Data flow: [Flow description if present]
|
||||
- Dependencies: [List of dependencies if identified]
|
||||
|
||||
### Fragment Context (if fragments_exist == true)
|
||||
|
||||
**Validated Assumptions** (from research):
|
||||
[For each in assumptions_list:]
|
||||
- [id]: [statement] - Status: [status]
|
||||
|
||||
Example:
|
||||
- A-1: Database supports transactions - Status: ✅ Validated
|
||||
- A-2: Frontend handles async responses - Status: ✅ Validated
|
||||
- A-3: External API supports webhooks - Status: ⏳ Pending
|
||||
|
||||
**Identified Risks** (from research):
|
||||
[For each in risks_list:]
|
||||
- [id]: [description] - Impact: [impact], Probability: [probability]
|
||||
|
||||
Example:
|
||||
- R-1: Database migration may cause downtime - Impact: High, Probability: Medium
|
||||
- R-2: Caching layer consistency issues - Impact: Medium, Probability: Low
|
||||
|
||||
**Defined Metrics** (from research):
|
||||
[For each in metrics_list:]
|
||||
- [id]: [description] - Target: [target]
|
||||
|
||||
Example:
|
||||
- M-1: API response time - Target: p95 < 200ms
|
||||
- M-2: Error rate during rollout - Target: < 0.1%
|
||||
|
||||
**Traceability Guidance**:
|
||||
Create acceptance criteria that:
|
||||
1. Validate pending assumptions (link with "validates: A-#")
|
||||
2. Mitigate identified risks (link with "mitigates: R-#")
|
||||
3. Verify metrics are met (link with "verifies: M-#")
|
||||
|
||||
[If fragments_exist == false:]
|
||||
No fragment context available. Spec generator will create acceptance criteria without fragment linkage.
|
||||
|
||||
### User Notes
|
||||
[Any user preferences, comments, or special requirements]
|
||||
|
||||
### Metadata
|
||||
- Jira ID: [ID or N/A]
|
||||
- Created date: [Today's date in YYYY-MM-DD format]
|
||||
- Created by: Claude Code
|
||||
- Template type: [full or minimal]
|
||||
- Fragments available: [true/false]
|
||||
```
|
||||
|
||||
**Template type selection:**
|
||||
- **"full"**: When detailed analysis exists (file:line refs, flows, multiple options considered)
|
||||
- **"minimal"**: When from-scratch mode or simple tasks without deep analysis
|
||||
|
||||
### Step 2.2: Spawn Spec Generator Subagent
|
||||
|
||||
```
|
||||
⏳ **[Create-Spec]** Generating implementation specification...
|
||||
```
|
||||
|
||||
Use Task tool to spawn spec-generator subagent:
|
||||
|
||||
```
|
||||
Task tool parameters:
|
||||
subagent_type: "schovi:spec-generator:spec-generator"
|
||||
description: "Generate implementation spec"
|
||||
prompt: """
|
||||
[Full input context from Step 2.1, formatted as markdown with all sections]
|
||||
"""
|
||||
```
|
||||
|
||||
**Important**: Use three-part naming format `schovi:spec-generator:spec-generator` for proper subagent resolution.
|
||||
|
||||
### Step 2.3: Receive and Validate Spec
|
||||
|
||||
The subagent will return spec with visual header/footer:
|
||||
|
||||
```markdown
|
||||
╭─────────────────────────────────────────────╮
|
||||
│ 📋 SPEC GENERATOR │
|
||||
╰─────────────────────────────────────────────╯
|
||||
|
||||
[FULL SPEC CONTENT - YAML frontmatter + all sections]
|
||||
|
||||
╭─────────────────────────────────────────────╮
|
||||
✅ Spec generated | ~[X] tokens | [Y] lines
|
||||
╰─────────────────────────────────────────────╯
|
||||
```
|
||||
|
||||
**Validation checks:**
|
||||
- [ ] Spec has YAML frontmatter with title, status, jira_id
|
||||
- [ ] Decision rationale present (full) or goal statement (minimal)
|
||||
- [ ] Implementation tasks are specific and actionable with checkboxes
|
||||
- [ ] Acceptance criteria are testable with checkboxes
|
||||
- [ ] Testing strategy included
|
||||
- [ ] File references use `file:line` format where applicable
|
||||
- [ ] Total spec is under 3000 tokens
|
||||
- [ ] Markdown formatting is valid
|
||||
|
||||
**If validation fails:**
|
||||
|
||||
```
|
||||
⚠️ **[Create-Spec]** Spec validation failed: [Issue description]
|
||||
|
||||
Regenerating with more specific guidance...
|
||||
```
|
||||
|
||||
Re-invoke Task tool with additional clarification in prompt.
|
||||
|
||||
**If subagent fails completely:**
|
||||
|
||||
```
|
||||
❌ **[Create-Spec]** Spec generation failed: [Error message]
|
||||
|
||||
Cannot proceed without specification. Please check:
|
||||
- Analysis content is complete
|
||||
- Technical details are present
|
||||
- File references are available
|
||||
|
||||
Would you like to:
|
||||
1. Try from-scratch mode: /schovi:plan --from-scratch "description"
|
||||
2. Provide more analysis detail
|
||||
3. Create spec manually
|
||||
```
|
||||
|
||||
HALT EXECUTION - Do not attempt fallback generation in main context.
|
||||
|
||||
**If successful:**
|
||||
|
||||
```
|
||||
✅ **[Create-Spec]** Specification generated ([X] lines, [Y] tasks, [Z] criteria)
|
||||
```
|
||||
|
||||
Extract spec content (strip visual header/footer) and store for Phase 3 output handling.
|
||||
|
||||
---
|
||||
|
||||
## PHASE 3: OUTPUT HANDLING
|
||||
|
||||
Use lib/output-handler.md:
|
||||
|
||||
```
|
||||
Configuration:
|
||||
content: [Generated spec from Phase 2]
|
||||
content_type: "plan"
|
||||
command_label: "Create-Spec"
|
||||
|
||||
flags:
|
||||
terminal_output: [terminal_output from argument parsing]
|
||||
file_output: [file_output from argument parsing]
|
||||
jira_posting: [jira_posting from argument parsing]
|
||||
|
||||
file_config:
|
||||
output_path: [output_path from arguments, or null for auto]
|
||||
default_basename: "plan"
|
||||
work_folder: [work_folder from Step 1.5, or null]
|
||||
jira_id: [from analysis, or null]
|
||||
workflow_step: "plan"
|
||||
|
||||
jira_config:
|
||||
jira_id: [from analysis, or null]
|
||||
cloud_id: "productboard.atlassian.net"
|
||||
jira_title: "Implementation Specification"
|
||||
jira_author: "Claude Code"
|
||||
|
||||
Output (store result for Phase 4):
|
||||
output_result: {
|
||||
terminal_displayed: [true/false],
|
||||
file_created: [true/false],
|
||||
file_path: [path or null],
|
||||
jira_posted: [true/false],
|
||||
metadata_updated: [true/false]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## PHASE 3.5: CREATE AC/EC FRAGMENTS (if fragments exist)
|
||||
|
||||
**Objective**: Parse spec output for acceptance criteria and exit criteria, create fragment files for traceability.
|
||||
|
||||
**If `fragments_exist == false` from Phase 1.5**:
|
||||
- Skip this phase, proceed to Phase 4
|
||||
- Spec works without fragments
|
||||
|
||||
**If `fragments_exist == true`**:
|
||||
|
||||
**Use lib/fragment-loader.md**:
|
||||
|
||||
Parse spec output (from Phase 2) for:
|
||||
1. **Acceptance Criteria**
|
||||
2. **Exit Criteria** (phase gates)
|
||||
|
||||
### Step 3.5.1: Create Acceptance Criteria Fragments
|
||||
|
||||
**Parse spec** for acceptance criteria section:
|
||||
- Look for lines starting with "- [ ]" under "Acceptance Criteria"
|
||||
- Extract criterion text
|
||||
- Extract fragment references: `*(validates: A-#, mitigates: R-#, verifies: M-#)*`
|
||||
|
||||
**For each AC**:
|
||||
|
||||
**Get next AC number** (Operation 11):
|
||||
```
|
||||
work_folder: [work_folder]
|
||||
fragment_type: "AC"
|
||||
```
|
||||
Returns next_number (e.g., 1, 2, 3, ...)
|
||||
|
||||
**Create AC fragment** (Operation 7):
|
||||
```
|
||||
work_folder: [work_folder]
|
||||
fragment_type: "AC"
|
||||
fragment_number: [next_number]
|
||||
fragment_data: {
|
||||
statement: [criterion text],
|
||||
validates: [A-IDs extracted from references],
|
||||
mitigates: [R-IDs extracted from references],
|
||||
verifies: [M-IDs extracted from references],
|
||||
verification_method: [extracted from spec if available],
|
||||
stage: "plan",
|
||||
timestamp: [current_timestamp]
|
||||
}
|
||||
```
|
||||
|
||||
**Get current timestamp**:
|
||||
```bash
|
||||
date -u +"%Y-%m-%dT%H:%M:%SZ"
|
||||
```
|
||||
|
||||
**Result**: New fragment file created (e.g., `fragments/AC-1.md`, `fragments/AC-2.md`, ...)
|
||||
|
||||
### Step 3.5.2: Create Exit Criteria Fragments
|
||||
|
||||
**Parse spec** for exit criteria by phase:
|
||||
- Look for exit criteria in implementation plan (usually in phases or deployment plan)
|
||||
- Extract criterion text
|
||||
- Extract phase name
|
||||
- Extract which ACs it validates
|
||||
|
||||
**For each EC**:
|
||||
|
||||
**Get next EC number** (Operation 11):
|
||||
```
|
||||
work_folder: [work_folder]
|
||||
fragment_type: "EC"
|
||||
```
|
||||
|
||||
**Create EC fragment** (Operation 7):
|
||||
```
|
||||
work_folder: [work_folder]
|
||||
fragment_type: "EC"
|
||||
fragment_number: [next_number]
|
||||
fragment_data: {
|
||||
statement: [criterion text],
|
||||
phase: [phase name - e.g., "Phase 1", "Pre-deployment"],
|
||||
validates: [AC-IDs this criterion proves],
|
||||
verification_method: [how to verify - e.g., command, test],
|
||||
stage: "plan",
|
||||
timestamp: [current_timestamp]
|
||||
}
|
||||
```
|
||||
|
||||
**Result**: New fragment file created (e.g., `fragments/EC-1.md`, `fragments/EC-2.md`, ...)
|
||||
|
||||
### Step 3.5.3: Update Fragment Registry (Operation 9)
|
||||
|
||||
**Update registry** with all new fragments:
|
||||
- New acceptance criteria added (AC-1, AC-2, ...)
|
||||
- New exit criteria added (EC-1, EC-2, ...)
|
||||
- Summary counts updated
|
||||
|
||||
**Update**:
|
||||
```
|
||||
work_folder: [work_folder]
|
||||
identifier: [identifier]
|
||||
updates: [all AC and EC fragment updates from above steps]
|
||||
```
|
||||
|
||||
**Result**: `fragments.md` registry updated with AC/EC fragments
|
||||
|
||||
**If fragment creation fails**:
|
||||
- Log warning but don't block command
|
||||
- Continue to Phase 4
|
||||
|
||||
---
|
||||
|
||||
## PHASE 4: COMPLETION & NEXT STEPS
|
||||
|
||||
Use lib/completion-handler.md:
|
||||
|
||||
```
|
||||
Configuration:
|
||||
command_type: "plan"
|
||||
command_label: "Create-Spec"
|
||||
|
||||
summary_data:
|
||||
problem: [One-line problem summary from analysis or from-scratch input]
|
||||
output_files: [file_path from output_result if file_created]
|
||||
jira_posted: [jira_posted from output_result]
|
||||
jira_id: [from analysis or null]
|
||||
work_folder: [work_folder from Step 1.5 or null]
|
||||
terminal_only: [true if file_output was false]
|
||||
|
||||
command_specific_data:
|
||||
spec_title: [Title from generated spec]
|
||||
template: "Full" | "Minimal" [from Phase 2]
|
||||
task_count: [Count of implementation tasks in spec]
|
||||
criteria_count: [Count of acceptance criteria in spec]
|
||||
test_count: [Count of test scenarios in spec]
|
||||
|
||||
This will:
|
||||
- Display completion summary box
|
||||
- Suggest next steps (review spec, start implementation, share with team)
|
||||
- Wait for user direction
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## QUALITY GATES CHECKLIST
|
||||
|
||||
Before presenting the spec, verify ALL of these are complete:
|
||||
|
||||
### Input Validation (Phase 1)
|
||||
- [ ] Input type classified correctly (analysis file, conversation, from-scratch, or raw)
|
||||
- [ ] If raw input: STOPPED with clear guidance message (not proceeded to spec generation)
|
||||
- [ ] If valid input: Analysis content successfully extracted
|
||||
- [ ] User's chosen approach identified (or prompted if multiple options)
|
||||
- [ ] Enrichment decision made (if applicable): yes/no/manual/skipped
|
||||
|
||||
### Fragment Loading (Phase 1.5, if applicable)
|
||||
- [ ] Fragment existence checked (if work folder available)
|
||||
- [ ] If fragments exist: Assumptions loaded (A-#)
|
||||
- [ ] If fragments exist: Risks loaded (R-#)
|
||||
- [ ] If fragments exist: Metrics loaded (M-#)
|
||||
- [ ] Fragment context passed to spec-generator (if applicable)
|
||||
|
||||
### Spec Generation (Phase 2)
|
||||
- [ ] Spec generated via spec-generator subagent (context isolated)
|
||||
- [ ] Spec contains title and metadata
|
||||
- [ ] Decision rationale or goal statement present
|
||||
- [ ] Implementation tasks are specific and actionable (checkboxes)
|
||||
- [ ] Acceptance criteria are testable and clear
|
||||
- [ ] If fragments provided: Acceptance criteria reference fragment IDs (validates: A-#, mitigates: R-#, verifies: M-#)
|
||||
- [ ] Testing strategy included (unit/integration/manual)
|
||||
- [ ] Risks documented (if applicable for full template)
|
||||
- [ ] File references use `file:line` format where applicable
|
||||
|
||||
### Output Handling (Phase 3)
|
||||
- [ ] Terminal output displayed (unless --quiet)
|
||||
- [ ] File written to correct path (unless --no-file)
|
||||
- [ ] Jira posted successfully (if --post-to-jira flag)
|
||||
- [ ] All output operations confirmed with success messages
|
||||
- [ ] Error handling executed for any failed operations
|
||||
|
||||
### Fragment Creation (Phase 3.5, if applicable)
|
||||
- [ ] If fragments exist: Acceptance criteria fragments created (AC-1.md, AC-2.md, ...)
|
||||
- [ ] If fragments exist: Exit criteria fragments created (EC-1.md, EC-2.md, ...)
|
||||
- [ ] If fragments exist: Fragment registry updated with AC/EC counts
|
||||
- [ ] Fragment IDs properly linked to assumptions/risks/metrics
|
||||
|
||||
### Quality
|
||||
- [ ] Spec is actionable (can be implemented from it)
|
||||
- [ ] Spec is complete (all required sections present)
|
||||
- [ ] Spec is clear (no ambiguous requirements)
|
||||
- [ ] Spec matches chosen approach from analysis
|
||||
|
||||
---
|
||||
|
||||
## INTERACTION GUIDELINES
|
||||
|
||||
**Communication Style**:
|
||||
- Be clear and concise - spec generation is straightforward
|
||||
- Use visual formatting (boxes, emojis) for status updates
|
||||
- Provide helpful next steps after completion
|
||||
- Always confirm file paths and operations
|
||||
|
||||
**Handling Errors**:
|
||||
- If input source fails, offer alternatives
|
||||
- If file write fails, try alternate path or terminal-only
|
||||
- If Jira post fails, confirm file was still saved locally
|
||||
- Never fail completely - always provide partial output
|
||||
|
||||
**Flexibility**:
|
||||
- Support multiple input sources (conversation, Jira, file, scratch)
|
||||
- Support multiple output destinations (terminal, file, Jira)
|
||||
- Handle both full and minimal spec templates
|
||||
- Work with or without Jira integration
|
||||
|
||||
**Proactive Guidance**:
|
||||
After creating spec, suggest:
|
||||
- "Need me to start the implementation workspace?"
|
||||
- "Want me to break down any section further?"
|
||||
- "Should I create implementation tasks in Jira?"
|
||||
|
||||
---
|
||||
|
||||
**Command Version**: 2.0 (Fragment System Integration)
|
||||
**Last Updated**: 2025-11-08
|
||||
**Dependencies**:
|
||||
- `lib/argument-parser.md`
|
||||
- `lib/output-handler.md`
|
||||
- `lib/completion-handler.md`
|
||||
- `lib/fragment-loader.md` (NEW: Fragment loading and creation)
|
||||
- `schovi/agents/spec-generator/AGENT.md`
|
||||
- `schovi/templates/spec/full.md`
|
||||
**Changelog**: v2.0 - Added fragment system integration: loads A/R/M fragments, passes to spec-generator, creates AC/EC fragments
|
||||
|
||||
---
|
||||
|
||||
## 🚀 BEGIN WORKFLOW
|
||||
|
||||
Start with Argument Parsing, then proceed to Phase 1: Input Validation & Analysis Extraction.
|
||||
Reference in New Issue
Block a user