# Research

> Intelligence gathering phase - spawns parallel agents to analyze codebase, patterns, git history, and web research. Creates or updates task file with findings. Use when this capability is needed.

- Skill: `tomevault-io/research-5` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/research-5`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/research-5/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/research-5

---


<skill name="apex:research" phase="research">

<overview>
Conduct comprehensive research by orchestrating parallel sub-agents. Outputs to `./apex/tasks/[ID].md`.

This is the **first phase** of the APEX workflow. It gathers all intelligence needed for planning and implementation.
</overview>

<initial-response>
<if-no-arguments>
I'll conduct comprehensive research to gather intelligence and explore the codebase.

Please provide:
- Task description (e.g., "implement dark mode toggle")
- Linear/JIRA ticket ID (e.g., "APE-59")
- Path to task file (e.g., "./tickets/feature.md")
- Existing APEX task ID

I'll analyze patterns, explore the codebase, find similar tasks, and create a detailed research document.
</if-no-arguments>
<if-arguments>Immediately begin research - skip this message.</if-arguments>
</initial-response>

<workflow>

<step id="1" title="Parse input and identify task">
<instructions>
Determine input type and create/find task:

**Text description**: Create a task entry with intent, inferred type, generated identifier, and tags
**Ticket ID (APE-59)**: Fetch ticket details (if available), then create a task entry with identifier set to ticket ID
**File path**: Read file fully, parse content, then create a task entry
**Database ID**: Look up existing task by ID to retrieve it

Store `taskId` and `identifier` for all subsequent operations.
</instructions>
</step>

<step id="2" title="Clarify intent and scope">
<instructions>
Before any deep research, answer these three questions in 1-2 sentences each:

1. **Intent**: What is the user actually trying to accomplish? (Look past the literal request)
2. **Scope**: What files/systems are in play? What's explicitly out?
3. **Verification**: How will we know it's done? (Test command, observable behavior, or acceptance criteria)

If any answer is "I don't know," that's an ambiguity to resolve in step 4.
</instructions>
</step>

<step id="3" title="Read mentioned files FULLY">
<critical>
Before ANY analysis or spawning agents:
- If user mentions specific files, READ THEM FULLY first
- Use Read tool WITHOUT limit/offset parameters
- Read in main context BEFORE spawning sub-tasks
- This ensures full context before decomposing research
</critical>
</step>

<step id="4" title="Triage scan + Ambiguity Gate">
<purpose>
Run cheap scans to locate target areas and detect ambiguity before spawning agents.
</purpose>

<triage-scan>
- Use Grep/Glob to locate entrypoints, tests, and likely target areas using keywords from step 2.
- Capture candidate files/areas to refine scope.
- Do NOT open large files unless the user explicitly mentioned them.
</triage-scan>

<critical>
Ambiguity is a BLOCKING condition that ONLY users can resolve.
DO NOT spawn deep research agents with unclear requirements.
</critical>

<ambiguity-triggers>
Ask the user if ANY of these are true:
- Goal is vague ("improve", "enhance", "optimize") without measurable criteria
- Multiple plausible interpretations exist after triage scan
- Architecture/library choices the user should make
- Scope is unbounded (no clear in/out boundary)
</ambiguity-triggers>

<decision>
- **0 ambiguities**: PROCEED to determine research depth and spawn agents
- **1+ ambiguities**: ASK USER (max 1 round, options with implications, then proceed)
</decision>
</step>

<step id="4b" title="Determine research depth">
<purpose>
Scale agent deployment to task complexity. Not every task needs 6+ agents.
</purpose>

<complexity-signals>
Assess from triage scan results:
- **How many files/systems are touched?** (1-3 files = small, 4-10 = medium, 10+ = large)
- **Does this involve external APIs, libraries, or unfamiliar tech?** (triggers web research)
- **Does this cross module/package boundaries?** (triggers systems research)
- **Is this in a high-risk area (auth, data, payments, public API)?** (triggers risk analyst)
</complexity-signals>

<depth-tiers>
**LIGHT** (simple bug fix, small refactor, test addition):
- Skip: web-researcher, systems-researcher, risk-analyst
- Run: implementation-pattern-extractor, git-historian, learnings-researcher
- Output: Concise but complete research section — include all core sections (executive summary, target files, codebase patterns, risks, recommendations, task contract) even if brief

**STANDARD** (feature, multi-file change, moderate complexity):
- Run: implementation-pattern-extractor, git-historian, documentation-researcher, learnings-researcher
- Conditional: web-researcher (only if external dependencies involved)
- Conditional: systems-researcher (only if cross-module)
- Output: Full research section

**DEEP** (architecture change, new subsystem, high-risk, cross-cutting):
- Run: ALL agents including risk-analyst and systems-researcher
- Output: Full research section with all sections populated
</depth-tiers>
</step>

<step id="5" title="Create task file">
<instructions>
Create `./apex/tasks/[identifier].md` with frontmatter:

```markdown
---
id: [database_id]
identifier: [identifier]
title: [Task title]
created: [ISO timestamp]
updated: [ISO timestamp]
phase: research
status: active
---

# [Title]

<research>
<!-- Will be populated by this skill -->
</research>

<plan>
<!-- Populated by /apex:plan -->
</plan>

<implementation>
<!-- Populated by /apex:implement -->
</implementation>

<ship>
<!-- Populated by /apex:ship -->
</ship>
```
</instructions>
</step>

<step id="6" title="Spawn parallel research agents">
<critical>
- Use clarified intent from step 2 as source of truth for all agent prompts.
- Only spawn agents appropriate for the depth tier from step 4b.
- Launch all selected agents in parallel.
</critical>

<agents>

<agent type="implementation-pattern-extractor" tier="LIGHT+">
**Task Context**: [Brief description]
**Task Type**: [bug|feature|refactor|test]

Extract concrete implementation patterns from THIS codebase with file:line references.
Return: primary patterns, conventions, reusable snippets, testing patterns.
</agent>

<agent type="apex:git-historian" tier="LIGHT+">
**Scope**: [files/directories from triage scan]
**Window**: 9 months

Analyze git history for similar changes, regressions, ownership.
Return: Structured git intelligence.
</agent>

<agent type="apex:documentation-researcher" tier="STANDARD+">
**Focus**: [Task-relevant topics]

Search project docs for architecture context, past decisions, learnings, and gotchas.
Return: architecture_context, past_decisions, historical_learnings, docs_to_update.
</agent>

<agent type="learnings-researcher" tier="STANDARD+">
**Task Intent**: [Intent from step 2]
**Keywords**: [Extracted keywords]

Search past task files for problems solved, decisions made, and gotchas.
Return: Top 5 relevant learnings ranked by relevance.
</agent>

<agent type="web-researcher" tier="STANDARD+ when external deps involved">
**Research Topic**: [Component/Technology/Pattern]
**Context**: [What we're trying to accomplish]

Find official documentation, best practices, security concerns.
Return: official_docs, best_practices, security_concerns, recent_changes.

**Skip this agent when**: task is purely internal codebase work with no external APIs or libraries.
</agent>

<agent type="apex:systems-researcher" tier="DEEP or cross-module">
**Focus Area**: [Component or subsystem]

Trace execution flow, dependencies, state transitions, integration points.
</agent>

<agent type="apex:risk-analyst" tier="DEEP or high-risk area">
Surface forward-looking risks, edge cases, monitoring gaps, mitigations.
</agent>

</agents>

<wait-for-all>Wait for ALL spawned agents to complete before proceeding.</wait-for-all>
</step>

<step id="7" title="Synthesize findings">
<priority-order>
1. Live codebase = primary truth (what actually exists)
2. Implementation patterns = concrete project conventions
3. Official documentation = authoritative reference
4. Pattern library = proven cross-project solutions
5. Best practices = industry consensus
6. Git history = evolution understanding
</priority-order>

<synthesis-tasks>
- Validate pattern library findings against actual codebase
- Cross-reference with official docs
- Identify gaps between current code and recommendations
- Flag inconsistencies and deprecated patterns
- Note security concerns
- Resolve contradictions (codebase > docs > patterns > opinions)
</synthesis-tasks>

<evidence-rule>
**Every factual assertion must cite its source.** No bare claims.
- Code assertions → file:line or function name with file path
- Behavioral claims → test name or command that demonstrates it
- Risk claims → specific code construct that could fail, not "could break things"
- Performance claims → allocation count, hot-path evidence, or "no perf data available"
If you cannot cite evidence for a claim, qualify it as an assumption or open question.
</evidence-rule>
</step>

<step id="8" title="Display Intelligence Report">
<purpose>Give user visibility into gathered intelligence before the gap check.</purpose>

<display-format>
```
## Research Summary

**Task**: [Title]
**Depth**: [LIGHT|STANDARD|DEEP] — [N] agents deployed

### Target Files
- [file:line] — [why this file changes]

### Key Findings
1. [Most important finding from agents]
2. [Second most important]
3. [Third, if applicable]

### Recommended Approach
[1-2 sentence summary of the winning solution]

### Open Questions
- [Any gaps or unknowns for the plan phase]
```
</display-format>
</step>

<step id="9" title="Gap check">
<purpose>
Before writing the research document, verify you can answer these concrete questions.
If you can't, that's a gap to flag — not a score to compute.
</purpose>

<must-know>
1. **Which files change?** (specific paths from triage + pattern extraction)
2. **How is this tested?** (existing test patterns or new test strategy)
3. **What could break?** (downstream consumers, edge cases from git history)
4. **Is there a prior art?** (similar past task, codebase pattern, or documented decision)
</must-know>

<if-gaps>
If any must-know is unanswered:
- Spawn a targeted recovery agent for the specific gap, OR
- Flag it as an open question in the research output for the user/architect
Do NOT block on gaps that the plan phase can resolve.
</if-gaps>
</step>

<step id="10" title="Generate solution approaches">
<instructions>
**For all tasks**: Produce at least 2 solution approaches with pros, cons, risk level, and a recommended winner. The second approach provides valuable contrast even when one approach is clearly better.

**For genuinely ambiguous tasks** (multiple viable architectures, real trade-offs):
Produce 3 distinct approaches.

Do not pad to 3 by inventing obviously bad options — but always have at least 2.

**For each approach**: Name the specific functions/types to create or modify (not abstract descriptions). Include before/after signatures for key interface changes.
</instructions>
</step>

<step id="11" title="Write research section to task file">
<output-format>
Append to `<research>` section. **Include all core sections** even if brief — the completeness of coverage matters for downstream quality assessment. Optional sections (web-research, past-learnings) may be omitted when agents returned nothing relevant.

```xml
<research>
<metadata>
  <timestamp>[ISO]</timestamp>
  <depth>[LIGHT|STANDARD|DEEP]</depth>
  <agents-deployed>[N]</agents-deployed>
  <files-analyzed>[X]</files-analyzed>
</metadata>

<executive-summary>
[1-3 paragraphs synthesizing findings. This is the most important section — downstream
phases read this first. Lead with: what changes, where, why, and the recommended approach.]
</executive-summary>

<target-files>
[List of files that will change, with file:line references and brief rationale.
Include function/method names — bare file paths are insufficient.
This is what the plan phase consumes most directly.]
</target-files>

<codebase-patterns>
  <primary-pattern location="file:line">[Description with code snippet]</primary-pattern>
  <key-signatures>[Before/after signatures for interfaces or types being modified]</key-signatures>
  <testing-patterns>[How similar features are tested, with specific test file:line references]</testing-patterns>
  <conventions>[Only if non-obvious naming/structure/error-handling conventions exist]</conventions>
</codebase-patterns>

<!-- Include only sections with real findings. Omit empty sections. -->

<web-research><!-- Only if web-researcher was deployed -->
  <official-docs>[Key findings with URLs]</official-docs>
  <best-practices>[Practices with sources]</best-practices>
  <security-concerns>[Issues with severity and mitigation]</security-concerns>
</web-research>

<past-learnings><!-- Only if learnings-researcher found relevant matches -->
  <learning task-id="[ID]">[What's relevant and why — problems, decisions, gotchas]</learning>
</past-learnings>

<git-history>
  <similar-changes>[Commits with lessons]</similar-changes>
</git-history>

<risks><!-- Only if concrete risks identified -->
  <risk probability="H|M|L" impact="H|M|L" evidence="[file:line or code construct]">
    [Description]. Mitigation: [concrete action, not "be careful"].
  </risk>
</risks>

<performance><!-- Include when changes touch request paths, loops, or allocation-heavy code -->
  [Allocation impact, hot-path analysis, or explicit "no perf impact — [reason]"]
</performance>

<recommendations>
  <!-- For straightforward tasks: single recommended approach -->
  <!-- For ambiguous tasks: 2-3 approaches with winner -->
  <solution id="A" name="[Name]">
    <path>[Implementation steps]</path>
    <pros>[Advantages]</pros>
    <cons>[Disadvantages]</cons>
    <risk-level>[Low|Medium|High]</risk-level>
  </solution>
  <winner id="[A]" reasoning="[Why]"/>
</recommendations>

<task-contract version="1">
  <intent>[Single-sentence intent]</intent>
  <in-scope>[Explicit inclusions]</in-scope>
  <out-of-scope>[Explicit exclusions]</out-of-scope>
  <acceptance-criteria>
    <criterion id="AC-1">Given..., When..., Then...</criterion>
  </acceptance-criteria>
  <verification>
    <command>[Exact test command an agent can run to verify success]</command>
    <test-strategy>[Which test files/patterns cover this change]</test-strategy>
  </verification>
  <open-questions><!-- Gaps from step 9 that plan phase should resolve -->
    <question>[Specific unanswered question]</question>
  </open-questions>
</task-contract>

<next-steps>
Run `/apex:plan [identifier]` to create architecture from these findings.
</next-steps>
</research>
```
</output-format>

<update-frontmatter>
Set `updated: [ISO timestamp]` and verify `phase: research`
</update-frontmatter>
</step>

</workflow>

<success-criteria>
- Intent, scope, and verification strategy clarified
- All mentioned files read fully before spawning agents
- Ambiguity resolved before spawning agents (0 ambiguities OR user clarified)
- Research depth determined (LIGHT/STANDARD/DEEP) and agents scaled accordingly
- All spawned agents completed
- Target files identified with file:line references
- Implementation patterns extracted from codebase
- Gap check passed (must-know questions answered or flagged)
- Recommended approach documented with rationale
- Task contract created with intent, scope, and acceptance criteria
- Task file created/updated at ./apex/tasks/[ID].md
- Intelligence report displayed to user
</success-criteria>

<next-phase>
`/apex:plan [identifier]` - Architecture and design decisions
</next-phase>

</skill>

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/benredmond) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->