Review agent should cross-reference ADRs cited in PR descriptions to validate implementation compliance

[fullsend-ai-retro]

What happened

On PR #2954, human reviewer ralphbean caught that the migrate-customizations command was placed under fullsend admin instead of fullsend agent, violating ADR-0058 which specifies agent management commands belong under the agent subcommand tree. The PR description explicitly referenced ADR-0064, and ADR-0058 is a related architectural decision governing CLI structure. The fullsend-ai-review bot ran 18 times and never flagged this CLI placement issue despite it being documented in a committed ADR. The human reviewer's knowledge of ADR-0058 was the key differentiator.

What could go better

The review agent does not read or cross-reference ADR documents when reviewing feature implementations, even when the PR description explicitly cites an ADR by number. Human reviewers have internalized these architectural decisions; the agent has no mechanism to access them during review. This is a missing-context gap: the information exists in the repo (as committed ADR files) but the review agent does not consult it.

Proposed change

Add a review sub-agent step or repo-level skill that extracts ADR references from PR descriptions and commit messages (pattern: ADR-NNNN or docs/ADRs/NNNN-*.md), reads the referenced ADRs plus any ADRs they cross-reference, and validates that the implementation is consistent with stated requirements. For this specific case, reading ADR-0064 would have surfaced ADR-0058 (referenced in the deprecation context), which states agent management commands go under fullsend agent. This could be implemented as a skill in .claude/skills/ that the review agent automatically picks up, or as an enhancement to the pr-review skill's sub-agent dispatch logic.

Validation criteria

On the next 5 PRs that reference ADRs in their description, the review agent should read the cited ADRs and flag any implementation choices that contradict ADR requirements. Validate by checking review agent transcripts for ADR file reads and corresponding findings. Success means the agent catches at least one ADR compliance issue it would have previously missed.

---

Generated by retro agent from #2954

[fullsend-ai-triage]

🤖 Finished Triage · ✅ Success · Started 9:48 PM UTC · Completed 9:51 PM UTC
Commit: 0a95cac · View workflow run →

[fullsend-ai-triage]

Triage Summary

Severity: Medium · Category: Feature

Problem

The review agent does not consult ADR documents when reviewing PRs, even when those PRs explicitly cite ADRs by number. On PR #2954, the review agent ran 18 times without catching a CLI placement violation documented in ADR-0058, which was transitively referenced from the cited ADR-0064. A human reviewer had to catch it.

Root Cause

The review sub-agent pipeline has no step to extract ADR references from PR metadata and load the referenced content into review context. The architectural decisions are committed and available but never read during review.

Recommended Approach

Add a review sub-agent or skill step that:

1. Extracts ADR references from PR description and commit messages (pattern: ADR-NNNN or docs/ADRs/NNNN-*.md)
2. Reads the referenced ADRs plus any transitively cross-referenced ADRs
3. Validates that implementation choices are consistent with ADR requirements

Related issues that could share infrastructure:

• Enhance review agent to cross-reference superseded ADRs in docs reviews #1568 — cross-reference superseded ADRs in docs reviews
• Review agent should verify implementation against ADR rejected alternatives #2812 — verify implementation against ADR rejected alternatives

Proposed Test Case

Scenario: Review agent detects ADR compliance violation
  Given a PR whose description references ADR-0058
  And the PR places a new agent management command under `fullsend admin`
  When the review agent runs
  Then it reads ADR-0058 and flags the CLI placement violation

Edge cases:
  - Transitive ADR references (ADR-0064 → ADR-0058)
  - Nonexistent ADR number (graceful handling)
  - No ADR references in PR description (early exit, no false positives)

---

Labels: Review agent feature request targeting the harness/skills layer for ADR cross-referencing during PR review, medium priority per retro-identified gap.