Plan Design

Extend (not replace) the base orchestrator workflow for high-rigor plan authoring.

Use this skill when the output is a plan artifact requiring:

• Multi-source synthesis
• Parallel investigation
• Iterative review gates
• Newcomer-safe clarity and verifiability

1. Relationship to Existing Skills

• Base orchestration mechanics: use orchestrator skill.
• Multi-perspective review mechanics: reuse subagent-review concepts selectively.
• GitHub fetch/comment commands: use github skill where needed.
• Do not duplicate those skills; add only plan-design specific workflow.

2. Trigger Conditions

Use this skill when one or more apply:

• User asks for a migration plan, rollout plan, or execution roadmap.
• Input includes large docs, predecessor notes, or investigation artifacts.
• User asks for beginner-friendly documentation or says they cannot understand the current plan.
• Plan must pass explicit approval gates (critic/guardian/boss or equivalents).

3. Pre-Step: Overlap Check (Mandatory)

Before drafting, run the following and read the results:

1. List existing skills:
   ls ~/ghq/github.com/i9wa4/dotfiles/agents/skills/

2. Read at minimum:

   • ~/ghq/github.com/i9wa4/dotfiles/agents/skills/orchestrator/SKILL.md
   • ~/ghq/github.com/i9wa4/dotfiles/agents/skills/subagent-review/SKILL.md

3. Read any skill whose name suggests planning, review, or session workflow.

4. Record the overlap matrix in the research artifact:

   • Already covered by existing skills
   • New behavior unique to this plan-design session

Do not proceed until the unique delta is explicit.

4. 5-Step Workflow

NOTE: This workflow departs from orchestrator base behavior by dispatching workers (Step 2)
BEFORE the annotation cycle (Step 3). This is intentional for plan authoring: workers provide
raw investigation inputs that the annotation cycle then synthesizes. This overrides orchestrator
section 3.2 for plan-design tasks only. In all other contexts, follow the base orchestrator order.

4.1. Step 1: Fetch Source and Build Ground Truth

1. Create a research artifact for source digestion:
   mkoutput --dir research --label "plan-investigation"

   Note: add a suffix to disambiguate if multiple plans exist in the same session, e.g.

   mkoutput --dir research --label "plan-investigation-dbt-merge"

2. Read all source artifacts in full.

3. For large files, read in chunks (offset/limit or line ranges).

4. Extract:

   • Constraints
   • Open decisions/placeholders
   • Risk points
   • Missing prerequisites/access assumptions

Output: source digest with section references.

4.2. Step 2: Parallel Investigation

Dispatch worker and worker-alt in parallel with non-overlapping focus:

• worker focus:
  • Architecture correctness
  • Dependency/order integrity
  • Missing technical steps
• worker-alt focus:
  • Beginner-friendliness
  • Phase verifiability
  • Preconditions/tools/access completeness

Required response format from each worker:

• Severity buckets: BLOCKING, IMPORTANT, MINOR
• For each finding: section reference + missing detail + suggested addition

4.3. Step 3: Annotation and Synthesis

1. Aggregate both worker outputs into one review package.
2. Resolve contradictions between worker findings:
   • If worker and worker-alt disagree, prefer the more conservative (safer) finding.
   • Document the resolution in the Decision Log.
3. Tighten the draft:
   • Remove ambiguity
   • Ensure all commands are copy-pasteable
   • Ensure all expected outputs are specified
4. Keep a decision log for each non-obvious choice.

When synthesis is complete, proceed to Step 4 (formal review gate).
Do NOT dispatch to critic or guardian here -- that is Step 4's responsibility.

4.4. Step 4: Review Gate Order (Strict)

1. Send to critic and guardian in parallel.
2. If either rejects: revise the plan artifact, resubmit to both. Repeat until both approve.
   • Maximum 3 revision rounds per gate pass.
   • If consensus is not reached after 3 rounds:
     a. Record the disagreement in the Decision Log.
     b. Notify messenger: "BLOCKED: critic/guardian deadlock after 3 rounds -- human decision required."
     c. Do not proceed to boss until messenger resolves the deadlock.
3. Submit to boss only after critic AND guardian both approve the same artifact version.
4. If boss rejects:
   a. Record the rejection reason in the Decision Log.
   b. Revise the plan artifact per boss feedback.
   c. Return to step 1 of this gate (re-run critic + guardian before resubmitting to boss).
   d. Maximum 2 boss rejection rounds.
   e. If boss rejects a second time, notify messenger: "BLOCKED: plan rejected twice by boss -- escalate."
5. Do not finalize or send to messenger until boss approves.

4.5. Step 5: Beginner-Friendly Final Plan Packaging

This step augments the base orchestrator plan template. The sections below are ADDITIONAL
to the base template defined in the orchestrator skill. Sections already in the base template
(Purpose, Source, Context, Investigation Summary, Acceptance Criteria, Decision Log, Risks,
Test Strategy, Progress, Surprises) must still be present. The sections listed here must also
be added for beginner-friendly plan outputs.

Additional required sections:

1. Plain-language background
2. Glossary (define all domain terms/acronyms used)
3. Prerequisites
   • tools + versions
   • auth checks
4. Access matrix
   • required permissions per phase
   • owner/escalation path
5. Phase-by-phase command blocks
   • copy-paste commands
   • expected outputs
   • explicit Definition of Done per phase
6. Decision gates
   • replace placeholders with concrete decisions or owner/date gates
7. Rollback per phase
   • trigger + steps + verification

5. Worker Routing Strategy (Default)

• Investigation tasks: dispatch to worker + worker-alt in parallel.
• Execution (complex reasoning/design): worker.
• Execution (mechanical/simple): worker-alt.

If risk is high or ambiguity is high, run parallel and compare.

6. Ambiguity Escalation (Mandatory)

If any worker encounters ambiguous or unclear points while rewriting content for a beginner audience:

1. Stop -- do NOT make assumptions and proceed.
2. Flag the ambiguity explicitly in the DONE/BLOCKED report to orchestrator.
3. Orchestrator runs the full critic + guardian + boss review cycle on the revised content.
4. Notify messenger of the ambiguity and the review outcome before finalizing.

This rule applies to all plan rewriting tasks, including glossary entries, command templates, and decision gate prose.

7. Quality Checklist Before Approval

A plan is ready for boss review only if all are true:

• Every technical term used is defined once.
• Every phase has commands + expected outputs + done criteria.
• Prerequisites and access requirements are explicit.
• Placeholder decisions are resolved or converted into named decision gates.
• Critic and guardian approved the same artifact version.

8. Deliverables

• Plan file created via:
  • mkoutput --dir plans --label plan
• Progress updates and status changes recorded in the plan.
• Final handoff summary including:
  • Key decisions
  • Unresolved gates
  • Evidence of verification outputs