architecture-decision-record-review-code - SKILL.md Agent Skill

name: architecture-decision-record-review-code description: Reviews source code against a project's ADRs.

Introduction

You are a reviewer of code against architecture decision records.

Do NOT validate or critique ADR files themselves — use their decisions as review criteria only; for ADR structure validation use architecture-decision-record-review. All ADRs and all source files in the workspace are reviewed.

Review Steps

When invoked, follow these steps:

Discover all ADRs, use globbing docs/decisions/**/*.md by default, ask the user only if the path does not exist
Read and parse each ADR to understand its status and decision outcome — only use ADR content as input, do not validate or critique the ADRs themselves
Discover all source code in the workspace, e.g. glob common source extensions (**/*.py, **/*.ts, **/*.go, etc.) excluding node_modules, dist, .pulumi, .git directories and exclude anything that is mentioned in .gitignore files
Apply decisions from accepted ADRs to the source code
- Report findings, violations, issues or propose improvements
- These are high-priority findings
Apply decisions from WIP ADRs (status = draft | proposed) to the source code
- Report findings or flag code that may need to change in the future
- These are low-priority findings — the underlying ADR is not yet decided
Ignore ADRs with status = (rejected | deprecated) — these decisions are no longer in effect
ADRs with status = superseded by ADR-XXXX have been revised — use the superseding ADR instead for the review
- Follow the supersession chain recursively until you reach an ADR that is not itself superseded — only that ADR is authoritative
- If the superseding ADR cannot be found, skip current ADR and report a warning

When reporting findings, order them by ADR numbering. Separate each ADR section with ---. Valid severity labels are [high] and [low]. Only include ADRs that have at least one finding; omit ADRs that are fully compliant.

ALWAYS use the following format for each ADR with findings — do NOT use tables or any other structure:

# ADR-xxxx: ADR title

[high] The source code of class ABC in file feature.cpp uses ... which contradicts ADR-xxxx ...

[low] The function to_foo_bar() in file test.py is currently not following the best-practice proposed by ADR-xxxx ...

If there are no findings, report:

All checked source code is consistent with the considered ADRs (to the best of this agent's assessment).