Initial commit

2025-11-30 08:54:26 +08:00
commit 3562b3d6a4
27 changed files with 16593 additions and 0 deletions
--- a/commands/research.md
+++ b/commands/research.md
@@ -0,0 +1,636 @@
+---
+description: Deep technical analysis of ONE specific approach with detailed file:line references
+argument-hint: --input PATH [--option N] [--output PATH] [--no-file] [--quiet] [--work-dir PATH]
+allowed-tools: ["Read", "Write", "Task", "ExitPlanMode", "AskUserQuestion"]
+---
+
+# Research Workflow
+
+You are performing **deep technical research** of ONE specific approach using the **executor pattern**. Follow this structured workflow to generate detailed analysis with comprehensive file:line references and implementation considerations.
+
+**Key Innovation**: The research-executor subagent performs ALL work (target extraction, context fetching, exploration, generation) in isolated context, keeping main context clean.
+
+---
+
+## ⚙️ MODE ENFORCEMENT
+
+**CRITICAL**: This command operates in **PLAN MODE** throughout Phases 1-2 (argument parsing and executor invocation). You MUST use the **ExitPlanMode tool** before Phase 3 (output handling) to transition from analysis to execution.
+
+**Workflow**:
+```
+┌──────────────────────────────────┐
+│  PLAN MODE (Read-only)           │
+│  Phases 1-2: Setup & Execute     │
+└──────────────────────────────────┘
+              ↓
+      [ExitPlanMode Tool]
+              ↓
+┌──────────────────────────────────┐
+│  EXECUTION MODE (Write)          │
+│  Phases 3-4: Output & Completion │
+└──────────────────────────────────┘
+```
+
+---
+
+## PHASE 1: ARGUMENT PARSING & OPTION SELECTION
+
+Use lib/argument-parser.md:
+
+```
+Configuration:
+  command_name: "research"
+  command_label: "Research-Approach"
+
+  positional: []
+
+  flags:
+    - name: "--input"
+      type: "path"
+      description: "REQUIRED: Brainstorm file, Jira ID, GitHub URL, file, or description"
+      required: true
+    - name: "--option"
+      type: "number"
+      description: "Option number to research (1, 2, 3) if input is brainstorm file"
+    - name: "--output"
+      type: "path"
+      description: "Custom output file path for research"
+    - 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"
+
+  validation:
+    - --input is REQUIRED
+    - --output and --no-file are mutually exclusive
+    - --option must be 1-5 if provided
+```
+
+**Store parsed values:**
+- `input_value`: --input value (file path, Jira ID, GitHub URL, or text)
+- `option_number`: --option value or null
+- `output_path`: --output value or null
+- `work_dir`: --work-dir value or null
+- `file_output`: true (unless --no-file)
+- `terminal_output`: true (unless --quiet)
+
+**If brainstorm file without --option flag**:
+```
+Use AskUserQuestion tool: "Which option would you like to research? (1, 2, or 3)"
+Store user response as option_number
+```
+
+---
+
+## PHASE 1.5: LOAD FRAGMENT CONTEXT (if fragments exist)
+
+**Objective**: Load existing fragment registry and assumption/unknown details to pass to research-executor for validation.
+
+**Use lib/fragment-loader.md**:
+
+### Step 1.5.1: Check if fragments exist (Operation 1)
+
+```
+work_folder: [from Phase 1, derived from input or work-folder library]
+```
+
+**If fragments don't exist**:
+- Skip this phase, proceed to Phase 2
+- Research will work without fragment context
+
+**If fragments exist**:
+- Continue to next step
+
+### Step 1.5.2: Load fragment registry (Operation 2)
+
+```
+work_folder: [work_folder path]
+```
+
+**Parse registry for**:
+- Count of assumptions (A-#)
+- Count of unknowns (U-#)
+- Current status of each
+
+**Store**:
+- `fragments_exist`: true
+- `assumption_count`: N
+- `unknown_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: "pending"},
+    {id: "A-2", statement: "...", status: "pending"}
+  ]
+
+### Step 1.5.4: Load all unknowns (Operation 4)
+
+```
+work_folder: [work_folder]
+fragment_type: "U"
+```
+
+**For each unknown**:
+- Extract ID (U-1, U-2, ...)
+- Extract question
+- Extract current status (pending, answered)
+
+**Store**:
+- `unknowns_list`: [
+    {id: "U-1", question: "...", status: "pending"},
+    {id: "U-2", question: "...", status: "pending"}
+  ]
+
+**After Phase 1.5**:
+- Fragment context loaded (if exists)
+- Ready to pass to research-executor for validation
+
+---
+
+## PHASE 2: EXECUTE RESEARCH (Isolated Context)
+
+**Objective**: Spawn research-executor subagent to perform ALL research work in isolated context, including assumption validation if fragments exist.
+
+**Use Task tool with research-executor**:
+
+```
+Task tool configuration:
+  subagent_type: "schovi:research-executor:research-executor"
+  model: "sonnet"
+  description: "Execute research workflow"
+  prompt: |
+    RESEARCH INPUT: [input_value]
+
+    CONFIGURATION:
+    - option_number: [option_number or null]
+    - identifier: [auto-detect or generate]
+    - exploration_mode: thorough
+
+    FRAGMENT CONTEXT (if fragments_exist == true):
+    ASSUMPTIONS TO VALIDATE:
+    [For each in assumptions_list:]
+    - [id]: [statement] (current status: [status])
+
+    UNKNOWNS TO INVESTIGATE:
+    [For each in unknowns_list:]
+    - [id]: [question] (current status: [status])
+
+    [If fragments_exist == false:]
+    No existing fragment context. Research will identify new assumptions/risks/metrics.
+
+    Execute complete research workflow:
+    1. Extract research target (from brainstorm option, Jira, GitHub, etc.)
+    2. Fetch external context if needed (Jira/GitHub via nested subagents)
+    3. Deep codebase exploration (Plan subagent, thorough mode)
+    4. If fragments exist: Validate each assumption and answer each unknown
+    5. Identify risks (R-1, R-2, ...) and metrics (M-1, M-2, ...)
+    6. Generate detailed technical analysis following template
+
+    Return structured research output (~4000-6000 tokens) with file:line references.
+    Include assumption validation results and unknown answers if fragments provided.
+```
+
+**Expected output from executor**:
+- Complete structured research markdown (~4000-6000 tokens)
+- Includes: problem summary, architecture, data flow, dependencies, implementation considerations, performance/security
+- All file references in file:line format
+- Already formatted following `schovi/templates/research/full.md`
+
+**Store executor output**:
+- `research_output`: Complete markdown from executor
+- `identifier`: Extract from research header or use fallback
+
+---
+
+## PHASE 3: EXIT PLAN MODE
+
+**CRITICAL**: Before proceeding to output handling, use ExitPlanMode tool.
+
+```
+ExitPlanMode tool:
+  plan: |
+    # Deep Research Completed
+
+    Research analysis completed via research-executor subagent.
+
+    **Identifier**: [identifier]
+    **Research Target**: [Brief description]
+
+    ## Key Findings
+
+    - Research target extracted and analyzed
+    - Deep codebase exploration completed (thorough mode)
+    - Architecture mapped with file:line references
+    - Dependencies identified (direct and indirect)
+    - Implementation considerations provided
+
+    ## Next Steps
+
+    1. Save research output to work folder
+    2. Display summary to user
+    3. Guide user to plan command for implementation spec
+```
+
+**Wait for user approval before proceeding to Phase 4.**
+
+---
+
+## PHASE 4: OUTPUT HANDLING & WORK FOLDER
+
+### Step 4.1: Update Fragments (if fragments exist)
+
+**If `fragments_exist == true` from Phase 1.5**:
+
+**Use lib/fragment-loader.md**:
+
+Parse research output for:
+1. **Assumption Validation Results**
+2. **Unknown Answers**
+3. **New Risks**
+4. **New Metrics**
+
+#### 4.1.1: Update Assumption Fragments (Operation 8)
+
+For each assumption in `assumptions_list`:
+
+**Parse research output** for validation section matching assumption ID:
+- Look for "Assumption Validation Matrix" table
+- Extract: validation method, result (✅/❌/⏳), evidence
+
+**Update fragment** (Operation 8):
+```
+work_folder: [work_folder]
+fragment_id: [assumption.id - e.g., "A-1"]
+updates: {
+  status: "validated" | "failed" | "pending",
+  validation_method: [extracted method],
+  validation_result: "pass" | "fail",
+  evidence: [extracted evidence items],
+  tested_by: "Research phase ([current_timestamp])"
+}
+```
+
+**Get current timestamp**:
+```bash
+date -u +"%Y-%m-%dT%H:%M:%SZ"
+```
+
+**Result**: Fragment file updated with validation results
+
+#### 4.1.2: Update Unknown Fragments (Operation 8)
+
+For each unknown in `unknowns_list`:
+
+**Parse research output** for answer matching unknown ID:
+- Look for answers in research output
+- Extract: finding, evidence, decision
+
+**Update fragment** (Operation 8):
+```
+work_folder: [work_folder]
+fragment_id: [unknown.id - e.g., "U-1"]
+updates: {
+  status: "answered" | "pending",
+  answer: [extracted finding],
+  evidence: [extracted evidence items],
+  decision: [extracted decision],
+  answered_by: "Research phase ([current_timestamp])"
+}
+```
+
+**Result**: Fragment file updated with answer
+
+#### 4.1.3: Create Risk Fragments (Operation 7)
+
+**Parse research output** for risks section:
+- Look for "Risks & Mitigation" or similar section
+- Extract risks identified
+
+**For each risk**:
+
+**Get next risk number** (Operation 11):
+```
+work_folder: [work_folder]
+fragment_type: "R"
+```
+Returns next_number (e.g., 1, 2, 3, ...)
+
+**Create risk fragment** (Operation 7):
+```
+work_folder: [work_folder]
+fragment_type: "R"
+fragment_number: [next_number]
+fragment_data: {
+  description: [risk description from research],
+  category: [Technical | Business | Operational],
+  impact: [High | Medium | Low],
+  probability: [High | Medium | Low],
+  impact_description: [what happens if risk occurs],
+  probability_rationale: [why this probability],
+  validates: [A-IDs this risk relates to],
+  mitigation_steps: [mitigation strategy],
+  contingency_steps: [contingency plan],
+  stage: "research",
+  timestamp: [current_timestamp]
+}
+```
+
+**Result**: New fragment file created (e.g., `fragments/R-1.md`)
+
+#### 4.1.4: Create Metric Fragments (Operation 7)
+
+**Parse research output** for metrics section:
+- Look for "What We Will Measure Later" section
+- Extract metrics defined
+
+**For each metric**:
+
+**Get next metric number** (Operation 11):
+```
+work_folder: [work_folder]
+fragment_type: "M"
+```
+
+**Create metric fragment** (Operation 7):
+```
+work_folder: [work_folder]
+fragment_type: "M"
+fragment_number: [next_number]
+fragment_data: {
+  description: [metric description],
+  purpose_validates: [A-IDs],
+  purpose_monitors: [R-IDs],
+  target_value: [target value],
+  acceptable_range: [min-max],
+  critical_threshold: [threshold],
+  baseline_commands: [how to establish baseline],
+  owner: [team or person],
+  timeline: [when to measure],
+  stage: "research",
+  timestamp: [current_timestamp]
+}
+```
+
+**Result**: New fragment file created (e.g., `fragments/M-1.md`)
+
+#### 4.1.5: Update Fragment Registry (Operation 9)
+
+**Update registry** with all changes:
+- Updated assumption statuses
+- Updated unknown statuses
+- New risks added
+- New metrics added
+
+**Update summary counts**:
+```
+work_folder: [work_folder]
+identifier: [identifier]
+updates: [all fragment updates from above steps]
+```
+
+**Result**: `fragments.md` registry updated with current state
+
+**If fragment updates fail**:
+- Log warning but don't block command
+- Continue to file writing
+
+### Step 4.2: Work Folder Resolution
+
+Use lib/work-folder.md:
+
+```
+Configuration:
+  mode: "auto-detect"
+
+  identifier: [identifier extracted from research_output or input]
+  description: [extract problem title from research_output]
+
+  workflow_type: "research"
+  current_step: "research"
+
+  custom_work_dir: [work_dir from argument parsing, or null]
+
+Output (store for use below):
+  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/research-EC-1234.md"]
+  identifier: [identifier from library]
+  is_new: [true/false from library]
+```
+
+**Note**: If `option_number` was provided (from brainstorm), adjust output_file:
+- Change from: `research-[identifier].md`
+- To: `research-[identifier]-option[N].md`
+
+**Store the returned values for steps below.**
+
+### Step 4.3: Write Research Output
+
+**If `file_output == true` (default unless --no-file):**
+
+Use Write tool:
+```
+file_path: [output_file from Step 4.1, adjusted for option if needed]
+content: [research_output from Phase 3]
+```
+
+**If write succeeds:**
+```
+📄 Research saved to: [output_file]
+```
+
+**If write fails or --no-file:**
+Skip file creation, continue to terminal output.
+
+### Step 4.4: Update Metadata
+
+**If work_folder exists and file was written:**
+
+Read current metadata:
+```bash
+cat [metadata_file from Step 4.1]
+```
+
+Update fields:
+```json
+{
+  ...existing fields,
+  "workflow": {
+    ...existing.workflow,
+    "completed": [...existing.completed, "research"],
+    "current": "research"
+  },
+  "files": {
+    ...existing.files,
+    "research": "research-[identifier].md"
+  },
+  "timestamps": {
+    ...existing.timestamps,
+    "lastModified": "[current timestamp]"
+  }
+}
+```
+
+Get current timestamp:
+```bash
+date -u +"%Y-%m-%dT%H:%M:%SZ"
+```
+
+Write updated metadata:
+```
+Write tool:
+  file_path: [metadata_file]
+  content: [updated JSON]
+```
+
+### Step 4.5: Terminal Output
+
+**If `terminal_output == true` (default unless --quiet):**
+
+Display:
+```markdown
+# 🔬 Research Complete: [identifier]
+
+Deep technical analysis completed.
+
+## 📊 Analysis Summary
+
+[Extract key findings from research_output - 3-5 bullet points]
+
+## 📁 Output
+
+Research saved to: `[output_file]`
+Work folder: `[work_folder]`
+
+## 📋 Next Steps
+
+Ready to create implementation specification:
+
+```bash
+/schovi:plan --input research-[identifier].md
+```
+
+This will generate detailed implementation tasks, acceptance criteria, and rollout plan.
+```
+
+---
+
+## PHASE 5: COMPLETION
+
+**Final Message**:
+```
+✅ Research completed successfully!
+
+🔬 Deep analysis for [identifier] complete
+📊 Architecture mapped with file:line references
+📁 Saved to: [file_path]
+
+📋 Ready for implementation planning? Run:
+   /schovi:plan --input research-[identifier].md
+```
+
+**Command complete.**
+
+---
+
+## ERROR HANDLING
+
+### Input Processing Errors
+- **--input not provided**: Report error, show usage example
+- **File not found**: Report error, ask for correct path
+- **Brainstorm file without option**: Ask user interactively which option to research
+- **--option with non-brainstorm input**: Report error, explain --option only for brainstorm files
+- **Invalid option number**: Report error, show valid options
+
+### Executor Errors
+- **Executor failed**: Report error with details from subagent
+- **Validation failed**: Check research_output has required sections
+- **Token budget exceeded**: Executor handles compression, shouldn't happen
+
+### Output Errors
+- **File write failed**: Report error, offer terminal-only output
+- **Work folder error**: Use fallback location or report error
+
+---
+
+## QUALITY GATES
+
+Before completing, verify:
+
+- [ ] Input processed successfully with research target identified
+- [ ] Fragment context loaded (if fragments exist)
+- [ ] Assumptions and unknowns passed to executor (if fragments exist)
+- [ ] Executor invoked and completed successfully
+- [ ] Research output received (~4000-6000 tokens)
+- [ ] Output contains all required sections
+- [ ] Architecture mapped with file:line references
+- [ ] Dependencies identified (direct and indirect)
+- [ ] Data flow traced with file:line references
+- [ ] Code quality assessed with examples
+- [ ] Implementation considerations provided
+- [ ] All file references use file:line format
+- [ ] Assumption fragments updated with validation results (if fragments exist)
+- [ ] Unknown fragments updated with answers (if fragments exist)
+- [ ] Risk fragments created for identified risks (if fragments exist)
+- [ ] Metric fragments created for defined metrics (if fragments exist)
+- [ ] Fragment registry updated with all changes (if fragments exist)
+- [ ] File saved to work folder (unless --no-file)
+- [ ] Metadata updated
+- [ ] Terminal output displayed (unless --quiet)
+- [ ] User guided to plan command for next step
+
+---
+
+## NOTES
+
+**Design Philosophy**:
+- **Executor pattern**: ALL work (extract + fetch + explore + generate) happens in isolated context
+- **Main context stays clean**: Only sees final formatted output (~4-6k tokens)
+- **Token efficiency**: 93% reduction in main context (from ~86k to ~6k tokens)
+- **Consistent experience**: User sees same output, just more efficient internally
+
+**Token Benefits**:
+- Before: Main context sees input + exploration (83k) + generation = ~86k tokens
+- After: Main context sees only final output = ~6k tokens
+- Savings: 80k tokens (93% reduction)
+
+**Integration**:
+- Input from: Brainstorm files (with option), Jira, GitHub, files, or text
+- Output to: Work folder with metadata
+- Next command: Plan for implementation spec
+
+**Executor Capabilities**:
+- Extracts research target from brainstorm files (with option selection)
+- Spawns jira-analyzer, gh-pr-analyzer for external context
+- Spawns Plan subagent for thorough-mode exploration
+- Reads research template and generates formatted output with file:line refs
+- All in isolated context, returns clean result
+
+---
+
+**Command Version**: 3.0 (Executor Pattern + Fragment System)
+**Last Updated**: 2025-11-08
+**Dependencies**:
+- `lib/argument-parser.md`
+- `lib/work-folder.md`
+- `lib/fragment-loader.md` (NEW: Fragment loading and updating)
+- `schovi/agents/research-executor/AGENT.md`
+- `schovi/templates/research/full.md`
+**Changelog**: v3.0 - Added fragment system integration: loads assumptions/unknowns, validates during research, updates fragment files with results, creates risk/metric fragments