---
name: architect-change
description: Design a consequential software change across boundaries, data, APIs, deployment, or reliability and record the decision as a lightweight ADR. Use when implementation choices affect long-term structure or migration. Do not use for trivial local edits.
license: Apache-2.0
metadata:
  compatibility: Codex, Kimi Code, and Grok Build.
  author: Lei Huang
  version: "0.1.0"
  status: experimental
---

# Architect Change

Choose the simplest architecture that satisfies current invariants and makes failure, migration, and reversal explicit.

## Workflow

1. Inspect existing boundaries, ownership, dependencies, runtime topology, data flow, and conventions.
2. Extract quality attributes from the spec: correctness, latency, availability, consistency, privacy, security, cost, operability, and evolvability.
3. State forces and constraints. Distinguish fixed constraints from preferences.
4. Develop at least two credible options plus “keep the current design” when applicable.
5. Evaluate options against the same decision matrix. Identify failure modes and operational burden.
6. Select one option and define interfaces, ownership, migration, compatibility, observability, rollout, rollback, and deletion of transitional paths.
7. Validate with the smallest useful spike or contract test when uncertainty is technical rather than product-level.

## ADR template

Write `.workshop/decisions/ADR-<number>-<slug>.md`:

```markdown
# <decision>
Status: proposed | accepted | superseded
Date: YYYY-MM-DD

## Context and forces
## Decision drivers
## Options considered
## Decision matrix
## Decision
## Boundaries and interfaces
## Data, consistency, and failure modes
## Security and privacy
## Observability and operations
## Migration, rollout, rollback, and cleanup
## Consequences
## Validation evidence
## Open risks
```

## Guardrails

- Do not introduce a service, queue, cache, abstraction, framework, or dependency without tying it to a named decision driver.
- Treat distributed state, retries, idempotency, timeouts, and partial failure as first-class when relevant.
- Avoid future-proofing for uncommitted scenarios.
- Record rejected alternatives fairly enough that a future maintainer can revisit the choice.
- “No ADR required” is a valid outcome when the change does not alter a meaningful boundary; record the reason.

## Evidence packet

Return the ADR, chosen option, decisive evidence, validation performed, migration and rollback summary, and risks that could invalidate the decision.