tomevault-io This is the first phase of the APEX workflow. It gathers all intelligence needed for planning and implementation.
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.
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.
- Intent: What is the user actually trying to accomplish? (Look past the literal request)
- Scope: What files/systems are in play? What's explicitly out?
- 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.
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
---
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.
Analyze git history for similar changes, regressions, ownership. Return: Structured git intelligence.
Search project docs for architecture context, past decisions, learnings, and gotchas. Return: architecture_context, past_decisions, historical_learnings, docs_to_update.
Search past task files for problems solved, decisions made, and gotchas. Return: Top 5 relevant learnings ranked by relevance.
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.
Trace execution flow, dependencies, state transitions, integration points.
Wait for ALL spawned agents to complete before proceeding.
Task: [Title] Depth: [LIGHT|STANDARD|DEEP] — [N] agents deployed
Target Files
- [file:line] — [why this file changes]
Key Findings
- [Most important finding from agents]
- [Second most important]
- [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>
Converted and distributed by TomeVault — claim your Tome and manage your conversions.