Adr Check

adr-check

Validates ADRs against references/adr-check-contract.md. Modes: Global (all ADR dirs + diff warnings), Scoped (file/dir/query — no diff noise), Diff (changed ADRs on branch). Outputs structured pass/fail report.

Step 1 — Determine mode and discover inputs

1. Inspect skill arg:

   • No arg → mode = global. Run dir discovery (steps 2–6).
   • Arg = .md file → mode = scoped_file, target = <path>. Skip dir discovery. Checks 2.2, 2.3, Step 4 skipped.
   • Arg = directory → mode = scoped_dir, target = <directory>. Skip CLAUDE.md discovery. Use target as sole adr_dirs entry. Run Checks 2.1, 2.1e, 2.2, 2.3. Skip Step 4.
   • Any other non-empty arg → mode = scoped_query, query = <arg>. Run dir discovery. Match ADR files via model judgment. Run Checks 2.1 and 2.1e only. Skip 2.2, 2.3, Step 4. No matches → emit advisory warning, exit PASS.

2. (global/scoped_query) Read project CLAUDE.md.

3. (global/scoped_query) Search for heading containing ADR Locations (case-insensitive).

4. (global/scoped_query) If found, collect bullet items as relative paths, strip inline # comments. Store as adr_dirs.

5. (global/scoped_query) If not found, fall back: scan repo root for docs/adrs/, decisions/, architecture/decisions/.

6. (global only) adr_dirs empty → output report Mode: Global, emit WARNING: No ADR directories found. Skipping validation., set Overall: PASS, stop.

Step 2 — Validate each directory

For each dir in adr_dirs, run checks below. Track failures as issues.

Check 2.1 — ADR file structure

1. List files matching NNNN-*.md (1+ digits, hyphen, any chars, .md).
2. For each ADR file, verify: a. Status present/non-empty: Line matching **Status:** or ## Status with non-empty value. Else: [ADR-NNNN] Missing or empty Status field b. Context non-trivial: ## Context body has ≥1 non-blank non-placeholder line (not solely whitespace, TODO, TBD, or template guidance). Else: [ADR-NNNN] ## Context section is empty or contains only placeholder text c. Decision non-trivial: Same for ## Decision. Else: [ADR-NNNN] ## Decision section is empty or contains only placeholder text d. Consequences present: ## Consequences section exists (content may be brief). Else: [ADR-NNNN] ## Consequences section is missing e. Consequences quality (style): Model judgment — ≥1 genuinely adverse outcome (risk, trade-off, migration cost, complexity increase, regression, reduced flexibility, or explicit statement of what's given up). If absent, style warning (not structural): [ADR-NNNN] Consequences section contains no clearly adverse consequence or trade-off — consider adding one for credibility. Style warnings don't affect pass/fail.

Check 2.2 — Index sync (whole-dir mode only)

1. If <dir>/README.md missing: issue README.md index is missing from <dir>. Skip index checks for this dir.
2. Parse README.md table: extract all ADR filenames/numbers linked in table.
3. Each ADR file w/o table entry → issue: [ADR-NNNN] ADR file exists but has no entry in README.md index
4. Each table entry w/o matching file → issue: [index entry] README.md references <filename> but file does not exist (orphaned entry)

Check 2.3 — Cross-reference integrity (whole-dir mode only)

1. ADR with status Superseded by ADR-NNNN: a. Verify NNNN-*.md exists. Else: [ADR-MMMM] Status says "Superseded by ADR-NNNN" but ADR-NNNN does not exist b. Verify referenced ADR contains Supersedes: ADR-MMMM. Else: [ADR-NNNN] Missing "Supersedes: ADR-MMMM" back-reference
2. ADR with Supersedes: ADR-NNNN: a. Verify NNNN-*.md exists. Else: [ADR-MMMM] References "Supersedes: ADR-NNNN" but ADR-NNNN does not exist b. Verify ADR-NNNN status is Superseded by ADR-MMMM. Else: [ADR-NNNN] Expected status "Superseded by ADR-MMMM" but found different status

Step 3 — Build the validation report

Separate Check 2.1e items into style_warnings (not structural, don't affect status).

Per validated target: structural issues (2.1a–2.1d) present → FAIL, else PASS.

Output report (header rows always present):

ADR Check Report
================

Mode:    Global | Scoped (file) | Scoped (directory) | Scoped (query)
Target:  <path, directory, or natural-language query>
ADRs:    <comma-separated list of all validated ADR filenames>

Results
-------
<path/to/directory-or-file>:
  Status: PASS | FAIL
  Issues:
    - [ADR-NNNN] <issue description>

<path/to/next-item>:
  Status: PASS
  Issues: none

Style Warnings (advisory only — not gate-blocking)
===================================================
  - [ADR-NNNN] <style warning message>

Overall: PASS | FAIL

Global/scoped_dir → group by dir. scoped_file/scoped_query → each file own entry.

Style Warnings section omitted if empty.

Any entry FAIL → Overall: FAIL. On FAIL, append Remediation section (each issue + fix action).

Step 4 — Diff-based warnings (Global only — skip all scoped sub-modes)

1. Run git diff HEAD.

2. Scan for:

   Pattern	Warning
   + lines defining new ABC/interface (Python class Foo(ABC), abstractmethod, Java/TS interface, Go interface with multiple methods, TS abstract class)	"New interface/ABC detected in <file> — consider documenting the design decision with /adr-create"
   + lines in new file matching *Config*, *Settings*, *Configuration* (case-insensitive)	"New configuration file <file> — consider documenting configuration decisions with /adr-create"
   + lines in package.json (deps/devDeps), pyproject.toml ([tool.poetry.dependencies]/[project]), Cargo.toml ([dependencies]), go.mod (require)	"New dependency added in <file> — consider documenting the technology choice with /adr-create"
   New root/top-level dir named service, module, component, pkg, lib, api, or gateway	"New service/module boundary <dir> — consider documenting the architectural boundary with /adr-create"

3. Warnings found → append to report:

   Diff-Based Warnings (advisory only — not gate-blocking)
   ========================================================
     - [WARNING] <message>
   

   No warnings → omit section.

Step 5 — Output and exit

Print full report.

• PASS (with/without diff/style warnings): success. Gate consumers continue.
• FAIL: failure. Gate consumers block; present remediation to user.

Additional Resources

• references/adr-check-contract.md — Full contract: discovery rules, checks (2.1–2.3, 2.1e), report format, pass/fail semantics, invocation modes.