/planning

name: planning
description: Templates and guidance for implementation plans with dynamic phase generation.
user-invocable: false

Planning Skill

Plan Location

Plans are stored alongside their specs:

`changes/YYYY/MM/DD/<id>-<name>/<NN-change-name>/PLAN.md`

This keeps all change documentation (spec + plan) together in one location.

Workflow Integration

Plans are created as part of the `/sdd` workflow:

1. User creates or imports a change via `/sdd I want to create a new feature` 2. Spec solicitation creates SPEC.md 3. User reviews and approves spec via `/sdd I want to approve the spec` 4. **This skill creates PLAN.md** immediately after spec approval 5. User reviews and approves plan via `/sdd I want to approve the plan` 6. Implementation can begin via `/sdd I want to start implementing`

**Plan creation requires an approved SPEC.md** as input — it does not run independently.

Input

Schema: [`schemas/input.schema.json`](./schemas/input.schema.json)

Accepts change ID, path to approved SPEC.md, and workflow ID.

Output

Schema: [`schemas/output.schema.json`](./schemas/output.schema.json)

Returns path to created PLAN.md and review status.

SPEC.md vs PLAN.md Separation

| File | Purpose | Contains | Does NOT Contain | |------|---------|----------|------------------| | **SPEC.md** | What to build and how | Requirements, design, API contracts, implementation details, test cases | Execution order, agent assignments | | **PLAN.md** | Execution coordination | Phases, agent assignments, dependencies, expected files, progress tracking | Implementation details, code patterns, specific coding tasks |

> **Key principle:** Because plans focus on execution coordination (not implementation details), the SPEC.md must be comprehensive enough that an implementer can complete each phase by reading only the spec. Plans reference specs; they don't duplicate them.

Plan Content Guidelines

**Acceptable in plans:**

• Standards references per phase (which standards skills apply to each agent's work)
• Methodology-level task descriptions (e.g., "Implement Model layer" not "Implement domain logic")
• Brief code snippets as constraints or guidelines (e.g., "interface must include X field")
• High-level examples showing intent
• File paths and component names
• Phase sequencing and dependencies
• Extensive test lists (tests define WHAT, not HOW)

**Not appropriate in plans:**

• Full implementations or complete code blocks
• Step-by-step coding instructions
• Line-by-line change lists
• Algorithm implementations (belong in spec)

SPEC.md: Thorough Technical Specification

SPEC.md is a **complete technical specification**. It must be:

• **Self-sufficient**: Anyone reading the spec understands the change fully without other docs
• **Thorough**: Covers all aspects (functional, non-functional, security, errors, observability)
• **Technical**: Includes schemas, algorithms, data models, API contracts
• **Testable**: Every requirement has clear acceptance criteria

Key sections:

• Background and current state (context)
• Functional and non-functional requirements
• Technical design (architecture, data model, algorithms)
• API contracts with request/response schemas
• Security considerations
• Error handling strategy
• Observability (logging, metrics, traces)
• Testing strategy with specific test cases
• Domain updates (glossary, definitions)
• Dependencies and migration plan

Domain Documentation in Specs

Domain documentation is specified **in SPEC.md during planning**, not discovered during implementation.

The SPEC.md file includes a `## Domain Updates` section that explicitly lists:

• **Glossary Terms** - exact terms to add/modify in `specs/domain/glossary.md`
• **Definition Specs** - domain definition files to create/update in `specs/domain/definitions/`
• **Architecture Docs** - updates needed in `specs/architecture/`

Testing Strategy in Specs

The SPEC.md file includes a `## Testing Strategy` section that defines:

• **Unit Tests** - what behaviors need unit tests (implemented via TDD during execution)
• **Integration Tests** - what integrations need testing
• **E2E Tests** - what user flows need end-to-end tests

This approach ensures: 1. All requirements (domain, tests, verification) are fully understood before implementation 2. Implementation simply executes the specified updates (no discovery) 3. Clear traceability from spec to implementation

Dynamic Phase Generation

Plans are generated dynamically based on the SPEC.md's Components section.

Component Source of Truth

**SPEC.md is the source of truth for required components.**

The planning skill: 1. Reads the `## Components` section from SPEC.md 2. May read `sdd/sdd-settings.yaml` for existing component details (delegate to the `project-settings` skill for the settings schema — it returns typed component objects with `name`, `type`, and type-specific `settings` like `server_type`, `databases`, `provides_contracts`) 3. Does NOT ask about tech stack or which components to use

If SPEC.md says a component is needed but it's not in `sdd-settings.yaml` yet, that's expected - the component will be created during implementation.

**DO NOT ask tech stack questions during planning.** Component discovery already determined what's needed.

Generation Algorithm

1. **Read required components** from SPEC.md `## Components` section 2. **Reference existing components** from `sdd/sdd-settings.yaml` for details 3. **Check for new components:** If SPEC.md `## Components` lists new components not yet in `sdd-settings.yaml`, prepend a "Phase 1: Component Scaffolding" phase and shift subsequent phase numbers. If all components already exist, omit the scaffolding phase. This applies to all change types (feature, refactor). 4. **Order by dependency graph:** Invoke `techpacks.dependencyOrder` for the active tech pack namespace to get the topological order of component types. Use this order for phase sequencing. 5. **Assign