docs(#6423): document extract-to-living-doc pattern for ADRs

[fullsend-ai-coder]

Summary

Adds the "extract to living doc" convention to the ADR contributing guide and the writing-adrs skill. When operational details in an accepted ADR evolve (field tables, struct definitions, merge rules, configuration examples), agents should extract them to a living reference document under docs/contributing/ and link back — rather than modifying the ADR in place.

This codifies the pattern already used by docs/contributing/harness-fields.md (which holds the evolving field tables from ADR-0045) and addresses the gap that led to the rejected PR #6161.

Changes

• docs/contributing/adrs.md: Added "Extracting evolving details to living docs" paragraph after the Immutability section. Added review heuristic to flag PRs that add evolving operational detail to accepted ADRs.
• skills/writing-adrs/SKILL.md: Added "When operational details evolve" guidance section with a concrete example. Added corresponding red flag and common mistake entries.

Testing

• Verified all linked files exist (docs/contributing/harness-fields.md, docs/ADRs/0045-forge-portable-harness-schema.md)
• Secret scan passed
• Gitlint passed
• make lint could not run due to sandbox network policy blocking pre-commit hook installation

---

Closes #6423

Post-script verification

• Branch is not main/master (agent/6423-adr-living-doc-guidance)
• Secret scan passed (gitleaks — 032e8c45469baad5228d84b4ad9000217fed8f6e..HEAD)
• PR body secret scan passed (gitleaks — no-git)

[github-actions]

Site preview

Preview: https://750e01e5-site.fullsend-ai.workers.dev

Commit: c26acd670b240428563715c9b528286d6317aabb

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 5:55 PM UTC · Completed 6:09 PM UTC

Commit: c26acd6 · View workflow run →

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[fullsend-ai-review]

Review

Findings

Medium

• [protected-path] skills/writing-adrs/SKILL.md — This PR modifies skills/writing-adrs/SKILL.md, which is under the protected skills/ path. The PR links to issue Document ADR immutability convention so agents avoid modifying accepted ADRs #6423 and explains the rationale (adding the extract-to-living-doc convention to the writing-adrs skill). Human approval is always required for protected-path changes, regardless of context.

Low

• [cross-reference gap] docs/contributing/documentation.md:21 — The "ADR annotations" section mentions supersession as the only strategy when a CLI change affects an ADR, and links to adrs.md for the full rules. Readers will discover the new extract-to-living-doc pattern by following that link, but the section could mention the pattern alongside supersession for completeness. The section is specifically scoped to CLI changes making decisions obsolete (a supersession scenario), so this is informational rather than a staleness issue.

[rh-hemartin]

Not a real consolidated pattern, instead living table will need to live in the reference part.

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 12:15 PM UTC · Completed 12:31 PM UTC

Commit: c26acd6 · View workflow run →

Runtime: claude · Model: opus → claude-opus-4-6 · Cost: $5.09

[fullsend-ai-retro]

Retro: PR #6426 — docs(#6423): document extract-to-living-doc pattern for ADRs

Outcome: Closed without merge by rh-hemartin after 6 days. Rejection reason: the proposed "extract to living doc" convention was not considered an established pattern.

Timeline

1. 2026-08-20 17:39 — Issue #6423 filed by the retro agent, proposing to document the "extract to living doc" pattern for ADRs. The issue was based on the observation that PR #6161 was rejected for modifying an accepted ADR, while PR #6398 succeeded by creating a living doc instead.
2. 2026-08-20 17:39–17:45 — Triage (run 32398825061) validated the issue and narrowed scope. Applied ready-to-code. Cost: $0.77.
3. 2026-08-20 17:46–17:53 — Code agent (run 32399418436) implemented the change: 2 files, +18/−1 lines. Clean docs-only change. Cost: $1.84.
4. 2026-08-20 17:53–18:09 — Review agent (run 32400112819) ran 5 sub-agents (3 required model-override retries). Found: medium protected-path governance (skills/ modification), low cross-reference gap (informational). Applied requires-manual-review. Cost: $3.19.
5. 2026-08-26 12:14 — rh-hemartin closed the PR: "Not a real consolidated pattern, instead living table will need to live in the reference part."

Total agent cost: ~$5.80 for a rejected 18-line docs change. Human review latency: 6 days.

Root cause

The retro agent extrapolated a general convention from a single data point. PR #6398 successfully used a living doc approach for ADR-0045's field tables, and the retro agent characterized this as "the pattern already used by docs/contributing/harness-fields.md" — but one instance does not make an established pattern worth codifying as repo-wide guidance. The triage agent reinforced this by noting the pattern was "exactly what PR #6398 did" without questioning whether one example constitutes a convention. The code and review agents executed correctly given the premise — the implementation was technically clean and internally consistent.

Pipeline observations

• Review worked as designed. The requires-manual-review label was correctly applied due to the skills/ protected-path change, ensuring human review. The review agent cannot reasonably assess whether a proposed convention has enough real-world instances to warrant documentation — that's a design judgment.
• Sub-agent model retries. Three of four review dimension sub-agents initially failed due to model availability and were re-dispatched without the model override. The retry succeeded, adding ~2–3 minutes of latency. The resilience pattern is working.
• Issue Document ADR immutability convention so agents avoid modifying accepted ADRs #6423 remains open with ready-to-code. This is an active risk — the code agent could re-dispatch and create another PR implementing the same rejected approach, wasting another ~$5+ cycle.

Evidence for existing issues

All improvement opportunities identified are already tracked by open issues. This PR provides additional supporting evidence:

• #3817 (retro generality threshold): This PR is a direct example — the retro agent proposed codifying a convention from a single instance. A generality threshold requiring ≥2 independent instances would have prevented this issue from being filed.
• fullsend-ai/agents#198 (retro files issues too eagerly): The retro agent created a well-argued but ultimately rejected issue based on insufficient evidence of a pattern.
• #3912 (label speculative proposals as needs-discussion): Issue Document ADR immutability convention so agents avoid modifying accepted ADRs #6423 proposed a new convention — a speculative/preventive change that should have been flagged for human discussion before entering the automated code pipeline.
• #5315 and #3818 (issue lifecycle after PR rejection): Issue Document ADR immutability convention so agents avoid modifying accepted ADRs #6423 still has ready-to-code despite PR docs(#6423): document extract-to-living-doc pattern for ADRs #6426 being closed without merge. This is an active re-dispatch risk.
• fullsend-ai/agents#260 (triage should not auto-promote ADR issues to ready-to-code): The triage agent auto-promoted a documentation convention issue without human validation of the premise.
• #5319 and fullsend-ai/agents#812 (retro chain detection): This retro is running on a PR that was itself generated from a retro-originated issue (Document ADR immutability convention so agents avoid modifying accepted ADRs #6423), which was generated from a retro on PR docs(#6160): extract harness field reference into living doc #6398, which was generated from a retro on PR docs(#6160): add ADR-0045 maintenance step to harness-composition checklist #6161. The chain detection proposed in these issues would reduce token spend on self-referential retro loops.

No new proposals

All identified improvement opportunities are already tracked by open issues. No new proposals are warranted.