docs(#201): add cross-reference update guidance to AGENTS.md#225
docs(#201): add cross-reference update guidance to AGENTS.md#225fullsend-ai-coder[bot] wants to merge 1 commit into
Conversation
When implementing a feature previously described as in progress, coming soon, or planned in the docs, authors should search for and update those stale references in the same PR. This gives the review agent a documented convention to cite when flagging stale cross-references, making the finding more actionable for both human authors and code agents. The new bullet is placed in the "How to work in this repo" section alongside existing documentation conventions. It instructs contributors to grep for the feature name, relevant PR/issue numbers, and status terms like "in progress", "coming soon", "planned", and "not yet implemented". Closes #201
Review of PR #225Verdict: Approve ✅ This PR adds a single bullet point to the "How to work in this repo" section of Assessment
Findings[low · style-consistency · AGENTS.md:13] The new bullet is notably longer (~50 words, 2 sentences) than most surrounding bullets in the section (typically 10–20 words each). This is a minor style observation — the content is clear and actionable as written. Optionally, the grep implementation details could be moved to a sub-bullet or a dedicated subsection to match the pattern used elsewhere in the file (e.g., the "Go code" and "Forge abstraction" sections use headings for longer guidance). No blocking findings. The change is well-scoped, accurately implements the linked issue, and improves contributor guidance for documentation maintenance.
Previous runReviewVerdict: Approve Clean, well-scoped documentation change that adds a single bullet to the "How to work in this repo" section of AGENTS.md, instructing contributors to search for and update stale cross-references when implementing a previously-planned feature. The change traces directly to issue #201 with no scope creep, and the placement among existing documentation conventions is appropriate. Dimensions evaluated
Low-severity findings1. Internal consistency — ADR immutability tension ( The new guidance instructs contributors to "search for and update those references in the same PR" when implementing a previously-planned feature. However, the ADR immutability rule later in the same file (line 69) states that Accepted ADRs are point-in-time records that should not be substantially rewritten. Several Accepted ADRs contain the exact phrases this guidance tells agents to grep for — e.g., ADR 0024 uses "planned — not yet implemented" in multiple places. While the immutability rule permits "minor annotations" (cross-references, short notes), the new guidance does not mention this carve-out or advise contributors to treat Accepted ADRs differently. An agent following the new guidance literally could attempt to modify Accepted ADR content in ways that violate the immutability rule. Suggested follow-up: Consider adding a qualifier such as "For Accepted ADRs, limit changes to minor annotations per the ADR immutability rules" or scoping the guidance to exclude ADR content sections. 2. Incomplete guidance — missing ADR 0023 callout format ( The new guidance recommends searching for terms like Suggested follow-up: Consider adding the
Labels: PR modifies project-level documentation (AGENTS.md contributor guidance) |
![fullsend-ai-review[bot]](https://avatars.githubusercontent.com/in/3478501?s=60&v=4){kind=small}
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
fullsend-ai-review
Bot
added
requires-manual-review
|
/fs-review |
| - The security threat model (threat priority: external injection > insider > drift > supply chain) should inform all other documents. | ||
| - Keep core problem documents organization-agnostic. Organization-specific details belong in `docs/problems/applied/<org-name>/`. | ||
| - The target audience for problem documents is any contributor community considering autonomous agents — keep language accessible and avoid presuming solutions. | ||
| - When implementing a feature that was previously described as *in progress*, *coming soon*, or *planned* elsewhere in the docs, search for and update those references in the same PR. Grep for the feature name, relevant PR/issue numbers, and terms like `in progress`, `coming soon`, `planned`, `not yet implemented`. |
There was a problem hiding this comment.
[low] style-consistency
New bullet point is notably longer (~50 words, 2 sentences) than most surrounding bullets in the section (typically 10-20 words). The content is clear and actionable as written, but the grep implementation details could optionally be moved to a sub-bullet or dedicated subsection to match the pattern used elsewhere in AGENTS.md for complex guidance.
fullsend-ai-review
Bot
added
requires-manual-review
1 participant
When implementing a feature previously described as in progress, coming soon, or planned in the docs, authors should search for and update those stale references in the same PR. This gives the review agent a documented convention to cite when flagging stale cross-references, making the finding more actionable for both human authors and code agents.
The new bullet is placed in the "How to work in this repo" section alongside existing documentation conventions. It instructs contributors to grep for the feature name, relevant PR/issue numbers, and status terms like "in progress", "coming soon", "planned", and "not yet implemented".
Closes #201
Post-script verification
agent/201-update-crossref-guidance)f96750babbed5ada406a9ae04e8068449701d9c7..HEAD)