Planning Workflow

Overview

A good plan reduces risk without ceremony. Convert a goal into scope, phases, tasks, dependencies, gates, rollback, and next action.

When to Use

Phase 0 Benchmark Decision

Type: Technique with planning judgment. Adopt Superpowers writing-plans: exact paths, bite-sized tasks, commands with expected output, no placeholders, self-review against the spec. Adopt GStack habits: challenge scope, identify architecture/test/performance/security gaps, keep unresolved decisions visible, and require gates for risky work. Omit save-to-doc, telemetry, browser, and commit rules.

Planning Gate

No clear goal/scope -> use requirements-clarifier.
No evidence/work surface -> add discovery before implementation.
No gate -> no "ready to execute" claim.
No rollback for risky work -> mark blocked or discovery-first.
Sensitive/destructive boundary -> load agent-security-guard.

The Process

goal -> evidence -> risk -> phases -> gates -> tasks -> review -> handoff

Step 1: Establish the Planning Frame

Expected Output: objective=<one sentence>, scope=<in>, non_goals=<out>, constraints=<list>, unknowns=<blocking|assumed|deferred>

Define what the plan may solve. Pull from the request, requirements, issue, design doc, diff, logs, or release goal.

git status --short
git rev-parse --show-toplevel
rg -n "requirement|acceptance|scope|non-goal|TODO|FIXME|migration|release|rollback|flag" .

Frame format:

Objective:
In scope:
Non-goals:
Constraints:
Known unknowns:

If fails:

• Objective or scope is unclear -> use requirements-clarifier.
• Scope covers unrelated systems -> split into separate plans.
• One-step edit -> produce a short checklist, not a phased plan.

Step 2: Inventory Evidence and Work Surface

Expected Output: artifacts=<paths>, work_surface=<files|systems>, dependencies=<internal|external>, test_surfaces=<commands|manual>

Plan from evidence. Identify what exists, what changes, what depends on it, and how success is observed.

git diff --name-status
git diff --stat
rg --files
rg -n "describe\\(|it\\(|test\\(|pytest|playwright|cypress|go test|cargo test|health|metric|alert" .

Evidence table:

| Area | Evidence | Plan impact |
|------|----------|-------------|
| <module/system> | <file/log/doc> | <task/risk/gate> |

If fails:

• No evidence -> add a discovery phase with explicit output.
• Too much surface -> narrow to affected paths, APIs, data, and tests.
• Test surface is missing -> plan verification before implementation.

Step 3: Classify Plan Shape and Risk

Expected Output: plan_type=<implementation|migration|refactor|release|investigation|roadmap>, risk=<low|medium|high>, mode=<checklist|phased|discovery>

Choose the smallest plan shape that controls risk.

Risk scale:

If fails:

• Risk is high and rollback is unknown -> add discovery and rollback design first.
• Plan type is mixed -> split by independent outcomes.
• Security boundary appears -> load agent-security-guard.

Step 4: Decompose into Phases with Entry and Exit Criteria

Expected Output: phases=<ordered table>, entry=<criteria>, exit=<criteria>, gate=<verification>

A phase is not a topic. It needs a start reason and done proof.

| Phase | Goal | Entry criteria | Work | Exit criteria | Gate |
|-------|------|----------------|------|---------------|------|
| 0 Discovery | <unknown resolved> | <needed context> | <reads/probes/spike> | <decision/evidence> | <review/check> |
| 1 Build | <behavior> | <contract ready> | <tasks> | <tests pass> | <command> |

Rules:

• Use discovery phase for unknowns that would change architecture or scope.
• Put irreversible work after a checkpoint.
• Keep each phase shippable, reversible, or marked not shippable.
• Do not mix unrelated outcomes in one phase.

If fails:

• Phase has no exit criteria -> add status, test, artifact, decision, or visible proof.
• Phase depends on a later phase -> reorder or split.
• Exit criteria require unavailable signals -> use observability-workflow.

Step 5: Map Dependencies, Risks, Gates, and Rollback

Expected Output: risk_table=<risk/mitigation/gate>, validation=<commands>, rollback=<points>

Every risky plan needs proof and an undo/stop path.

| Risk | Trigger | Mitigation | Gate | Rollback |
|------|---------|------------|------|----------|
| <risk> | <when it appears> | <prevention> | <proof> | <undo/stop> |

Check: data loss, schema drift, auth/tenant leak, secrets, shell/destructive command, downtime, performance, compatibility, flaky tests, external service, migration order, manual steps, stale assumptions.

Validation gates must name exact evidence:

Gate: `python -m pytest tests/path -q` -> selected tests pass.
Gate: staging health check returns 200 for `/health`.
Gate: migration dry run reports `0 destructive changes`.

If fails:

• Risk lacks mitigation -> add task or reduce scope.
• Gate says "verify manually" -> specify what to click, inspect, or observe.
• Rollback impossible -> mark high risk and require approval before execution.

Step 6: Define Concrete Tasks and Sequencing

Expected Output: tasks=<ordered checklist>, parallel=<yes|no>, commands=<with expected output>, owner=<agent|user|external>

Tasks are execution units. They must name files, action, expected result, and verification.

Task format:

- [ ] P1.T1 <imperative task title>
  - Files: <exact paths or "discover in P0.T1">
  - Do: <specific change or investigation>
  - Verify: `<command>` -> <expected output>
  - Depends on: <task id|none>

Sequencing rules:

• Write or identify tests before implementation when behavior changes.
• For migrations, stage expand -> backfill -> switch -> contract unless local pattern differs.
• Group tasks by dependency, not by file type.
• Mark parallel lanes only when they share no write targets or ordering dependency.

If fails:

• Task says "handle edge cases" or "add tests" -> replace with exact cases or test files.
• File path is unknown -> make discovery a task, not a guess.
• Two tasks can conflict on the same file -> sequence them or merge them.

Step 7: Review the Plan Before Execution

Expected Output: review=<pass|revise|blocked>, gaps=<list>, confidence=<low|medium|high>

Run self-review before claiming readiness.

Review checks:

• Coverage: every requirement maps to a phase/task/gate.
• Placeholder scan: no TBD, TODO, "later", "appropriate", "etc.", "similar to".
• Consistency: task names, paths, APIs, and types agree across phases.
• Tests: success, failure, boundary, regression, and security cases exist when relevant.
• Risk: high-risk actions have rollback and gate.
• Staleness: plan matches current branch, diff, and artifact state.

rg -n "TBD|TODO|later|appropriate|etc\\.|similar to|handle edge|add tests" .
git status --short

If fails:

• Missing coverage -> add or revise tasks.
• Placeholder remains -> replace with exact action, file, command, or decision.
• Confidence is low on high-risk work -> use cross-model-verification.

Step 8: Handoff Execution and Update Loop

Expected Output: ready=<yes|with-assumptions|blocked>, next_action=<task id>, update_rule=<when plan changes>, residual=<risks>

End with an executable, updateable plan.

Objective:
Scope/non-goals:
Assumptions:
Phases:
Tasks:
Gates:
Rollback:
Open decisions:
Next action:
Status: ready=<yes|with-assumptions|blocked>

Update rule:

After each gate, update: completed, evidence, changed assumptions, new risks, next action.
If a gate fails, stop execution and revise the plan before continuing.

If fails:

• Next action is vague -> pick the first task id and exact command/action.
• ready=yes has open blockers -> change to ready=blocked.
• Work is ready for code changes -> use git-workflow-for-agents.

Bad/Good Planning Patterns

Pattern 1: Milestone Without Exit Criteria

Bad:

Phase 1: Build backend.

Good:

Phase 1 exits when `POST /reports` returns 201, persists one row, and `pytest tests/reports -q` passes.

Pattern 2: Risk Without Rollback

Bad:

Run migration in production after tests pass.

Good:

Run dry-run, snapshot tables, deploy expand-only schema, verify old/new callers, then switch reads.

Pattern 3: Task Without Verification

Bad:

- [ ] Add validation and update UI.

Good:

- [ ] P2.T3 Add duplicate-name validation in `src/forms/project.ts`.
  - Verify: `npm test -- project-form.test.ts` -> duplicate name shows field error and submit is blocked.

Rationalization Table

Red Flags

• You are planning before objective, scope, and non-goals are explicit.
• A phase has no entry criteria, exit criteria, or validation gate.
• A task lacks exact files, action, verification, or dependency.
• Plan contains TBD, TODO, "later", "appropriate", "etc.", or "similar".
• High-risk work has no rollback point.
• Migration work lacks expand/backfill/switch/contract thinking.
• Tests are deferred until after implementation without reason.
• Manual verification lacks specific observable steps.
• Plan says ready while blockers or unresolved decisions remain.

Common Pitfalls

Verification Checklist

• Description triggers on project, roadmap, migration, refactor, release, investigation, multi-step implementation, and risky change planning.
• Objective, scope, non-goals, constraints, and unknowns are explicit.
• Evidence and work surface are inspected before sequencing.
• Plan shape and risk level are named.
• Phases have entry criteria, exit criteria, dependencies, and gates.
• Risks include mitigation, validation, and rollback.
• Tasks include exact files or discovery tasks, action, verification, and dependencies.
• Commands include expected output or manual checks name evidence.
• Placeholder scan and coverage review are complete.
• Handoff includes ready=yes, ready=with-assumptions, or ready=blocked and a concrete next action.

Interaction with Other Skills