/external-spec-integration

name: external-spec-integration
description: Process external specifications through transformation, classification, gap analysis, component discovery, and decomposition. Creates workflow items with classified context.
user-invocable: false

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