Sdd translate

SDD Translate

Convert existing specifications from other frameworks, tools, or formats into SDD spec files.

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

Invocation Notice

• Inform the user when this skill is being invoked by name: sdd-translate.

When to Use

• Migrating from Spec Kit, Kiro, ADRs, Jira, Confluence, or similar
• Converting structured requirements documents into SDD format
• Reverse-engineering third-party spec output into SDD specs

When Not to Use

• No existing specs to translate — use sdd-derive instead
• Already in SDD format — run sdd-verify to check completeness

Determine Output Type

Baseline specs (.specs/specs/) document implemented behavior. Translated specs should only go to baseline when the codebase already implements the described behavior.

digraph output_type {
    "Codebase implements\nthe described behavior?" [shape=diamond];
    "Translate to baseline specs\n(.specs/specs/)" [shape=box];
    "Translate to change directory\n(.specs/changes/<name>/)\nADDED-only delta specs" [shape=box];

    "Codebase implements\nthe described behavior?" -> "Translate to baseline specs\n(.specs/specs/)" [label="yes — documenting what exists"];
    "Codebase implements\nthe described behavior?" -> "Translate to change directory\n(.specs/changes/<name>/)\nADDED-only delta specs" [label="no — greenfield or aspirational"];
}

How to check: After inventorying source specs (Phase 1), survey the codebase for relevant implementation. If the capabilities described in the source specs have no corresponding code, the translated specs are aspirational — generate a change directory with ADDED-only delta specs, a proposal.md, and optionally a tasks.md. If the codebase already implements the described behavior, translate directly to baseline.

Process

Phase 1: Inventory Source Specs

1. Identify source format and structure:

   • Spec Kit → spec.md + plan.md with Markdown headings
   • Kiro → steering docs + requirements files
   • ADRs → architecture decision records (context/decision/consequences)
   • Jira/Linear → issue descriptions + acceptance criteria
   • Prose documents → natural language requirements

2. Read all source files before generating anything.

3. Group into capabilities — logical groupings that will each become one .specs/specs/<capability>/spec.md:

   • By feature area: auth/, payments/, notifications/
   • By component: api/, frontend/, workers/
   • By bounded context: ordering/, fulfillment/

Phase 2: Assess Scope and Plan Decomposition

Before generating specs, count requirements across all source material:

Signal	Action
≤ 8 requirements total	Single capability, proceed directly
9–20 requirements	Split into 2–4 capabilities, proceed
20+ requirements	Present capability split to user, wait for confirmation

When decomposing, present the proposed split:

Proposed capabilities:
- auth/      → login, session, token management (5 reqs)
- payments/  → billing, subscriptions (6 reqs)
- ui/        → themes, layout (4 reqs)

Proceed with this split? (or suggest changes)

When the output type is a change directory (greenfield or aspirational — see Determine Output Type above), present capabilities in build-dependency order rather than alphabetically; the implementer will work through them in the order shown. See references/sdd-change-formats.md § 4. For baseline output (code already exists), ordering is a presentation choice — alphabetical is fine.

Phase 3: Translate Each Capability

Output path depends on the output type decision above:

• Baseline (code exists): produce .specs/specs/<capability>/spec.md following SDD baseline format.

• Change directory (greenfield/aspirational): create .specs/changes/<name>/ with:

  • proposal.md — intent, user stories, scope, approach (see references/sdd-change-formats.md § 1.1)
  • specs/<capability>/spec.md — ADDED-only delta specs, each requirement carrying a Serves: backlink to a proposal story
  • tasks.md — when implementation steps are clear (optional)

Also seed .specs/NORTH-STAR.md if absent — draft a candidate product north star from the source specs for the user to ratify; each user story ladders to it. When the source uses user-story grammar ("As a … I want … so that …"), the story belongs in proposal.md § User Stories (keep the "so that {value}" clause); translate only the WHAT into the requirement and point its Serves: line back at the story.

Preserve the Phase 2 build-dependency order in proposal.md Scope and tasks.md when present. If implementation steps are unclear and tasks.md is omitted, mention any ordering assumptions in the output summary.

See references/sdd-spec-formats.md for both baseline and delta spec formats.

Add a source attribution blockquote at the top of each generated spec (see format reference Section 2):

Translated from {source tool/format} on {date} Source: {source file or description}

Read references/sdd-spec-formats.md § 1 before translating. The translation is from the source doc's grammar into SDD contract statements (see § 1.1 contract shapes). Source docs from other tools (Spec Kit, Jira, ADRs, prose) commonly mix WHAT and HOW in the same sentence; translate only the contract, and route mechanism detail to design.md or discard it.

When the translated requirement is a universal SHALL, apply the partition heuristic in references/sdd-spec-formats.md § 1.6 to the source's acceptance criteria. Source docs frequently capture only the happy-path acceptance criterion; if the heuristic flags a partition the source did not cover, surface the gap as an Uncertainty rather than fabricating scenarios.

Translation rules:

Source pattern	SDD translation
"Users can X"	The system SHALL allow users to X
Acceptance criteria bullets	#### Scenario: entries with GIVEN/WHEN/THEN (as evidence of the requirement — see § 1.5)
"It should Y"	The system SHOULD Y
"Required: Z"	The system MUST Z
Implementation detail (class names, libraries)	Move to ## Technical Notes (baseline) or design.md (change directory); omit from the requirement
Named algorithm / threshold / strategy (e.g., "use TF-IDF bottom quartile", "retry 3 times")	Translate to the property it produces (e.g., "queries that produce no relevant documents"); route the named strategy to design.md
Phase-gated steps (plan.md, tasks.md)	Omit — not behavior
"As a user, I want X so that Y"	Baseline: The system SHALL allow users to X (value layer dropped — baseline is value-free). Change directory: capture the story incl. "so that Y" in proposal.md § User Stories and add a Serves: backlink on the requirement
"Shall not / Must not"	The system SHALL NOT / MUST NOT {prohibited behavior}
Numbered requirement IDs (e.g., REQ-001:)	Strip the ID prefix; preserve the requirement text

Critical rules:

• Every translated requirement is a contract statement in one of the shapes from references/sdd-spec-formats.md § 1.1 (guarantee, invariant, prohibition, precondition-consequence, observable-state relationship)
• Every scenario must have GIVEN, WHEN, THEN (bold labels, exact casing)
• Scenarios use #### (4 hashtags), requirements use ### (3 hashtags)
• Baseline output: no delta markers (ADDED/MODIFIED/REMOVED)
• Change directory output: use ADDED sections only (all behavior is new); no ## Purpose or ## Technical Notes
• Change directory value layer: author ## User Stories in proposal.md (keep each "so that {value}" clause) and add a Serves: backlink to each delta requirement; seed .specs/NORTH-STAR.md if absent. Baseline output is value-free — no stories or backlinks.

Phase 4: Validate Output

Common to both output types:

• Every ### Requirement: uses RFC 2119 keywords (SHALL/MUST/SHOULD/MAY)
• Every scenario uses GIVEN/WHEN/THEN with bold labels
• Each requirement is a contract statement in one of the shapes from references/sdd-spec-formats.md § 1.1 — a property about observable state that stands on its own without its scenarios
• Universal SHALL claims have partition coverage per the heuristic in references/sdd-spec-formats.md § 1.6 — when a positive signal fires, scenarios cover each partition (or the gap is recorded as an Uncertainty)
• Scenarios use #### heading level (not ### or #####)
• Implementation details and named strategies from source were routed to ## Technical Notes (baseline) or design.md (change directory), not left in the requirement text

Baseline output only:

• ## Purpose section present in each spec
• No delta markers (ADDED/MODIFIED/REMOVED)

Change directory output only:

• All specs use ADDED sections only (delta format)
• proposal.md exists with Intent, User Stories, Scope, Approach
• Each user story keeps its "so that {value}" clause and ladders to NORTH-STAR.md
• Each delta requirement carries a Serves: backlink to a proposal story
• proposal.md Scope and tasks.md preserve build-dependency order when the translation produced implementer-facing change artifacts
• No ## Purpose or ## Technical Notes in delta specs

Phase 5: Schema Snapshot (if schemas configured)

If .specs/.sdd/schema-config.yaml exists:

1. Generate schema snapshots using the configured extraction commands.
2. Store in .specs/schemas/ — this establishes the baseline for all future sdd-verify conformance checks.
3. Update .specs/schemas/.schema-sources.yaml with the generation date.

If no schema config exists but schema artifacts are detected in the repo (e.g., openapi.yaml, .proto files, schema.graphql), suggest creating .specs/.sdd/schema-config.yaml before the first sdd-verify run:

"Detected schema artifacts. A .specs/.sdd/schema-config.yaml would let sdd-verify cross-validate implementation against these specs. See references/sdd-schema.md § 3 for the format. Say 'skip' to dismiss."

If no schema config and no artifacts detected, skip silently.

Output

Baseline (code exists):

• .specs/specs/<capability>/spec.md per capability

Change directory (greenfield/aspirational):

• .specs/changes/<name>/proposal.md
• .specs/changes/<name>/specs/<capability>/spec.md (ADDED-only delta format)
• .specs/changes/<name>/tasks.md (when applicable)

Summary: capabilities created, requirement count per capability, translation notes and assumptions.

Common Mistakes

• Translating source-doc grammar without translating the content — a Jira ticket saying "POST to /users then insert into users table" is mechanism in both the source and a literal translation. Translate to the property the source was trying to guarantee ("a user account is created") and route the mechanism to design.md. See references/sdd-spec-formats.md § 1.
• Using non-RFC-2119 language ("the system will", "users can") instead of SHALL/MUST/SHOULD
• One giant spec instead of capability decomposition for large surface areas
• Including delta markers (ADDED/MODIFIED) in baseline specs
• Not reading all source files before generating output
• Writing baseline specs for a greenfield project — .specs/specs/ asserts implemented behavior; if nothing is built yet, use a change directory with ADDED-only delta specs
• Discarding the "so that {value}" clause when producing a change directory — it should become a proposal user story with the requirement's Serves: backlink; only baseline output (which is value-free) drops the value layer

References

• references/sdd-spec-formats.md — baseline spec and scenario formats
• references/sdd-schema.md — schema config format and lifecycle policy