external-spec-integration

External Spec Integration Skill

Processes external specification files into the SDD workflow structure. Transforms product specs into classified tech spec context - specs are created interactively one at a time.

Purpose

When a user provides an external specification via /sdd I want to import an external spec:

• Archive the external spec to sdd/archive/external-specs/ (single copy, yyyymmdd-HHmm-filename format)
• TRANSFORM the spec: classify information, identify gaps, ask clarifying questions
• DISCOVER required components through targeted questions
• DECOMPOSE into workflow items with classified context
• Create workflow items with context in sdd/workflows/<id>-<name>/
• DO NOT create SPEC.md or PLAN.md files - those are created interactively

CRITICAL: External specs are product specs (WHAT/WHY). This skill transforms them into tech spec context (HOW) before decomposition.

Key Insight: External Specs Are Inherently Incomplete

Always assume external specs are lacking:

• Details not thought through by product people
• Technical implications not considered by non-engineers
• Missing edge cases, error handling, and non-functional requirements
• Implicit assumptions never made explicit

Critical asymmetry: | Area | Typical Detail Level | Action Required | |------|---------------------|-----------------| | User-Facing Interface | High | Extract and classify | | UX/Design | High | Extract and classify | | Integration Contracts | Low | Must be DERIVED from interface | | Business Logic | Very Low | Must be extracted through questions | | Persistence/Data | Very Low | Must be discovered from interface + actions | | Non-Functional | Absent | Must be explicitly asked |

When to Use

• During /sdd I want to import an external spec when external spec is provided

Input

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

Accepts path to external spec file, target directory, workflow ID, and optional domain.

Output

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

Returns archived spec path, workflow ID, hierarchical flag, and list of created workflow items.

Workflow Overview

1. Archive external spec to sdd/archive/external-specs/ via system CLI
2. Detect large specs (>15K tokens) and chunk if needed
3. Transform product spec: classify information, identify gaps, ask clarifying questions
4. Discover components via component-discovery skill (once for entire spec)
5. Present outline to user with hierarchical decomposition if applicable
6. Thinking step — domain analysis, specs impact, gap analysis, API-first ordering
7. Display thinking output for user review
8. Create workflow items via workflow-state skill
9. Create context files (context.md) for each leaf item
10. Return summary with transformation, components, items, and thinking output

Resource Files

For detailed guidance, read these on-demand:

• [workflow-steps.md](resources/workflow-steps.md) — Detailed steps 1-10 with YAML examples
• [transformation.md](resources/transformation.md) — Classification, gap analysis, clarification process

Key Differences from Previous Version

| Before | After | |--------|-------| | Created SPEC.md + PLAN.md immediately | Creates workflow items with context only | | Archived to archive/ | Archives to sdd/archive/external-specs/ | | No domain analysis | Comprehensive thinking step with domain extraction | | No transformation | NEW: Transformation classifies and identifies gaps | | No component discovery | NEW: Component discovery before decomposition | | Order in session only | Order persisted in workflow.yaml | | All specs created upfront | Specs created one at a time through solicitation | | Modal dialogs for questions | NEW: Non-blocking conversational questions |

Dependencies

This skill orchestrates:

• workflow-state - Creates workflow and items
• component-discovery - Identifies needed components (NEW)
• spec-decomposition - Analyzes spec structure with thinking step

Trigger: /sdd I want to import an external spec command.

Workflow Steps Summary

| Step | Action | Output | |------|--------|--------| | 1 | Archive External Spec | sdd/archive/external-specs/... | | 2 | Detect Large Specs | Size estimation, chunking plan | | 3 | Transformation | Classification, gaps, clarifications | | 4 | Component Discovery | Components list (not applied) | | 5 | Present Outline | User reviews structure | | 6 | Thinking Step | Domain analysis, dependencies | | 7 | Display Thinking | User confirms analysis | | 8 | Create Workflow Items | Items in workflow.yaml | | 9 | Create Context Files | context.md for each item | | 10 | Return Summary | Complete output |

Notes

• External specs are product specs - they are transformed, not copied
• Transformation happens BEFORE decomposition
• Component discovery runs ONCE for entire spec (not per-item)
• Questions are non-blocking and conversational (no modal dialogs)
• All Q&A is preserved and flows into SPEC.md Requirements Discovery section
• Context files contain classified content for use during solicitation
• Items are processed one at a time - user reviews each spec before moving to next
• Hierarchical decomposition is mandatory for specs meeting criteria (2+ H1 with H2+)
• Numbers indicate implementation order based on API-first dependency sort
• Large specs (>15K tokens) use chunked processing with per-section progress