ralplan

name	ralplan
description	Multi-reviewer consensus planning workflow. Draft a plan, then iterate through architect and critic reviews until both approve. Use when: planning complex features, reviewing architecture tradeoffs, creating implementation plans that need validation, or any work that benefits from structured plan approval before execution.

Ralplan — Consensus Planning

Ralplan produces implementation plans that have been reviewed and approved by two independent reviewers: an architect (feasibility, design) and a critic (gaps, edge cases, risks). Plans iterate until both approve.

Input Contract

Ralplan is the planning consumer of the deep-interview brief. Before drafting, it must adopt the upstream spec/state pair so plans never silently drop inherited context.

• Accept explicit deep-interview spec/state paths
• If invoked directly without them, discover artifacts using the deterministic discovery rule defined in deep-interview/SKILL.md under ### Artifact discovery, or surface that planning is running without interview fidelity
• After adopting a brief, append ralplan to consumed_by in the machine-readable state

The adopted brief supplies the non-goals, decision boundaries, constraints, and acceptance criteria that reviewers will check the plan against.

Phase State Machine

draft → architect-review → critic-review → complete
  ↑                                    |
  └────────── iterate ─────────────────┘

Phases:

• draft — Produce an implementation plan from the task description
• architect-review — Architect reviews for feasibility, architecture, and design quality
• critic-review — Critic reviews for gaps, edge cases, missing tests, risks
• complete — Both reviewers approved
• failed — Max iterations exceeded
• cancelled — User cancelled

Review Verdicts

Each reviewer returns one of:

• approve — Plan is good, proceed
• iterate — Plan needs changes, redraft with feedback
• reject — Plan is fundamentally flawed (escalate to user)

Execution Flow

When the user invokes /ralplan <task> or $ralplan <task>:

1. Initialize

• Create .oh-my-pi/plans/ directory
• Set phase to draft, iteration to 1
• Accept explicit deep-interview spec/state paths, or discover them using the deterministic discovery rule defined in deep-interview/SKILL.md under ### Artifact discovery
• Read the adopted brief before drafting, or surface reduced-fidelity planning if no brief is available
• Append ralplan to consumed_by in the machine-readable state after adopting the brief

2. Consensus Loop

for iteration in 1..max_iterations (default 5):
  
  # DRAFT
  Use superpowers_dispatch with agent="worker" to:
  - Read the task description (and prior feedback if iterating)
  - Produce an implementation plan covering:
    - Architecture and approach
    - Component breakdown
    - Data flow and interfaces
    - Testing strategy
    - Risks and mitigations
    - Acceptance criteria
  - Save plan to .oh-my-pi/plans/plan-<slug>.md
  
  # ARCHITECT REVIEW
  Use superpowers_dispatch with agent="worker" to:
  - Review the plan as an architect
  - Assess: feasibility, design quality, separation of concerns,
    scalability, alignment with existing patterns
  - Return verdict: approve / iterate / reject
  - If iterate: provide specific feedback for redrafting
  
  if architect_verdict == "reject":
    Notify user, present architect feedback, ask how to proceed
    
  # CRITIC REVIEW  
  Use superpowers_dispatch with agent="worker" to:
  - Review the plan as a critic
  - Assess: completeness, edge cases, missing tests, error handling,
    security considerations, rollback plan, observability
  - Return verdict: approve / iterate / reject
  - If iterate: provide specific feedback for redrafting
  
  if critic_verdict == "reject":
    Notify user, present critic feedback, ask how to proceed
  
  if architect_verdict == "approve" AND critic_verdict == "approve":
    phase = "complete"
    DONE ✅ — Plan approved by consensus
  
  # If either said "iterate", loop back to draft with feedback

if loop exits without consensus:
  phase = "failed"
  notify the user that max iterations were exhausted

3. Handoff to Ralph

When planning completes:

• Present the approved plan to the user
• Ask: "Plan approved. Start ralph execution?"
• If yes: invoke ralph skill with the plan as input
• The plan path is passed so ralph's implementer subagent can read it

Artifacts

Plans stored at: .oh-my-pi/plans/plan-<slug>.md

Review history at: .oh-my-pi/plans/reviews-<slug>.json

{
  "task": "Add user authentication",
  "source_brief_spec": ".oh-my-pi/specs/deep-interview-<slug>.md",
  "source_brief_state": ".oh-my-pi/state/deep-interview-<slug>.json",
  "inherited_ambiguity_preserved": true,
  "boundary_violations": [],
  "iterations": [
    {
      "iteration": 1,
      "draft_summary": "JWT-based auth with refresh tokens",
      "architect_verdict": "iterate",
      "architect_feedback": "Consider session-based auth for simplicity",
      "critic_verdict": "iterate", 
      "critic_feedback": "Missing rate limiting on login endpoint"
    },
    {
      "iteration": 2,
      "draft_summary": "Session-based auth with rate-limited login",
      "architect_verdict": "approve",
      "architect_feedback": "Clean design, follows existing patterns",
      "critic_verdict": "approve",
      "critic_feedback": "All edge cases covered"
    }
  ]
}

The top-level source_brief_spec / source_brief_state pin the adopted deep-interview brief. inherited_ambiguity_preserved records whether the plan carried forward the brief's ambiguity and decision boundaries, and boundary_violations captures reviewer outputs as a string array listing plan elements flagged against inherited non-goals, decision boundaries, or constraints. The slug-scoped reviews-<slug>.json path prevents later ralplan runs from overwriting earlier review histories.

Subagent Prompts

Drafter

Create an implementation plan for: <task>

<if brief_available>
Read the deep-interview brief at <source_brief_spec> before drafting.
Treat inherited non-goals, decision boundaries, constraints, and acceptance criteria as binding inputs.
</if>

Cover: architecture, components, data flow, testing strategy, risks, acceptance criteria.
Follow existing codebase patterns. Be specific about file paths and interfaces.

<if iterating>
Previous feedback to incorporate:
- Architect: <feedback>
- Critic: <feedback>
</if>

Architect Reviewer

Review this implementation plan as a software architect.

<if brief_available>
Read the deep-interview brief at <source_brief_spec> before reviewing the plan.
Flag any plan element that contradicts inherited non-goals, decision boundaries, or constraints.
If you find contradictions, list them so they can populate `boundary_violations`.
</if>

Assess: feasibility, design quality, separation of concerns, scalability, 
alignment with existing codebase patterns.

Return your verdict as: VERDICT: approve|iterate|reject
If iterate, provide specific actionable feedback.

Critic Reviewer

Review this implementation plan as a critical reviewer.

<if brief_available>
Read the deep-interview brief at <source_brief_spec> before reviewing the plan.
Flag any missing acceptance criteria, hidden scope expansion, or unresolved risk that the plan fails to carry forward.
If you find scope contradictions, list them so they can populate `boundary_violations`.
</if>

Assess: completeness, edge cases, missing tests, error handling paths,
security considerations, rollback plan, observability gaps.

Return your verdict as: VERDICT: approve|iterate|reject
If iterate, provide specific actionable feedback.

Commands

• /ralplan <task> — Start consensus planning
• /ralplan status — Show current phase and review verdicts

Key Principles

1. Two independent reviewers — Architect and critic catch different issues
2. Iterate, don't settle — Plans improve through feedback loops
3. Reject escalates — Fundamental issues go to the user, not more iterations
4. Plans are artifacts — Saved to disk, readable, referenceable
5. Handoff to ralph — Approved plans flow directly into execution