Step2

/step2 - Structured Plan for Subagent Execution

Create _step2_plan.md that a fresh /step3 session can execute with zero prior context.

_step2_plan.md is the only context bridge between this session and execution. Everything a subagent needs must be in the plan.

Design principle: Maximize safe parallel execution. Design for parallelism from the start, then serialize only where truly necessary.

Flow

1. Load context — FIRST ACTION: read _step1_decisions.md at repository root. Do NOT ask the user anything before checking this file.
   • Found: Use it as the goal. Apply Scan Integration rules below. If it contains ## Unresolved, warn the user and ask whether to resolve now or proceed.
   • Not found: Fall back to conversation context or ask the user what's being built.
2. Research — Read codebase, identify files, patterns, dependencies
3. Design phases (parallelism-first) — See Phase Design below
4. Validate — See Validation Checklist below
5. MANDATORY: Write _step2_plan.md — At repository root (NEVER in subdirectories) using the Write tool. Use date for timestamps. Do this BEFORE any closing remarks. This file is the primary deliverable — without it, /step2 failed.
6. MANDATORY: Delete _step1_decisions.md — Immediately after writing _step2_plan.md, delete it with Bash rm. Leaving it behind causes stale context in future sessions. Verify deletion before continuing.
7. Confirm — Only AFTER both file operations are confirmed, show summary and end with Next: /step3 to execute. Tip: /clear first so /step3 gets a full context window.

Scan Integration

Only applies when _step1_decisions.md exists. Actively transform it — don't just copy:

• Themed decision groups → organize phases by theme
• Pitfalls / Risks → concrete guardrails placed in the specific phase where they apply
• Key decisions → stated in the phase they constrain, so the subagent sees them in context
• Rejected alternatives → per-phase guardrails ("Do NOT use X because Y")
• Scope (what's out) → restate exclusions in relevant phases to prevent drift

The Rationale section is rewritten for execution, not copied from _step1_decisions.md. A subagent needs: the approach, what NOT to do, and the patterns to follow.

Phase Design (Parallelism-First)

1. Identify the work units — every distinct file or module change
2. Group by independence — which units touch completely separate files?
3. Form parallel groups first — units that can't conflict go in the same group as separate phases
4. Serialize only what must be serial — shared interfaces, types that other phases consume
5. Split to unlock parallelism — if a phase touches 4 files but only 1 creates a dependency, split it

Granularity rule: Prefer more smaller phases over fewer large ones, as long as each phase remains coherent. More phases = more parallelism. Never split below the point where a phase can't be understood in isolation.

Phase Requirements

Each phase executes as an isolated subagent in a fresh context — must be self-contained:

• Explicit file paths — name specific files, never "the file from Phase 2"
• No cross-phase references — describe what's needed, don't point to other phases
• One clear objective — single responsibility
• Concrete tasks — actionable, unambiguous

Context Budget

/step3 targets 50-150 lines per subagent dispatch. Design phases to fit:

• A phase with 5 Reference files and 8 tasks will blow the budget — split it
• If a phase needs extensive context to execute, it's too big or too vague

Reference Field

The **Reference:** field is how a subagent orients itself without exploring the codebase. Guide attention:

**Reference:**
- `src/auth/middleware.ts` — follow the existing guard pattern (line ~30) for new guards
- `src/types/api.ts` — conform to the Response<T> wrapper type

What to include: files to read, what pattern to follow, interfaces to conform to. What NOT to include: files the subagent won't need.

Guardrails Field

Per-phase guardrails derived from _step1_decisions.md pitfalls and codebase constraints:

**Guardrails:**
- Do NOT modify the existing User type — extend with a new interface
- All new endpoints must use the validation middleware from src/middleware/validate.ts

Only include when a phase has real risks of going wrong. Not every phase needs guardrails.

Dependencies

• Explicit numeric: "Depends: 2,3"
• No transitive repetition (if 3→2→1, phase 3 lists only "2")
• Document what it provides: "Depends: 2 (creates lib/core.py)" — /step3 passes this verbatim to subagents

Parallel Safety

• Same group MUST NOT touch same files
• Each phase lists what it modifies via Modifies: field
• When truly uncertain after analysis, serialize (safety > speed)

Validation Checklist

Before writing _step2_plan.md, verify:

1. Parallel maximization — could any sequential dependency be broken by splitting a phase? Could any phase's dependencies be reduced?
2. No file collisions — scan every parallel group, confirm no two phases in the same group touch the same file
3. Subagent autonomy — for each phase: "could a subagent execute this with ONLY the phase text and the Reference files?" If no, add what's missing. Check that dispatch stays within ~150 lines
4. Guardrail placement — every _step1_decisions.md pitfall is addressed in a specific phase, not just floating in the Rationale
5. Completeness — all decisions are reflected in at least one phase's tasks or guardrails

Rules

• NEVER use Task or EnterPlanMode. This skill IS the planning framework. Subagents lose your context. Plan mode hijacks your flow. Read/Glob/Grep directly.
• Gate: write before farewell. Never mention /step3 or signal completion until _step2_plan.md has been written with the Write tool AND _step1_decisions.md has been deleted in the current conversation. Both file operations are proof the skill finished. Missing either = skill failed.

_step2_plan.md Format

<!-- @plan: /step2 YYMMDD_HHMM -->
# [Goal Title]

**Goal:** [1-2 sentence description]
**Created:** YYYY-MM-DD

## Rationale

Rewritten for subagent consumption — what approach, what to avoid, what patterns to follow.

**Approach:** [chosen approach]
**Why:** [key reasons grounded in codebase evidence]
**Patterns:** [codebase conventions subagents must follow]
**Non-goals:** [what's explicitly out of scope]

## Phases Overview

| Phase | Name | Depends | Parallel Group | Est. Lines |
|-------|------|---------|----------------|------------|
| 1 | ... | - | A | ~60 |
| 2 | ... | 1 | B | ~80 |
| 3 | ... | 1 | B | ~45 |
| 4 | ... | 2,3 | C | ~70 |

## Phase Details

### Phase 1: [title]
**Modifies:** [file/directory scope]
**Reference:**
- `path/to/file.ts` — [what to look at and why]
**Guardrails:**
- [constraint, if any]
**Tasks:**
- [ ] Task 1
- [ ] Task 2

Note: Depends and Parallel Group live only in the Phases Overview table (for /step3's orchestration). Phase Details sections contain only what subagents need: Modifies, Reference, Guardrails, Tasks.

Output

Plan created: _step2_plan.md
- Phases: N (M can run in parallel)
- Parallel groups: N
- Est. dispatch sizes: all within budget / Phase X may be tight
Next: /step3 to execute. Tip: /clear first so /step3 gets a full context window.

Lifecycle

/step1 → _step1_decisions.md written
    ↓ (fresh session)
/step2 → reads _step1_decisions.md → writes _step2_plan.md → deletes _step1_decisions.md
    ↓ (fresh session)
/step3 → checkpoint → executes → deletes _step2_plan.md (or reset to checkpoint on failure)

Both _step1_decisions.md and _step2_plan.md are disposable. Each stage produces an artifact, the next consumes and deletes it. The code changes are the deliverable, not the artifacts.