plan

<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: [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] </schema> </artifact> </step> <step id="6" title="Architecture checkpoint"> <template> ## Architecture Review Checkpoint

I've completed the 5 mandatory artifacts. Here's the selected architecture:

Chosen Solution: [Winner from Tree of Thought] Key Patterns: [Top 3 patterns] Excluded Scope: [Top 3 YAGNI items] Complexity: [X/10] Risk Level: [LOW|MEDIUM|HIGH]

Implementation will:

1. [Key outcome 1]
2. [Key outcome 2]

Implementation will NOT:

• [YAGNI item 1]
• [YAGNI item 2]

Should I proceed with the detailed architecture, or adjust any decisions? </template> <wait-for-user>Get confirmation before finalizing.</wait-for-user> </step>

<step id="7" title="Generate architecture decision record"> <schema> 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] </schema> </step> <step id="8" title="Write plan section to task file"> <output-format> Append to `<plan>` 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>

</output-format> <update-frontmatter> Set `phase: plan` and `updated: [ISO timestamp]` </update-frontmatter> </step> </workflow> <self-review-checklist> - [ ] 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 </self-review-checklist>

<success-criteria> - 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 </success-criteria> <next-phase> `/apex:implement [identifier]` - Build and validate loop </next-phase> </skill>