convergence-check

Files (1)

• SKILL.md

SKILL.md (first lines)

# Convergence Check

## Purpose

A change is finished when its artifacts agree. Each one is reviewed on its own —
the issue at refinement, the scenario at specification, the ADR at decision, the
diff at review — and nothing looks across them at the end. Drift between two
individually correct artifacts is what this check exists to find.

It is a **gate**, not a phase. It adds no work of its own: it inspects what the
other skills already produced and reports whether it holds together.

## What it is not

- **Not a demand that artifacts say the same thing.** They sit at different
  abstraction levels and are supposed to. An issue states intent, a scenario
  states behaviour, an ADR states a decision and its cost. Convergence means no
  contradiction and no missing mandatory evidence, not repetition.
- **Not a repair tool.** A failed check produces findings and follow-up actions.
  It must never rewrite an accepted requirement, soften a recorded decision, or
  retarget a relation in order to make the artifacts agree. Making the evidence
  fit the conclusion is the failure this check is supposed to catch.
- **Not proof.** Only the deterministic tier proves anything. See
  "Automation boundary".

## When to run it

At least once, at the end:

- before a pull request is declared mergeable, and
- before an implementation issue is treated as complete.

Running it earlier is fine and cheap, but an early pass is not a result: the
artifacts it inspects are not all final yet.

## Every question must be able to fail

Before answering a question, know what evidence would make it fail for **this**
change. A question that cannot fail here is **not applicable**, and it is
reported as such.

Do not report a question as passed when it never had a way to fail. That is the
same defect as a scenario written to be green against unfixed code: a guard with
no failure path is worse than an absent guard, because it reads like coverage.

**Not applicable is not the same as blocked.** A question is *not applicable*
when it has no bearing on this change — nothing touched the deployment view, so
there is nothing there to contradict. It is an *unavailable blocker* when it does
bear on the change but cannot be answered at this layer. The first needs no
follow-up; the second does. See "Every blocker names its kind".

## The seven questions

### 1. Intent and scope

- Does the implemented change still match the Epic or UserStory it came from?
- Is every scope change reflected in the issue and the specification, rather
  than only in the diff?

### 2. Behaviour

- Is every added or changed observable behaviour described by a Gherkin
  scenario, or covered by an explicit recorded waiver?
- Is each scenario mapped to at least one automated verification under the
  bridge convention?
- Does any implemented edge case contradict the specification?

`../bdd-specification/SKILL.md` owns these rules. This check asks whether they
were met; it does not restate what a scenario or a bridge must look like.

### 3. Architecture impact

- Were the affected boundaries, components, interfaces, dependencies, runtime
  interactions, deployment elements, quality attributes, risks and constraints
  assessed?
- Were only genuinely affected architecture artifacts changed? Collateral
  updates to unaffected documents are a finding, not tidiness.

`../architecture-impact/SKILL.md` owns the assessment.

### 4. Decisions

- Are conflicts with existing ADRs resolved rather than left implicit?
- Is every architecture-significant decision recorded as an ADR, instead of
  living only in code or pull request discussion?
- Are the decisions that still need a human explicit?

Apply the proportionality rule from `../adr/SKILL.md`: a decision that does not
warrant an ADR is not a finding, and a missing ADR for a decision that does is.

### 5. Traceability

- Can the path from Epic or UserStory through specification and architecture
  impact to implementation, tests and pull request be followed?
- Are the authoritative outgoing relations valid, and were the derived views
  regenerated?

`../traceability-review/SKILL.md` owns relation review.

### 6. Implementation and verification

- Do code and configuration implement the specified behaviour and the recorded
  decisions?
- Do the relevant tests, validators, generators, render checks and builds pass?
- Are unavailable checks and residual risks reported rather than omitted?

### 7. Documentation and delivery state

- Do the issue, the pull request, the source documentation and the code describe
  the same resulting state?
- Are superseded assumptions and stale references removed, or explicitly kept
  with a valid lifecycle status?
- Do deliberately deferred pieces have follow-up issues?

## Automation boundary

Three tiers, and they must not be presented as one.

| Tier | What it is | Examples |

From docs-as-code-toolkit/architecture-knowledge-toolkit, MIT.

More from docs-as-code-toolkit/architecture-knowledge-toolkit