sdd-derive

SDD Derive

Orchestrate spec generation from existing code: a change directory (new or modified behavior) or baseline specs (retroactive documentation).

The orchestrator holds context across phases; subagents are dispatched for scoped work that benefits from context isolation.

SPECS_ROOT is resolved by the sdd router before this skill runs. Replace .specs/ with the project's actual specs root.

Writing Style

Write the derived specs in the voice of a professional technical writer. Prefer ASD-STE100 Simplified Technical English: short sentences, one instruction per sentence, active voice, and one term per concept. Keep identifiers, commands, paths, and RFC 2119 keywords exact.

When to Use

• Deriving specs from existing code ("derive SDD specs for the auth flow")
• Documenting implemented behavior retroactively into baseline specs
• Producing a change directory for behavior already implemented
• User phrases: "derive specs", "generate specs from code", "retrofit specs", "document this code in SDD"

When Not to Use

• Translating specs from another tool or format — use sdd-translate
• No codebase and no existing behavior to anchor against — use sdd-propose
• Exploring a problem before deciding what to spec — use sdd-explore

Invocation Notice

• Tell the user when this skill is running: sdd-derive. Skip the notice when the user asked for the skill by name or slash command; spelling and spacing need not match. A phrase from this skill's own trigger list is not a name — naming the work is not naming the skill.

Determine Output Type

Baseline specs (.specs/specs/) document implemented behavior. Write baseline specs only when existing code anchors them; otherwise generate a change directory.

digraph output_type {
    ".specs/specs/ exists?" [shape=diamond];
    "Codebase has relevant\nimplementation?\n(answered by Phase 2 discovery)" [shape=diamond];
    "New or existing behavior?" [shape=diamond];
    "Generate change directory\n(.specs/changes/<name>/)\nADDED-only delta specs" [shape=box];
    "Generate change directory\n(.specs/changes/<name>/)" [shape=box];
    "Generate baseline specs\n(.specs/specs/)" [shape=box];

    ".specs/specs/ exists?" -> "Codebase has relevant\nimplementation?\n(answered by Phase 2 discovery)" [label="no"];
    "Codebase has relevant\nimplementation?\n(answered by Phase 2 discovery)" -> "Generate baseline specs\n(.specs/specs/)" [label="yes — retroactive doc"];
    "Codebase has relevant\nimplementation?\n(answered by Phase 2 discovery)" -> "Generate change directory\n(.specs/changes/<name>/)\nADDED-only delta specs" [label="no — greenfield"];
    ".specs/specs/ exists?" -> "New or existing behavior?" [label="yes"];
    "New or existing behavior?" -> "Generate change directory\n(.specs/changes/<name>/)" [label="new or modified"];
    "New or existing behavior?" -> "Generate baseline specs\n(.specs/specs/)" [label="retroactive doc"];
}