# Architecting Technical Solution

> Use when making technology choices — database selection, framework decisions, sync vs async, REST vs gRPC — especially when choices are made implicitly or "obvious" without documenting trade-offs. Use when transitioning from approved contracts to domain coding, or when an agent starts coding with implicit architectural assumptions. Symptoms include picking PostgreSQL/Redis/Kafka "by default" with…

- **Type:** Skill
- **Install:** `agentstack add skill-lockp111-agent-ddd-engineering-architecting-technical-solution`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [lockp111](https://agentstack.voostack.com/s/lockp111)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [lockp111](https://github.com/lockp111)
- **Source:** https://github.com/lockp111/agent-ddd-engineering/tree/main/skills/architecting-technical-solution

## Install

```sh
agentstack add skill-lockp111-agent-ddd-engineering-architecting-technical-solution
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 service_name_metric_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.
4. **Human Review:** Present decisions by dimension. Ask: "Do you approve these technology choices?" Do NOT code until explicit approval.
5. **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:

4. **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](https://github.com/lockp111)
- **Source:** [lockp111/agent-ddd-engineering](https://github.com/lockp111/agent-ddd-engineering)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-lockp111-agent-ddd-engineering-architecting-technical-solution
- Seller: https://agentstack.voostack.com/s/lockp111
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.