plan

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.

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 plan - **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 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]

Load task file and begin architecture process.

1. Read `./apex/tasks/[identifier].md` 2. Verify frontmatter `phase: research` 3. Parse `` from the research output FIRST and treat it as authoritative scope/ACs 4. If `` is missing, STOP and ask to rerun research or add the contract with an explicit amendment rationale 5. Parse `` section for context 6. If phase != research, refuse with: "Task is in [phase] phase. Expected: research" 7. Extract context pack references from ``: - 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 <amendment ...> entry inside task-contract and bump its version

Read ALL files mentioned in research section FULLY before any analysis. Verify and extend pattern intelligence from research Map system flows for components mentioned in research Surface timelines and regressions for affected areas Identify what could go wrong based on history Enumerate edge cases and mitigations <template> Based on research and analysis, I understand we need to [accurate summary]. <p><strong>Key Findings:</strong></p> <ul> <li>[Current implementation at file:line]</li> <li>[Pattern discovered with confidence rating]</li> <li>[Complexity identified]</li> </ul> <p><strong>Questions Requiring Human Judgment:</strong></p> <ul> <li>[Design preference that affects architecture]</li> <li>[Business logic clarification]</li> <li>[Risk tolerance decision]</li> </ul> <p>Let&#39;s address these before I develop architecture options.<br></template>
Get confirmation before proceeding.

<template> Here's my proposed architecture approach: <h2>Core Components:</h2> <ol> <li>[Component A] - [purpose]</li> <li>[Component B] - [purpose]</li> <li>[Component C] - [purpose]</li> </ol> <h2>Implementation Phases:</h2> <ol> <li>[Phase name] - [what it delivers]</li> <li>[Phase name] - [what it delivers]</li> </ol> <p>Does this structure align with your vision? Should I adjust?<br></template>
Get confirmation before developing artifacts.

YOU CANNOT PROCEED WITHOUT ALL 5 ARTIFACTS. Explain rationale and evidence: WHY exists? WHAT problems before? WHO depends? WHERE are landmines? 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] Generate EXACTLY 3 substantially different architectures. 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] Show thinking evolution through 3 drafts. 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] Focus on production edge cases, exclude everything else. 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] Justify every pattern choice with evidence. 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

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) pattern_selection: applying: - pattern_id: [PAT:CATEGORY:NAME] confidence_rating: [★★★★☆] usage_stats: [X uses, Y% success] why_this_pattern: [Specific fit] where_applying: [file:line] source: [ctx.patterns | ctx.impl | ctx.web] considering_but_not_using: - pattern_id: [PAT:ID] why_not: [Specific reason] missing_patterns: - need: [Gap identified] workaround: [Approach without pattern] <template> ## Architecture Review Checkpoint <p>I&#39;ve completed the 5 mandatory artifacts. Here&#39;s the selected architecture:</p> <p><strong>Chosen Solution</strong>: [Winner from Tree of Thought]<br><strong>Key Patterns</strong>: [Top 3 patterns]<br><strong>Excluded Scope</strong>: [Top 3 YAGNI items]<br><strong>Complexity</strong>: [X/10]<br><strong>Risk Level</strong>: [LOW|MEDIUM|HIGH]</p> <p><strong>Implementation will</strong>:</p> <ol> <li>[Key outcome 1]</li> <li>[Key outcome 2]</li> </ol> <p><strong>Implementation will NOT</strong>:</p> <ul> <li>[YAGNI item 1]</li> <li>[YAGNI item 2]</li> </ul> <p>Should I proceed with the detailed architecture, or adjust any decisions?<br></template>
Get confirmation before finalizing.

architecture_decision: decision: [Clear statement of chosen approach] files_to_modify: - path: [specific/file.ext] purpose: [Why changing] pattern: [PAT:ID applying] validation: [How to verify] files_to_create: - path: [new/file.ext] purpose: [Why needed] pattern: [PAT:ID template] test_plan: [Test approach] implementation_sequence: 1. [Step with checkpoint] 2. [Step with validation] validation_plan: automated: [Commands to run] manual: [User verification] potential_failures: - risk: [What could go wrong] mitigation: [Prevention strategy] detection: [Early warning] Append to `` section:

<plan>
<metadata>
  <timestamp>[ISO]</timestamp>
  <chosen-solution>[A|B|C]</chosen-solution>
  <complexity>[1-10]</complexity>
  <risk>[LOW|MEDIUM|HIGH]</risk>
</metadata>

<contract-validation>
  <contract-version>[N]</contract-version>
  <status>aligned|amended</status>
  <acceptance-criteria-coverage>
    <criterion id="AC-1">[How the plan will satisfy this AC]</criterion>
  </acceptance-criteria-coverage>
  <out-of-scope-confirmation>[Confirm no out-of-scope work is planned]</out-of-scope-confirmation>
  <amendments-made>
    <amendment version="[N]" reason="[Rationale or 'none']"/>
  </amendments-made>
</contract-validation>

<design-rationale>
  [Full artifact]
</design-rationale>

<tree-of-thought>
  <solution id="A">[Full details]</solution>
  <solution id="B">[Full details]</solution>
  <solution id="C">[Full details]</solution>
  <winner id="[X]" reasoning="[Why]"/>
</tree-of-thought>

<chain-of-draft>
  <draft id="1">[Raw design]</draft>
  <draft id="2">[Refined]</draft>
  <draft id="3">[Final]</draft>
</chain-of-draft>

<yagni>
  <excluding>[Features cut with reasons]</excluding>
  <scope-creep-prevention>[Temptations resisted]</scope-creep-prevention>
  <complexity-budget allocated="X" used="Y" reserved="Z"/>
</yagni>

<patterns>
  <applying>[Patterns with locations and justifications]</applying>
  <rejected>[Patterns considered but not used]</rejected>
</patterns>

<architecture-decision>
  <files-to-modify>[List with purposes and patterns]</files-to-modify>
  <files-to-create>[List with test plans]</files-to-create>
  <sequence>[Implementation order with checkpoints]</sequence>
  <validation>[Automated and manual checks]</validation>
  <risks>[Potential failures with mitigations]</risks>
</architecture-decision>

<builder-handoff>
  <mission>[Clear directive]</mission>
  <core-architecture>[Winner approach summary]</core-architecture>
  <pattern-guidance>[PAT:IDs with locations]</pattern-guidance>
  <implementation-order>[Numbered steps]</implementation-order>
  <validation-gates>[Checks after each step]</validation-gates>
  <warnings>[Critical risks and edge cases]</warnings>
</builder-handoff>

<next-steps>
Run `/apex:implement [identifier]` to begin implementation.
</next-steps>
</plan>

Set `phase: plan` and `updated: [ISO timestamp]` - [ ] Design Rationale and Evidence: ALL hidden complexity identified? - [ ] Tree of Thought: 3 FUNDAMENTALLY different solutions? - [ ] Chain of Draft: REAL evolution shown? - [ ] YAGNI: 3+ explicit exclusions? - [ ] Patterns: Trust scores and usage stats included? - [ ] Architecture decision: CONCRETE file paths? - [ ] New files: Test plan included for each? - [ ] Task contract validated with AC coverage and amendments recorded if any?

If ANY unchecked → STOP and revise

- All 5 artifacts completed with evidence - User confirmed architecture decisions - Research insights incorporated (ctx.* references used) - Pattern selections justified with confidence ratings (NO fabricated patterns) - 3 DISTINCT architectures in Tree of Thought - YAGNI boundaries explicit - Task contract validated; AC coverage documented; amendments (if any) recorded with version bump - Implementation sequence concrete with validation - Task file updated at ./apex/tasks/[ID].md - Checkpoints recorded at start and end - Task metadata updated for architecture completion - Architecture artifacts recorded in the task log `/apex:implement [identifier]` - Build and validate loop