tachyon-beep/using-solution-architect

Using Solution Architect

Overview

Solution Architect produces forward design artifacts from a brief / HLD / epic / brownfield change.

This pack is the forward-design counterpart to the backward-looking Axiom pair:

• axiom-system-archaeologist → documents existing code (neutral)
• axiom-system-architect → assesses existing architecture (critical)
• axiom-solution-architect (this pack) → designs new/changed solutions (forward)

When to Use

Use solution-architect skills when:

• You have a business brief, HLD, epic, or brownfield change request
• You need a traceable artifact set (not a one-off diagram or ad-hoc ADR)
• The design will be reviewed, handed off, or implemented by another team
• The context is enterprise (TOGAF phases, ArchiMate tooling, ARB submission)
• User asks: "Design me a solution for…" / "Take this brief and architect it" / "What artifacts do we need for this?"

Do not use this pack when:

• You are assessing an existing system → use /system-architect
• You are documenting an existing system → use /system-archaeologist
• You need process governance (branching, CI/CD, ADR lifecycle) → use /sdlc-engineering

Start Here

If your input is a new brief, HLD, epic, or change request and you have not run this pack before:

1. Read triaging-input-maturity — classify the input and emit 00-scope-and-context.md and 01-requirements.md.
2. Use the workflow plan triage emits to see which subsequent skills apply at your scope tier.
3. Return to the Routing section below for scenario-specific branching.
4. Produce the numbered artifacts required by your tier (see Scope Tier table) using each specialist skill.
5. Run assembling-solution-architecture-document to consolidate into 99- and pass the consistency gate.

The Expected Artifact Set and Scope Tier tables below are reference material — consult them when producing or checking artifacts, not as a linear read.

How to Access Reference Sheets

All reference sheets are in the same directory as this SKILL.md. When you see a link like [quantifying-nfrs.md](quantifying-nfrs.md), read the file from the same directory.

The Pipeline

archaeologist (docs) → architect (assesses) → (future) project-manager
                                 ↑
solution-architect (designs) ────┘  (solution-architect output can later
                                    be critiqued by system-architect)

Expected Artifact Set

The pack produces numbered artifacts in a solution-architecture/ workspace:

| # | Artifact | Producer | |---|----------|----------| | 00 | scope-and-context.md | triaging-input-maturity | | 01 | requirements.md | triaging-input-maturity | | 02 | nfr-specification.md | quantifying-nfrs | | 03 | nfr-mapping.md | quantifying-nfrs | | 04 | solution-overview.md | resisting-tech-and-scope-creep | | 05 | tech-selection-rationale.md | resisting-tech-and-scope-creep | | 06 | descoped-and-deferred.md | resisting-tech-and-scope-creep | | 07 | c4-context.md | router-owned artifacts | | 08 | c4-containers.md | router-owned artifacts | | 09 | component-specifications.md | router-owned artifacts | | 10 | data-model.md | router-owned artifacts | | 11 | interface-contracts.md | router-owned artifacts | | 12 | sequence-diagrams.md | router-owned artifacts | | 13 | deployment-view.md | router-owned artifacts | | 14 | requirements-traceability-matrix.md | maintaining-requirements-traceability | | 15 | integration-plan.md | designing-for-integration-and-migration | | 16 | migration-plan.md (brownfield only) | designing-for-integration-and-migration | | 17 | risk-register.md | designing-for-integration-and-migration | | — | adrs/NNNN-<title>.md | writing-rigorous-adrs | | — | archimate-model/ (enterprise only) | mapping-to-togaf-archimate | | — | togaf-deliverable-map.md (enterprise only) | mapping-to-togaf-archimate | | 99 | solution-architecture-document.md | assembling-solution-architecture-document |

Scope Tier

Every workflow is classified at the end of triaging-input-maturity into one of five tiers. The tier is recorded in 00-scope-and-context.md and determines which artifacts are required by the consistency gate.

| Tier | Trigger | Required structural artifacts | |------|---------|-------------------------------| | XS | Single-component change, ≤1 integration, no new data, no new NFR targets | 00, 01, 02, 03, 04, 06, 09, 14, 15, 17; ADRs only if a decision is made | | S | ≤3 components, ≤2 integrations, existing NFR envelope | XS set + 05, 11 | | M | New subsystem, new integrations, or new NFR targets | S set + 07, 08, 10, 13 | | L | Cross-system, multiple new services, new data stores | M set + 12 (sequence diagrams) + C4 component view (produced as a subsection of 09-component-specifications.md — not a new numbered artifact) | | XL | Governed by ARB / TOGAF / regulator (enterprise context) | L set + archimate-model/, togaf-deliverable-map.md |

triaging-input-maturity is the authoritative source for tier classification — if a trigger here is ambiguous, defer to the precise form in that sheet.

The tier is authoritative. If 04-solution-overview.md or any ADR references an artifact from a higher tier, that artifact becomes required regardless of the declared tier — this is a tier promotion, not a waiver. Brownfield adds 16-migration-plan.md at every tier.

Guidance for Router-Owned Artifacts (07–13)

Note: These seven artifacts (C4 context through deployment view) are not produced by specialist skills. Every workflow produces them according to the quality floor below. The consistency gate's Check 1b enforces this floor — follow the criteria below when producing them, and expect the gate to reject artifacts that fall below the floor.

Required quality floor per artifact:

• 07-c4-context.md: exactly one system box; named external actors and systems; no internal detail.
• 08-c4-containers.md: technology labels on each container; one page; no component-level elements.
• 09-component-specifications.md: every component has name, single-sentence responsibility, public interface, dependencies, consumed NFR IDs (cross-ref 03-), satisfied requirement IDs.
• 10-data-model.md: every entity names its owning service / bounded context; cardinalities stated; logical (not ORM-specific).
• 11-interface-contracts.md: machine-readable where the protocol supports it (OpenAPI, AsyncAPI, Protobuf, GraphQL SDL) or prose contract including inputs, outputs, errors, idempotency, versioning.
• 12-sequence-diagrams.md: 3–5 scenarios; each scenario has at least one failure-path variant; source is PlantUML or Mermaid and checked in.
• 13-deployment-view.md: environments, runtime topology, scaling posture, zones/regions, network boundaries.

The longer-form guidance below expands on each. An artifact that is present but fails its floor fails Check 1b — independent of file presence.

C4 views (07, 08)

• Context diagram (07): users, external systems, and the system-under-design. One box for the system. No internal detail.
• Container diagram (08): the system broken into deployable/runnable units (services, databases, queues, front-ends). Show technology labels (e.g., "PostgreSQL 16", "FastAPI"). Keep to one page.
• Skip component and code-level diagrams unless specifically requested — they duplicate 09-component-specifications.md and rot fast.
• One diagram per purpose. Do not produce five overlapping diagrams.

Component specifications (09)

Per component: name, responsibility (one sentence), public interface, dependencies (components it calls), consumed NFRs (which NFRs it is load-bearing for — cross-reference 03-nfr-mapping.md), and requirement IDs it satisfies. The maintaining-requirements-traceability skill checks this cross-referencing.

Data model (10)

Entities + relationships + ownership (which service/bounded-context owns which entity). Include cardinality and lifecycle notes where non-obvious. Avoid ORM-specific schema; stay at the logical level.

Interface contracts (11)

Machine-readable where possible (OpenAPI, AsyncAPI, Protobuf, GraphQL SDL). If prose, include: method/operation, inputs, outputs, errors, idempotency, versioning stance.

Sequence diagrams (12)

One per critical scenario (happy path + notable failure paths). PlantUML or Mermaid source checked in. Do not produce one per endpoint — pick the 3-5 scenarios that actually reveal design tension.

Deployment view (13)

Target environments, runtime topology, scaling posture, regions/zones, network boundaries. This is the operations/SRE handoff surface.

Routing

Scenario: "Design me a solution for X"

1. Read the input. Use: triaging-input-maturity → 00-scope-and-context.md, 01-requirements.md (scope tier is classified and recorded in 00-).
2. Use: quantifying-nfrs → 02-, 03-
3. Use: resisting-tech-and-scope-creep → 04-, 05-, 06-
4. Produce router-owned artifacts required by the scope tier (07-13 subset per the Scope Tier table) following the quality floor above
5. Use: writing-rigorous-adrs as decisions arise throughout → adrs/
6. Use: maintaining-requirements-traceability → 14-
7. Use: designing-for-integration-and-migration — always for 15- and 17- (integration contracts and architectural risk apply to greenfield too); additionally produces 16- for brownfield
8. If enterprise context: use mapping-to-togaf-archimate → archimate-model/, togaf-deliverable-map.md
9. Use: assembling-solution-architecture-document → 99-

Scenario: "Critique this design package"

Use /review-solution-design, which dispatches agent: solution-design-reviewer. Provide the path to your solution-architecture/ workspace or a single SAD file.

Scenario: "Is Kafka the right choice for this?"

Use agent: tech-selection-critic. Red-teams a tech choice against requirements and constraints.

Specialist Agents

The pack includes two agents that review or critique designs without producing artifacts:

• agent: solution-design-reviewer — Critiques an existing design package (99-solution-architecture-document.md or numbered artifact set) for the ten canonical failure modes (tech-before-problem, NFR handwaving, untraceable design, etc.). Invoked via /review-solution-design.
• agent: tech-selection-critic — Red-teams a single tech choice (datastore, messaging, language, platform) against requirements and alternatives. Invoke when you have a proposed choice and want to validate it before recording in 05- or an ADR.

Agents vs. skills: Skills produce artifacts end-to-end (triage → assembly). Agents review or critique existing artifacts or decisions. Invoke an agent when the work is in review or validation; load a skill when you are producing.

Integration with Other Skillpacks

Security (ordis-security-architect)

Solution architect produces 02 (NFRs), 04 (overview), 09 (components)
→ ordis-security-architect reads these, produces threat model + controls
→ Threats feed back into 17 (risk-register) and adrs/

When the threat model exists, the solution architect's 17-risk-register.md does not duplicate threat entries — it carries a pointer to the threat ID and records only the architectural consequence and mitigation. See the "Security surface" category in designing-for-integration-and-migration.

Compliance drivers

When compliance frameworks are in scope (SOC 2, HIPAA, PCI-DSS, GDPR, data residency), the framework itself is a driver for NFRs (auditability, retention, encryption-at-rest, residency) and for risks (compliance exposure). Record the framework as a CON-REG-* in 01-requirements.md and trace it through 02- → 14- → 17-. If ordis-security-architect is in play, the threat model carries the canonical control mapping; the solution architect carries the architectural consequences.

Documentation (muna-technical-writer)

Solution architect produces 99-solution-architecture-document.md
→ muna-technical-writer polishes for target register (exec, technical, public, policy)

SDLC governance (axiom-sdlc-engineering)

Solution architect produces adrs/
→ axiom-sdlc-engineering/design-and-build manages ADR lifecycle + governance

Brownfield input (axiom-system-archaeologist)

Archaeologist produces 01-discovery-findings.md, 02-subsystem-catalog.md
→ Solution architect's triage consumes these as input context
→ No duplicate analysis

Domain packs

Consult during tech selection:

• yzmir-ml-production → ML-serving tech choices
• axiom-web-backend → API framework choices
• axiom-rust-engineering / axiom-python-engineering → language-level patterns

Decision Tree

Do you have a design brief / HLD / epic / change request?
├─ No → Clarify input with user first
└─ Yes → Continue

Is this brownfield (modifying existing system)?
├─ Yes → Is there archaeologist output for the system?
│         ├─ No → Run /system-archaeologist first, OR record [ASSUMED]
│         │       brownfield context in 00- and raise RSK
│         │       (see designing-for-integration-and-migration)
│         └─ Yes → triaging-input-maturity consumes it
│         → designing-for-integration-and-migration produces 15, 16, 17
└─ No (greenfield) → triaging-input-maturity
                  → designing-for-integration-and-migration produces 15 and 17 (skip 16)

A small change request against a well-documented brownfield system is usually tier XS or S —
run the XS/S artifact subset from the Scope Tier table, not the full pipeline.

Enterprise activation — decide early, record the decision

Keyword presence alone (a stakeholder saying "ArchiMate" in passing) does not activate enterprise mode. Activate only when one of the following is true:

• ARB submission is a release gate for this project
• The customer organization publishes a TOGAF-aligned deliverable set (even if not named as such)
• A governing enterprise-architecture function must countersign the SAD
• ArchiMate models are a required artifact for downstream tooling

If any of these four criteria are true:

1. Use the mapping-to-togaf-archimate skill to produce archimate-model/ (Business, Application, Technology layers) and togaf-deliverable-map.md (phase mapping).
2. Record Enterprise: activated — [which criterion applies] in 00-scope-and-context.md.
3. This promotes the scope tier to XL — all L-tier artifacts are required, plus ArchiMate and TOGAF binding.

If none of these criteria are true:

1. Skip mapping-to-togaf-archimate entirely — TOGAF and ArchiMate binding is overhead for product-engineering work without an EA consumer.
2. Record Enterprise: not activated — [reason] in 00-scope-and-context.md.

The gate report carries the activation state explicitly so a reader can tell whether enterprise mode was considered-and-declined or forgotten.

Stop Conditions

The pipeline is designed to be run end-to-end for M-tier and above. For lighter tiers, and when inputs are adverse, declare a stop condition explicitly rather than silently dropping steps. Every stop condition results in a recorded artifact (00- note, waiver, or RSK entry) — silent drops are the pattern this pack is built to prevent.

| Condition | Response | |-----------|----------| | Tier is XS and no cross-system impact | Run the XS artifact subset (see Scope Tier table); emit the SAD with tier noted; skip enterprise binding unless explicitly required | | Requirements cannot be quantified because the business context is absent | Stop at quantifying-nfrs. Do not proceed to tech selection with adjective-only NFRs. Escalate to the business owner. | | Brownfield with no archaeologist output and no budget to run archaeology | Record [ASSUMED] context in 00- with explicit unknowns, raise RSK-NN: brownfield context unverified (High/High, mitigation = run archaeologist), proceed but mark the SAD as "provisional — unverified brownfield context" | | Enterprise binding required but no TOGAF/ArchiMate skill capacity on the team | Produce the non-enterprise artifact set; record as a gate waiver in the Check 8 section of the gate report (not in 06-descoped-and-deferred.md — waivers and scope decisions are distinct; see assembling-solution-architecture-document); schedule the TOGAF mapping as a follow-up task | | Stakeholder insists on big-bang cutover with no business-time-constraint reason | Stop 16- production, return to stakeholder with the "reshape into stages" guidance from designing-for-integration-and-migration |

Gate waiver vs descope: gate waivers record failures shipped anyway; 06-descoped-and-deferred.md entries record out-of-scope features with reactivation triggers. See assembling-solution-architecture-document for the full distinction between gate waivers and descopes.

Update Workflows

A SAD is a living document. After v1.0.0, changes come as scope extensions, requirement drift, new decisions, or learning from production. The table below names what re-runs and what re-gates for each change shape.

| Change shape | Re-run | Re-gate | |--------------|--------|---------| | New or changed requirement | 01-, 02- if NFRs affected, 14-, 09- cross-ref, affected ADRs | Checks 2, 3, 4 | | New ADR (no requirement change) | adrs/, 05- if tech choice | Checks 4, 5 | | Component split or merge | 09-, 14-, affected interface contracts (11-), affected sequences (12-) | Checks 1b, 2 | | New integration | 15-, 17- | Checks 6, 7 | | Migration stage added or redesigned | 16-, 17- | Checks 6, 7, 1 | | NFR re-target (e.g., scale target raised) | 02-, 03-, affected components in 09-, affected ADRs | Checks 3, 4, 7 | | Scope descope | 06-, 01-, 14- (remove), affected 09-, 03- (redistribute NFR load), affected ADRs | Checks 1, 2, 3 |

Bump the SAD version (semver) on every re-emission. The gate report is versioned alongside the SAD. A SAD whose gate report is older than its latest numbered artifact is stale and must be re-gated before the SAD is cited downstream.

Quick Reference

| Need | Use This | |------|----------| | Classify input + emit scope/requirements | triaging-input-maturity | | Quantified NFRs + per-component mapping | quantifying-nfrs | | Tech selection + YAGNI discipline | resisting-tech-and-scope-creep | | Rigorous ADRs | writing-rigorous-adrs | | Requirements traceability matrix | maintaining-requirements-traceability | | Integration + migration + risks | designing-for-integration-and-migration | | TOGAF phase mapping + ArchiMate views | mapping-to-togaf-archimate | | Consolidate into SAD with consistency gate | assembling-solution-architecture-document | | Critique a draft design package | agent: solution-design-reviewer | | Red-team a tech choice | agent: tech-selection-critic |

Related Documentation

• Archaeologist plugin: axiom-system-archaeologist
• System architect plugin: axiom-system-architect

The Bottom Line

Forward design. Constraints before technology. Traceability by default. Numbered artifacts, one consolidated SAD, one consistency gate before emission.

---

Solution Architect Specialist Skills Catalog

After routing, load the appropriate specialist skill for detailed guidance:

1. triaging-input-maturity.md — Classify input shape, decide workflow, emit scope & requirements
2. resisting-tech-and-scope-creep.md — Constraints-first tech selection, YAGNI audit, stakeholder-pressure resistance
3. quantifying-nfrs.md — Quantified NFRs with measurement methods + per-component mapping
4. writing-rigorous-adrs.md — Full ADR template with alternatives, tradeoffs, rollback, expiry
5. maintaining-requirements-traceability.md — RTM, orphan detection
6. designing-for-integration-and-migration.md — Integration reality, migration plan, architectural risk discipline
7. mapping-to-togaf-archimate.md — TOGAF ADM phase mapping, ArchiMate layer/element discipline, viewpoint subsets
8. assembling-solution-architecture-document.md — Consolidation + cross-artifact consistency gate