| name | matilha-scout |
| description | Use when user is in Phase 10 discovery for a feature — runs parallel research subagents and produces a research markdown that feeds matilha-plan. |
| category | matilha |
| version | 1.0.0 |
| optional_companions | [] |
When this fires
User wants to explore a feature's problem space before writing a spec. project-status.md shows current_phase: 0 or 10. The skill dispatches research subagents (market, user needs, competitive, technical, regulatory if relevant) in parallel and synthesizes their output.
Preconditions
- Feature slug provided (or inferable from prompt).
- matilha-scout lazy-bootstraps project structure;
project-status.md is created if absent.
Execution Workflow
- Lazy bootstrap: Ensure
docs/matilha/research/ exists (mkdir -p). If project-status.md missing, write a minimal stub (current_phase: 0, phase_status: in_progress, project_slug: <from cwd or prompt>, next_action: "matilha-scout running"). Read project-status.md; verify current_phase ≤ 10 (if present and higher, warn user — scout is Phase 10 territory).
- Dispatch 3-5 research subagents via Task tool IN PARALLEL (one Task call per scope: market analysis, user-needs mapping, competitive landscape, technical options, regulatory if applicable).
- Wait for all subagents to complete.
- Synthesize outputs into
docs/matilha/research/<slug>-research.md with sections per subagent + a "Key findings" synthesis at the end.
- Update
project-status.md: current_phase: 10, phase_status: in_progress, next_action: "Run matilha-plan to write spec + plan".
Rules: Do
- Use parallel subagent dispatch (multiple Task tool calls in a single message).
- Cite sources in research output.
- Separate findings from recommendations.
- Update project-status on success only.
Rules: Don't
- Write the spec yourself (that's matilha-plan).
- Recommend decisions (research surfaces options, user decides).
- Advance
current_phase past 10.
Expected Behavior
Output is a 500-1500 word markdown with structured sections. User reads it, forms a mental model, then invokes matilha-plan. If research surfaces blockers, log them in project-status.md:pending_decisions.
Quality Gates
- Research output exists and is non-empty.
project-status.md shows current_phase: 10.pending_decisions populated if blockers found.
Companion Integration
- If ux-* skills from matilha-ux-pack are available: dispatch an additional ux-research subagent via Task tool for cognitive/perception considerations.
- If growth-* skills from matilha-growth-pack are available: dispatch a growth-research subagent mapping JTBD forces-of-progress.
- Otherwise: proceed with the 3-5 core subagents above.
Output Artifacts
docs/matilha/research/<slug>-research.md- Updated
project-status.md
Example Constraint Language
- Use "must" for: every finding cites a source.
- Use "should" for: dispatch research subagents in parallel (single message with multiple Task calls).
- Use "may" for: skip competitive analysis if scope is internal-only.
Troubleshooting
- "research output is thin": Re-run with more specific sub-topics.
- "subagent dispatch fails": Check Task tool availability (Codex requires
multi_agent = true in ~/.codex/config.toml).
CLI shortcut (optional)
If matilha CLI is installed (matilha --version succeeds), you can run
matilha scout <slug> to execute this deterministically. The plugin path
above works without any CLI installation.
