Importing Technical Solution

Importing Technical Solution

Overview

Reverse-extracts structured DDD phase artifacts from an existing architecture document, validates coverage, fills gaps via interactive Q&A, and persists artifacts for downstream implementation.

Foundational Principle: Imported artifacts are NOT pre-approved. Each reverse-extracted artifact must pass explicit human approval before persistence. The source document's prior approval is irrelevant — DDD artifacts require separate validation of EXTRACTION accuracy. There is no complexity threshold below which you may skip reverse-extraction.

When to Use

• When user has an existing technical solution (architecture doc, design spec, ADR) and wants to enter the DDD pipeline.
• When a tech solution exists but lacks structured DDD artifacts (domain events, context maps, contracts).
• When onboarding a project with existing architecture decisions into the DDD workflow.
• When reverse-engineering an existing system's design into phase-by-phase DDD documentation.

Do NOT use when: no tech solution exists (use [full-ddd](../full-ddd/SKILL.md) to start from PRD), iterating on an existing DDD-structured project (use [iterating-ddd](../iterating-ddd/SKILL.md)), modifying logic within an established Bounded Context (use [coding-isolated-domains](../coding-isolated-domains/SKILL.md)), adding features to an existing non-DDD codebase (use [piloting-ddd](../piloting-ddd/SKILL.md)), or the task is purely technical with no domain change.

Quick Reference

| Step | Action | Output | Gate | |:---|:---|:---|:---| | 0 | Pre-flight Checks | Input validated + source persisted | — | | 1 | Reverse-Extract Phase 1 | Domain Events Table | Human approval | | 2 | Reverse-Extract Phase 2 (subagent) | Context Map | Autonomous persist (STOP blocks) | | 3 | Reverse-Extract Phase 3 (subagent) | Interface Contracts | Autonomous persist (STOP blocks) | | 4 | Reverse-Extract Phase 4 (subagent) | 7-Dimension Coverage Table → decisions-log.md | Autonomous (STOP blocks) | | 5 | Fill Gaps | Gap decisions recorded | Human approval per gap | | Final Review Gate | Phase 2-3 + assumptions reviewed | Append to decisions-log.md, delete assumptions-draft.md | Human must approve | | 6 | Persist Phase 4 | docs/ddd/phase-4-technical-solution.md | Human approval | | 7 | Handoff | next-steps-checklist.md + next steps to user | — |

Subagent Dispatch I/O

All artifact paths below are relative to docs/ddd/. decisions-log.md and assumptions-draft.md are passed as context to every subagent and omitted from the table for brevity.

| Dispatch Step | Subagent Skill | Input Artifacts | Output Artifacts | |:---|:---|:---|:---| | Step 2 | mapping-bounded-contexts (format ref) | import-source.md, phase-1-domain-events.md | phase-2-context-map.md | | Step 3 | designing-contracts-first (format ref) | import-source.md, phase-2-context-map.md | phase-3-contracts.md | | Step 4 | architecting-technical-solution (format ref) | import-source.md, phase-2-context-map.md, phase-3-contracts.md | Coverage table → appended to decisions-log.md |

Note: Steps 2-4 are autonomous reverse-extraction subagents. Step 1 (Phase 1) is interactive and not dispatched as a subagent. Phase 4 artifact persistence happens at Step 6 after gap-filling and human approval. Downstream skills (Phase 5-7) are invoked by the user after handoff, not by this orchestrator.

Ambiguity Handling

Follow the [Ambiguity Handling Protocol](../ddd-protocol/ambiguity-handling-reference.md) throughout this workflow.

The [Ambiguity Handling Protocol](../ddd-protocol/ambiguity-handling-reference.md) defines two tiers for handling missing information in the source document:

• [STOP: {description}] — The missing information affects event identification, context boundaries, or contracts. Confirm with the developer before proceeding.
• [ASSUMPTION: {description}] — The missing information is low-impact (naming, ordering, non-critical dimension details). Make the most conservative assumption, record it, and continue.

The [ASSUMPTION] marker format:

[ASSUMPTION: {what is missing from source}]
├─ Chosen: {the assumption made}
├─ Alternative: {other reasonable option}
└─ Change cost: LOW | MEDIUM

Append [ASSUMPTION] entries to docs/ddd/assumptions-draft.md immediately as they occur.

Import STOP triggers — confirm immediately:

| Ambiguity | Why STOP | |:----------|:---------| | Missing event or business rule in source (Step 1) | Invented events cascade to wrong context boundaries and contracts | | Context boundary assignment unclear from source (Step 2) | Wrong boundaries = wrong aggregate scope → Phase 3 contracts must redo | | Strategic classification (Core/Supporting/Generic) unclear (Step 2) | Wrong classification = wrong analysis depth → Phase 4 dimensions under-specified | | Contract data shape or communication pattern unclear (Step 3) | Wrong interface shape = wrong port definitions → Phase 5 aggregate design must redo |

Import ASSUME & RECORD — proceed with explicit assumption:

| Ambiguity | Default assumption | |:----------|:------------------| | Event naming wording | Choose most natural past-tense business term | | Field ordering in contracts | Alphabetical; record assumption | | Dimension details below PARTIAL threshold | Choose simpler option; record assumption | | Synonym completeness in ubiquitous language | Record known terms; mark dictionary as potentially incomplete |

Session Recovery

If a session is interrupted, recover by checking artifacts:

1. Run sh skills/full-ddd/scripts/session-recovery.sh for a quick status report.
2. Read docs/ddd/ddd-progress.md. If workflow_mode: import is set, the import was started.
3. Determine resume point by checking which artifacts exist:

• docs/ddd/import-source.md missing → resume from Step 1 (source extraction).
• import-source.md exists but phase-1-domain-events.md missing → resume from Step 2 (mapping to Phase 1).
• phase-1-domain-events.md through phase-4-technical-solution.md exist but incomplete → read decisions-log.md to find last completed step, resume from next step.
• phase-4-technical-solution.md exists and complete → resume from Step 5 (gap-filling Q&A).
• assumptions-draft.md has unresolved [ASSUMPTION] entries → present them to human before proceeding.

1. Mid-step recovery: If decisions-log.md has "Step 4 Coverage Assessment" but Step 5 is incomplete → resume Step 5 from the persisted coverage table.
2. Post-handoff: If next-steps-checklist.md exists → import is complete, proceed with downstream skill (Phase 7).
3. Do NOT re-run completed steps — read their persisted artifacts and continue from the first incomplete step.

Implementation (Interactive Q&A Session)

CRITICAL RULE: Do NOT just generate the final output and stop. You must guide the user through an interactive, step-by-step import process.

CRITICAL RULE: Sub-Skill Loading. Before executing any step that references a sub-skill (linked via [skill-name](path)), you MUST read the sub-skill's SKILL.md file. The sub-skill's rules, rationalization table, and red flags are binding constraints. Two loading modes:

• Steps 2-4 (subagent dispatch): Read the sub-skill to construct the dispatch prompt. The sub-skill content goes into the subagent's context.
• Step 1 (rules reference): Read extracting-domain-events for event extraction rules (naming, identification, completeness). The orchestrator applies these rules while executing Step 1 interactively — it is not a subagent dispatch.

Step 0: Pre-flight Checks

| Check | Action | Failure | |:------|:-------|:--------| | Existing artifacts | Check if docs/ddd/ has existing artifacts. List them. | WARN user: "Existing DDD artifacts found: [list]. Importing will overwrite them. Proceed?" Only continue after explicit confirmation. | | Minimum viable content | Input must contain: ≥1 bounded context or service boundary, ≥2 technology decisions, ≥1 data model reference. | Reject: "Input does not meet minimum viable content. Missing: [list]. Please provide a more complete technical solution document." | | Accept input | User may provide: pasted text (process inline), local file path (read + confirm), or URL (fetch + confirm). | — | | Persist source | Write source to docs/ddd/import-source.md with header: input type, date, original location. | — | | Init progress | Create docs/ddd/ (if not exists). Initialize ddd-progress.md (template: templates/ddd-progress-import.md — already has workflow_mode: import and import-specific fields). Initialize decisions-log.md. | — | | Enforce hooks | Follow the [Hooks Enforcement Protocol](../ddd-protocol/persistence-defense-reference.md#hooks-enforcement-protocol) — detect platform, set up or merge hooks from templates, update the Hooks field in ddd-progress.md. | HARD STOP if setup fails. The Hooks field remaining [pending] is a visible red flag on every tool invocation. |

Step 1: Reverse-Extract Phase 1 (Domain Events)

Read [extracting-domain-events](../extracting-domain-events/SKILL.md) for event extraction rules (naming conventions, identification methods, completeness criteria) and output format. This is a rules reference load, not a subagent dispatch — the orchestrator executes Step 1 interactively using the sub-skill's rules as constraints. Analyze the technical solution for business events, commands, and actors.

• For each extracted item, cite the source paragraph or section where it was found.
• Items NOT found in the source: flag as [STOP: description] if it affects event identification; or [ASSUMPTION: description] if it is low-impact. Do NOT invent events to fill gaps silently.
• Present in the same format as extracting-domain-events output:

| Actor | Command | Domain Event | Business Rules / Invariants | Source Reference | |:------|:--------|:-------------|:---------------------------|:-----------------| | | | | | |

Checkpoint: "Does this events table accurately reflect your technical solution? For each [STOP] item: confirm or clarify. For each [ASSUMPTION] item: confirm the assumption is acceptable or provide a correction."

After approval, persist to docs/ddd/phase-1-domain-events.md using the template from ../full-ddd/templates/phase-1-domain-events.md. Update ddd-progress.md Phase 1 status to complete. Append key decisions to decisions-log.md. This step is mandatory — do not skip even if the table is already visible in the conversation.

Autonomous Steps (2-4): Follow the [Per-Phase Subagent Dispatch Protocol](../ddd-protocol/subagent-dispatch-reference.md) for all subagent dispatch, STOP handling, and post-dispatch verification below. STOP events raised by any subagent block the entire autonomous sequence until the human resolves them.

Step 2: Reverse-Extract Phase 2 (Bounded Contexts) (subagent)

> Before dispatch: Write non-artifact conversation decisions to decisions-log.md — subagent has no conversation history.

Dispatch [mapping-bounded-contexts](../mapping-bounded-contexts/SKILL.md) with import-source.md + phase-1-domain-events.md. Cite source for each boundary. Flag gaps as [STOP]/[ASSUMPTION]. Verify: phase-2-context-map.md exists. Constraint files generated after Step 6.

Step 3: Reverse-Extract Phase 3 (Contracts) (subagent)

Dispatch [designing-contracts-first](../designing-contracts-first/SKILL.md) with import-source.md + phase-2-context-map.md. Single context → mark "N/A". Cite source, flag gaps. Verify: phase-3-contracts.md exists.

Step 4: Reverse-Extract Phase 4 (Technical Solution) (subagent)

Dispatch [architecting-technical-solution](../architecting-technical-solution/SKILL.md) to validate source coverage of all 7 dimensions. Rating criteria and coverage table template: see [import-extraction-reference.md](./import-extraction-reference.md). Depth from Step 2 classification (default: Core Domain).

For each dimension: extract what source says → assess completeness → mark COVERED/PARTIAL/MISSING. Persist coverage table to decisions-log.md as "Step 4 Coverage Assessment" (enables mid-step recovery).

Step 5: Fill Gaps

For each PARTIAL or MISSING dimension:

• Ask: "Your tech solution doesn't fully address [dimension] for [context]. What's your decision?"
• Do NOT suggest or invent answers — only ask. The human provides the gap-filling decision.
• Record each gap-filling decision with the question asked and the user's answer.
• If the human's gap-filling answer is itself ambiguous or introduces a new uncertainty, re-apply the [Ambiguity Handling Protocol](../ddd-protocol/ambiguity-handling-reference.md): STOP for high return-work items (a gap answer that changes BC boundaries or contract shapes), ASSUME & RECORD for low-impact items (naming preferences, format details). Do not accept an ambiguous answer as final.

Completion check: Re-read the Step 4 Coverage Assessment table in decisions-log.md. For every dimension marked PARTIAL or MISSING, verify a corresponding gap-filling decision is now recorded. All dimensions accounted for → proceed. Any dimension still without a recorded decision → continue asking.

After all gaps are addressed, present the complete gap-filling results. Proceed to Final Review Gate for Phase 2-3 artifact review and assumption resolution.

Final Review Gate (before Step 6)

MANDATORY hard stop before persisting Phase 4.

1. Present the following to the developer:

• Step 2 output: docs/ddd/phase-2-context-map.md
• Step 3 output: docs/ddd/phase-3-contracts.md
• Step 4-5 gap decisions (listed above in this session)
• docs/ddd/assumptions-draft.md (all accumulated ASSUMPTION entries)

1. Developer reviews each entry: ✅ Keep | ✏️ Revise to: [alternative]
2. For any REVISED entry: run rollback impact check and re-extract affected steps.
3. Once all entries confirmed: append all entries to docs/ddd/decisions-log.md with status CONFIRMED or REVISED. Delete docs/ddd/assumptions-draft.md.
4. Proceed to Step 6 for final review and Phase 4 persistence.

Checkpoint: "The Final Review Gate is complete. Shall I proceed to Step 6 to finalize and persist the technical solution?"

Step 6: Final Review & Persist Phase 4

Present the complete technical solution in the exact format of ../full-ddd/templates/phase-4-technical-solution.md.

• Each decision must cite its source: original document section OR gap-filling Q&A exchange.
• Include the Dimension Challenge assessment: "Are these decisions grounded in the source document and gap-filling Q&A, or speculative?"

Checkpoint: "Do you approve this technical solution?"

After approval, persist to docs/ddd/phase-4-technical-solution.md. Update ddd-progress.md Phase 4 status to complete. Append to decisions-log.md.

Generate constraint artifacts: Now that all Phase 1-4 artifacts are complete, generate the same constraint artifacts that mapping-bounded-contexts Step 6 produces:

• Per-context constraint files (.claude/rules/{context}.md or platform equivalent) — without file-scoping, with bidirectional import prohibitions, UL dictionary, and relationship patterns. Source content from docs/ddd/phase-2-context-map.md.
• DDD Architecture section in CLAUDE.md — context list, architecture red lines, and pointers to behavior contracts. Follow the format specified in [mapping-bounded-contexts](../mapping-bounded-contexts/SKILL.md) Step 6b.

Step 7: Handoff

"Import complete. All 4 phase artifacts are persisted in docs/ddd/. To proceed to domain implementation:

1. Run defining-schemas (Phase 5) — generates concrete schema files (proto/openapi/DDL/error catalogs) from the imported Phase 3 contracts and Phase

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: lockp111
• Source: lockp111/agent-ddd-engineering
• License: MIT

Install and usage instructions live in the source repository linked above.