carloscape/octorato/sdd-plan

SDD: Implementation Planning

You are acting as a senior software engineer creating a precise, actionable implementation plan.

Pre-conditions

Verify both files exist before proceeding:

• feature.md: the feature spec (if missing, tell the user to run /sdd-feature first)
• docs/project.md: project context

Process

0. Refuse an Unready Spec

Run the linter in ready mode on the spec directory:

python3 ~/.claude/scripts/spec_lint.py --ready <spec-directory>

If it exits non-zero, stop. Print the findings (open [NEEDS CLARIFICATION] markers or a malformed criterion) and tell the user to run /sdd-refine. Do not write plan.md. A feature.md without Spec-Format: ears-1 is skipped by the linter; plan it as before.

1. Read Both Files

Read feature.md and docs/project.md in full.

2. Identify the Tech Stack

From docs/project.md, note:

• Primary language and framework
• Build tool and compile/test commands
• Database and data access layer
• Messaging systems
• Testing frameworks
• Any architecture patterns (e.g., Hexagonal, DDD, Layered)

3. Produce plan.md

Create plan.md in the spec directory, next to feature.md, with this structure:

# Implementation Plan: <Feature Name>
 
## Overview
Brief description of the implementation approach.
 
## Architecture Decisions
-Key design choices and their rationale
-Patterns to follow (aligned with docs/project.md)
 
## Implementation Steps
 
Group tasks under headings by layer or phase. Every task is one line in this exact grammar:
 
-[ ] T01 [AC-01] db/migrations/0042_add_table.sql: create the table
-[ ] T02 [AC-02, AC-03] src/service.py, tests/test_service.py: implement and test the use case
 
## Risks & Mitigations
-Risk: ... → Mitigation: ...
 
## Estimated Complexity
Low / Medium / High, with a brief justification

4. Task Grammar Rules

• T## ids are unique and sequential. At most 20 tasks; consolidate if you need more.
• The brackets list every criterion the task serves. Every criterion in feature.md appears

in at least one task, and no task names a criterion that does not exist.

• Paths are separated by a comma and a space; a path itself contains no spaces or commas. They

name the files the task creates or changes.

• There is no separate mapping table: the brackets are the mapping.
• Sections titled ## Convergence <n> are appended later by the converge pass and are not

counted against the cap. Never write one yourself.

5. Lint the Plan

Run python3 ~/.claude/scripts/spec_lint.py <spec-directory> again. It now also checks the plan: grammar, the cap, and coverage in both directions. Fix every finding.

After the linter is clean, present a summary of the plan and ask the user to approve before proceeding to /sdd-implement.