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 specwhen external spec is provided
Input
Schema: schemas/input.schema.json
Accepts path to external spec file, target directory, workflow ID, and optional domain.
Output
Schema: schemas/output.schema.json
Returns archived spec path, workflow ID, hierarchical flag, and list of created workflow items.
Workflow Overview
- Archive external spec to
sdd/archive/external-specs/via system CLI - Detect large specs (>15K tokens) and chunk if needed
- Transform product spec: classify information, identify gaps, ask clarifying questions
- Discover components via component-discovery skill (once for entire spec)
- Present outline to user with hierarchical decomposition if applicable
- Thinking step — domain analysis, specs impact, gap analysis, API-first ordering
- Display thinking output for user review
- Create workflow items via workflow-state skill
- Create context files (
context.md) for each leaf item - Return summary with transformation, components, items, and thinking output
Resource Files
For detailed guidance, read these on-demand:
- workflow-steps.md — Detailed steps 1-10 with YAML examples
- 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 itemscomponent-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