{
  "schema_version": 1,
  "skill_name": "software-architecture",
  "evals": [
    {
      "id": "greenfield-design",
      "prompt": "Design the architecture for a new appointment platform. It has a small team, uncertain demand, strict audit needs, and a requirement to keep booking responsive when a notification provider is down. Compare a modular monolith with a distributed option and define the first evidence to collect.",
      "expected_output": "A decision brief that starts with drivers and scenarios, compares deployment shapes, makes audit and notification failure behavior explicit, recommends a proportionate starting shape, records uncertainty, and names specialist handoffs.",
      "assertions": [
        "Drivers and observable scenarios are stated before technology choices",
        "Modular monolith and distributed alternatives are compared with negative consequences",
        "Notification-provider failure has an explicit user-visible and recovery behavior",
        "Uncertain demand is treated as an evidence gap rather than an invented scale fact",
        "The output names specialist handoffs without absorbing implementation or security ownership"
      ]
    },
    {
      "id": "modular-monolith-service-choice",
      "prompt": "Should we split checkout pricing into a service? It shares a transaction with order creation, four jobs read its tables directly, traffic is low and stable, and no team owns pricing data end to end. Give an architecture recommendation and next steps.",
      "expected_output": "A recommendation to retain or strengthen the modular monolith pending evidence, citing shared transactions, direct table consumers, unclear authority, and low independent scaling benefit. It distinguishes target architecture from migration execution.",
      "assertions": [
        "Shared transaction and direct table access are identified as boundary risks",
        "Unclear data ownership is identified as a blocker or explicit evidence gap",
        "Low stable traffic is used against a service-specific scaling justification",
        "The recommendation does not assume service decomposition is the desired outcome",
        "Migration sequencing is routed separately from the architecture decision"
      ]
    },
    {
      "id": "distributed-consistency-failure",
      "prompt": "Design a payment authorization workflow across an order service, payment provider, and ledger. The provider can timeout after charging, messages can duplicate or arrive out of order, and users must not see a confirmed order without a durable payment outcome.",
      "expected_output": "A workflow design that defines authority, acknowledgement, consistency scope, idempotency, duplicate and ordering behavior, timeout ambiguity, reconciliation, user-visible pending state, and recovery evidence.",
      "assertions": [
        "The design distinguishes durable payment authority from derived order state",
        "Timeout after a possible charge has an explicit pending or reconciliation path",
        "Duplicate and out-of-order delivery behavior is defined",
        "The user-visible confirmation rule is tied to a durable payment outcome",
        "Recovery and reconciliation have named owners and evidence"
      ]
    },
    {
      "id": "evolutionary-fitness",
      "prompt": "Our architecture decision requires dependencies to point toward domain policy and forbids new cross-module database writes. Define an evolutionary fitness plan and drift response without turning the ADR skill into a full architecture governance program.",
      "expected_output": "A plan linking the architecture decision to bounded structural checks, evidence owners, cadence, threshold rationale, exceptions, drift classification, and ADR confirmation while routing execution to project tooling.",
      "assertions": [
        "Each architectural claim maps to a bounded observable check",
        "The plan names cadence, owner, threshold rationale, and missing-result behavior",
        "Drift is classified into defect, exception, changed requirement, stale rule, or unknown",
        "Execution remains with test, CI, telemetry, or governance systems",
        "ADR authoring is limited to the durable decision and confirmation trace"
      ]
    },
    {
      "id": "cloud-topology",
      "prompt": "Review a proposed multi-region cloud topology for a read-heavy public catalog. It includes regional replicas, a global entry point, asynchronous replication, and a single write region. Identify the architecture questions and tradeoffs before anyone chooses provider-specific services.",
      "expected_output": "A provider-neutral topology review covering authority, replication lag, stale reads, regional failure, write routing, recovery, network and identity boundaries, deployment blast radius, and handoff to platform and capacity owners.",
      "assertions": [
        "Single write authority and replica staleness are made explicit",
        "Regional failure and recovery behavior are analyzed",
        "Logical architecture is separated from provider-specific provisioning",
        "Network, identity, and deployment blast radius questions are included",
        "Platform and capacity implementation or evidence ownership is routed explicitly"
      ]
    },
    {
      "id": "api-routing-boundary",
      "prompt": "Write an OpenAPI contract for a new search endpoint with pagination, error semantics, and backward compatibility rules.",
      "expected_output": "A routing response that sends the task to api-design-and-evolution rather than producing a system architecture method, while optionally noting that a broader topology decision would return to software architecture.",
      "assertions": [
        "The request is routed to api-design-and-evolution",
        "Pagination, error, and compatibility semantics are identified as API ownership",
        "The architecture skill does not duplicate an OpenAPI contract workflow"
      ]
    },
    {
      "id": "data-platform-routing",
      "prompt": "Choose between a lakehouse and warehouse for event analytics, including data product ownership, freshness, governance, and platform migration sequencing.",
      "expected_output": "A routing response that sends data platform, data product, governance, and modeling decisions to data-architect, with migration-engineering involved only for an approved transition.",
      "assertions": [
        "Data platform and data product design are routed to data-architect",
        "Modeling and governance are not reimplemented by software-architecture",
        "Migration execution is conditional on an approved target decision"
      ]
    },
    {
      "id": "implementation-security-migration-routing",
      "prompt": "Implement the chosen architecture by adding OAuth authorization, Kubernetes manifests, retry logic, and a zero-downtime data migration from the old service.",
      "expected_output": "A multi-owner routing response: security to secure-software-engineering, service code to backend-engineering, substrate to platform-engineering, and approved migration execution to migration-engineering. It does not pretend architecture design owns those implementations.",
      "assertions": [
        "OAuth and authorization are routed to secure-software-engineering",
        "Retry logic and service implementation are routed to backend-engineering",
        "Kubernetes manifests and substrate operations are routed to platform-engineering",
        "Zero-downtime cross-system migration is routed to migration-engineering",
        "The response preserves the architecture skill as the decision owner rather than an implementation owner"
      ]
    },
    {
      "id": "multi-writer-replication-decision",
      "prompt": "Choose a replication architecture for a multi-region document service that must accept offline edits in two regions. Define read freshness, concurrent-write conflict behavior, failover, and repair.",
      "expected_output": "A system architecture decision that states write authority and visibility semantics, compares replication options against latency and failure constraints, defines conflict detection and resolution, and names reconciliation and recovery evidence. It loads DDIA progressively for mechanism detail while preserving specialist handoffs.",
      "assertions": [
        "The decision makes writable replicas, durability, visibility, staleness, and read-your-writes expectations explicit",
        "Concurrent multi-writer conflict detection, resolution, reconciliation, and repair are defined",
        "The response uses DDIA as mechanism guidance while software-architecture retains the system decision",
        "Message handling, contracts, data-platform work, and recovery exercises are routed to their specialist owners"
      ]
    },
    {
      "id": "partition-skew-rebalancing-decision",
      "prompt": "Design the partitioning approach for a tenant-aware event store where a few tenants and hot keys dominate traffic, ordinary queries sometimes cross partitions, and rebalancing must not silently violate ordering or availability promises.",
      "expected_output": "A system architecture decision that evaluates partitioning by workload locality and consistency boundaries; covers skew, routing, secondary indexes, rebalancing, and cross-partition operations; and defines a reversible evidence plan. DDIA supplies mechanism principles while data-platform implementation remains with data-architect.",
      "assertions": [
        "Partitioning is evaluated by workload locality and consistency boundary rather than node count or convenience",
        "Tenant or hot-key skew, routing metadata, secondary indexes, rebalancing cost, and cross-partition behavior are addressed",
        "The proposed option has measurable evidence, failure behavior, and a reversible stop condition",
        "The response preserves software-architecture, DDIA, data-architect, and implementation ownership boundaries"
      ]
    },
    {
      "id": "stale-leader-fencing-decision",
      "prompt": "Design authority and coordination for a replicated scheduler that uses leases. During a network partition, an old leader may continue issuing work after its lease expires. Decide the fencing, quorum, timeout, duplicate-work, and recovery behavior.",
      "expected_output": "A failure-aware architecture decision that states clock, lease, quorum, and coordination assumptions; treats stale leadership as a concrete fault; uses fencing or equivalent authority validation; and defines duplicate-effect prevention, repair, and exercised recovery evidence.",
      "assertions": [
        "Stale-leader authority is treated as a concrete failure rather than assuming lease expiry is sufficient",
        "Clock, quorum, timeout, lease, coordination-service, and fencing assumptions are explicit",
        "The design explains how conflicting or duplicate work is prevented, detected, or repaired",
        "Backend implementation and resilience exercise ownership remain separate from the architecture decision"
      ]
    },
    {
      "id": "transaction-isolation-invariant-decision",
      "prompt": "Choose the transaction and isolation behavior for an inventory reservation workflow where two concurrent requests can each observe the final unit under snapshot isolation. State what must remain atomic, what may be asynchronous, and how the decision will be verified.",
      "expected_output": "An architecture decision that names the inventory invariant and transaction scope, identifies the concurrency anomaly, compares isolation or concurrency-control choices, and defines compensating and verification behavior if weaker isolation remains. DDIA supplies mechanism detail without taking ownership of the system decision.",
      "assertions": [
        "The inventory invariant and exact atomicity or transaction boundary are named",
        "The concurrency anomaly is tied to the isolation choice rather than answered with a blanket default",
        "Locks, compare-and-set, versioning, serializable behavior, or another explicit control and failure path are evaluated",
        "The response preserves the architecture decision and API, backend, data-platform, and recovery handoffs"
      ]
    }
  ]
}

# Architecture Characteristics And Tradeoffs

## Start with scenarios

Do not list qualities as adjectives. Write a scenario with a stimulus, affected boundary, measurable response, and context. For example: "During a regional dependency outage, checkout preserves order acceptance for 15 minutes, returns a clear pending state, and reconciles accepted orders when the dependency returns." The scenario makes the tradeoff and evidence surface visible.

Classify each driver as business outcome, user expectation, operational need, legal or contractual constraint, team constraint, or technical constraint. Mark each claim as observed, reported, inferred, or unknown.

## Prioritize without pretending precision

Rank scenarios using a short rationale such as must-preserve, differentiating, enabling, or deferrable. Record who supplied the priority and what would change it. Avoid universal numeric weights when evidence cannot support them. If a score is useful, show the inputs and uncertainty.

## Compare options

For each candidate, assess:

- value delivered for the drivers;
- cost paid in complexity, latency, coordination, and operations;
- failure and recovery behavior;
- reversibility and migration burden;
- team capability and ownership fit;
- evidence available now and evidence still needed.

Separate hard constraints from preferences. A candidate that violates a hard constraint is not a lower-scoring option; it is rejected unless the constraint changes.

## Conflicts are decisions

Common tensions include consistency versus availability, isolation versus cost, autonomy versus duplicated capability, latency versus durability, flexibility versus simplicity, and local ownership versus cross-system reuse. State which side is favored, for which scenario, and what consequence is accepted. A tradeoff record is incomplete if it names only benefits.

## Review questions

Ask: What user or operator harm occurs if this characteristic is missed? Where is the boundary that can enforce it? What is the tail behavior, not just the average? Which assumption is most likely to be wrong? What evidence would reverse the choice?

# Architecture Practice And Facilitation

Architecture practice is a decision-making activity, not a ceremony. Start with the smallest group that owns the drivers, affected boundaries, operations, security, data, and delivery consequences. Invite specialists for their decisions, not as a substitute for accountable ownership.

## Review flow

1. Share the decision brief and evidence gaps before the session.
2. Confirm the decision to be made and the authority to make it.
3. Test drivers and scenarios before debating technologies.
4. Compare options using the same criteria and expose rejected alternatives.
5. Challenge failure, ownership, operability, security, capacity, cost, and evolution assumptions.
6. Record decisions, dissent, open questions, owners, and due dates.
7. Define the evidence that can confirm or reverse the choice.

## Proportionality

Use lightweight peer review for local, reversible decisions. Increase evidence and cross-team participation for broad, irreversible, regulated, expensive, or safety-sensitive decisions. Do not turn every choice into a central board review; route technology portfolio governance to `technology-radar` and durable decision records to `adr-authoring`.

## Facilitation guardrails

Separate facts, assumptions, preferences, and decisions. Make the quietest stakeholder's constraint visible without manufacturing consensus. Time-box exploration only after the decision boundary is clear. If authority or evidence is missing, stop the decision, name the blocker, and assign the next discovery rather than filling the gap with confidence.

## Outputs

The minimum useful record is a decision brief, one or more tradeoff records, an architecture view or diagram handoff, an evidence plan, and a review outcome. The record should tell a future reader what changed, why, what was rejected, and what would cause reconsideration.

# Coupling, Modularity, And Data Ownership

Assess a candidate boundary across several coupling surfaces:

- **Policy coupling:** one invariant requires coordinated changes;
- **data coupling:** components share tables, records, keys, or write authority;
- **temporal coupling:** one step must be available or ordered before another;
- **runtime coupling:** latency, availability, or resource pressure propagates;
- **deployment coupling:** changes must ship together;
- **organizational coupling:** ownership, incentives, or skills require coordination.

High coupling is not automatically bad. Shared coupling can be cheaper inside one process when the invariant is strong and the team is one owner. The question is whether the proposed boundary reduces the costly coupling without creating a worse failure or coordination surface.

## Modularity checks

Inspect change history, dependency direction, call paths, data access, transaction scope, and operational ownership when evidence exists. For a greenfield design, mark these as hypotheses and define a probe. Prefer a cohesive module with a narrow interface over a distributed component whose interface exposes internal data or transaction assumptions.

## Data authority

For each important fact, identify the authoritative writer, derived views, caches, replicas, audit history, and deletion authority. State who may mutate it, what an accepted write means, and how conflicting updates are resolved. Data platform and data-model decisions belong to `data-architect`; architecture owns the cross-boundary ownership decision.

## Decomposition decision

Recommend a modular monolith or staged boundary when ownership is unclear, transactions span the candidate, consumers bypass an interface, load is not independently shaped, or recovery cannot be tested. Recommend separate deployment only when the benefit is concrete and the team can own the new operational surface. Hand an approved transition to `migration-engineering`.

# Distributed Workflows And Consistency

For every cross-process workflow, describe the command or event path, authority, durable state, acknowledgement point, and recovery path. Use a sequence or state table when prose would hide timing.

## Consistency contract

State what must be atomic, what may be eventually consistent, the allowed staleness or lag, the visibility point, and the conflict rule. Do not say "strong consistency" without naming the invariant and scope. Route message or API contract semantics to `api-design-and-evolution` and implementation patterns to `backend-engineering`.

## Failure inventory

Cover timeouts, retries, duplicate delivery, lost or delayed messages, reordering, partial commits, dependency outage, process restart, poison input, overloaded consumers, and operator intervention. For each, state detection, user-visible result, retry or compensation rule, idempotency key or deduplication scope, and reconciliation owner.

## Orchestration and choreography

Choose orchestration when a coordinator makes progress and compensation legible; choose choreography when independent facts and local reactions reduce central coordination. Either choice must expose observability, completion detection, stuck-work handling, and ownership. Do not treat asynchronous messaging as automatically decoupled or reliable.

## Recovery evidence

Name the state that can be rebuilt, the source of truth, the replay or reconciliation mechanism, and the test or exercise that proves recovery. Route RTO/RPO, game days, and restore verification to `resilience-and-recovery`; route service SLOs and incident operation to `site-reliability-engineering`.

# Evolution, Fitness Functions, And Drift

Treat architecture as a sequence of decisions exposed to change. For each important decision, identify the characteristic it protects, the boundary where violation can be observed, the evidence type, cadence, owner, threshold rationale, exception path, and retirement condition.

## Fitness evidence

Use structural checks for dependency direction or forbidden relationships, scenario tests for recovery or isolation, runtime evidence for latency or saturation, and human review for intent that cannot be mechanized. A check is not proof outside its scope. Record denominator, exclusions, missing-data behavior, and known false-positive or false-negative paths.

`adr-authoring` owns the durable decision and its link to confirmation. The project test, CI, telemetry, runtime, or governance system owns execution. Load `adr-authoring` for the ADR and fitness-function record.

## Drift loop

1. Detect a deviation or changed driver.
2. Classify it as defect, intentional exception, changed requirement, stale rule, or unknown.
3. Record impact, affected scenarios, owner, and expiry or review date.
4. Choose repair, accepted exception, decision revision, or retirement.
5. Re-run evidence and update the decision record.

Avoid metrics that can improve while architecture intent worsens. Review tails, exclusions, boundary shifts, and gaming paths. Route portfolio governance to `technology-radar` and operational telemetry to its specialist owner.

## Evolution slices

Prefer increments that preserve a selectable path, create evidence, and keep recovery legible. State what becomes irreversible, what must coexist, and what observation closes the slice. This is architecture sequencing, not migration execution.

# Migration And Coexistence

Architecture decides whether a target boundary is justified and what properties the transition must preserve. `migration-engineering` owns the current-to-target execution method: compatibility windows, dual-running, reconciliation, cutover, recovery classification, deprecation, and cleanup.

## Handoff fields

Before handoff, provide:

- current and target boundaries;
- decision drivers and rejected alternatives;
- authority and ownership changes;
- interface and data contracts to be designed by specialists;
- coupling and consumer inventory with evidence gaps;
- consistency and failure invariants;
- coexistence assumptions and selectable paths;
- fitness evidence and cutover conditions;
- irreversible steps and explicit acceptance needs;
- named architecture, migration, implementation, platform, security, data, and operations owners.

## Patterns as roles

Name a transition pattern by the risk it controls: routing controls traffic selection, an abstraction controls call-site change, a translation boundary protects semantic ownership, change capture carries state, and parallel comparison creates evidence. Do not select a pattern merely because extraction was requested. Load `migration-engineering` once the boundary is approved.

## Retain the monolith when

The candidate still needs shared writes, frequent cross-boundary transactions, unowned data, hidden consumers, untestable recovery, or no measurable independent scaling or ownership benefit. Record modular improvements and the evidence that would reopen the decision.

# Source Index

This skill is an original, task-centered synthesis. Public sources inform concepts and terminology; they are not copied as instructional text.

| Source | Use in this skill | URL |
|---|---|---|
| ISO/IEC/IEEE 42010:2022 overview | Architecture description concerns, stakeholders, viewpoints, and rationale | https://www.iso.org/standard/74393.html |
| C4 model | Choosing a communication level for structural views | https://c4model.com/ |
| arc42 | Practical architecture documentation sections and review prompts | https://arc42.org/ |
| AWS Well-Architected Framework | Public quality-area questions and tradeoff framing; not provider prescription | https://docs.aws.amazon.com/wellarchitected/latest/framework/welcome.html |
| Google SRE resources | Reliability, service behavior, and evidence-oriented operational thinking | https://sre.google/sre-book/table-of-contents/ |
| Martin Fowler, Monolith First | Reasons to delay distribution and learn boundaries before splitting | https://martinfowler.com/bliki/MonolithFirst.html |
| Martin Fowler, StranglerFigApplication | Coexistence and incremental replacement vocabulary | https://martinfowler.com/bliki/StranglerFigApplication.html |
| Thoughtworks Technology Radar | Public technology adoption and uncertainty vocabulary; portfolio governance remains with `technology-radar` | https://www.thoughtworks.com/radar |
| NIST SP 800-160 Vol. 1 Rev. 1 | Systems security engineering as a neighboring lifecycle owner | https://csrc.nist.gov/pubs/sp/800/160/v1/r1/final |
| `programming-principles` DDIA references | Existing repository mechanism guide loaded by progressive disclosure for replication, partitioning, coordination, ordering, and transaction-isolation questions; system decisions remain here | https://github.com/mattpocock/agent-rules-books |

## Licensed-books boundary

The private architecture comparison report and purchased books may inform research only. This repository does not reproduce their prose, tables, diagrams, examples, taxonomies, chapter order, or distinctive presentation. The skill was written from the user-task workflow, repository ownership boundaries, and public sources above. The separately attributed `programming-principles` DDIA references are an existing repository dependency loaded only for mechanism detail; this skill links to them without reproducing their text or structure. No purchased ebook is a source file for this deliverable, and no purchased ebook should be read or quoted as part of using it.

## Provenance and review

- Research input: a safe synthesized architecture comparison supplied for this task.
- Transformation: claims and failure pressures were compared across public sources and existing repository owners, then rewritten as original procedures, templates, and eval prompts.
- Review rule: if future edits resemble a source's distinctive expression or structure, rewrite from the user task and re-check this boundary before publication.

# Styles, Topologies, And Granularity

Choose a shape because it fits the scenarios and ownership, not because the label is fashionable.

## Style comparison

Compare a modular monolith, separately deployed services, event-oriented collaboration, batch or workflow-oriented integration, and managed platform capabilities by the same questions: where policy lives, where data is authoritative, how callers coordinate, how failures surface, how teams deploy and operate, and how the shape changes later.

## Deployment topology

Describe runtime placement and trust boundaries separately from logical boundaries. Include process and network hops, regions or zones, data stores, queues, ingress and egress, and operator paths. Show which parts are managed by the application team and which are substrate responsibilities. Route concrete cloud resource selection or provisioning to `platform-engineering`.

## Granularity test

A boundary is promising when it has a coherent policy, an owner who can change and operate it, a stable interaction surface, data authority that can be stated, and a failure behavior that callers can tolerate. A boundary is premature when it exists only to reduce file size, mirrors team names without ownership, requires frequent distributed transactions, or adds a hop without a scenario that benefits.

## Cloud topology questions

For a cloud design, document regional assumptions, availability zones, state placement, network admission, identity boundaries, dependency failure, deployment blast radius, data movement, and recovery. Do not claim provider resilience from a service name alone. Load `platform-engineering` for substrate implementation and `capacity-and-cost-engineering` for measured capacity or spend.

## Diagram handoff

Use `c4-diagramming` for context, container, component, or code views. A diagram supports the decision; it does not replace ownership, runtime behavior, or evidence.

# Architecture Design Brief

## Decision

- Decision to make:
- Accountable decision owner:
- Date and horizon:
- Reversibility:

## Drivers and stakeholders

| Driver or outcome | Source | Priority | Evidence status |
|---|---|---|---|
| | | | |

Stakeholders and constraints:

## Scenarios

| ID | Stimulus | Boundary | Required response | Measure or evidence |
|---|---|---|---|---|
| | | | | |

## Options

| Option | Fits | Costs | Failure and recovery | Ownership fit | Evidence gap |
|---|---|---|---|---|---|
| | | | | | |

## Boundaries and runtime shape

- Policy ownership:
- Data authority and derived state:
- Logical boundaries:
- Deployment topology:
- Interaction paths:
- Team and operational ownership:

## Decision and consequences

- Chosen option:
- Rejected alternatives and reasons:
- Benefits accepted:
- Costs and risks accepted:
- Open questions and assumptions:

## Verification and handoffs

| Claim or characteristic | Check or evidence | Owner | Trigger | Failure action |
|---|---|---|---|---|
| | | | | |

Specialist handoffs: API, data, backend, platform, security, capacity, diagrams, ADR, migration, operations.

# Architecture Review

## Scope and authority

- Decision under review:
- Review owner and accountable decider:
- Reviewers and affected teams:
- Decision deadline:
- Review mode and rationale:

## Evidence check

- Facts observed:
- Assumptions:
- Unknowns requiring discovery:
- Sources and artifacts:

## Challenge checklist

- [ ] Drivers and prioritized scenarios are explicit.
- [ ] Alternatives use comparable criteria and rejection reasons are recorded.
- [ ] Boundaries, data authority, and coupling are named.
- [ ] Consistency, ordering, retries, duplicates, timeout, partial failure, and recovery are explicit.
- [ ] Security, capacity, cost, and operational evidence have owners or explicit gaps.
- [ ] Deployment topology is distinct from logical architecture.
- [ ] Evolution slices, drift response, and irreversible steps are visible.
- [ ] Specialist handoffs do not duplicate their methods.

## Outcome

- [ ] Accept
- [ ] Accept with conditions
- [ ] Rework
- [ ] Defer pending evidence
- [ ] Reject

Decision, dissent, conditions, owners, evidence triggers, and reconsideration criteria:

# Architecture Tradeoff Record

- Topic:
- Decision owner:
- Date:

## Driver or scenario

- Required outcome:
- Hard constraints:
- Evidence and uncertainty:

## Options compared

| Criterion | Option A | Option B | Option C |
|---|---|---|---|
| User or business outcome | | | |
| Consistency and correctness | | | |
| Failure and recovery | | | |
| Change and deployment | | | |
| Team operability | | | |
| Capacity and cost evidence | | | |
| Reversibility | | | |

## Decision

- Selected option:
- Why it fits the highest-priority scenario:
- Negative consequences accepted:
- Rejected options and rejection reasons:
- What evidence would reverse this choice:

## Follow-up

| Action or evidence | Owner | Due or trigger | Handoff |
|---|---|---|---|
| | | | |