ADR Check

ADR Check

Category: Quality Last Updated: December 24, 2025

---

Purpose

Validate code changes against Spaarke's Architecture Decision Records (ADRs) before committing. This skill helps developers identify architectural violations early, ensuring code aligns with established constraints.

---

Applies When

• Developer asks to "check ADRs", "validate architecture", or "review changes against ADRs"
• Before creating a pull request
• After making significant code changes
• When reviewing code for architectural compliance
• NOT for general code review (use code-review skill instead)

---

Workflow

Step 1: Identify Scope

Determine what code to validate:

1. If files specified: Check those specific files
2. If no files specified: Check recent git changes

   git status --short
   git diff --name-only HEAD~1
   

3. If scope unclear: Ask developer to clarify

Step 2: Load ADR Context

1. Use the ADR index as the source of truth: docs/​reference/​adr/​README-ADRs.md
2. Use references/​adr-validation-rules.md for grep/​pattern-based checks (where available)

Quick reference of key constraints:

Note: This table is not exhaustive. Validate against the full ADR index in docs/​reference/​adr/​README-ADRs.md.

Step 3: Run Validation Checks

For each applicable ADR:

1. Search codebase using grep/​find patterns from references/​adr-validation-rules.md
2. Categorize findings as Compliant, Warning, or Violation
3. Note specific file paths and line numbers

Step 4: Generate Report

Output structured report using the format in Output Format section.

Step 5: Suggest Fixes

For each violation:

1. Explain why it violates the ADR
2. Provide concrete fix with code example
3. Reference the ADR document for full context

---

Conventions

• Always check all ADRs in the current ADR index (docs/​reference/​adr/​README-ADRs.md)
• Report warnings for potential issues that need human judgment
• Provide specific file paths and line numbers for violations
• Reference ADR documents by full path: /​docs/​reference/​adr/​ADR-XXX-*.md
• Suggest running ArchTests after fixes: dotnet test tests/​Spaarke.ArchTests/​Spaarke.ArchTests.csproj

---

Resources

---

Output Format

## ADR Validation Report

**Scope:** [files/​changes being validated]
**Date:** [timestamp]

### ✅ Compliant ADRs

- ADR-001: Minimal API + BackgroundService
- ADR-007: Graph isolation
- [list all compliant ADRs]

### ⚠️ Warnings (Review Required)

- **ADR-010:** Found [N] interfaces with single implementation
  - `src/​server/​Services/​IFooService.cs` → `FooService.cs`
  - **Recommendation:** Consider registering `FooService` directly unless testing seam needed

### ❌ Violations (Must Fix)

- **ADR-007:** Graph types found outside Infrastructure layer
  - **File:** `src/​server/​api/​Sprk.Bff.Api/​Api/​FileAccessEndpoints.cs:42`
  - **Code:** `Microsoft.Graph.DriveItem item = ...`
  - **Fix:** Replace with `FileHandleDto` and route through `SpeFileStore`

### Summary

| Status | Count |
|--------|-------|
| ✅ Compliant | [N] |
| ⚠️ Warnings | [N] |
| ❌ Violations | [N] |

### Next Steps

1. Fix violations listed above
2. Review warnings with team if needed
3. Re-run validation: invoke `adr-check` skill
4. Run NetArchTest: `dotnet test tests/​Spaarke.Bff.Api.ArchTests/`

---

Examples

Example 1: Check recent changes

Input:

Developer: "Check my changes against ADRs before I commit"

Output: Claude runs git diff --name-only, identifies changed files, validates each against ADRs, and produces a structured report.

Example 2: Check specific file

Input:

Developer: "Validate src/​server/​api/​Sprk.Bff.Api/​Api/​DocumentsEndpoints.cs against ADRs"

Output: Claude focuses validation on the specified file, checking for Graph types, authorization patterns, caching usage, etc.

Example 3: Full project scan

Input:

Developer: "Run a full ADR compliance check on the solution"

Output: Claude scans all source directories, producing a comprehensive report across all ADRs.

---

Error Handling

---

Related Skills

• code-review - General code quality review (not architecture-focused)
• push-to-github - Include ADR check as part of PR creation
• ci-cd - CI pipeline status and ADR validation in CI

---

CI/​CD Integration

Local vs CI ADR Validation

This skill performs local ADR validation. The same checks run in CI via GitHub Actions:

CI Pipeline ADR Checks

The sdap-ci.yml workflow runs ADR tests in the code-quality job:

- name: ADR architecture tests (NetArchTest)
  run: dotnet test tests/​Spaarke.ArchTests/​Spaarke.ArchTests.csproj

Results appear in two places:

1. PR Comments: adr-pr-comment job posts violations as PR comments
2. Test Results: Uploaded as workflow artifact adr-test-results

Weekly ADR Audit

The adr-audit.yml workflow runs weekly and:

• Creates/​updates GitHub issue with architecture and adr-audit labels
• Groups violations by ADR number
• Auto-closes issue when all violations resolved
• Provides remediation guidance

Troubleshooting CI ADR Failures

# View PR ADR check status
gh pr checks | grep -i "code-quality"

# View ADR test results
gh run view {run-id} --log --job=code-quality

# Download test results artifact
gh run download {run-id} --name adr-test-results

# Trigger ADR audit manually
gh workflow run adr-audit.yml

Local Validation Before Push

RECOMMENDED: Run this skill before pushing to catch violations early:

1. Make code changes
2. Run /​adr-check (this skill)
3. Fix any violations
4. Run NetArchTest locally for additional validation:
   dotnet test tests/​Spaarke.ArchTests/​Spaarke.ArchTests.csproj
5. Push changes
6. CI will re-run same checks

---

Tips for AI

• Be thorough: check all ADRs in the ADR index even when changes seem small
• Be thorough: check all ADRs in the ADR index, even when changes seem small
• Be specific: always include file paths and line numbers
• Be actionable: provide concrete fixes, not just problem descriptions
• When in doubt, report as warning rather than skipping
• Encourage running automated NetArchTest for additional validation