arch-deviate git:20260929.3422014A

Immutable. This exact content never changes and is served at /api/v1/blob/21c8da36f87fa6dc.

---
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.
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. When the lens has a `Check` line naming `arch-check`, 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 lens has no `Check` line), 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.>
```