Document ADR immutability convention so agents avoid modifying accepted ADRs

[fullsend-ai-retro]

What happened

Issue #6160 asked agents to add a maintenance step for ADR-0045. The code agent produced PR #6161 on Aug 12, which added a checklist step directing agents to update ADR-0045's field tables in place. The review agent (run 32299704901 on the predecessor) approved with "Looks good to me" — zero inline comments, zero findings — and the PR was auto-labeled ready-for-merge. Seven days later, maintainer ralphbean closed it without merging, explaining that accepted ADRs should be immutable records of decisions and evolving operational details (field tables, merge rules, struct definitions) should live in a separate living document. The system then re-triaged and the code agent produced the correct approach in PR #6398, which was merged after a thorough review/fix cycle.

What could go better

The root cause is that neither the code agent nor the review agent had access to a documented convention about ADR immutability. ADRs being point-in-time records is an established software engineering practice, but it was not codified anywhere in this repo's agent-facing guidance. The code agent followed the issue description literally (add a step to update ADR-0045) and the review agent had no heuristic to flag "directing agents to modify accepted ADR content" as architecturally suspect. This wasted one full code agent cycle, one review agent cycle, and 7 days of human review latency on a PR that was architecturally wrong. Confidence is high that the missing convention was the proximate cause — the maintainer's rejection message directly articulated the principle that was undocumented. Three existing open issues touch adjacent aspects: #2948 covers plan doc immutability, #1660 addresses the review agent suggesting ADR edits, and fullsend-ai/agents#404 asks the challenger to respect ADR conventions. None of these documents the convention itself; they all presuppose it exists.

Proposed change

Add ADR handling guidance to AGENTS.md (in the agent guidance index) and to docs/contributing/writing-adrs.md (or create a section in the existing ADR contribution guide). The convention should state: (1) Accepted ADRs are point-in-time records of decisions — do not modify their substantive content after acceptance. (2) When operational details in an ADR evolve (field tables, struct definitions, merge rules, configuration examples), extract them to a living reference document under docs/contributing/ and link back to the ADR. (3) Acceptable ADR modifications are limited to: updating status fields (e.g., marking as Superseded), adding cross-references to successor ADRs or living docs, and fixing typos. This convention would give code agents the context to choose living-doc extraction over ADR modification, and review agents a heuristic to flag PRs that add evolving content to accepted ADRs.

Validation criteria

The next time a code agent is tasked with changes involving ADR content, it should prefer creating or updating a living doc over modifying the ADR body. The next time a review agent reviews a PR that adds evolving operational detail to an accepted ADR, it should flag the approach. Measure over the next 5 agent PRs that touch ADR files — none should propose adding mutable tables or implementation details to accepted ADRs without the review agent flagging the approach.

---

Generated by retro agent from #6398

[fullsend-ai-triage]

🤖 Finished Triage · ✅ Success · Started 5:41 PM UTC · Completed 5:45 PM UTC

Commit: 032e8c4 · View workflow run →

[fullsend-ai-triage]

Most of the ADR immutability convention requested here is already documented in docs/contributing/adrs.md — it covers point-in-time immutability, acceptable modifications (status changes, cross-references, typo fixes), and review-time flagging of substantive rewrites. The AGENTS.md topic index also already references this guide.

The remaining gap is the "extract to living doc" pattern: when operational details in an accepted ADR evolve (field tables, struct definitions, merge rules), agents should extract them to a living reference document under docs/contributing/ and link back to the ADR. This is exactly what PR #6398 did by creating docs/contributing/harness-fields.md, but the pattern itself is not codified in the ADR guide.

Recommended scope

• Add a paragraph to docs/contributing/adrs.md under the Immutability section covering the extract-to-living-doc pattern
• Reference docs/contributing/harness-fields.md as a concrete example
• Check skills/writing-adrs/SKILL.md for consistency

Related issues

• Add AGENTS.md guidance that implementation plan docs are historical records #2948 — plan doc immutability (adjacent, different document type)
• Review agent should not suggest adding implementation details to ADRs #1660 — review agent suggesting ADR edits (agent behavior, not documentation)
• fullsend-ai/agents#404 — challenger respecting ADR conventions

# Conceptual test: verify the guidance exists and is complete
def test_adr_extract_to_living_doc_guidance():
    adr_guide = read_file("docs/contributing/adrs.md")
    assert "living" in adr_guide.lower() or "extract" in adr_guide.lower()
    assert "docs/contributing/" in adr_guide  # points to target directory
    # Verify AGENTS.md table entry is accurate
    agents_md = read_file("AGENTS.md")
    assert "immutability" in agents_md.lower()

---

Labels: Documentation-only change to the ADR contributing guide. Medium priority — prevents wasted agent cycles but is not blocking any current work. Good first issue given its narrow, well-defined scope.

---

Next steps:

• /fs-code — agent creates a PR to implement this issue
• /fs-code <your instruction> — agent implements with your specific guidance

[fullsend-ai-coder]

🤖 Finished Code · ✅ Success · Started 5:47 PM UTC · Completed 5:53 PM UTC

Commit: 032e8c4 · View workflow run →

[fullsend-ai-prioritize]

RICE Priority Score: 3.6

Score breakdown

Dimension	Score	Reasoning
Reach	1	Affects all agents operating on this repo when they encounter ADR-related tasks, plus human maintainers who review those PRs. The issue documents one concrete incident (PR #6161) and three related open issues (#2948, #1660, agents#404) that presuppose this convention exists, indicating a moderate but recurring need across the agent ecosystem.
Impact	1	Medium — the missing guidance caused one wasted code agent cycle, one wasted review agent cycle, and 7 days of human review latency on an architecturally wrong PR. However, triage confirmed most of the convention is already documented and the remaining gap is narrow (the extract-to-living-doc pattern), so the incremental improvement is noticeable but not blocking core functionality.
Confidence	0.9	Very high — the issue is exceptionally well-described with a concrete incident, clear root cause analysis from the retro agent, and the triage agent confirmed the exact gap and narrowed scope to adding a paragraph to an existing doc. The proposed change and validation criteria are specific and actionable.
Effort	0.25	Trivial — the triage agent confirmed this is a 'good first issue' with 'narrow, well-defined scope.' The change is adding a paragraph to the existing docs/contributing/adrs.md Immutability section about the extract-to-living-doc pattern, referencing an existing example (harness-fields.md), and checking consistency with a skill file.

Formula: (1 x 1 x 0.9) / 0.25 = 3.6