Architecting Technical Solution

Architecting Technical Solution

Overview

This skill forces explicit, evidence-based technology decisions between contract design and domain coding. Each context's dimensions must be analyzed at appropriate depth and approved before implementation.

Foundational Principle: Contracts define what boundaries look like. This phase defines how to realize them. All rules in this skill are mandatory constraints. No coding until decisions are approved.

When to Use

• After Phase 3 contracts are approved; before domain implementation; when technology choices are needed.

Do NOT use when:

• Context boundaries are not yet defined (REQUIRED PREREQUISITE: [mapping-bounded-contexts](../mapping-bounded-contexts/SKILL.md) — strategic classification is read in Step 1 to set analysis depth).
• Contracts are not yet approved (REQUIRED PREREQUISITE: [designing-contracts-first](../designing-contracts-first/SKILL.md)).
• Modifying logic within an established Bounded Context where tech decisions already exist (use [coding-isolated-domains](../coding-isolated-domains/SKILL.md)).

Quick Reference

| Step | Action | Output | |:---|:---|:---| | 1 | Review Strategic Classification | Depth confirmed | | 2 | Walk 7 Dimensions | Decisions at depth | | 3 | Dimension Challenge | Pass / Roll back | | 4 | Human Review | Decisions frozen | | 5 | Persist to Filesystem | docs/ddd/phase-4-technical-solution.md |

Ambiguity Handling

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

Phase 4 STOP triggers — confirm immediately:

| Ambiguity | Why STOP | |:----------|:---------| | Persistence technology choice (SQL vs NoSQL vs event store) | Determines data model shape → Phase 5 schema generation must align | | Consistency strategy (eventual vs strong) | Wrong strategy = wrong aggregate boundaries and transaction scope | | Interface type (REST vs gRPC vs async events) | Wrong interface = wrong contract shape → Phase 3 contracts may need revision | | Security model unclear (RBAC vs ABAC vs custom) — Core Domain only | Wrong authorization model creates domain invariant violations that are expensive to fix | | Schema evolution strategy not discussed but data model is complex — Core Domain only | Wrong migration strategy risks data loss or extended downtime |

Phase 4 ASSUME & RECORD — proceed with explicit assumption:

| Ambiguity | Default assumption | |:----------|:------------------| | Specific library version | Use latest stable version; record assumption | | Log format details | Use structured JSON logging; record assumption | | Monitoring metric naming | Use servicenamemetric_name convention; record assumption | | Non-critical implementation details | Choose the simpler option; record assumption |

Orchestrator Mode Exception

When invoked by an orchestrator (full-ddd, iterating-ddd, piloting-ddd, restructuring-ddd, importing-technical-solution) in Autonomous Mode, the interactive Q&A steps (1, 3, 4) are replaced by autonomous execution:

• Skip interactive human Q&A. Instead, read docs/ddd/phase-2-context-map.md and docs/ddd/phase-3-contracts.md, then derive the complete 7-dimension technical decision tables in a single pass from Phase 2 strategic classification, Phase 3 contracts, and the input requirements.
• Apply STOP/ASSUME protocol: STOP for Phase 4 STOP triggers (above), ASSUME & RECORD for Phase 4 ASSUME items (above).
• Self-check replaces Dimension Challenge (Step 3): The agent performs the Dimension Challenge autonomously — verifying that every decision traces to a domain event or contract artifact. Untraceable decisions are removed. The written trace (decision table with trade-off rationale) is still mandatory; only the human confirmation prompt is skipped.
• Skip Human Review (Step 4).
• Optional extensions: In Autonomous Mode, optional extensions (Security & Authorization Model, Schema Evolution Strategy) are skipped by default unless Phase 3 contracts or Phase 2 context map explicitly mention security requirements or schema evolution concerns. If mentioned, include them at Supporting depth.
• Persist the 7-dimension technical decision tables immediately (Step 5). Do NOT wait for human approval — the orchestrator manages the approval gate.
• Return the technical decision tables to the orchestrator. If STOP was triggered, return the STOP reason instead.

This exception applies ONLY when dispatched as a subagent by an orchestrator. When invoked standalone (user directly asks for technical solution architecture), the full interactive Q&A session is mandatory.

Implementation (Interactive Q&A Session)

CRITICAL RULE: Do NOT just list technology choices. Guide the user through interactive, step-by-step architectural decisions.

1. Review Strategic Classification: Read classification from Phase 2 (Core Domain → Full RFC, Supporting → Medium, Generic → Lightweight). No classification? Default to Core Domain. Ask: "Classified as [X] — [depth]. Correct?"
2. Walk 7 Dimensions: Use [technical-dimensions-reference.md](./technical-dimensions-reference.md) for the full depth guidance with trade-off tables. The 7 dimensions are: (1) Data Model & Persistence, (2) Interface Type, (3) Consistency Strategy, (4) External Dependency Integration, (5) Observability, (6) Error Handling, (7) Test Strategy. Optional extensions (Core Domain only): Security & Authorization Model, Schema Evolution Strategy — the agent MUST ask the user whether to address them; they are NOT mandatory. If the user chooses to address them and ambiguity surfaces, treat as STOP triggers. Core: options tables with trade-offs. Supporting: choice + rationale. Generic: one-line. For Core Domain, ask whether Security & Authorization Model and Schema Evolution Strategy need analysis.
3. Dimension Challenge: Ask: "Are these decisions grounded in domain events and contracts, or speculative?" Untraceable decisions get removed or trigger return to Phase 3. Minimum depth requirements by classification:

• Core Domain: ALL 7 dimensions MUST have ≥ 1 concrete decision with trade-off rationale (options considered + rejected + why). The decision table MUST be written in the artifact — mental-only challenge does not count.
• Supporting: Dimensions 1-2 MUST have concrete decisions with rationale; dimensions 3-7 may be brief (choice + one-line reason).
• Generic: Dimensions 1-2 only; others marked "default" or "N/A" with one-line justification.

1. Human Review: Present decisions by dimension. Ask: "Do you approve these technology choices?" Do NOT code until explicit approval.
2. Persist to Filesystem: Write to docs/ddd/phase-4-technical-solution.md using the template from ../full-ddd/templates/phase-4-technical-solution.md (read the template file; populate fields from session output). Update ddd-progress.md Phase 4 to complete. Append to decisions-log.md.

Example: Dimension Decision Output (Core Domain)

Context: Inventory (Core Domain) — Dimension 1: Data Model & Persistence

| Field | Decision | |:------|:---------| | Storage technology | PostgreSQL | | Data model | Relational; inventory_items table with reserved_qty and available_qty columns | | ORM strategy | GORM with mapper layer — ORM tags in data/ only, not in domain structs | | Migration strategy | Schema migration via Flyway on deploy | | Rationale | Phase 3 InventoryServicePort requires structured queries by SKU and warehouse; NoSQL key-value cannot express the reservation invariant available_qty ≥ 0 at write time | | Options rejected | MongoDB — document model cannot enforce multi-field consistency constraint without application-level locking |

Dimension Challenge result: Decision traces to Phase 3 contract (InventoryServicePort.reserve(skuId, qty)) and Phase 1 event (InventoryShortage requires per-SKU query). Not speculative. ✅

NEXT STEP: → [defining-schemas](../defining-schemas/SKILL.md)

Loading Guidance

This skill references supporting files on demand — do not preload them all:

• Before Step 1: read docs/ddd/phase-2-context-map.md (strategic classification determines depth).
• During Step 2: read [technical-dimensions-reference.md](./technical-dimensions-reference.md) for the full 7-dimension guidance with trade-off tables.
• On first STOP/ASSUME decision: read ../ddd-protocol/ambiguity-handling-reference.md.

Self-Check Protocol

Follow the [Persistence Defense Reference](../ddd-protocol/persistence-defense-reference.md) after Step 5, with this context-specific item 4:

1. Phase 4 Artifact Exists with Decision Tables: After completing Step 5, verify docs/ddd/phase-4-technical-solution.md exists AND contains a dimension decision table for each bounded context. For Core Domain contexts, verify all 7 dimensions have entries with trade-off rationale. No table = Dimension Challenge was not run.

If the check fails → STOP. Write the missing file or complete the missing dimension decisions. Do NOT proceed to Phase 5.

Note: This skill has no platform hooks. When invoked by an orchestrator ([full-ddd](../full-ddd/SKILL.md), [iterating-ddd](../iterating-ddd/SKILL.md), [piloting-ddd](../piloting-ddd/SKILL.md), [restructuring-ddd](../restructuring-ddd/SKILL.md), [importing-technical-solution](../importing-technical-solution/SKILL.md)), the orchestrator's hooks provide Layer 1 defense. When invoked standalone, this Self-Check Protocol (Layer 2) is the primary defense.

Session Recovery

If a Phase 4 session is interrupted:

1. Check docs/ddd/ddd-progress.md — read Phase 4 status.
2. If docs/ddd/phase-4-technical-solution.md exists and is complete (contains dimension decision tables for all bounded contexts at appropriate depth): Phase 4 is done. Proceed to Phase 5.
3. If phase-4-technical-solution.md exists but is partial (some contexts missing or dimensions incomplete): Read the file to identify which contexts and dimensions are complete. Resume from the first incomplete context/dimension.
4. If phase-4-technical-solution.md does not exist: Restart from Step 1. Re-read docs/ddd/phase-2-context-map.md for strategic classification and docs/ddd/phase-3-contracts.md for contract inputs.
5. Dimension Challenge check: If the file exists but the Dimension Challenge result is missing for any context, resume at Step 3 (Dimension Challenge) for those contexts — do not re-walk the 7 dimensions.

Run sh skills/full-ddd/scripts/session-recovery.sh for a quick status report.

Rationalization Table

If you catch yourself thinking any excuse in the left column — STOP and re-read the Reality column.

| Excuse | Reality | |:---|:---| | "Contracts already imply the technical decisions" | Contracts define boundaries, not technology; InventoryServicePort doesn't decide HTTP vs gRPC vs async. | | "Standard choices don't need analysis" | "PostgreSQL + REST" without evaluating alternatives is not a decision. Core Domain always gets Full RFC. | | "A good architect anticipates future needs" | Decisions must trace to domain artifacts; Kafka and CQRS without domain evidence is speculative waste. | | "Depth classification is overkill here" | Depth follows strategic classification, not how trivial decisions feel. | | "I'll document decisions after coding" | Post-hoc documentation rationalizes existing code; the gate must be synchronous. | | "Self-approve — decisions are clearly grounded" | Self-approval defeats the human checkpoint. | | "Technical decisions are obvious, no need to confirm" | "Obvious" technical decisions that turn out wrong require Phase 4 redo and Phase 5-7 rewrite. Confirm STOP-level decisions. | | "STOP is too disruptive, I'll finish the dimension analysis first" | A STOP-level wrong technical decision means redoing Phase 4 and Phase 5-7. Pausing costs nothing. | | "I ran the Dimension Challenge mentally" | The challenge must produce a written trace in the artifact — a decision table row per dimension with trade-off rationale. No table = no challenge. Mental-only review is self-certification, not verification. | | "Just reuse the same tech stack from the last project" | Each project's domain has different consistency, persistence, and interface requirements. Reusing a tech stack without re-evaluating against the 7 dimensions is gambling that two different domains have identical technical needs. | | "This is Supporting/Generic, mark most dimensions N/A" | Minimum depth requirements exist per classification; N/A without a one-line reason is an empty cell, not a decision. | | "Optional extensions obviously not needed" | For Core Domain, agent MUST ASK user about extensions; deciding for the user is prohibited. "Obviously" is a rationalization word. | | "I read the Phase 2 classification from memory" | Step 1 requires reading from file; memory vs file mismatch cascades wrong depth across all 7 dimensions. |

Red Flags — STOP

If you catch yourself thinking "contracts are enough to start coding", "obvious choices", "document later", "I ran the Dimension Challenge mentally", "standard choices don't need analysis", "self-approve — decisions are clearly grounded", "STOP is too disruptive, I'll finish the dimension analysis first", "depth classification is overkill here", "I'll skip the conditional dimensions (Security, Schema Evolution) for this Core Domain", "same tech stack across all contexts for simplicity", "I'll run code generators autonomously", "a good architect anticipates future needs", "one dimension table per project is enough", "team already agreed on the tech stack", "Supporting contexts don't need any analysis", "defaults are fine without justification", "tech decisions can be implied from contracts", or "skip the dimension challenge — decisions are obviously grounded" — STOP. Walk each dimension. Run the Dimension Challenge. Wait for approval.

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.