Repository navigation
docs(#6423): keep operational details out of accepted ADRs - #7676
fullsend-ai-coder[bot] wants to merge 3 commits into
Conversation
Accepted ADRs already forbid substantial rewrites of Context, Decision, and Consequences, but that did not stop agents from adding evolving field tables or checklists that tell people to edit ADR bodies in place (PR #6161). Reviewers had no heuristic for that case. Clarify that current-state operational detail belongs in living documentation (docs/architecture.md, docs/reference/, or an existing contributing guide the ADR already links to), not in the ADR. Reviewers should flag both the tables themselves and instructions to update accepted ADR content. This is not the "extract to living doc under docs/contributing/" procedure from PR #6426. That PR was closed because living tables belong in the reference part, not as a general pattern. Note: pre-commit could not fetch remote hook repos (HTTP 403). Applicable hooks were run directly (trailing-whitespace, EOF, conflict markers, lint-docs-links, lint-broken-symlinks, lychee, scan-secrets). make lint was not run for the same reason. Closes #6423
|
🤖 Finished Review · ✅ Success · Started 2:29 PM UTC · Completed 2:41 PM UTC Commit: Runtime: pi · Model: sonnet → claude-sonnet-5 · Effort: high · Cost: $2.69 |
Site previewPreview: https://0f14f819-site.fullsend-ai.workers.dev Commit: |
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
|
Risk Assessment: moderate (2/5) DetailsSmall documentation-only follow-up fix by an established bot author matching linked issue scope, anchored to prior moderate risk due to modified protected paths (AGENTS.md, skills/) and historical churn on AGENTS.md. Previous runRisk Assessment: moderate (2/5) DetailsSmall documentation-only update by an established bot author matching linked issue scope, anchored to prior moderate risk due to modified protected paths (AGENTS.md, skills/) and historical churn on AGENTS.md. Previous run (2)Risk Assessment: moderate (2/5) DetailsSmall documentation-only update by an established bot author matching linked issue scope, with moderate risk arising from touched protected paths (AGENTS.md, skills/) and historical churn on AGENTS.md. |
ReviewFindingsMedium
Previous runReviewFindingsMedium
Low
Next steps:
Previous run (2)ReviewFindingsMedium
Low
Next steps:
|
|
🤖 Finished Fix · ✅ Success · Started 2:44 PM UTC · Completed 2:50 PM UTC Commit: Runtime: claude · Model: sonnet → claude-sonnet-5 · Effort: high · Cost: $0.89 |
The Red Flags bullet and Common Mistakes row for "evolving operational details" only named docs/architecture.md and docs/reference/, dropping the "existing contributing guide the ADR already links to" option that the overview (lines 53-56) and docs/contributing/adrs.md already list. For the field-table/merge-rule/struct-definition case this PR targets, that contributing guide is often the authoritative destination, so the omission could redirect content to the wrong place. Note: pre-commit could not fetch remote hook repos (HTTP 403, same infra issue noted in the PR description). Applicable hooks (end-of-file-fixer, trailing-whitespace, mixed-line-ending, check-merge-conflict, check-added-large-files, detect-private-key, gitleaks, lychee --offline, lint-broken-symlinks) were run directly against the changed file instead and all passed. Addresses #7676
🔧 Fix agent — iteration 1 (bot-triggered)Addressed the low-severity internal-inconsistency finding by adding the missing third living-doc destination to two spots in skills/writing-adrs/SKILL.md. Acknowledged the medium-severity protected-path finding as requiring no code change, per its own remediation — it only demands human approval before merge. Project CI is fully green; no pr-related failures found. Fixed (2):
Tests: passed CI inspections (13):
Decision points
Next steps:
|
|
🤖 Finished Review · ✅ Success · Started 2:52 PM UTC · Completed 3:11 PM UTC Commit: Runtime: pi · Model: sonnet → claude-sonnet-5 · Effort: high · Cost: $2.99 |
|
🤖 Finished Fix · ✅ Success · Started 3:13 PM UTC · Completed 3:19 PM UTC Commit: Runtime: claude · Model: sonnet → claude-sonnet-5 · Effort: high · Cost: $0.90 |
Addresses two review findings on PR #7676: - The "reviewing PRs" heuristic that flags instructions to update accepted ADR content in place never loaded for the exact PR #6161 pattern it targets, because both AGENTS.md's topic-index row and adrs.md's applicability sentence gated loading on touching docs/ADRs/. Broadened both to also trigger when a checklist, skill, or contributing guide elsewhere in the repo instructs an in-place edit to an accepted ADR. - The living-doc destination list (docs/contributing/adrs.md, skills/writing-adrs/SKILL.md overview, Red Flags, and Common Mistakes) named only docs/architecture.md, docs/reference/, and "an existing contributing guide" -- too coarse to point at this repo's actual field-table homes. Named docs/contributing/harness-fields.md, docs/contributing/harness-composition.md, and docs/normative/ explicitly, and noted that a short cross-reference annotation is how an ADR gains that link. The third review finding (protected-path edits to AGENTS.md and skills/writing-adrs/SKILL.md require human approval) needs no code change -- the merge gate already enforces it. Note: pre-commit could not fetch remote hook repos (HTTP 403, same infra issue noted earlier in this PR). Applicable hooks were run directly against the changed files instead: end-of-file-fixer, trailing-whitespace, mixed-line-ending, check-merge-conflict, check-added-large-files, detect-private-key, gitleaks, lint-broken-symlinks, lint-docs-links, and lychee --offline. All passed. Addresses #7676
🔧 Fix agent — iteration 2 (bot-triggered)Addressed the two content findings by broadening where the in-place-ADR-update review heuristic loads (AGENTS.md topic index + adrs.md applicability sentence) and by widening the living-doc destination list across adrs.md and all three spots in skills/writing-adrs/SKILL.md to name the repo's actual contributing/normative field-table homes. The third finding (protected-path) requires no code change and needs human approval at merge, per its own remediation. No pr-related CI failures found; all project CI checks are passing. Fixed (3):
Tests: passed CI inspections (12):
Decision points
Next steps:
|
|
🤖 Finished Review · ✅ Success · Started 3:22 PM UTC · Completed 3:33 PM UTC Commit: Runtime: pi · Model: sonnet → claude-sonnet-5 · Effort: high · Cost: $1.97 |
Superseded by updated review
|
This pull request has been automatically marked as stale because it has not had any activity in the last month. It will be closed in 2 weeks if no further activity occurs. Remove the |
ADR reviews (0144, 0147-0149, 0151, 0152) kept flagging the same problems. Authors met the "cite current behavior" rule with line-pinned blob/<sha>#L links in Context and Decision, which turned ADRs into code tours that went stale. Decisions repeated sibling ADRs or normative contracts. Numbers had no stated basis. Series of ADRs landed out of step with each other. Claims about current behavior still have to be checked against the code at a commit SHA. The file/function evidence now goes in the PR description, and the ADR body describes the behavior in plain prose and links the PR, issue, or ADR that introduced it. - skills/writing-adrs/SKILL.md: reword checklist step 6; extend "Link, don't repeat" to cover sibling ADRs and docs/normative/ contracts; add Red Flags for numbers with no basis and for re-checking a series after a sibling merges; add Common Mistakes rows for line-pinned links, slugs that name a rejected option, and "Planned:" status blocks in Context. - docs/ADRs/0000-adr-template.md: update the Context prompt to match. - docs/contributing/adrs.md: reviewers check claims against the evidence in the PR description and flag line-pinned links in the ADR body. - AGENTS.md: reword the ADR row to match. Edits stay within step 6, "Link, don't repeat", Red Flags, and Common Mistakes, to keep conflicts small with open PRs fullsend-ai#7356, fullsend-ai#7428, fullsend-ai#7676. Note: pre-commit could not fetch remote hook repos (TLS failure in the sandbox). The applicable hooks ran directly instead (pre-commit-hooks 6.0.0 fixers/checks, lint-adr-*, lint-docs-links, lint-broken-symlinks, lychee) and all passed. gitleaks was covered by scan-secrets. Closes fullsend-ai#8971 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Summary
Accepted ADRs already forbid rewriting Context, Decision, and Consequences, but that did not stop agents from adding evolving field tables or checklists that tell people to edit ADR bodies in place (the failure mode in PR #6161). This change makes that rule explicit and tells reviewers to flag it.
Current-state operational detail belongs in living documentation (
docs/architecture.md,docs/reference/, or an existing contributing guide the ADR already links to), not in the ADR.This is a different approach from closed PR #6426, which documented an "extract to living doc under
docs/contributing/" procedure. That was rejected as not a real consolidated pattern; living tables belong in the reference part.Related Issue
Implements the remaining gap in #6423 after ADR immutability itself was already documented.
Changes
docs/contributing/adrs.md: Immutability now forbids adding evolving operational details to accepted ADRs, and points current-state tables at living docs. Review heuristic also flags instructions to update accepted ADR content in place.AGENTS.md: Topic-index row for ADRs now mentions where current-state operational details belong, so agents load the guide for that case.skills/writing-adrs/SKILL.md: Matching acceptable/not-acceptable rules, red flag, and common-mistake row. This file is under the protectedskills/path.Testing
lychee --offline) passedhack/lint-docs-linkspassedhack/lint-broken-symlinkspassedmake lintcould not run: pre-commit failed to fetch remote hook repos (HTTP 403). Applicable hooks were run directly instead.Checklist
!for breaking changes)Closes #6423
Post-script verification
agent/6423-adr-operational-details-guidance)37d3d1117f9f9daed321bd492d0d07eda06c4588..HEAD)