Menu
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".
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Research codebase, validate external claims, and emit a work-ready spec.json for a new planning session. Single-pass creation with integrated validation via Context7 and locator/analyzer agents. Triggers on "create plan", "plan for", "write a plan". For exploratory requests where the user is unsure what to build, prefer brainstorm first. Once spec.json exists, use plan-review for evaluation or go straight to work. For a reviewed spec, use plan-consolidation to merge findings.
Execute spec.json (plan mode) or review.findings.json (fix-findings mode) by dispatching subagents per chunk. Triggers on "work on", "implement", "execute plan", "carry on", "continue".
Shared conventions for Flywheel subagents. Tool discipline, output format, research patterns.
Perform exhaustive code reviews using multi-agent analysis. Reviews PRs, branches, or current changes. Writes review.findings.json to the active session. Triggers on "review", "code review", "check PR".
Refine the active session's spec.json by merging reviewer findings.json into it. Backs up the pre-refinement spec to a .pre-consolidation sidecar. Triggers on "consolidate plan", "finalize plan".
Run ALL reviewer agents in parallel against a plan. Deduplicates findings semantically and writes findings.json to the active session. Triggers on "review plan", "check plan".
| 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"] |
Conduct comprehensive research using a two-phase locate-then-analyze approach that reduces context usage by 40-60%.
Research question via $ARGUMENTS. If empty, ask user.
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?"
If no matches or no docs/research/ directory, proceed to Phase 1.
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.
Map the canonical analyzer outputs to research-doc sections:
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.
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.
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.
This skill is context-heavy. Monitor usage:
After ANY 2 of these operations:
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.