Architecture Decision Making

Lifecycle: draft

Architecture Decision-Making

Purpose and scope

Choose a system structure that fits current constraints while making tradeoffs and future change explicit. This skill covers architecture reasoning and decision records; it does not replace requirements ownership, threat modeling, formal design review, or domain-specialist approval for critical systems.

Triggers and prerequisites

Trigger when a change introduces or removes a service/module boundary, changes data ownership, selects an integration or storage pattern, changes deployment topology, or creates a long-lived dependency or operational obligation. Prerequisites: desired outcomes, quality attributes, constraints, current architecture, owners, workloads, failure model, security/data requirements, and alternatives worth considering.

Decision criteria

• Architecture is a set of observable consequences and constraints, not a diagram or fashionable pattern.
• Compare alternatives against the same criteria: correctness, security, privacy, performance, reliability, operability, cost, complexity, team capability, and reversibility.
• Separate constraints from preferences and evidence from assumptions. A local optimization must not silently weaken protected principles.
• Prefer the simplest design that satisfies demonstrated requirements; preserve an escape route when uncertainty is high.

Procedure

1. State the problem, desired outcome, scope, non-goals, stakeholders, quality attributes, constraints, and decision deadline. Identify which claims require evidence.
2. Map the current system: boundaries, data/control flow, owners, dependencies, interfaces, state, failure paths, deployment, and operational responsibilities. Confirm the model with code and runtime evidence where possible.
3. Generate at least two plausible alternatives, including keeping the current design when appropriate. Describe each alternative’s assumptions, consequences, and migration path.
4. Define decision criteria and weights only when justified. Consider normal, boundary, failure, scale, security, privacy, maintenance, and organizational scenarios rather than only the happy path.
5. Trace evidence to primary specifications, measurements, existing constraints, incidents, and independent implementations. Ask what evidence would make the leading choice wrong.
6. Identify irreversible commitments, coupling, lock-in, data migration, operational burden, blast radius, and exit strategy. Prefer a reversible experiment or staged seam when evidence is insufficient.
7. Choose or defer the decision. Record the chosen boundary, rejected alternatives and reasons, assumptions, tradeoffs, confidence, consequences, and triggers for revisiting it.
8. Translate the decision into acceptance criteria, ownership, interfaces, migration steps, observability, security controls, and verification evidence. Route implementation to the relevant task skills.
9. Re-evaluate after implementation or new evidence. If the observed system contradicts the decision, preserve the record and revise or supersede it rather than silently changing the rationale.

Examples and counterexamples

Good: Compare an in-process queue, a durable broker, and the current synchronous path against delivery guarantees, failure recovery, throughput, operations, cost, and migration before selecting one.

Bad: Choose a broker because distributed systems are “more scalable” without defining workload, delivery semantics, or operational capacity.

Good: Record that a temporary adapter preserves compatibility while evidence is gathered, plus the condition and date for removing it.

Bad: Introduce an abstraction layer “for future flexibility” without a current problem, owner, or removal boundary.

Failure modes and recovery

If requirements or quality attributes conflict, use requirements-to-acceptance or ask the owner; do not hide the conflict in a weighted score. If the current architecture cannot be mapped confidently, investigate before proposing a replacement. If evidence is insufficient, choose a reversible experiment or defer rather than pretending certainty. If a decision causes unexpected coupling or failure, contain impact, preserve the original rationale, and create a superseding decision with the new evidence.

Validation evidence and provenance

Claims in this skill map to graded findings in docs/research.md:

• Decision records (context, options, consequences) improve traceability (F6, Principled): established practitioner methodology; no controlled study shows ADRs prevent bad architecture.
• Recording tradeoffs rather than presenting one choice as universal: Principled, consistent with the evidence standard's facts-versus-advice rules.

Source boundary: the ADR source is design input; this skill does not claim better architectural outcomes, only inspectable decisions.

Confidence: medium for the methodology; low for any specific architectural judgment made while applying it. Freshness: review when the ADR guidance or research base changes.

Disconfirmation: evidence that decision-record overhead yields no revisit value, or that recorded tradeoffs systematically mislead later readers, would require simplifying the practice.

Related skills and conflicts

Related: requirements-to-acceptance, repository-exploration, implementation-planning, api-contract-compatibility, concurrency-and-shared-state, data-migration-safety, performance-regression-analysis, secure-coding-review, and skill-quality-review. This skill does not authorize architecture changes without owner approval, confuse a pattern with evidence, or preserve a failed decision for consistency’s sake.