gh-schovi-claude-schovi-schovi/commands/research.md

description, argument-hint, allowed-tools

description	argument-hint	allowed-tools
Deep technical analysis of ONE specific approach with detailed file:line references	--input PATH [--option N] [--output PATH] [--no-file] [--quiet] [--work-dir PATH]	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:

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:

cat [metadata_file from Step 4.1]

Update fields:

{
  ...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:

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:

# 🔬 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