git:20261014.7748a1f to git:20261014.fec008f

---

name: arch-deviate

description: "Record a deliberate deviation from the guideline as an ADR under docs/adr/: the rule quoted, the decision, the consequences. Use when a finding is accepted as intentional."

allowed-tools: Read, Grep, Glob, Write, Edit, Bash(date:*)

---

# arch-deviate

A project that follows the guideline may still need to diverge from a

rule. The divergence is recorded, not argued about in review threads:

one ADR quotes the rule, states the decision, and names what the

project accepts in exchange. A breach whose ADR is cited next to the

code is a documented exception. A review reports it on one line under

Deviations. It is not a finding, and it never lowers a severity.

## Input

The arguments name the rule being deviated from, as a lens id

(`STO-02`), a section by title (`The Storage Layer, Storage

Principles`), or a sentence describing it, optionally followed by a

one-line reason. A technology substitution (an equivalent in place of

a technology the guideline names) is not a deviation and is recorded

in the project's technology-choices ADR instead (in a copy, its own,

never the scaffold's), as the guideline's

"Technology Choices and How to Override Them" section states; when

the arguments describe one, say so and stop. Ask in one

message for what is missing: the reason, the scope of the deviation

(which namespace, service, or table), and whether it is permanent or

has a condition for ending.

## Procedure

1. Resolve the rule: find the lens in `../../lenses/` and the section in

`../../architecture.md`, paths from this skill's folder as `realpath`

resolves it. Quote the principle verbatim. When the rule itself

allows what the arguments describe, there is nothing to record: say

so, quote the words that allow it, and stop. A manager interface

kept whole past its count because its operations are one duty is

such a case (CON-01): a review's pass names it.

2. The ADR goes under `docs/adr/`, created when it does not exist:

`arch-check` refuses a deviation whose `adr` is anywhere else. Number

the new record as one more than the highest numeric prefix present

(`NNNN-<slug>.md`), except in a copy of the scaffold: a project whose

`docs/adr/` holds records under file names of

`../../scaffold/acme_root/docs/adr/`, most of them or all. The

scaffold itself is not a copy: its records stay below 1000. A copy's

own records go from 1001 (Records of Decisions): count only the

prefixes at 1001 or above, and take 1001 when there is none. Refuse

to write a path that already exists.

3. Take the date from `date +%F`: the ADR records the day the decision

is made, which is today, not the day of the last commit.

4. Write the ADR with the template below, under `docs/adr/` only.

Keep it under one page.

5. When `specs/architecture.md` exists and has a `## Deviations` table,

append one row: the ADR number, the rule, and a one-line summary.

6. An `arch-check` entry goes only with a finding the checker

reports. The lens's `Check` line says which part that is: the whole

lens when it reads "decides it", and only the part it names when it

ends "the rest is judged". What the line says the checker names as

no finding, under `to_judge`, is judged too. A deviation in a

judged part, or under a lens with no `Check` line, gets no entry

and no inline comment: the checker reports nothing there, and an

entry that matches no finding is itself a finding that fails the

gate. The ADR, the Deviations row, and the citation beside the code

are its record. For a deviation in the part the checker decides,

the ADR alone does not pass the gate: the checker still fails on

the code. Give it the entry that names the ADR, in the shape

`checkers/README.md` in this plugin shows

(`../../checkers/README.md`, Exceptions); the rule id is the lens

id. A whole rule turned off

is a `[[tool.arch-check.disable]]` entry with `rule`, `adr` (the

ADR's path), and `reason`. A rule

broken in some files is a `[[tool.arch-check.exception]]` entry

with `rule`, `path` (a glob), `adr`, and `reason`. One line is the

inline comment `# arch-check: ignore[<LENS-ID>] ADR-NNNN` at the end

of that line. Append a table entry to the root `pyproject.toml` when

it has a `[tool.arch-check]` table, and print it otherwise. Print

the inline comment and never place it: which line it goes on is the

person's call. The checker resolves an inline comment only to

`docs/adr/NNNN-*.md` with a four-digit number. When the folder's

records are numbered otherwise, give only the table entry, and say

why. Its `adr` still names a Markdown file under `docs/adr/`: the

checker refuses any other path.

7. Whatever the lens, tell the person to cite `ADR-NNNN` in a comment

beside the code that deviates. A review reports the code under

Deviations, and not as a finding, only when the ADR is cited there.

Do not commit. Do not edit the guideline or the lenses; a deviation

belongs to the project, not to the rule. Edit nothing but the ADR

folder, the deviations table, and the `[tool.arch-check]` entry.

## Output

The path of the new ADR, the row appended to the deviations table (or

"no deviations table"), the `arch-check` entry written or printed (or

"judged by review only" when the checker decides no part the deviation

is in), the

reminder to cite `ADR-NNNN` beside the code, and the one-line summary

for the reviewer. Nothing else.

## ADR template

```markdown

# ADR NNNN: <title that names the deviation>

**Status**: accepted (<date>)

## Context

<The rule: lens id, section, and the principle quoted verbatim. Why it

does not fit here. Facts, not preferences.>

## Decision

<What the project does instead, in the present tense. Where it applies.

Whether it is permanent or ends when a named condition holds.>

## Consequences

<What the project accepts: the guarantee it gives up, the test or check

that stands in for it, the reviews that must treat the cited code as an

exception.>

```