plan · git:20260519.a169a22 · 2026-05-19 · sha256 5f11353ee5037376
plan git:20260519.a169a22A
Immutable. This exact content is served forever at /api/v1/blob/5f11353ee5037376.
--- name: plan <<<<<<< HEAD description: "Primary router for planning, architecture, and track management workflows. Analyzes user intent and dispatches to new-track, decompose, adr, tech-debt, change (and related). Use for starting features, breaking down work, recording decisions, managing debt, or handling scope changes." --- # Plan - Planning & Architecture Router `/draft:plan` is the consolidated entry point for all planning and upfront architecture work in the Context-Driven Development lifecycle. ## When to Use - Starting a new feature, bug fix, or refactor track - Decomposing large modules or changes into dependency-aware units - Recording Architecture Decision Records (ADRs) - Cataloging and prioritizing technical debt - Handling mid-track requirement or scope changes ## Routing Logic The router parses intent from natural language and dispatches to the correct leaf skill. Ambiguous requests surface a short menu of options. | User Intent Keywords | Dispatches To | Purpose | |---------------------------------------|-----------------------|---------| | new feature, new track, start X, add Y, plan a refactor, fix the Z bug | `/draft:new-track` | Collaborative spec + plan creation for track | | decompose, break into modules, dependency map | `/draft:decompose` | Module decomposition + graph | | adr, architecture decision, record decision, design decision | `/draft:adr` | ADR authoring and evaluation | | tech debt, technical debt, catalog debt, debt analysis | `/draft:tech-debt` | 6-dimension debt scan + prioritization | | change, scope changed, requirements changed, update spec, mid-track pivot | `/draft:change` | Structured change impact & plan update | ## Dispatch Examples User: "start a new feature for user profile editing" → dispatches to `/draft:new-track "user profile editing"` User: "decompose the payment module" → dispatches to `/draft:decompose "payment module"` User: "document our decision to use event sourcing" → dispatches to `/draft:adr "Use event sourcing for order processing"` User: "find and prioritize our technical debt" → dispatches to `/draft:tech-debt` User: "the requirements changed, we need to support multi-tenancy now" → dispatches to `/draft:change "add multi-tenancy support"` ## Relationship to Primary Workflow `/draft:plan` augments but does not replace the core `/draft:new-track` and `/draft:implement` flow. Many planning activities are launched via `/draft:plan` for discoverability, then flow into the primary track lifecycle. Direct leaf commands remain available during the transition period (see MIGRATION). ## Quality Gate All planning dispatches should result in updated `draft/tracks/<id>/spec.md` or `plan.md` (or new ADR/debt artifacts) with proper metadata headers and citations back to product/tech-stack context. ======= description: "Canonical planning entry point. Routes high-level planning intent to new-track, decompose, change, or adr, and provides a planning checkpoint when the next planning step depends on track state. Use when the user says 'plan this', 'scope this work', 'start a feature', 'continue planning', or wants one command to handle planning and design flow." --- # Plan Work `/draft:plan` is the **parent planning command**. It exists to remove planning command soup from the developer experience. Do not treat this command as a static menu. It must either: - route to the correct planning workflow, or - produce a useful planning checkpoint that tells the developer the next best planning action Specialist planning skills remain available: - `/draft:new-track` - `/draft:decompose` - `/draft:change` - `/draft:adr` But `/draft:plan` is now the canonical entry point for planning intent. ## Red Flags - STOP if you're: - dumping a list of planning commands instead of routing - creating a new track without reading existing Draft context - mutating a track plan without first checking whether the request is actually a requirement change - sending the user to `/draft:decompose` or `/draft:adr` without explaining why - overriding explicit user intent for a named planning mode **Route first. Explain why. Then execute the chosen planning workflow.** --- ## Parent Contract `/draft:plan` owns four planning jobs: 1. **Create work** → `/draft:new-track` 2. **Break work into modules and architecture** → `/draft:decompose` 3. **Amend planned work safely** → `/draft:change` 4. **Capture a durable technical decision** → `/draft:adr` The parent command should absorb the choice burden whenever the intent is obvious. --- ## Step 1: Parse Intent Inspect `$ARGUMENTS` and classify the request into one of these buckets. ### Explicit Named Modes If the command already names a specialist mode, route directly: - `new-track` - `decompose` - `change` - `adr` Examples: - `/draft:plan new-track add user auth` - `/draft:plan decompose` - `/draft:plan change support JSON export` - `/draft:plan adr choose outbox pattern` ### High-Signal Natural Language Route by intent when the user did not name the specialist command explicitly. | Intent Pattern | Route To | |---|---| | "start a feature", "plan this feature", "scope this work", "I want to build X", "fix Y bug", "create a track" | `/draft:new-track` | | "break into modules", "architecture this", "decompose", "design boundaries", "need HLD/LLD" | `/draft:decompose` | | "requirements changed", "scope changed", "update the plan", "we also need X", "adjust the spec" | `/draft:change` | | "document decision", "write an ADR", "record the tradeoff", "capture this architecture decision" | `/draft:adr` | ### Bare `/draft:plan` If there are no meaningful arguments, do not fall back to a command list. Instead, inspect Draft state and determine the next planning action. --- ## Step 2: Verify Draft Context Run this check first: ```bash ls draft/tracks.md 2>/dev/null ``` If `draft/` does not exist: - If the user is trying to create new planned work, stop and say: `No Draft context found. Run /draft:init first.` - Do not continue into planning without initialized context. --- ## Step 3: Inspect Current Planning State For bare `/draft:plan`, or when intent is ambiguous, inspect current project state before routing. ### 3.1 Active Track Detection Read `draft/tracks.md`. Find: - first `[~]` In Progress track - otherwise first `[ ]` Pending track If no track exists: - default to `/draft:new-track` Announce: ```text Planning mode selected: new-track Reason: no active Draft track exists yet. ``` Then follow the `/draft:new-track` workflow. ### 3.2 Track Artifact Inspection For the active track, inspect: - `draft/tracks/<id>/spec.md` - `draft/tracks/<id>/plan.md` - `draft/tracks/<id>/hld.md` if present - `draft/tracks/<id>/lld.md` if present - `draft/tracks/<id>/metadata.json` if present Extract: - track name and status - whether architecture artifacts already exist - whether the plan appears structurally complex - whether there are recent planning amendments or unresolved scope drift ### 3.3 Complexity Signals Treat these as signals that `/draft:decompose` is likely the next best planning step: - plan spans multiple phases or modules - spec mentions migrations, concurrency, background jobs, external systems, or multi-service boundaries - work touches auth, payments, persistence, or public APIs - user explicitly asks for module boundaries, interfaces, implementation order, HLD, or LLD - `hld.md` is absent for clearly non-trivial work ### 3.4 Change Signals Treat these as signals that `/draft:change` is likely the next step: - user asks to revise scope of an existing active track - user adds or removes acceptance criteria after planning already exists - completed or in-progress work may be invalidated by a new requirement ### 3.5 ADR Signals Treat these as signals that `/draft:adr` is likely the next step: - a durable architecture decision is being proposed - multiple viable options exist and the tradeoff matters long-term - the team wants the rationale preserved independently of the track --- ## Step 4: Route Deterministically Apply these routing rules in order. ### Rule 1: Explicit Mode Wins If the user invoked: - `/draft:plan new-track` - `/draft:plan decompose` - `/draft:plan change` - `/draft:plan adr` route directly and follow that specialist workflow. ### Rule 2: Requirement Drift Beats Architecture Work If an active track exists and the request changes already-planned work, prefer `/draft:change` before `/draft:decompose` or `/draft:adr`. Reason: - spec/plan truth must be corrected before deeper design artifacts are regenerated ### Rule 3: Architecture Work Beats New Feature Intake If a track already exists and complexity signals show the next planning bottleneck is structure, route to `/draft:decompose`. ### Rule 4: Decision Capture Is Explicit or Triggered by a Confirmed Tradeoff Route to `/draft:adr` when: - the user asked for an ADR, or - planning analysis exposes a material architectural fork that should be recorded ### Rule 5: Otherwise Default to New Track Intake If no stronger signal exists, route to `/draft:new-track`. This is the default parent behavior for feature, bugfix, and refactor planning requests. --- ## Step 5: Announce the Selected Planning Mode Before executing the chosen workflow, tell the user what `/draft:plan` decided. Use this format: ```text Planning mode selected: <mode> Reason: <short reason grounded in track state or user intent> ``` Examples: ```text Planning mode selected: new-track Reason: this is a fresh feature request and no active matching track exists. ``` ```text Planning mode selected: change Reason: an active track already exists and the request alters approved scope. ``` ```text Planning mode selected: decompose Reason: the track is multi-phase, crosses service boundaries, and has no HLD yet. ``` --- ## Step 6: Execute the Specialist Workflow After routing, fully follow the corresponding specialist skill as the canonical implementation: - `/draft:new-track` for intake, spec, plan, and metadata creation - `/draft:decompose` for architecture/module decomposition - `/draft:change` for scoped amendments to an existing track - `/draft:adr` for decision records Do not partially imitate those commands. Route, announce, then execute their workflow. --- ## Bare `/draft:plan` Fallback Output If `/draft:plan` is bare and the next planning step is genuinely ambiguous even after inspecting context, produce a short planning checkpoint instead of a command list. Format: ```text Planning checkpoint: <track_id> - <track_name> - Current state: <one-line summary> - Next recommended planning action: <new-track|decompose|change|adr> - Why: <short reason> ``` Then proceed with the recommended action unless the user objects. The parent command should still move planning forward. --- ## Examples ### Example 1: Fresh feature request Input: ```text /draft:plan add user authentication ``` Route: - `/draft:new-track` ### Example 2: Existing track got new scope Input: ```text /draft:plan we also need JSON export ``` Context: - active track already exists for CSV export Route: - `/draft:change` ### Example 3: Complex track needs structure Input: ```text /draft:plan ``` Context: - active track exists - plan spans multiple modules - no `hld.md` Route: - `/draft:decompose` ### Example 4: Decision needs durable record Input: ```text /draft:plan should we use the outbox pattern here? ``` If the tradeoff is real and decision-worthy: - `/draft:adr` Otherwise: - discuss briefly during planning, then continue with the best planning workflow --- ## Compatibility Notes The following specialist commands remain valid and should continue to work: - `/draft:new-track` - `/draft:decompose` - `/draft:change` - `/draft:adr` `/draft:plan` is the canonical parent. When helpful, reinforce the canonical form in output: ```text `/draft:new-track` remains supported. Canonical parent: `/draft:plan new-track`. ``` >>>>>>> a79c14023e16774c77463870ac3510b728e8a91c