---
name: davekilleen/architecture-decision
source: https://app.decimal.ai/s/davekilleen-architecture-decision@2/SKILL.md
source_sha256: cffdc1cadb4e
---

# Architecture decision

## When to use

Use this skill when a material architecture choice, constraint, or reversal needs a
traceable Architecture Decision Record (ADR), or when an existing ADR's state and
rationale need review.

Do not use it for live incident response, implementation instructions that do not
require a design decision, or a decision that has no identifiable evidence or human
decision authority. Not for silently choosing on behalf of the team or rewriting
historical ADRs.

## Inputs and source discipline

Start with the decision question, scope, constraints, affected systems, decision
authority, and intended decision window. Treat a missing authority, constraint, or
date as unknown; ask for it or mark it TBD.

Build a source ledger before comparing options. For every material claim record the
source, source date, as-of date/time, locator, and freshness or access limitation.
Prefer directly inspected code, configuration, tests, measured operations, and dated
requirements; label meeting recollections and interpretations accordingly. Keep
conflicting sources linked rather than silently choosing one.

## Method

1. Read the relevant context in read-only mode. State the problem, desired outcome,
   non-negotiable constraints, decision deadline if evidenced, and what is outside
   scope.
2. Enumerate the status quo and credible alternatives. For each option capture
   supporting evidence, fit to constraints, benefits, costs, risks, reversibility,
   migration or operational burden, trade-offs, and unresolved unknowns.
3. Compare options with the same criteria. Record confidence for each material
   assessment and retain contradictions; do not manufacture a score, percentage, or
   cost when the source does not provide one.
4. Draft the ADR with one explicit state:
   - **Proposed** means the evidence-backed draft is awaiting human authority.
   - **Accepted** means the human decision authority explicitly approved the stated
     option and trade-offs; a recommendation is not approval.
   - **Superseded** means a later accepted ADR replaces it, with links in both
     directions. Preserve the earlier record as immutable history.
5. Present a recommendation as an option for the human decision authority. Do not
   change a proposed ADR to accepted, or create the canonical ADR, until that human
   authority confirms the action and the exact decision text.

## Truth and uncertainty rules

Label each claim as observed, inferred, unknown, stale, or contradictory. Observed
means the cited source directly supports it; inferred means reasoning from cited
facts; unknown means the evidence is absent; stale means the source may no longer
represent the decision context; contradictory means credible sources disagree.

Never invent dates, metrics, owners, intent, money, percentages, causes, status, or
evidence. Do not turn an inference into a constraint or an unknown into a risk score.
State which source would resolve each material unknown and do not hide disagreement
behind a single confidence number.

## Output contract

Return a decision brief or ADR containing:

- decision question, scope, constraints, as-of date/time, and decision authority;
- a source ledger with source, source date, citations, and freshness;
- alternatives, consistent comparison criteria, evidence-backed trade-offs, and
  confidence;
- state as Proposed, Accepted, or Superseded, with the approval or successor link
  required by that state;
- unknowns and contradictions, including their effect on the recommendation;
- implementation consequences and follow-up evidence, if known; and
- a clearly labelled recommendation that is not a human decision.

## Safety and write boundaries

The default is read-only. A write requires a preview of exact destination and content,
then explicit confirmation from the human decision authority before creation or
modification. Do not edit source code, configuration, tickets, or an accepted or
superseded ADR as part of this review. Do not claim that a proposed option is adopted
or send implementation instructions as if they were approval.

Keep ADR history append-only. If a historical record is wrong, preserve it and
propose a correction or successor for human review; never erase the evidence of the
earlier state. Recommendations are not human decisions, and no external action is
authorized by this skill alone.

## Verification and recovery

Before writing, read back the preview and reconcile the state, decision text,
authority, source citations, option links, and destination. After a confirmed write,
read back the persisted ADR and reconcile it with the approved preview and its
successor or predecessor links. Check that no unsupported date, status, or evidence
appeared.

If a read, write, or reconciliation check fails, stop and report the exact failure,
partial state, and missing evidence. Do not retry blindly or overwrite history.
Recover by re-reading the destination and source ledger; only a human-authorized
append, correction, or superseding ADR may resolve a partial or contradictory record.