research

# 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**:

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

</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 APEX patterns found (trust ≥ 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

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

<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 = apex-patterns section
  ctx.impl = codebase-patterns section
  ctx.web = web-research section
  ctx.history = git-history section
  ctx.docs = documentation section (from documentation-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>

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

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

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