willianbs Purpose
Make ADRs the authority for architectural choices. Detect conflicts before code hardens the wrong pattern.
When to Use / When NOT to Use
Use when: feature touches structure/patterns/deps; delivery-planner emits ADR triggers; review suspects drift; greenfield with no ADRs.
Do not use when: pure style nits; bugfix with no architectural impact.
Preconditions
Task or change set identified. If no ADRs found → enter bootstrap mode (do not pretend compliance).
Inputs / Outputs
Inputs: proposed change / plan / diff, CONTEXT_PACK.
Outputs: ADR_COMPLIANCE
Upstream / Downstream
Upstream: context-loader, spec-validator, delivery-planner, code-reviewer, quality-gate.
Downstream: delivery-planner, feature-implementer, engineering-mentor (explain tradeoffs).
Core Principles
- ADRs win over preference.
- Unknown compliance is not approval.
- Conflicts Block until a superseding ADR is drafted/approved.
- Prefer existing patterns over new frameworks.
- Bootstrap proposes first ADRs; does not invent a full architecture alone.
- Drift is a first-class finding.
- Do not rewrite ADR files unless the user explicitly asks.
Process
Discovery algorithm
Search in order; stop when found:
docs/adr/,adr/,docs/architecture/decisions/- Files matching
**/ADR*.md,**/*adr*.md - Links from
ARCHITECTURE.md/ README - Index files (
READMEinside adr dirs)
Record paths + IDs/titles + status if present (accepted, superseded, proposed).
Evaluation
- Map change to relevant ADRs.
- Compliance matrix: requirement → ADR → Compliant / Gap / Conflict / Unknown.
- Detect new patterns, deps, or layers not covered by ADRs.
- If Conflict → Decision
Block; list required superseding ADR outline (title, context, decision, consequences)—do not auto-write the ADR file. - If NoADRs → bootstrap: propose 1–3 minimal ADR outlines for decisions the change forces; status
NoADRs/ProceedWithConditions.
Evidence Requirements
Cite ADR path + clause. Cite code paths that drift.
Stop Conditions / Failure Modes
| Condition | Action |
|---|---|
| Conflict with accepted ADR | Block |
| Unknown whether ADR applies | CompliantWithGaps or Block for HighRisk |
| No ADRs + HighRisk change | ProceedWithConditions only with bootstrap ADR outlines approved by user |
Severity + Confidence
Conflict with accepted ADR on security/data boundaries → Critical/High.
Output Contract
## ADR_COMPLIANCE
Status: Compliant | CompliantWithGaps | Conflict | NoADRs | Blocked
Checked ADRs: ...
Violations: ...
Required new ADRs: ...
Bootstrap outlines (if NoADRs): ...
Decision: Proceed | ProceedWithConditions | Revise | Block
Handoffs
- delivery-planner — after compliance known
- feature-implementer — only if Compliant / CompliantWithGaps with conditions
- code-reviewer / quality-gate — consume this report; do not re-litigate ADRs shallowly
Never
- Never auto-modify ADR files without explicit user request.
- Never approve Conflict as “temporary.”
- Never invent a complete architecture under NoADRs—only the decisions forced by the change.