arch-deviate git:20260930.d863924A

Immutable. This exact content never changes and is served at /api/v1/blob/4aec0669a248bd26.

---
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, 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`). 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.>
```