plan

What this skill does

# Plan Skill

> **Quick Ref:** Decompose goal into trackable issues with waves. Output: `.agents/plans/*.md` + bd issues.

**YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.**

## Loop position

Moves **3 (vertical slice decomposition)** and **5 (wave validity check)** of the [operating loop](../../docs/architecture/operating-loop.md). Consumes the [BDD intent issue](../../docs/templates/intent-issue.md); produces a [slice validation plan](../../docs/templates/slice-validation.md) — one slice per Given/When/Then row with a first-failing-test target, write-scope, bounded context, and ownership. Slices group into a wave only when every row of the wave-validity check passes (distinct write scopes, no shared migration/contract/CLI surface, declared integration order, owner per slice, discard path per slice). Default to sequential when in doubt — parallel waves are an optimization, not a default.

**CLI dependencies:** bd (issue creation). If bd is unavailable, write the plan to `.agents/plans/` as markdown with issue descriptions, and use TaskList for tracking instead. The plan document is always created regardless of bd availability.

## Discovery Boundary

Use the [Skill Ports and Adapters](../../docs/contracts/skill-ports-and-adapters.md)
vocabulary and the [Intent-to-Loop Hexagon](../../docs/architecture/intent-to-loop-hexagon.md)
for the boundary from Discovery into Plan:

| Boundary piece | Plan contract |
|---|---|
| Inbound port | `plan_slices` from BDD intent, bead, research artifact, or execution packet |
| Outbound ports | `persist_issue`, `verify_symbols`, `retrieve_context`, `seed_execution_packet` |
| Driving adapter | `/plan` skill invocation |
| Driven adapters | bd, `rg`, `.agents/findings`, `.agents/plans`, execution-packet writer |
| Context packet | slice plan, file dependency matrix, acceptance criteria, test levels |
| Guard adapter | stale-scope verification, symbol verification, wave-validity check |

Executable acceptance: [references/plan.feature](references/plan.feature) — consumes Discovery output, one slice per Given/When/Then row, wave-validity gate, durable slice-validation artifact.

## Flags

| Flag | Default | Description |
|------|---------|-------------|
| `--auto` | off | Skip human approval gate. Used by `/rpi --auto` for fully autonomous lifecycle. |
| `--fast-path` | off | Force Minimal detail template (see Step 3.2) |
| `--skip-symbol-check` | off | Skip symbol verification in Step 3.6 (for greenfield plans) |
| `--skip-audit-gate` | off | Skip baseline audit gate in Step 6 (for documentation-only plans) |

## Execution Steps

Given `/plan <goal> [--auto]`:

### Step 0: Bead-Input Pre-Flight (Stale-Scope Gate)

When the input to `/plan` is a bead ID (matches pattern `[a-z]{2,6}-[0-9a-z.]+`) AND **any** of the following conditions hold, automatically run `ao beads verify <bead-id>` as the **very first action** before any other planning step:

- complexity is `"full"`
- the bead is older than 7 days
- the bead description was filed by a prior session (e.g., handoff-sourced, deferred, or reopened)

```bash
# Example guard — run before Step 1
if [[ "$INPUT" =~ ^[a-z]{2,6}-[0-9a-z.]+$ ]]; then
    ao beads verify "$INPUT" || true
fi
```

If `ao beads verify` reports any STALE citations, present them to the user (or log them to the execution packet in `--auto` mode) and ask for scope re-validation before proceeding to Step 1. Do not decompose against stale evidence.

This implements the shared stale-scope validation rule — re-validate inherited scope estimates against HEAD before acting on deferred beads, handoff docs, or prior-session plans.

### Step 1: Setup
```bash
mkdir -p .agents/plans
```

### Step 2: Check for Prior Research + Knowledge Flywheel

`ls -la .agents/research/` and use Grep to find prior research. If found, read it before planning.

Then run `ao search` / `ao lookup` for prior planning patterns and **apply** (not just retrieve) any relevant learnings as planning constraints. Record citations with `ao metrics cite --type applied|retrieved`.

Read [references/pre-decomposition.md](references/pre-decomposition.md) for full flywheel-search commands, the apply-retrieved-knowledge contract, and section-evidence handling.

### Step 2.1: Load Compiled Prevention First (Mandatory)

Load compiled planning rules from `.agents/planning-rules/*.md` (primary) and fall back to `.agents/findings/registry.jsonl`. Match by finding ID, `applicable_when`, language, literal goal-text overlap, and changed-file overlap. Cap at top 5.

Record applied finding IDs and how they changed the plan. Fail open on missing/malformed files. Read [references/pre-decomposition.md](references/pre-decomposition.md) for the full ranked-packet contract.

Active findings from `.agents/findings/registry.jsonl` are a fallback planning input. Every written plan must include an `Applied findings:` line, even when the value is `none`.

### Step 2.2: Read and Validate Research Content

If research files exist, read the most recent one and verify it contains substantive sections (Summary, Findings, Architecture, Executive Summary, Recommendations) before proceeding. See [references/pre-decomposition.md](references/pre-decomposition.md) for the validation grep and warning behavior.

### Step 2.3: Optional Strategic Duel Gate

When the plan is likely to span more than one execution session AND it contains
at least one contested operator-default decision, recommend the
dueling-idea-wizards route (`/council --mode=debate --focus=ideas`) on the
strategic question before decomposition. Treat it as advisory, not a hard
prerequisite: skip it for single-session plans or plans with no meaningful
contested default. Evidence from the 2026-05-17 Mt Olympus run: a roughly
22 minute duel flipped 3/5 operator defaults and surfaced one already-shipped
adapter bug that ordinary review and passing tests had missed.

### Step 3: Explore the Codebase (if needed)

Dispatch an Explore sub-agent (Task tool) with a prompt that demands symbol-level detail: file inventory, function/method signatures, struct/type definitions, reuse points with `file:line`, test file locations and naming conventions, import paths. Read [references/pre-decomposition.md](references/pre-decomposition.md) for the canonical explore prompt.

#### Pre-Planning Baseline Audit (Mandatory)

Before decomposing, run grep/wc/ls commands to quantify files to change, sections to add/remove, LOC to modify, coverage gaps. Record commands alongside results. File size limits (800-line SKILL.md lint limit) and test fixture counts are mandatory checks. Ground truth with numbers prevents scope creep.

Read [references/pre-decomposition.md](references/pre-decomposition.md) for the bad/good examples table and the full audit recipe.

### Step 3.2: Scale Detail by Complexity

Auto-select plan detail level based on issue count and goal complexity:

| Level | Criteria | Template | Description |
|-------|----------|----------|-------------|
| **Minimal** | 1-2 issues, fast complexity | Bullet points per issue | Title, 2-line description, acceptance criteria, files list |
| **Standard** | 3-6 issues, standard complexity | Current plan format | Full implementation specs, tests, verification |
| **Deep** | 7+ issues, full complexity, or `--deep` | Extended format | Symbol-level specs, data transformation tables, design briefs, cross-wave registry |

Read [references/detail-templates.md](references/detail-templates.md) for the template definitions.

**Override:** `--deep` forces Deep regardless of issue count. `--fast-path` forces Minimal.

### Step 3.5: Generate Implementation Detail (Mandatory)

After exploring the codebase, generate symbol-level implementation detail for EVERY file in the plan. A worker reading the plan should know exactly what to write without rediscovering function names, parameters, or code locations.

Read [references/implementation-detail.md](references/implementation-detail.md) for the full