docs: allow minor annotations on accepted ADRs

[ralphbean]

Summary

• Replaces the strict "immutable once accepted" ADR policy with a nuanced one
• Cross-references, short notes linking to newer ADRs, and typo fixes are now explicitly welcome on accepted ADRs
• Substantial rewrites still require a new superseding ADR
• Directs agents to use docs/architecture.md for evolving design narrative

Agents were getting confused when we'd add notes to old ADRs linking to newer related decisions. The old policy told them ADRs are frozen, so they'd resist adding navigational links. This update draws the line at the right place: annotations that help readers navigate are good, turning old ADRs into living documents is not.

🤖 Generated with Claude Code

[github-actions]

Site preview

Preview: https://3f228212-site.fullsend-ai.workers.dev

Commit: cb18f319a215698aed74de7b8910d7b18ec2c4f3

[fullsend-ai-review]

Review

Findings

Medium

• [missing-authorization] AGENTS.md — This PR modifies ADR governance policy across 6 files without a linked issue. The change relaxes the strict "frozen/immutable" ADR policy to explicitly allow minor annotations. While the change codifies existing practice (ADR 0026 and ADR 0038 already contain post-acceptance annotations), non-trivial policy modifications benefit from a linked issue that captures the rationale and any discussion about the scope of allowable annotations.

• [stale-doc] docs/problems/architectural-invariants.md:112 — The supersession description says "its content remains unchanged (ADRs are point-in-time records)", which contradicts the new policy that explicitly allows minor annotations. This doc was not updated in the PR.
  Remediation: Update to clarify that minor annotations are allowed while substantial rewrites are not, e.g., "but its content is not substantially rewritten (ADRs are point-in-time records that may receive minor annotations)."

Low

• [ambiguous-phrasing] skills/renumber-adr/SKILL.md:131 — "Substantial ADR content is not rewritten once accepted" is ambiguous — "Substantial" reads as modifying the noun "content" (i.e., only important content is protected) rather than the verb "rewritten." Every other file in this PR uses the clearer "do not substantially rewrite" construction.
  Remediation: Rephrase to "ADR content is not substantially rewritten once accepted; this skill only fixes numbering."

• [scope-definition] skills/writing-adrs/SKILL.md — The new policy introduces "substantial rewrites" vs. "minor annotations" but the boundary between them is left to judgment. The examples (cross-references, short notes, typo fixes) are helpful but edge cases remain (e.g., is adding a full paragraph linking to a related ADR "minor"?). Consider adding a couple of boundary examples to the "Stop if" section.

Info

• [stale-doc] docs/ADRs/0018-scripted-pipeline-for-multi-agent-orchestration.md:21, docs/ADRs/0029-central-token-mint-secretless-fullsend.md:23 — These accepted ADRs still carry the old HTML comment saying "content is frozen." Updating them to match the new template comment would itself be a minor annotation permitted under the new policy. Only 2 of 42 ADRs are affected.

Previous run

Review

Findings

High

• [incomplete-scope] AGENTS.md:33 — The PR updates ADR policy in the template and writing-adrs skill but does not update AGENTS.md, which still states: "its Context, Decision, and Consequences sections are frozen. Do not add post-decision notes, rewrite rationale, or edit consequences in place." This directly contradicts the new policy that explicitly welcomes "short notes that connect the ADR to newer decisions or clarifications." Since AGENTS.md is the primary instruction file for agents working with ADRs, this creates conflicting directives — agents following AGENTS.md will reject the very annotations the new policy encourages.
  Remediation: Update the AGENTS.md "Immutability" section (lines 33–37) to distinguish between prohibited substantial rewrites and acceptable minor annotations (cross-references, short notes, typo fixes), consistent with the updated template and skill.

Medium

• [stale-doc] CONTRIBUTING.md:84 — States "Once accepted, their content is frozen — do not edit the Context, Decision, or Consequences sections" which contradicts the new policy allowing minor annotations.
  Remediation: Update to reflect the nuanced policy: point-in-time records that can receive minor annotations but should not be substantially rewritten.

• [stale-doc] docs/architecture.md:6 — States "ADRs are point-in-time records and are not modified after acceptance" which is now inaccurate. The new policy allows minor modifications while prohibiting substantial rewrites.
  Remediation: Update to: "ADRs are point-in-time records that can receive minor annotations but are not substantially rewritten after acceptance."

• [stale-doc] skills/renumber-adr/SKILL.md:131 — States "ADR content is immutable once accepted" which contradicts the new policy.
  Remediation: Update to clarify that substantial modifications are prohibited but minor annotations are acceptable.

Low

• [stale-doc] docs/ADRs/0018-scripted-pipeline-for-multi-agent-orchestration.md:21 — Contains the old HTML template comment ("content is frozen") which now contradicts the updated template. The same applies to docs/ADRs/0029-central-token-mint-secretless-fullsend.md:23. Under the new policy, updating these comments would itself be an acceptable minor annotation.

• [table-formatting] skills/writing-adrs/SKILL.md:219 — New table entries "Not adding cross-references to related ADRs" and "Using old ADRs as evolving design docs" use a different phrasing pattern than existing mistake entries. Consider "Omitting cross-references" and "Treating old ADRs as evolving design docs" for parallel structure.

• [missing-authorization] docs/ADRs/0000-adr-template.md — Non-trivial policy change (106 changed lines across 2 files) has no linked issue. The PR body provides clear rationale, but a linked issue would document the decision trail for this policy shift.

[fullsend-ai-review]

See the review comment for full details.

[fullsend-ai-review]

[low] table-formatting

New table entries 'Not adding cross-references to related ADRs' and 'Using old ADRs as evolving design docs' use a different phrasing pattern than existing mistake entries. Consider 'Omitting cross-references' and 'Treating old ADRs as evolving design docs' for parallel structure.

[ralphbean]

Fixed in cb18f31 — "Omitting" and "Treating" now.

[ralphbean]

Pushed cb18f31. The original PR only updated the template and the writing-adrs skill but left the old strict-immutability language in AGENTS.md, CONTRIBUTING.md, architecture.md, and the renumber-adr skill — so agents would've gotten contradictory instructions depending on which file they read first.

All five files now use the same "minor annotations welcome, substantial rewrites prohibited" framing. Also fixed the table entry phrasing for parallel structure.

Skipped the old HTML comments in ADRs 0018/0029 — those are cosmetic and can be cleaned up whenever someone's in the neighborhood.

[fullsend-ai-retro]

🤖 Retro · Started 3:38 PM UTC
Commit: d0ac11b · View workflow run →

[fullsend-ai-retro]

Retro: PR #1966 — docs: allow minor annotations on accepted ADRs

Workflow went well — no new proposals.

This was a human-authored PR (ralphbean) that relaxed the ADR immutability policy to allow minor annotations like cross-references and typo fixes. The review agent delivered genuine value:

1. Review caught a real issue. The initial commit only updated 2 of 6 files that reference ADR immutability, leaving contradictory instructions in AGENTS.md, CONTRIBUTING.md, architecture.md, and the renumber-adr skill. The review agent flagged this as High severity ([incomplete-scope]) and requested changes.
2. Human acted on feedback. A follow-up commit aligned the language across all remaining files.
3. Second review run acknowledged fixes. The High and Medium scope findings were resolved; only lower-severity items remained (missing linked issue, stale HTML comments).
4. Human approved and merged. The requires-manual-review label was appropriately applied since the PR touched agent configuration files (AGENTS.md, skills/).

Minor edge cases already tracked by existing issues:

• Review agent not updating its CHANGES_REQUESTED verdict after fixes → Review agent should not re-request changes for unchanged findings #1500, fullsend-ai-review bot does not revoke stale APPROVED reviews on subsequent commits #827, Review agent should honor explicit author dismissals of findings #1672
• Severity calibration for human-authored PRs → Review agent: downgrade protected-path severity for human-authored PRs #1551, Extend retro skip guard to human-authored PRs with no-finding reviews #1675
• Out-of-diff findings influencing verdict → Out-of-diff findings should not escalate review verdict #1446
• Incomplete scope detection patterns → Code agent: analyze all usage sites before implementing, not just the one in the issue #1214, Code agent: add scaffold layered-dirs pattern to agent context for multi-site updates #1255

No new proposals needed — the pipeline worked as designed.

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 3:38 PM UTC · Completed 3:44 PM UTC
Commit: d0ac11b · View workflow run →