mindsystem-cc 3.13.1 → 3.16.0

package/commands/ms/research-phase.md

@@ -6,14 +6,14 @@ allowed-tools:
   - Read
   - Bash
   - Task
+  - Write
+  - AskUserQuestion
 ---
 
 <objective>
-Research how to implement a phase. Spawns ms-researcher agent with phase context.
+Research how to implement a phase by spawning 3 parallel specialized agents, then synthesizing their findings into RESEARCH.md.
 
-**Orchestrator role:** Parse phase, validate against roadmap, check existing research, gather context, spawn researcher agent, present results.
-
-**Why subagent:** Research burns context fast (WebSearch, Context7 queries, source verification). Fresh 200k context for investigation. Main context stays lean for user interaction.
+**Orchestrator role:** Parse phase, validate, pre-scan project context, spawn 3 agents (external docs, codebase patterns, best practices), synthesize findings, resolve conflicts, write RESEARCH.md.
 </objective>
 
 <context>
@@ -51,135 +51,282 @@ ls .planning/phases/${PHASE}-*/RESEARCH.md 2>/dev/null
 
 **If doesn't exist:** Continue.
 
-## 3. Gather Phase Context
+## 3. Pre-scan Project Context
+
+Gather baseline context that all agents need:
 
 ```bash
+# Dependency file (first 100 lines)
+cat pubspec.yaml package.json Gemfile requirements.txt go.mod pyproject.toml 2>/dev/null | head -100
+
+# Phase context from roadmap
 grep -A20 "Phase ${PHASE}:" .planning/ROADMAP.md
+
+# Requirements
 cat .planning/REQUIREMENTS.md 2>/dev/null
+
+# Phase-specific context and design
 cat .planning/phases/${PHASE}-*/${PHASE}-CONTEXT.md 2>/dev/null
 cat .planning/phases/${PHASE}-*/${PHASE}-DESIGN.md 2>/dev/null
+
+# Locked decisions
 grep -A30 "### Decisions Made" .planning/STATE.md 2>/dev/null
+
+# Prior knowledge — match subsystem(s) by comparing phase description against config.json names
+jq -r '.subsystems[]' .planning/config.json 2>/dev/null
+cat .planning/knowledge/{matched_subsystem}.md 2>/dev/null
+```
+
+Extract from pre-scan:
+- `existing_tech`: Libraries already in the project (from dependency file)
+- `phase_description`: What this phase aims to build
+- `phase_requirements`: Specific requirements
+- `locked_decisions`: From CONTEXT.md and STATE.md
+- `design_specs`: From DESIGN.md if exists
+- `prior_knowledge`: From `.planning/knowledge/{subsystem}.md` — prior decisions, known pitfalls, architecture patterns (so agents don't re-research settled decisions)
+
+## 4. Determine Research Scope
+
+Research modes:
+- **ecosystem** (default): Survey available tools, libraries, and integration options
+- **feasibility**: Assess whether current stack can support the requirements
+- **implementation**: Concrete how-to patterns and step-by-step approaches
+- **comparison**: Evaluate alternatives side-by-side with tradeoffs
+
+Frame the research question based on mode + phase description. Present to user:
+
 ```
+Research scope for Phase {N}: {name}
 
-Present summary with phase description, requirements, prior decisions.
+Mode: {mode}
+Question: {framed_question}
+Existing tech: {existing_tech_summary}
 
-**If DESIGN.md exists:** Research should address:
-- Libraries needed for specified interactions (animations, gestures, charts)
-- Technical feasibility of design requirements
-- Platform-specific implementation approaches
-- Component libraries that match the design system
+Spawning 3 parallel agents:
+1. External Docs — library documentation, APIs, code examples
+2. Codebase Patterns — existing patterns, learnings, established conventions
+3. Best Practices — community consensus, pitfalls, SOTA
 
-## 4. Spawn ms-researcher Agent
+Proceed? (yes / adjust scope / change mode)
+```
 
-Research modes: ecosystem (default), feasibility, implementation, comparison.
+## 5. Spawn 3 Agents in Parallel
 
-```markdown
+Announce: "Spawning 3 research agents in parallel..."
+
+All 3 receive pre-scan context (existing tech, phase description, requirements, locked decisions, design specs if any). Spawn all 3 in a single message using the Task tool.
+
+### Agent 1: External Docs (ms-researcher)
+
+```
+Task(
+  prompt="
 <research_type>
-Phase Research — investigating HOW to implement a specific phase well.
+Phase Research — External Documentation focus.
 </research_type>
 
-<key_insight>
-The question is NOT "which library should I use?"
+<focus>
+Library documentation, APIs, version-specific behavior, verified code examples.
+Use the ms-lookup CLI for library docs and deep research:
+  ~/.claude/mindsystem/scripts/ms-lookup-wrapper.sh docs <library> '<query>'
+  ~/.claude/mindsystem/scripts/ms-lookup-wrapper.sh deep '<query>'
+Use WebSearch for ecosystem discovery.
+Focus on finding authoritative, current documentation for the libraries and tools
+needed to implement this phase.
+</focus>
 
-The question is: "What do I not know that I don't know?"
+<existing_tech>
+{existing_tech from pre-scan — so agent knows what's already in the project}
+</existing_tech>
 
-For this phase, discover:
-- What's the established architecture pattern?
-- What libraries form the standard stack?
-- What problems do people commonly hit?
-- What's SOTA vs what Claude's training thinks is SOTA?
-- What should NOT be hand-rolled?
-</key_insight>
+<prior_knowledge>
+{prior_decisions, known_pitfalls, architecture_patterns from knowledge files — so agents don't re-research settled decisions}
+</prior_knowledge>
 
 <objective>
-Research implementation approach for Phase {phase_number}: {phase_name}
-Mode: ecosystem
+Research external documentation for Phase {N}: {name}
+Mode: {mode}
 </objective>
 
 <context>
-**Phase description:** {phase_description}
-**Requirements:** {requirements_list}
-**Prior decisions:** {decisions_if_any}
-**Phase context:** {context_md_content}
-**Design specs:** {design_md_content_if_exists}
+{phase_description, requirements, locked_decisions, design_specs}
 </context>
 
 <downstream_consumer>
-Your RESEARCH.md will be loaded by `/ms:plan-phase` which uses specific sections:
-- `## Standard Stack` → Plans use these libraries
-- `## Architecture Patterns` → Task structure follows these
-- `## Don't Hand-Roll` → Tasks NEVER build custom solutions for listed problems
-- `## Common Pitfalls` → Verification steps check for these
-- `## Code Examples` → Task actions reference these patterns
-
-Be prescriptive, not exploratory. "Use X" not "Consider X or Y."
+Your findings feed into orchestrator synthesis -> RESEARCH.md sections:
+- Standard Stack (libraries, versions, install commands)
+- Architecture Patterns (library-recommended patterns)
+- Don't Hand-Roll (library solutions for common problems)
+- Code Examples (verified from official docs)
+- State of the Art (latest approaches, deprecated patterns)
+Be prescriptive. Specific versions. Verified code.
 </downstream_consumer>
 
-<quality_gate>
-Before declaring complete, verify:
-- [ ] All domains investigated (not just some)
-- [ ] Negative claims verified with official docs
-- [ ] Multiple sources for critical claims
-- [ ] Confidence levels assigned honestly
-- [ ] Section names match what plan-phase expects
-</quality_gate>
-
 <output>
-Write to: .planning/phases/{phase}-{slug}/{phase}-RESEARCH.md
+Return findings as structured text. Do NOT write to filesystem.
+Format:
+## EXTERNAL DOCS FINDINGS
+### Recommended Libraries (name, version, purpose, install)
+### API Patterns & Code Examples (verified from docs)
+### Architecture Recommendations (from library docs)
+### Don't Hand-Roll (library solutions exist for these)
+### Version Constraints & Compatibility
+### Confidence (HIGH/MEDIUM/LOW per section with sources)
+Complete your built-in verification protocol and quality checklist before returning findings.
 </output>
+",
+  subagent_type="ms-researcher",
+  description="External docs: Phase {N}"
+)
 ```
 
+### Agent 2: Codebase Patterns (ms-codebase-researcher)
+
 ```
 Task(
-  prompt=filled_prompt,
-  subagent_type="ms-researcher",
-  description="Research Phase {phase}"
-)
-```
+  prompt="
+<objective>
+Analyze project codebase for patterns relevant to Phase {N}: {name}
+</objective>
 
-## 5. Handle Agent Return
+<research_question>
+{framed_question}
+</research_question>
 
-**`## RESEARCH COMPLETE`:**
+<phase_context>
+{phase_description, requirements, locked_decisions}
+</phase_context>
 
-Commit the research file:
+<existing_tech>
+{existing_tech from pre-scan}
+</existing_tech>
 
-```bash
-git add .planning/phases/${PHASE}-*/*-RESEARCH.md
-git commit -m "docs: complete research for phase ${PHASE}"
+<prior_knowledge>
+{prior_decisions, known_pitfalls, architecture_patterns from knowledge files — so agents don't re-research settled decisions}
+</prior_knowledge>
+
+<scan_hints>
+{keywords extracted from phase description for targeted scanning}
+</scan_hints>
+
+<quality>
+Complete your built-in success criteria checklist before returning findings.
+</quality>
+",
+  subagent_type="ms-codebase-researcher",
+  description="Codebase patterns: Phase {N}"
+)
 ```
 
-Display summary, then read `~/.claude/mindsystem/references/prework-status.md` to show what's done vs still needed. Also offer: Dig deeper, Review full.
+### Agent 3: Best Practices (ms-researcher)
+
+```
+Task(
+  prompt="
+<research_type>
+Phase Research — Best Practices & Community Consensus focus.
+</research_type>
 
-**`## CHECKPOINT REACHED`:** Present to user, get response, spawn continuation.
+<focus>
+Community consensus, common pitfalls, proven approaches, state of the art.
+Use the ms-lookup CLI for deep research on high-value questions:
+  ~/.claude/mindsystem/scripts/ms-lookup-wrapper.sh deep '<query>'
+Use WebSearch for community articles, blog posts, Stack Overflow patterns.
+Focus on what practitioners recommend and what mistakes to avoid.
+</focus>
 
-**`## RESEARCH INCONCLUSIVE`:** Show what was attempted, offer: Add context, Try different mode, Manual.
+<existing_tech>
+{existing_tech from pre-scan}
+</existing_tech>
 
-## 6. Spawn Continuation Agent
+<prior_knowledge>
+{prior_decisions, known_pitfalls, architecture_patterns from knowledge files — so agents don't re-research settled decisions}
+</prior_knowledge>
 
-```markdown
 <objective>
-Continue research for Phase {phase_number}: {phase_name}
+Research best practices for Phase {N}: {name}
+Mode: {mode}
 </objective>
 
-<prior_state>
-Research file: @.planning/phases/{phase}-{slug}/{phase}-RESEARCH.md
-</prior_state>
+<context>
+{phase_description, requirements, locked_decisions, design_specs}
+</context>
 
-<checkpoint_response>
-**Type:** {checkpoint_type}
-**Response:** {user_response}
-</checkpoint_response>
-```
+<downstream_consumer>
+Your findings feed into orchestrator synthesis -> RESEARCH.md sections:
+- Common Pitfalls (community war stories, warning signs)
+- State of the Art (current vs deprecated approaches)
+- Architecture Patterns (industry patterns, not library-specific)
+- Don't Hand-Roll (community-known solved problems)
+- Alternatives Considered (why X over Y)
+Be prescriptive. Cite sources. Flag confidence levels.
+</downstream_consumer>
 
-```
-Task(
-  prompt=continuation_prompt,
+<output>
+Return findings as structured text. Do NOT write to filesystem.
+Format:
+## BEST PRACTICES FINDINGS
+### Recommended Approaches (community consensus)
+### Common Pitfalls (what goes wrong, warning signs, prevention)
+### State of the Art (current vs deprecated, when things changed)
+### Alternative Approaches (what else exists, why not chosen)
+### Industry Patterns (architecture, testing, deployment)
+### Confidence (HIGH/MEDIUM/LOW per section with sources)
+Complete your built-in verification protocol and quality checklist before returning findings.
+</output>
+",
   subagent_type="ms-researcher",
-  description="Continue research Phase {phase}"
+  description="Best practices: Phase {N}"
 )
 ```
 
-## 7. Update Last Command
+## 6. Synthesize Findings
+
+After all 3 agents return, read their structured outputs. Map findings to RESEARCH.md sections:
+
+| RESEARCH.md Section | External Docs | Codebase | Best Practices | Synthesis Rule |
+|---------------------|--------------|----------|----------------|----------------|
+| Summary | Key libraries found | What exists already | Community direction | 2-3 paragraph synthesis |
+| Standard Stack | Recommended + versions | Already in project | Community recommended | Merge: keep existing when sufficient, add new when needed |
+| Architecture Patterns | Library-recommended | Established project patterns | Industry patterns | Follow existing; adopt recommended for new capabilities |
+| Don't Hand-Roll | Library solutions | Internal solutions | Solved problems | Union of all three |
+| Common Pitfalls | Library-specific gotchas | Past failures/learnings | Community war stories | Union, deduplicate |
+| Code Examples | From official docs | From project | From community | Prefer official docs; show project examples for "how we do it here" |
+| State of the Art | Latest versions/APIs | — | Current vs deprecated | Combine external + community |
+
+**Conflict resolution:** If external recommends library X but project already uses library Y for the same purpose, present conflict to user via AskUserQuestion:
+- Options: "Keep existing [Y]" / "Switch to recommended [X]" / "Use both (different purposes)" / "Something else"
+- Record decision in RESEARCH.md
+
+**Source attribution:** In `<sources>` section, prefix findings with their agent origin: "From external docs:", "From codebase analysis:", "From best practices:"
+
+Write RESEARCH.md to `.planning/phases/{phase}-{slug}/{phase}-RESEARCH.md` using the standard template structure (semantic XML tags: `<research_summary>`, `<standard_stack>`, `<architecture_patterns>`, `<dont_hand_roll>`, `<common_pitfalls>`, `<code_examples>`, `<sota_updates>`, `<open_questions>`, `<sources>`, `<metadata>`).
+
+## 7. Commit and Present
+
+```bash
+git add .planning/phases/${PHASE}-*/*-RESEARCH.md
+git commit -m "docs: complete research for phase ${PHASE}"
+```
+
+Display research summary. Read `~/.claude/mindsystem/references/prework-status.md` to show what's done vs still needed for this phase.
+
+**Post-synthesis routing:**
+
+Scan the synthesized RESEARCH.md for LOW confidence sections and significant open questions.
+
+If all sections HIGH/MEDIUM confidence with no major gaps, use AskUserQuestion:
+1. Proceed to planning
+2. Dig deeper into specific area
+3. Review full research
+
+If any section has LOW confidence or significant open questions, flag the weak areas explicitly, then use AskUserQuestion:
+1. Dig deeper into [specific LOW area] — re-run targeted agent
+2. Try different research mode (e.g., ecosystem -> implementation)
+3. Proceed to planning with caveats noted
+4. Review full research
+
+## 8. Update Last Command
 
 Update `.planning/STATE.md` Last Command field:
 - Find line starting with `Last Command:` in Current Position section
@@ -188,11 +335,28 @@ Update `.planning/STATE.md` Last Command field:
 
 </process>
 
+<checkpoint_handling>
+
+**With parallel agents:**
+- Wait for ALL 3 agents to complete before synthesizing
+- If any agent returns CHECKPOINT: present all checkpoints after other agents finish, handle sequentially
+- If any agent returns BLOCKED: report which failed, offer to retry that agent or proceed with 2/3 findings
+
+**Continuation mechanics:**
+When an agent returns CHECKPOINT, its text response contains partial findings. To continue:
+1. Capture the checkpointed agent's full text response
+2. Present the checkpoint reason to the user, get their input
+3. Spawn a fresh agent of the same type, injecting the captured text as inline content in `<prior_state>`
+
+The `{partial_findings}` placeholder in the continuation template is the agent's raw text response, not a file reference. Read `mindsystem/templates/research-subagent-prompt.md` Continuation section for the prompt template.
+
+</checkpoint_handling>
+
 <success_criteria>
-- [ ] Phase validated against roadmap
-- [ ] Existing research checked
-- [ ] ms-researcher spawned with context
-- [ ] Checkpoints handled correctly
-- [ ] RESEARCH.md committed on completion
+- [ ] Conflicts reconciled (with user input if needed)
+- [ ] RESEARCH.md synthesized and written
+- [ ] 3 agents spawned in parallel (external-docs, codebase-patterns, best-practices)
+- [ ] All 3 agent results received
+- [ ] RESEARCH.md committed
 - [ ] User knows next steps
 </success_criteria>

package/commands/ms/verify-work.md

@@ -61,6 +61,7 @@ Phase: $ARGUMENTS (optional)
    - Generate UAT fixes patch
    - Restore user's pre-existing work (if stashed)
    - Commit UAT.md, present summary
+   - **Update knowledge pitfalls** — if significant UAT issues (blocker/major) were fixed, append pitfall entries to relevant knowledge files
 
 10. **Update last command**
     - Update `.planning/STATE.md` Last Command field
@@ -82,18 +83,11 @@ Phase: $ARGUMENTS (optional)
 </anti_patterns>
 
 <success_criteria>
-- [ ] Dirty tree handled at start (stash/commit/abort)
-- [ ] Tests extracted from SUMMARY.md and classified
-- [ ] Tests batched by mock requirements
-- [ ] Mocks applied inline when needed (1-4 direct, 5+ via subagent)
-- [ ] Tests presented in batches of 4 using AskUserQuestion
-- [ ] Issues investigated with lightweight check first
-- [ ] Simple issues fixed inline with proper commit message
-- [ ] Complex issues escalated to fixer subagent
-- [ ] Failed re-tests get 2 retries then options
-- [ ] Stash conflicts auto-resolved to fix version
-- [ ] Mocks reverted on completion (git checkout)
+- [ ] Mocks stashed before fixing, restored after (git stash push/pop cycle)
+- [ ] Stash conflicts auto-resolved to fix version (git checkout --theirs)
+- [ ] Blocked tests re-presented after blocking issues resolved
+- [ ] Failed re-tests get 2 retries then options (tracked via retry_count)
+- [ ] All mocks reverted on completion (git checkout -- <mocked_files>)
 - [ ] UAT fixes patch generated
-- [ ] User's pre-existing work restored
-- [ ] UAT.md committed with final summary
+- [ ] User's pre-existing work restored from stash
 </success_criteria>