Skip to content

docs(#6423): keep operational details out of accepted ADRs - #7676

Open
fullsend-ai-coder[bot] wants to merge 3 commits into
mainfrom
agent/6423-adr-operational-details-guidance
Open

fullsend-ai-coder[bot] wants to merge 3 commits into
mainfrom
agent/6423-adr-operational-details-guidance

Conversation

@fullsend-ai-coder

Copy link
Copy Markdown
Contributor

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 protected skills/ path.

Testing

  • Secret scan passed
  • Markdown link check (lychee --offline) passed
  • hack/lint-docs-links passed
  • hack/lint-broken-symlinks passed
  • make lint could not run: pre-commit failed to fetch remote hook repos (HTTP 403). Applicable hooks were run directly instead.
  • Docs-only change; no unit tests.

Checklist

  • PR title follows Conventional Commits (correct type, ! for breaking changes)
  • Commits are signed off (DCO) — autonomous agent, DCO-exempt
  • I wrote this contribution myself and can explain all changes in it

Closes #6423

Post-script verification

  • Branch is not main/master (agent/6423-adr-operational-details-guidance)
  • Secret scan passed (gitleaks — 37d3d1117f9f9daed321bd492d0d07eda06c4588..HEAD)
  • PR body secret scan passed (gitleaks — no-git)

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
@fullsend-ai-coder
fullsend-ai-coder Bot requested a review from a team September 24, 2026 14:26
@fullsend-ai-coder fullsend-ai-coder Bot added the ready-for-review Triggers review agent dispatch label Sep 24, 2026
@fullsend-ai-review

fullsend-ai-review Bot commented Sep 24, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 2:29 PM UTC · Completed 2:41 PM UTC

Commit: 4b7e5c3 · View workflow run →

Runtime: pi · Model: sonnet → claude-sonnet-5 · Effort: high · Cost: $2.69

@github-actions

github-actions Bot commented Sep 24, 2026 •

Copy link
Copy Markdown

Site preview

Preview: https://0f14f819-site.fullsend-ai.workers.dev

Commit: 095456b8443ccd582a32312c3e4bf51ee77b30ee

@codecov

codecov Bot commented Sep 24, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@fullsend-ai-review fullsend-ai-review Bot added the risk/moderate PR risk: moderate label Sep 24, 2026
@fullsend-ai-review

fullsend-ai-review Bot commented Sep 24, 2026 •

Copy link
Copy Markdown

Risk Assessment: moderate (2/5)

Details

Small 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 run

Risk Assessment: moderate (2/5)

Details

Small 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)

Details

Small 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.

@fullsend-ai-review

fullsend-ai-review Bot commented Sep 24, 2026 •

Copy link
Copy Markdown

Review

Findings

Medium

  • [protected-path] AGENTS.md, skills/writing-adrs/SKILL.md — This PR modifies files under the repository's protected paths list (AGENTS.md, skills/). Protected-path changes always require human approval, regardless of context. The PR links issue Document ADR immutability convention so agents avoid modifying accepted ADRs #6423 and its description explains the rationale for touching these files, so this is treated as sufficient-context justification — but human review/approval is still required before merge.
    Remediation: No code change needed; a human reviewer must explicitly approve the protected-path edits before merge.
Previous run

Review

Findings

Medium

  • [protected-path] AGENTS.md, skills/writing-adrs/SKILL.md — This PR modifies files under the repository's protected paths list (AGENTS.md, skills/). Protected-path changes always require human approval, regardless of context. The PR links issue Document ADR immutability convention so agents avoid modifying accepted ADRs #6423 and its description explains the rationale for touching these files, so this is treated as sufficient-context justification — but human review/approval is still required before merge.
    Remediation: No code change needed; a human reviewer must explicitly approve the protected-path edits before merge.

  • [logic-error] docs/contributing/adrs.md:9 — The new review heuristic's second clause — flag PRs that "add instructions to update accepted ADR content in place" — is meant to catch exactly the failure mode from issue Document ADR immutability convention so agents avoid modifying accepted ADRs #6423 / PR docs(#6160): add ADR-0045 maintenance step to harness-composition checklist #6161 (a checklist in a non-ADR file directing an in-place edit to an accepted ADR). But this file's own applicability sentence (line 3, unchanged) still scopes its rules to "whenever you touch docs/ADRs/ or review a PR that does," and AGENTS.md's topic-index row for this guide still gates loading it on "Touching docs/ADRs/ or reviewing ADR changes." A PR that only adds an in-place-ADR-update instruction to a contributing guide, skill, or checklist (i.e. the exact PR docs(#6160): add ADR-0045 maintenance step to harness-composition checklist #6161 pattern) never touches docs/ADRs/, so a reviewing agent following AGENTS.md's "read only the file relevant to your current task" guidance will not load this heuristic for the case it was written to catch. The first clause (operational detail added directly inside an accepted ADR body) does fire correctly on the existing trigger — only the second clause has this gap.
    Remediation: Broaden the ADR topic-table trigger in AGENTS.md and this file's applicability sentence (line 3) so reviewers load these rules for PRs that instruct in-place updates of accepted ADRs even when docs/ADRs/ itself is untouched. Alternatively, add a one-line always-on rule under AGENTS.md's "How to work in this repo" section: do not instruct in-place updates of accepted ADR bodies elsewhere in the repo.

Low

  • [incorrect-spec] skills/writing-adrs/SKILL.md:55 — The new living-doc destination list ("docs/architecture.md for architectural truth, docs/reference/ for field and config tables, or an existing contributing guide the ADR already links to") is coarser than this repo's actual field-table homes. docs/reference/ genuinely hosts some field/config tables (config-reference.md, harness-reference.md), so the sentence isn't factually wrong, but it doesn't give first-class mention to the contributor living references that actually hold the kind of content this PR is motivated by — docs/contributing/harness-fields.md (Harness/ForgeConfig classification, merge rules, struct definitions) and docs/contributing/harness-composition.md (AgentEntry fields) — nor to versioned field contracts under docs/normative/. An agent following only this sentence could route new operational detail to the wrong living doc.
    Remediation: Widen the third bucket beyond "a guide the ADR already links to" to explicitly include contributing/normative living homes such as docs/contributing/harness-fields.md, docs/contributing/harness-composition.md, and docs/normative/, and note that a short cross-reference annotation (already listed as acceptable) is how an ADR gains that link when one doesn't yet exist. Mirror the same wording in docs/contributing/adrs.md.

Next steps:

  • /fs-fix — agent addresses review findings automatically
  • /fs-fix <your instruction> — agent fixes with your specific guidance
  • Push commits directly — review re-runs automatically on push
  • /fs-fix-stop — disable automatic fix runs for this PR
Previous run (2)

Review

Findings

Medium

  • [protected-path] AGENTS.md — This PR modifies files under the repository's protected paths list (AGENTS.md, skills/): specifically AGENTS.md and skills/writing-adrs/SKILL.md. Protected-path changes always require human approval, regardless of context. The PR links issue Document ADR immutability convention so agents avoid modifying accepted ADRs #6423 and its description explains the rationale for touching these files (it even calls out that skills/writing-adrs/SKILL.md is under the protected skills/ path), so this is treated as sufficient-context justification — but human review/approval is still required before merge.
    Remediation: No code change needed; a human reviewer must explicitly approve the protected-path edits before merge.

Low

  • [internal-inconsistency] skills/writing-adrs/SKILL.md:213 — The overview (lines 53–56) names three living-doc destinations for current-state operational detail: docs/architecture.md, docs/reference/, or an existing contributing guide the ADR already links to. The "Red Flags" bullet (lines 213–215) and the "Common Mistakes" table row (line 231) drop the third option and mention only docs/architecture.md and docs/reference/. docs/contributing/adrs.md (also touched in this PR) correctly lists all three. For the motivating case this PR cites (ADR field tables / merge rules / struct definitions), the authoritative living doc is often an existing contributing guide the ADR already links to (e.g. docs/contributing/harness-fields.md) rather than docs/reference/ — an agent scanning only the Red Flags/Common Mistakes rows could redirect content to the wrong place or fail to recognize the contributing-guide option as valid.
    Remediation: In the Red Flags bullet (lines 213–215) and the Common Mistakes row (line 231), repeat the third destination already stated in the overview: "or an existing contributing guide the ADR already links to."

Next steps:

  • /fs-fix — agent addresses review findings automatically
  • /fs-fix <your instruction> — agent fixes with your specific guidance
  • Push commits directly — review re-runs automatically on push
  • /fs-fix-stop — disable automatic fix runs for this PR

fullsend-ai-review[bot]

This comment was marked as outdated.

@fullsend-ai-coder

fullsend-ai-coder Bot commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor Author

🤖 Finished Fix · ✅ Success · Started 2:44 PM UTC · Completed 2:50 PM UTC

Commit: 4b7e5c3 · View workflow run →

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
@fullsend-ai-coder

Copy link
Copy Markdown
Contributor Author

🔧 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):

  1. protected-path: AGENTS.md and skills/writing-adrs/SKILL.md are under protected paths (skills/writing-adrs/SKILL.md): No code change required for this finding — its own remediation states the protected-path gate only requires a human reviewer's explicit approval before merge, since the PR description already provides sufficient-context justification for the edits.
  2. internal-inconsistency: Red Flags bullet and Common Mistakes row omit the third living-doc destination (skills/writing-adrs/SKILL.md): Added "or an existing contributing guide the ADR already links to" to the Red Flags bullet (was lines 213-215) and the Common Mistakes table row (was line 231), matching the three destinations already listed in the overview (lines 53-56) and in docs/contributing/adrs.md, so an agent scanning only those rows won't redirect content to the wrong living doc.

Tests: passed

CI inspections (13):

  1. CI / test (passing, success)
  2. CI / web (passing, success)
  3. CI / test-sandbox-darwin (passing, success)
  4. CI / commit-lint (passing, success)
  5. Functional Tests / functional-tests (passing, success)
  6. Functional Tests / gate (passing, success)
  7. E2E Tests / e2e (passing, success)
  8. E2E Tests / behaviour (passing, success)
  9. E2E Tests / gate (passing, success)
  10. Build Site / build (passing, success)
  11. Vouch Check / vouch-gate (passing, success)
  12. codecov/patch (passing, success)
  13. DCO (passing, success)
Decision points
  • Edited the protected-path file skills/writing-adrs/SKILL.md on a bot-triggered run (alternatives: Skip the edit and record a disagreement, deferring entirely to human review, Make the specific content fix the finding described; rationale: The internal-inconsistency finding (not the protected-path finding itself) named this file, was not categorized protected-path, and its remediation described a specific content change — the conditions under which editing a protected-path file is authorized on a bot-triggered run.)

Next steps:

  • /fs-review — request a re-review of the changes
  • /fs-fix <your instruction> — run another fix pass with specific guidance
  • Push commits directly — review re-runs automatically on push
    Updated by fullsend fix agent

@fullsend-ai-review

fullsend-ai-review Bot commented Sep 24, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 2:52 PM UTC · Completed 3:11 PM UTC

Commit: 0589222 · View workflow run →

Runtime: pi · Model: sonnet → claude-sonnet-5 · Effort: high · Cost: $2.99

fullsend-ai-review[bot]

This comment was marked as outdated.

@fullsend-ai-coder

fullsend-ai-coder Bot commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor Author

🤖 Finished Fix · ✅ Success · Started 3:13 PM UTC · Completed 3:19 PM UTC

Commit: 0589222 · View workflow run →

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
@fullsend-ai-coder

Copy link
Copy Markdown
Contributor Author

🔧 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):

  1. logic-error: the in-place-ADR-update review heuristic in docs/contributing/adrs.md:9 never loads for the exact PR docs(#6160): add ADR-0045 maintenance step to harness-composition checklist #6161 pattern, because AGENTS.md's topic-index row and this file's applicability sentence gate loading on touching docs/ADRs/ (AGENTS.md, docs/contributing/adrs.md): Broadened the AGENTS.md topic-index trigger for the ADRs guide and the applicability sentence at the top of docs/contributing/adrs.md so both also fire when a checklist, skill, or contributing guide elsewhere in the repo instructs an in-place edit to an accepted ADR's Context, Decision, or Consequences, not only when docs/ADRs/ itself is touched.
  2. incorrect-spec: skills/writing-adrs/SKILL.md:55 living-doc destination list is coarser than this repo's actual field-table homes (skills/writing-adrs/SKILL.md, docs/contributing/adrs.md): Widened the third living-doc bucket in all four places it appears (SKILL.md overview, Red Flags bullet, Common Mistakes row, and docs/contributing/adrs.md immutability paragraph) to explicitly name docs/contributing/harness-fields.md, docs/contributing/harness-composition.md, and docs/normative/ alongside the existing docs/architecture.md and docs/reference/ options, and noted that a short cross-reference annotation is how an ADR gains that link when one doesn't already exist.
  3. protected-path: AGENTS.md and skills/writing-adrs/SKILL.md are under the repo's protected paths and require human approval before merge (AGENTS.md, skills/writing-adrs/SKILL.md): No code change made for this finding — its own remediation states none is needed. The repo's merge gate already requires explicit human approval for protected-path edits regardless of PR context; flagging here for reviewer visibility.

Tests: passed

CI inspections (12):

  1. test (passing, success): CI workflow unit tests passed.
  2. web (passing, success): Web workflow job passed.
  3. commit-lint (passing, success): Commit lint passed.
  4. test-sandbox-darwin (passing, success): Darwin sandbox test passed.
  5. build (passing, success): Build Site workflow passed.
  6. functional-tests (passing, success): Functional test suite passed.
  7. gate (functional-tests) (passing, success): Functional tests gate passed.
  8. e2e (passing, success): E2E test job passed.
  9. behaviour (passing, success): Behaviour test job passed.
  10. gate (e2e) (passing, success): E2E tests gate passed.
  11. codecov/patch (passing, success): Patch coverage check passed (docs-only change).
  12. DCO (passing, success): DCO check passed.
Decision points
  • Edited AGENTS.md and skills/writing-adrs/SKILL.md despite both being under the protected-path list (alternatives: Skip the edits and only note a disagreement, Make the content edits the other two findings specifically call for; rationale: The protected-path finding's own category is separate from the logic-error and incorrect-spec findings that name these same files, and those two findings' remediations describe specific content edits to make in AGENTS.md and SKILL.md. Per the fix-agent's protected-path rule, a non-protected-path finding with a concrete remediation authorizes the edit; the protected-path finding itself still stands and requires human approval before merge.)

Next steps:

  • /fs-review — request a re-review of the changes
  • /fs-fix <your instruction> — run another fix pass with specific guidance
  • Push commits directly — review re-runs automatically on push
    Updated by fullsend fix agent

@fullsend-ai-review

fullsend-ai-review Bot commented Sep 24, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 3:22 PM UTC · Completed 3:33 PM UTC

Commit: 095456b · View workflow run →

Runtime: pi · Model: sonnet → claude-sonnet-5 · Effort: high · Cost: $1.97

@fullsend-ai-review
fullsend-ai-review Bot dismissed stale reviews from themself September 24, 2026 15:33

Superseded by updated review

@fullsend-ai-review fullsend-ai-review Bot added the requires-manual-review Review requires human judgment label Sep 24, 2026
@github-actions

Copy link
Copy Markdown

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 stale label to reset the inactivity timer.

@github-actions github-actions Bot added the stale label Oct 25, 2026
jflowers pushed a commit to jflowers/fullsend-ai-fullsend that referenced this pull request Nov 2, 2026
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>
@github-actions github-actions Bot removed the stale label Nov 16, 2026

This branch was successfully deployed

1 active and 1 inactive deployments
site-preview — 095456b8 Deployed Sep 24, 2026 by github-actions[bot]
dev — 095456b8 Deployed Sep 24, 2026 by fullsend-ai-coder[bot] via behaviour #13886
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ready-for-review Triggers review agent dispatch requires-manual-review Review requires human judgment risk/moderate PR risk: moderate

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document ADR immutability convention so agents avoid modifying accepted ADRs

0 participants