Skip to content

Add an ADR proportionality gate to the architecture workflow #66

Description

@dieterbaier

Problem

AI makes drafting an ADR very cheap. That removes useful mechanical work, but it
also removes a natural friction that previously discouraged recording minor or
short-lived implementation details as architecture decisions.

The current ADR skill starts by inspecting context and drafting an ADR. It does
not first decide whether an ADR is the proportionate artifact.

This can produce a formally excellent but increasingly ceremonial architecture
record.

Goal

Add a proportionality gate before the ADR workflow starts.

An ADR should record a decision with durable architectural significance, not
merely an unusual configuration line or implementation detail.

Decision test

Before creating an ADR, ask:

Without this record, would a later contributor probably make a materially
different decision or miss an important assumption?

An ADR is normally justified when one or more of these apply:

  • reversing the decision would be costly;
  • it constrains multiple future changes;
  • it materially affects system boundaries, contracts, quality goals, risks,
    deployment or operations;
  • it establishes a cross-cutting architectural rule;
  • the rejected alternative is plausible enough that the discussion is likely to
    recur.

If none applies, prefer the smallest durable record that fits:

  • code comment for a surprising implementation detail;
  • automated test for required behaviour;
  • CONTRIBUTING.md for contributor workflow;
  • issue or commit message for local change reasoning;
  • existing architecture prose when no standalone decision is needed.

Scope

  • Add the normative proportionality rule to
    general-semantic-contracts.md, under Documenting Decisions.
  • Add an ADR eligibility step before impact analysis in
    skills/adr/SKILL.md.
  • Allow the skill to return a justified No ADR recommended result with the
    smaller documentation target.
  • Update skills/references/adr-writing-guide.md if it currently describes ADR
    selection criteria.
  • Do not add a mandatory section to templates/adr.adoc; the check belongs to
    the workflow, not to every rendered ADR.

AI responsibility

AI-generated ADRs remain proposed and reviewed: false. Cheap generation is
not evidence that a decision is ADR-worthy. Only human review may accept both the
decision and the choice to preserve it as an ADR.

Acceptance criteria

  • The ADR skill checks proportionality before drafting.
  • A configuration-only example results in No ADR recommended and proposes a
    smaller record.
  • A cross-cutting decision affecting quality goals and future changes results in
    a proposed ADR.
  • The general contract contains one canonical rule; the skill references and
    applies it without duplicating the full guidance.
  • Existing ADR templates and metadata remain backwards compatible.

Origin

Found while validating the toolkit in
dieterbaier/budget: the toolkit made
high-quality ADR creation so inexpensive that artifact proportionality became an
explicit governance concern.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions