plan

What this skill does

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

<overview>
Transform research findings into battle-tested implementation plans through interactive design.

Produces 5 mandatory artifacts: Design Rationale and Evidence, Tree of Thought, Chain of Draft, YAGNI Declaration, Pattern Selection.
</overview>

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

<phase-gate requires="research" sets="plan">
  <reads-file>./apex/tasks/[ID].md</reads-file>
  <requires-section>research</requires-section>
  <appends-section>plan</appends-section>
</phase-gate>

<principles>
- **Be Skeptical**: Question vague requirements, identify issues early, verify with code
- **Be Interactive**: Get buy-in at each step, don't create full plan in one shot
- **Be Thorough**: Read ALL files FULLY, research patterns with parallel agents
- **Be Evidence-Based**: Every decision backed by code, patterns, or research
- **No Open Questions**: STOP and clarify before proceeding with unknowns
</principles>

<initial-response>
<if-no-arguments>
I'll create a rigorous technical architecture. Please provide the task identifier.

You can find active tasks in `./apex/tasks/` or run with:
`/apex:plan [identifier]`
</if-no-arguments>
<if-arguments>Load task file and begin architecture process.</if-arguments>
</initial-response>

<workflow>

<step id="1" title="Load task and verify phase">
<instructions>
1. Read `./apex/tasks/[identifier].md`
2. Verify frontmatter `phase: research`
3. Parse `<task-contract>` from the research output FIRST and treat it as authoritative scope/ACs
4. If `<task-contract>` is missing, STOP and ask to rerun research or add the contract with an explicit amendment rationale
5. Parse `<research>` section for context
6. If phase != research, refuse with: "Task is in [phase] phase. Expected: research"
7. Extract context pack references from `<context-pack-refs>`:
   - ctx.patterns = research.pattern-library
   - ctx.impl = research.codebase-patterns
   - ctx.web = research.web-research
   - ctx.history = research.git-history
   - ctx.docs = research.documentation
   - ctx.risks = research.risks
   - ctx.exec = research.recommendations.winner

Contract rules:
- Architecture artifacts MUST NOT contradict task-contract scope or ACs
- If scope/ACs must change, append a <amendments><amendment ...> entry inside task-contract and bump its version
</instructions>

</step>

<step id="2" title="Read research and spawn verification agents">
<critical>
Read ALL files mentioned in research section FULLY before any analysis.
</critical>

<agents parallel="true">
<agent type="intelligence-gatherer">Verify and extend pattern intelligence from research</agent>
<agent type="apex:systems-researcher">Map system flows for components mentioned in research</agent>
<agent type="apex:git-historian">Surface timelines and regressions for affected areas</agent>
<agent type="failure-predictor">Identify what could go wrong based on history</agent>
<agent type="apex:risk-analyst">Enumerate edge cases and mitigations</agent>
</agents>
</step>

<step id="3" title="Present initial understanding">
<template>
Based on research and analysis, I understand we need to [accurate summary].

**Key Findings:**
- [Current implementation at file:line]
- [Pattern discovered with confidence rating]
- [Complexity identified]

**Questions Requiring Human Judgment:**
- [Design preference that affects architecture]
- [Business logic clarification]
- [Risk tolerance decision]

Let's address these before I develop architecture options.
</template>
<wait-for-user>Get confirmation before proceeding.</wait-for-user>
</step>

<step id="4" title="Propose architecture structure">
<template>
Here's my proposed architecture approach:

## Core Components:
1. [Component A] - [purpose]
2. [Component B] - [purpose]
3. [Component C] - [purpose]

## Implementation Phases:
1. [Phase name] - [what it delivers]
2. [Phase name] - [what it delivers]

Does this structure align with your vision? Should I adjust?
</template>
<wait-for-user>Get confirmation before developing artifacts.</wait-for-user>
</step>

<step id="5" title="Develop 5 mandatory artifacts">
<critical>
YOU CANNOT PROCEED WITHOUT ALL 5 ARTIFACTS.
</critical>

<artifact id="1" name="Design Rationale and Evidence">
<purpose>Explain rationale and evidence: WHY exists? WHAT problems before? WHO depends? WHERE are landmines?</purpose>
<schema>
design_rationale:
  current_state:
    what_exists: [Component at file:line, purpose]
    how_it_got_here: [Git archaeology with commit SHA]
    dependencies: [Verified from code]
  problem_decomposition:
    core_problem: [Single sentence]
    sub_problems: [Specific technical challenges]
  hidden_complexity: [Non-obvious issues from patterns/history]
  success_criteria:
    automated: [Test commands, metrics]
    manual: [User verification steps]
</schema>
</artifact>

<artifact id="2" name="Tree of Thought Solutions">
<purpose>Generate EXACTLY 3 substantially different architectures.</purpose>
<schema>
tree_of_thought:
  solution_A:
    approach: [Name]
    description: [2-3 sentences]
    implementation: [Steps with file:line refs]
    patterns_used: [PAT:IDs with confidence ratings]
    pros: [Evidence-backed advantages]
    cons: [Specific limitations]
    complexity: [1-10 justified]
    risk: [LOW|MEDIUM|HIGH with reason]
  solution_B: [FUNDAMENTALLY different paradigm]
  solution_C: [ALTERNATIVE architecture]
  comparative_analysis:
    winner: [A|B|C]
    reasoning: [Why, with evidence]
    runner_up: [A|B|C]
    why_not_runner_up: [Specific limitation]
</schema>
</artifact>

<artifact id="3" name="Chain of Draft Evolution">
<purpose>Show thinking evolution through 3 drafts.</purpose>
<schema>
chain_of_draft:
  draft_1_raw:
    core_design: [Initial instinct]
    identified_issues: [Problems recognized]
  draft_2_refined:
    core_design: [Improved, pattern-guided]
    improvements: [What got better]
    remaining_issues: [Still problematic]
  draft_3_final:
    core_design: [Production-ready]
    why_this_evolved: [Journey from draft 1]
    patterns_integrated: [How patterns shaped design]
</schema>
</artifact>

<artifact id="4" name="YAGNI Declaration">
<purpose>Focus on production edge cases, exclude everything else.</purpose>
<schema>
yagni_declaration:
  explicitly_excluding:
    - feature: [Name]
      why_not: [Specific reason]
      cost_if_included: [Time/complexity]
      defer_until: [Trigger condition]
  preventing_scope_creep:
    - [Temptation]: [Why resisting]
  future_considerations:
    - [Enhancement]: [When makes sense]
  complexity_budget:
    allocated: [1-10]
    used: [By chosen solution]
    reserved: [Buffer]
</schema>
</artifact>

<artifact id="5" name="Pattern Selection Rationale">
<purpose>Justify every pattern choice with evidence.</purpose>

<critical>
YOU CANNOT FABRICATE PATTERNS.

Only use patterns that exist in:
- ctx.patterns (from research.pattern-library)
- ctx.impl (from research.codebase-patterns)

Before listing a pattern:
1. Verify it exists in the research section
2. Confirm confidence rating is from research, not invented
3. Document where in research you found it

VIOLATION: Claiming "PAT:NEW:THING" that wasn't in research
CONSEQUENCE: Final reflection becomes unreliable and confidence ratings become meaningless
</critical>

<intelligence-sources>
Check these sections for valid patterns:
- ctx.impl (reusable_snippets, project_conventions)
- ctx.patterns (pattern_cache.architecture)
- ctx.web (best_practices, official_docs)
- ctx.history (similar_tasks)
</intelligence-sources>

<schema>
pattern_selection:
  applying:
    - pattern_id: [PAT:CATEGORY:NAME]
      confidence_rating: [★★★★☆]
      usage_stats: [X uses, Y% success]
      why_this_pattern: [Speci