Agent Skills: [Title]

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

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>

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>

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>

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>

---
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>

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

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

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

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

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>

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

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

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>