research

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.

phase_model: frontmatter: [research, plan, implement, rework, complete] rework: enabled db_role: [RESEARCH, ARCHITECT, BUILDER, BUILDER_VALIDATOR, REVIEWER, DOCUMENTER] legacy_db_role: [VALIDATOR] source_of_truth: gating: frontmatter.phase telemetry: db_role ./apex/tasks/[ID].md research 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.

Immediately begin research - skip this message.

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.

Vague task briefs lead to wasted research effort. Enhance before proceeding. 1. **Clarify Intent**: What is the user REALLY trying to accomplish? - Look for implicit goals behind explicit requests - Identify the "why" behind the "what"

2. Add Specificity: Transform vague terms into concrete requirements

   • "improve performance" → "reduce API response time below 200ms"
   • "fix the bug" → "prevent null pointer when user has no profile"

3. Structure Requirements: Break into testable acceptance criteria

   • Given [context], When [action], Then [expected result]

4. Include Testing: How will we verify success?

   • Unit test expectations
   • Integration test scenarios
   • Manual verification steps

5. Pattern Enhancement: Check existing patterns or similar past tasks

   • What worked before?
   • What failed and why?

```yaml original_prompt: "[User's original request]" enhanced_prompt: intent: "[Clarified goal]" scope: in: ["[Specific inclusions]"] out: ["[Explicit exclusions]"] acceptance_criteria: - "[Testable criterion 1]" - "[Testable criterion 2]" success_metrics: - "[Measurable outcome]" related_patterns: ["[PAT:IDs from quick lookup]"] ``` 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 Run a low-cost scan to reduce ambiguity before spawning deep research agents. - Run cheap `rg` scans to locate entrypoints, tests, and likely target areas: - `rg -n "main|entry|cli|index\\.(ts|js)|server\\.(ts|js)" src` - `rg -n "describe\\(|it\\(" tests` - `rg -n "[task keywords]" src tests docs` (derive keywords from enhanced_prompt) - Capture candidate files/areas to refine scope. - Do NOT open large files unless the user explicitly mentioned them. - Use this scan ONLY to detect ambiguity and shape clarifying questions. Ambiguity is a BLOCKING condition that ONLY users can resolve. DO NOT spawn deep research agents with unclear requirements. Check for these ambiguity indicators:

Vague Goals:

• "improve", "enhance", "optimize" without metrics
• "fix the bug" without reproduction steps
• "make it better" without criteria

Unclear Scope:

• No defined boundaries (what's in/out)
• Multiple interpretations possible
• Triage scan surfaces multiple plausible entrypoints/tests

Technical Choices:

• Triage scan shows multiple candidate libraries/approaches
• Architecture decisions user should make
• Technology/library selection needed

Missing Constraints:

• No performance requirements
• No security requirements specified
• No compatibility requirements

```python def assess_ambiguity(enhanced_prompt, triage_scan): ambiguities = []

# Check each category
if has_vague_goals(enhanced_prompt):
    ambiguities.append({"type": "vague_goal", "question": "..."})

if has_unclear_scope(enhanced_prompt, triage_scan):
    ambiguities.append({"type": "unclear_scope", "question": "..."})

if needs_technical_choice(triage_scan):
    ambiguities.append({"type": "technical_choice", "question": "..."})

if missing_constraints(enhanced_prompt):
    ambiguities.append({"type": "missing_constraint", "question": "..."})

return ambiguities

</assessment-logic>

<decision>
- **0 ambiguities**: PROCEED to spawn parallel research agents
- **1+ ambiguities**: ASK USER before spawning deep research agents

**Question Format**:

Before I spawn deep research agents, I need to clarify:

[For each ambiguity, ONE focused question]

1. [Category]: [Specific question]?
   • Option A: [Choice with implication]
   • Option B: [Choice with implication]
   • Option C: [Let me know your preference]

</decision>

<max-rounds>
Maximum 1 clarification round. After user responds:
- Incorporate answers into enhanced_prompt
- Proceed to spawn parallel research agents (do NOT ask more questions)
</max-rounds>
</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>

Use the clarified enhanced_prompt (post-ambiguity resolution) as the source of truth for all agent prompts. **Task ID**: [taskId] **Research Focus**: [User's question/area]

Discover relevant patterns, find similar tasks, identify predicted failures, generate execution strategy.
Return: Context pack with pattern intelligence.

**Task Context**: [Brief description] **Task Type**: [bug|feature|refactor|test]

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

**Research Topic**: [Component/Technology/Pattern] **Context**: [What we're trying to accomplish]

Find official documentation, best practices, security concerns, recent changes.
Return: YAML with official_docs, best_practices, security_concerns, recent_changes.

**Scope**: [files/directories] **Window**: 9 months

Analyze git history for similar changes, regressions, ownership.
Return: Structured git intelligence.

**Scope**: Project markdown documentation **Focus**: [Task-relevant topics]

Search project docs for:

• Architecture context and design decisions
• Past decisions and rationale (ADRs)
• Historical learnings and gotchas
• Related documentation that may need updating

Return: YAML with architecture_context, past_decisions, historical_learnings, docs_to_update.

**Task Intent**: [Enhanced prompt intent] **Keywords**: [Extracted keywords from task]

Search past task files (apex/tasks/*.md) for:

• Problems solved and how they were fixed
• Decisions made with rationale
• Gotchas and surprising discoveries
• Related tasks via related_tasks links

Return: YAML with top 5 relevant learnings ranked by relevance score.

**Trigger**: Cross-component changes, architectural impacts **Focus Area**: [Component or subsystem]

Trace execution flow, dependencies, state transitions, integration points.

**Trigger**: Complexity >= 7, production-critical, security-sensitive

Surface forward-looking risks, edge cases, monitoring gaps, mitigations.

CRITICAL: Wait for ALL agents to complete before proceeding.

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 - 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) Give user visibility into gathered intelligence before the technical adequacy gate. ``` ## Intelligence Report

Task: [Title]
Agents Deployed: [N]
Files Analyzed: [X]

Baseline Metrics

• Complexity estimate: [1-10]
• Risk level: [Low/Medium/High]
• Pattern coverage: [X patterns found, Y% high-trust]

Pattern Intelligence

• High-trust patterns (★★★★☆+): [N] patterns applicable
• Similar past tasks: [N] found, [X]% success rate
• Predicted failure points: [N] identified

Historical Intelligence

• Related commits: [N] in last 9 months
• Previous attempts: [List any failed/reverted changes]
• Key maintainers: [Names/areas]

Execution Strategy

• Recommended approach: [Brief]
• Parallelization opportunities: [Yes/No]
• Estimated scope: [Small/Medium/Large]

Key Insights

1. [Most important finding]
2. [Second most important]
3. [Third most important]

</display-format>
</step>

<step id="9" title="Technical Adequacy Gate (Phase 2)">
<purpose>
Verify we have sufficient intelligence to architect a solution.
</purpose>

<scoring-dimensions>
**Technical Context (30% weight)**:
- [ ] Primary files identified with line numbers
- [ ] Dependencies mapped
- [ ] Integration points documented
- [ ] Current behavior understood

**Risk Assessment (20% weight)**:
- [ ] Security concerns identified
- [ ] Performance implications assessed
- [ ] Breaking change potential evaluated
- [ ] Rollback strategy considered

**Dependency Mapping (15% weight)**:
- [ ] Upstream dependencies known
- [ ] Downstream consumers identified
- [ ] External API constraints documented
- [ ] Version compatibility checked

**Pattern Availability (35% weight)**:
- [ ] Relevant patterns found (confidence ≥ 0.5)
- [ ] Similar past tasks reviewed
- [ ] Implementation patterns from codebase extracted
- [ ] Anti-patterns identified to avoid
</scoring-dimensions>

<confidence-calculation>
```python
def calculate_adequacy(checklist_results):
    weights = {
        "technical_context": 0.30,
        "risk_assessment": 0.20,
        "dependency_mapping": 0.15,
        "pattern_availability": 0.35
    }

    score = sum(
        weights[dim] * (checked / total)
        for dim, (checked, total) in checklist_results.items()
    )

    return score  # 0.0 to 1.0

- **≥ 0.8**: PROCEED to Tree of Thought - **0.6-0.8**: PROCEED with caution, note gaps - **< 0.6**: INSUFFICIENT - spawn recovery agents or escalate

If INSUFFICIENT:

## Insufficient Context

Adequacy Score: [X]% (threshold: 60%)

**Gaps Identified**:
- [Dimension]: [What's missing]

**Recovery Options**:
1. Spawn additional agents for [specific gap]
2. Ask user for [specific information]
3. Proceed with documented limitations

Which approach should I take?

Produce exactly 3 distinct solution approaches:

Solution A: [Approach name]

• Philosophy, implementation path, pros, cons, risk level

Solution B: [Different paradigm]

• Philosophy, implementation path, pros, cons, risk level

Solution C: [Alternative architecture]

• Philosophy, implementation path, pros, cons, risk level

Comparative Analysis: Winner with reasoning, runner-up with why not

Append to `` section:

<research>
<metadata>
  <timestamp>[ISO]</timestamp>
  <agents-deployed>[N]</agents-deployed>
  <files-analyzed>[X]</files-analyzed>
  <confidence>[0-10]</confidence>
  <adequacy-score>[0.0-1.0]</adequacy-score>
  <ambiguities-resolved>[N]</ambiguities-resolved>
</metadata>

<context-pack-refs>
  <!-- Shorthand for downstream phases -->
  ctx.patterns = pattern-library section
  ctx.impl = codebase-patterns section
  ctx.web = web-research section
  ctx.history = git-history section
  ctx.docs = documentation section (from documentation-researcher)
  ctx.learnings = past-learnings section (from learnings-researcher)
  ctx.risks = risks section
  ctx.exec = recommendations.winner section
</context-pack-refs>

<executive-summary>
[2-3 paragraphs synthesizing ALL findings]
</executive-summary>

<web-research>
  <official-docs>[Key findings with URLs]</official-docs>
  <best-practices>[Practices with sources]</best-practices>
  <security-concerns>[Issues with severity and mitigation]</security-concerns>
  <gap-analysis>[Codebase vs recommendations]</gap-analysis>
</web-research>

<codebase-patterns>
  <primary-pattern location="file:line">[Description with code snippet]</primary-pattern>
  <conventions>[Naming, structure, types, error handling]</conventions>
  <reusable-snippets>[Copy-pasteable code with sources]</reusable-snippets>
  <testing-patterns>[How similar features are tested]</testing-patterns>
  <inconsistencies>[Multiple approaches found]</inconsistencies>
</codebase-patterns>

<pattern-library>
  <pattern id="PAT:X:Y" confidence="★★★★☆" uses="N" success="X%">[Relevance]</pattern>
  <anti-patterns>[Patterns to avoid with reasons]</anti-patterns>
</pattern-library>

<documentation>
  <architecture-context>[Relevant architecture docs found]</architecture-context>
  <past-decisions>[ADRs and design decisions]</past-decisions>
  <historical-learnings>[Gotchas and lessons from docs]</historical-learnings>
  <docs-to-update>[Files that may need updating after this task]</docs-to-update>
</documentation>

<past-learnings>
  <count>[Number of relevant learnings found]</count>
  <coverage>[EXCELLENT|GOOD|SPARSE|NONE]</coverage>
  <learnings>
    <learning task-id="[ID]" relevance="[0.0-1.0]">
      <title>[Task title]</title>
      <summary>[Why this is relevant and what's useful]</summary>
      <problems>[Problems solved, if any]</problems>
      <decisions>[Decisions made, if any]</decisions>
      <gotchas>[Gotchas discovered, if any]</gotchas>
    </learning>
  </learnings>
  <patterns-across>[Common themes from multiple past tasks]</patterns-across>
</past-learnings>

<git-history>
  <similar-changes>[Commits with lessons]</similar-changes>
  <evolution>[How code got here]</evolution>
</git-history>

<risks>
  <risk probability="H|M|L" impact="H|M|L">[Description with mitigation]</risk>
</risks>

<recommendations>
  <solution id="A" name="[Name]">
    <philosophy>[Core principle]</philosophy>
    <path>[Implementation steps]</path>
    <pros>[Advantages]</pros>
    <cons>[Disadvantages]</cons>
    <risk-level>[Low|Medium|High]</risk-level>
  </solution>
  <solution id="B" name="[Name]">...</solution>
  <solution id="C" name="[Name]">...</solution>
  <winner id="[A|B|C]" 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>
  <non-functional>
    <performance>[Performance constraints]</performance>
    <security>[Security constraints]</security>
    <compatibility>[Compatibility constraints]</compatibility>
  </non-functional>
  <amendments>
    <!-- Append amendments in plan/implement/ship with explicit rationale and version bump -->
  </amendments>
</task-contract>

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

Set `updated: [ISO timestamp]` and verify `phase: research` - Prompt optimized and enhanced with specificity - All mentioned files read fully - Triage scan completed and ambiguity resolved before spawning agents - All parallel agents completed (including documentation-researcher, learnings-researcher) - Implementation patterns extracted with file:line refs - Web research validated against official docs - Patterns analyzed with confidence ratings - Documentation context gathered - Past learnings searched and top 5 relevant included - Git history examined - Intelligence report displayed to user - Ambiguity detection completed (0 ambiguities OR user clarified) - Technical adequacy score ≥ 0.6 - 3 solution approaches generated (Tree of Thought) - Risks identified with mitigations - Task contract created with intent, scope, ACs, and NFRs - Task file created/updated at ./apex/tasks/[ID].md - Context pack refs documented for downstream phases `/apex:plan [identifier]` - Architecture and design decisions