Controlflow Planning

---
name: controlflow-planning
description: "Use when a repository task needs a strict ControlFlow-style implementation plan before coding, especially for small, medium, or large scope, cross-file edits, risky migrations, architectural uncertainty, or any work that should produce a saved Markdown plan artifact in plans/."
---

# ControlFlow Planning

## Overview

Create a durable, execution-ready plan. Keep the contract local: the saved artifact defines
scope, risks, files, phases, validation, review route, and handoff without depending on
VS Code agent mode or plugin-host-specific runtime contracts.

Invoke this skill via `/controlflow-claude-code:controlflow-planning`.

## Local Contract

- Read the repository before phase decomposition; keep verified facts separate from
  assumptions.
- Use [references/plan-template.md](references/plan-template.md) as the plan contract,
  not a loose outline.
- Apply [references/llm-behavior-guidelines.md](references/llm-behavior-guidelines.md)
  for generic assumption, simplicity, scope, and verification discipline.
- Keep behavior portable: ask the user directly when a requirement changes scope, or record
  a bounded assumption when it does not.

## Workflow

1. Create a saved plan when the user asks for one or when work is SMALL, MEDIUM, or LARGE;
   skip it only for truly TRIVIAL work.
2. Save to `plans/<task-slug>-plan.md` unless the user names another path.
3. Clarify only when the answer changes file scope, user-visible behavior, architecture,
   or destructive-risk handling.
4. Map likely files, tests, commands, dependencies, and change boundaries before phase
   decomposition.
5. Read [references/complexity-tiers.md](references/complexity-tiers.md) and
   [references/semantic-risk-taxonomy.md](references/semantic-risk-taxonomy.md); assign one
   tier and fill all seven risk categories.
6. Write the artifact using [references/plan-template.md](references/plan-template.md).
7. For non-trivial plans (SMALL, MEDIUM, LARGE), include the five fixed lifecycle sections
   in this exact order with these exact headings:
   `## Progress`, `## Discoveries`, `## Decision Log`, `## Outcomes`,
   `## Idempotence & Recovery`.
   These headings are required by the plugin validator.
8. Use ABSTAIN or REPLAN_REQUIRED when confidence is below 0.9 or evidence is insufficient.
9. Add research or spike phases before implementation when a HIGH-impact risk is unresolved.
10. Keep phases incremental, testable, and explicit about files, dependencies, quality gates,
    and failure expectations.
11. Route non-trivial plans through strict review: SMALL -> plan-audit; MEDIUM/LARGE -> add
    assumption-verifier; unresolved HIGH risk -> include assumption-verifier regardless of
    size.
12. Check [references/controlflow-portability.md](references/controlflow-portability.md)
    before handoff.

## Spec Capture Handoff

When requirements, acceptance criteria, boundaries, or verification gates are not explicit,
use `/controlflow-claude-code:controlflow-spec` first. Carry its `spec_path`, scope,
acceptance criteria, constraints, success metrics, and open risks into the plan. If spec
capture is unnecessary, state why the request is already clear enough.

## Planning-Specific Failure Checks

- Do not plan from chat memory when a spec is required; cite the spec artifact or create one.
- Do not skip semantic risk review because the tier feels low; fill every category.
- Do not decompose phases before reading the repository and mapping likely files/tests.
- Do not mark READY_FOR_EXECUTION without a strict review route and artifact destination.
- Generic anti-rationalization rules live in
  [references/llm-behavior-guidelines.md](references/llm-behavior-guidelines.md).

## Mandatory Output Contract

- Prefer structured text over raw JSON.
- Default plan file path: `plans/<task-slug>-plan.md`.
- Use the ControlFlow-style header and section order from
  [references/plan-template.md](references/plan-template.md).
- Write `Agent: Planner` in the artifact so the document matches the original conceptual
  role even though the implementation is a skill.
- Record assumptions separately from verified facts.
- For READY_FOR_EXECUTION plans, include a clear handoff section that points execution to
  orchestration.

## References

- `references/plan-template.md`
- `references/complexity-tiers.md`
- `references/semantic-risk-taxonomy.md`
- `references/controlflow-portability.md`
- `references/planner-output-contract.md`
- `references/llm-behavior-guidelines.md`