菜单
Routes a design brief, HLD, epic, or brownfield change through the full solution-architecture workflow — triage, NFR quantification, tech selection, ADRs, traceability, integration/migration, optional TOGAF/ArchiMate, and consolidated SAD with consistency gate
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
Use when working on a Python task and unsure which specialist to load - routes to type-system, mypy-resolution, project-tooling, delinting, testing, async, scientific-computing, ML-workflows, debugging-and-profiling, or Textual-TUI specialists based on symptoms
Use when starting any UX/UI design task — visual design, IA, interaction, accessibility (WCAG 2.2), user research across mobile, web, desktop, game, and AI surfaces, plus first-principles audience-derived needs analysis. Routes to 11 specialist sheets.
Use when a Claude is taking **standing ownership** of a software product across many sessions — discovery, strategy, specs, and value validation — deciding *what to build, why, for whom,* and *whether it worked*, with continuity, decision provenance, and an authority boundary that escalates irreversible or outward-facing actions to the human owner. Owns the product disciplines: opportunity assessment (JTBD, problem validation, business case), vision/strategy/positioning and intent-roadmapping, PRDs with falsifiable acceptance criteria, delivery orchestration and acceptance, product-value metrics and experimentation, and the product anti-pattern catalog. Orchestrates rather than reimplements: routes sequencing/flow/WSJF to `/axiom-program-management`, plans to `/axiom-planning`, solution/architecture to `/axiom-solution-architect`, research method to `/lyra-ux-designer`. Do **not** load to build one feature, choose an architecture, or manage delivery flow for already-decided work.
This skill should be used when the user asks to "track work", "create an issue", "find something to work on", "what should I work on next", "triage bugs", "close an issue", "check what's blocked", "plan a milestone", "review sprint progress", "coordinate agents", or when working in a project that uses filigree for issue tracking. Provides workflow patterns, team coordination protocols, and operational guidance for the filigree issue tracker.
Use when designing a system that spans more than one process, machine, or failure domain and a partition, crash, or duplicate must not silently corrupt state. Use when you see split-brain, lost writes under partition, duplicate processing, stuck or half-applied sagas, retry storms, dual writes drifting apart, or "works in staging, melts under load." Architecture-level — how to design correctness under partial failure, not how to deploy it. Single-service API internals → `axiom-web-backend`; CI/CD and ops → `axiom-devops-engineering`; replay/seed determinism → `axiom-determinism-and-replay`; broker/event-sourcing mechanics → the event-driven pack.
Use when designing a system whose past behaviour must be recoverable as a fact — RL training substrates, multi-agent simulations, deterministic game engines, replay-debuggable services, multiplayer lockstep, or any pipeline where "I cannot reproduce that bug" is unacceptable. Use when teams disagree about what "snapshot", "seed", or "replay" mean across modules. Use when cross-machine or cross-process determinism is required, or a regulator will ask "what was the input at tick T?". Architecture-level — how to design a deterministic system. For verifying an existing simulation against known patterns, use `/check-determinism` from yzmir-simulation-foundations instead.
基于 SOC 职业分类
| name | using-solution-architect |
| description | Routes a design brief, HLD, epic, or brownfield change through the full solution-architecture workflow — triage, NFR quantification, tech selection, ADRs, traceability, integration/migration, optional TOGAF/ArchiMate, and consolidated SAD with consistency gate |
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)Use solution-architect skills when:
Do not use this pack when:
/system-architect/system-archaeologist/sdlc-engineeringIf your input is a new brief, HLD, epic, or change request and you have not run this pack before:
triaging-input-maturity — classify the input and emit 00-scope-and-context.md and 01-requirements.md.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.
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.
archaeologist (docs) → architect (assesses) → (future) project-manager
↑
solution-architect (designs) ────┘ (solution-architect output can later
be critiqued by system-architect)
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 |
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.
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.
09-component-specifications.md and rot fast.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.
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.
Machine-readable where possible (OpenAPI, AsyncAPI, Protobuf, GraphQL SDL). If prose, include: method/operation, inputs, outputs, errors, idempotency, versioning stance.
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.
Target environments, runtime topology, scaling posture, regions/zones, network boundaries. This is the operations/SRE handoff surface.
triaging-input-maturity → 00-scope-and-context.md, 01-requirements.md (scope tier is classified and recorded in 00-).quantifying-nfrs → 02-, 03-resisting-tech-and-scope-creep → 04-, 05-, 06-07-13 subset per the Scope Tier table) following the quality floor abovewriting-rigorous-adrs as decisions arise throughout → adrs/maintaining-requirements-traceability → 14-designing-for-integration-and-migration — always for 15- and 17- (integration contracts and architectural risk apply to greenfield too); additionally produces 16- for brownfieldmapping-to-togaf-archimate → archimate-model/, togaf-deliverable-map.mdassembling-solution-architecture-document → 99-Use /review-solution-design, which dispatches agent: solution-design-reviewer. Provide the path to your solution-architecture/ workspace or a single SAD file.
Use agent: tech-selection-critic. Red-teams a tech choice against requirements and constraints.
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 eleven 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.
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.
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.
Solution architect produces 99-solution-architecture-document.md
→ muna-technical-writer polishes for target register (exec, technical, public, policy)
Solution architect produces adrs/
→ axiom-sdlc-engineering/design-and-build manages ADR lifecycle + governance
Archaeologist produces 01-discovery-findings.md, 02-subsystem-catalog.md
→ Solution architect's triage consumes these as input context
→ No duplicate analysis
Consult during tech selection:
yzmir-ml-production → ML-serving tech choicesaxiom-web-backend → API framework choicesaxiom-rust-engineering / axiom-python-engineering → language-level patternsDo 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.
Keyword presence alone (a stakeholder saying "ArchiMate" in passing) does not activate enterprise mode. Activate only when one of the following is true:
If any of these four criteria are true:
mapping-to-togaf-archimate skill to produce archimate-model/ (Business, Application, Technology layers) and togaf-deliverable-map.md (phase mapping).Enterprise: activated — [which criterion applies] in 00-scope-and-context.md.If none of these criteria are true:
mapping-to-togaf-archimate entirely — TOGAF and ArchiMate binding is overhead for product-engineering work without an EA consumer.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.
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.
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.
| 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 |
axiom-system-archaeologistaxiom-system-architectForward design. Constraints before technology. Traceability by default. Numbered artifacts, one consolidated SAD, one consistency gate before emission.
After routing, load the appropriate specialist skill for detailed guidance: