| name | research |
| description | Conduct comprehensive codebase research producing a persistent document. Use when you need to understand something BEFORE planning, or for pure exploration. Triggers on "research", "investigate", "explore codebase". |
| user-invocable | true |
| allowed-tools | ["Read","Write","Grep","Glob","Bash","Task","WebFetch","AskUserQuestion"] |
Codebase Research Skill
Conduct comprehensive research using a two-phase locate-then-analyze approach that reduces context usage by 40-60%.
Philosophy: Documentarian Mode
- Document what IS, not what SHOULD BE
- No suggestions, critiques, or recommendations
- Pure technical mapping of the existing system
- Focus on paths and references, not full file contents
Input
Research question via $ARGUMENTS. If empty, ask user.
Phase 0: Check for Existing Research
Before starting new research, check if recent research already covers this topic:
find docs/research -name "*<topic-slug>*" -mtime -14 2>/dev/null | head -3
If matches found, read the YAML frontmatter (topic, tags) to assess relevance. If a strong match exists:
AskUserQuestion: "Found recent research: [filename] ([N] days old). Reuse, refresh, or start new?"
- Reuse (Recommended) — Read existing doc, skip to Phase 3 (summary)
- Refresh — Use existing doc as starting point, re-run locate/analyze to update
- Start new — Proceed normally
If no matches or no docs/research/ directory, proceed to Phase 1.
Phase 1: Research Workflow
Run the canonical research workflow: all four locators in parallel → consolidate → all four analyzers in parallel.
Read flywheel/skills/flywheel-conventions/references/research-workflow.md before proceeding — it contains locator templates, the consolidation rule (top-N selection per analyzer), and analyzer templates.
Phase 2: Synthesize & Persist
Map the canonical analyzer outputs to research-doc sections:
- analyzer-codebase findings → "Codebase Map" (file structure, components, interactions; file:line refs).
- analyzer-patterns findings → "Patterns" (named patterns with code examples and locations).
- analyzer-docs findings → "Decisions & Constraints" (extracted ADR / doc content).
- analyzer-web findings → "External References" (URL citations with extracted content).
The canonical analyzers' flags fold into a "Concerns & Open Questions" section:
EXISTING_SOLUTION, DRY_VIOLATION, PATTERN_CONFLICT, INTEGRATION_RISK → "Concerns" subsection with file:line citations.OPEN_QUESTION, CLAIM_INVALID, VERSION_ISSUE → "Open Questions" subsection.
These are documentarian observations (not recommendations) so they belong in the persisted research even though research doesn't act on them — downstream consumers (plan-creation, brainstorm) read the doc and act.
Write to docs/research/YYYY-MM-DD-<topic-slug>.md. Optionally git-commit the research document.
Read references/research-document-template.md before proceeding — it contains the full output document format with YAML frontmatter, all required sections, and the git commit template.
Phase 3: Summary & Next Steps
Display a summary to the user (not the full document). Offer three options: create a plan from the research, continue researching, or exit.
Read references/research-document-template.md before proceeding — the "Present & Offer Next Steps" section contains the AskUserQuestion format and option-action mapping.
Integration: Called by Other Skills
Other skills can check for recent research before starting work, and invoke this skill if none exists.
Read references/research-document-template.md before proceeding — the "Integration" section contains the bash lookup pattern for finding existing research.
Context Budget
This skill is context-heavy. Monitor usage:
- Within Phase 1, after locators: If >30 locator results, consolidate aggressively before dispatching analyzers
- After Phase 1 completes: Write findings immediately in Phase 2; don't hold in context
- Always: Prefer file:line references over quoting code
2-Action Rule for Visual Content
After ANY 2 of these operations:
- WebFetch
- Browser tool use
- Image viewing
- Search results review
IMMEDIATELY persist findings to the research document as text.
Visual/multimodal content doesn't persist well in context. Capture it as text before it's lost.
Anti-Patterns
- Skip locator phase — Don't go straight to analyzers
- Analyze everything — Only analyze top findings from locators
- Make suggestions — This is documentation, not consultation
- Return file contents — Paths and references only
- Forget to persist — Always write research document
- Hold in context — Write to file, reference by path
