docs(#373): add backlink guidance for new problem docs

[fullsend-ai-coder]

Extend the problem-doc section of AGENTS.md to require authors to search existing docs for references to their topic and add reciprocal backlinks in the same PR. This codifies the practice demonstrated in PR fullsend-ai#3064, where the maintainer had to manually add backlinks from three existing docs to a new doc.

---

Closes #373

Post-script verification

• Branch is not main/master (agent/373-agents-md-backlink-guidance)
• Secret scan passed (gitleaks — aa6585ddb3dff17dccfd4dba8b6c5c306275156a..HEAD)
• Pre-commit hooks passed (authoritative run on runner)
• Tests ran inside sandbox

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 9:06 AM UTC · Completed 9:12 AM UTC
Commit: aa6585d · View workflow run →

[fullsend-ai-review]

Review — approve

PR: #413 — docs(#373): add backlink guidance for new problem docs
Author: fullsend-ai-coder[bot]
Scope: AGENTS.md, README.md (2 additions, 1 deletion)

Summary

Clean documentation change that adds a new bullet to the AGENTS.md problem-doc section requiring authors to search existing docs for topic references and add reciprocal backlinks in the same PR. The README.md contribution table is updated to match.

Dimension results

Dimension	Result
Correctness	✅ No issues — guidance is internally consistent, correctly placed after the "link it from README" bullet, and technically sound
Security	✅ No issues — clean ASCII, no secrets, no injection patterns, no permission changes
Intent & coherence	✅ Properly scoped to issue #373; both AGENTS.md and README.md edits reinforce the same practice
Style & conventions	✅ New bullet follows imperative mood, dash-prefix format, backtick conventions, and em-dash patterns of surrounding content
Docs currency	✅ No staleness introduced — CONTRIBUTING.md delegates to README.md, and skill definitions don't cover problem-doc creation
Cross-repo contracts	⏭ Skipped — no API or schema changes

No findings.

---

Protected paths detected — this PR modifies files under one or more
protected paths. The review agent cannot approve PRs that touch these paths.
A human reviewer must approve this PR.

Protected files in this PR:

• AGENTS.md

Previous run

Review

Findings

Medium

• [protected-path] AGENTS.md — This PR modifies AGENTS.md, which is a protected governance file. The change is well-scoped and authorized by issue [ARCHIVED] Benchmark issue 373 #373, but human approval is always required for protected-path changes regardless of context.

Previous run (2)

Review

Findings

Medium

• [protected-path] AGENTS.md — AGENTS.md is a protected path that requires human approval for all changes. The PR links to issue [ARCHIVED] Benchmark issue 373 #373 and explains the rationale (codifying backlink guidance demonstrated in PR docs(problems): add flapping and convergence problem doc fullsend-ai/fullsend#3064), providing sufficient context. Human review is still required for governance file modifications regardless of justification.

Low

• [stale-guidance] README.md:73 — The "How to contribute" table tells contributors to "Create a problem doc in docs/problems/ and link it here" but does not mention the new backlink requirement added by this PR. However, AGENTS.md is the authoritative process guide and the README table is a brief summary — this is optional follow-up rather than a required change.

Previous run (3)

Review

Findings

Medium

• [protected-path] AGENTS.md — This PR modifies AGENTS.md, which is a protected governance file. The PR links to issue [ARCHIVED] Benchmark issue 373 #373 and explains the rationale for the change. Human approval is always required for protected-path changes, regardless of context.

• [issue-linkage] AGENTS.md — PR references issue [ARCHIVED] Benchmark issue 373 #373 (closed as duplicate) instead of canonical open issue [ARCHIVED] Benchmark issue 343 #343. The PR body says "Closes [ARCHIVED] Benchmark issue 373 #373" but [ARCHIVED] Benchmark issue 373 #373 is already closed, so the automatic issue linkage will not close the canonical tracking issue on merge.
  Remediation: Update PR body to reference "Closes [ARCHIVED] Benchmark issue 343 #343" instead of "Closes [ARCHIVED] Benchmark issue 373 #373" to ensure GitHub automatically closes the correct issue.

Previous run (4)

Review — ✅ Approve

Reviewed: 207a0d51a8195bf99f30a1002726b4c751f258e4
Scope: 1 file changed (AGENTS.md), 1 line added

Summary

Single-line addition to AGENTS.md's "How to work in this repo" section, adding guidance for problem doc authors to search existing docs for references to their topic and add reciprocal backlinks in the same PR. This codifies a manual practice observed on upstream PR fullsend-ai#3064.

Dimensions reviewed

Dimension	Result
Correctness	✅ No findings — guidance is internally consistent with existing bullets and complementary to the existing "link from README" instruction on line 9
Security	✅ No findings — plain ASCII text, no injection patterns, no permission changes
Intent & coherence	✅ Change matches issue #373's intent; see note below
Style & conventions	✅ Follows existing dash-prefix bullet format, backtick usage for paths, and sentence structure
Docs currency	⏭ Skipped — no code changes that could make documentation stale
Cross-repo contracts	⏭ Skipped — no API/schema changes

Notes

Duplicate issue reference (low): Issue #373 is closed with the duplicate label. The issue body identifies it as a mirror of upstream fullsend-ai/fullsend#3122, and references to PR fullsend-ai#3064 refer to the upstream repository — consistent with this being a fork. The change aligns precisely with the issue's stated intent. For a one-line documentation guidance addition, the broken authorization chain is a procedural observation rather than a blocking concern.

Verdict

The change is safe to merge. The new guidance is well-placed (immediately after the existing "create and link from README" bullet), correctly scoped to docs/problems/, and consistent with the repo's documentation philosophy.

---

Protected paths detected — this PR modifies files under one or more
protected paths. The review agent cannot approve PRs that touch these paths.
A human reviewer must approve this PR.

Protected files in this PR:

• AGENTS.md

---

Labels: PR modifies project governance documentation (AGENTS.md)

[guyoron1]

/fs-review

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 9:34 AM UTC · Completed 9:42 AM UTC
Commit: aa6585d · View workflow run →

[guyoron1]

/fs-fix

[fullsend-ai-coder]

🤖 Finished Fix · ✅ Success · Started 9:53 AM UTC · Completed 9:57 AM UTC
Commit: aa6585d · View workflow run →

[fullsend-ai-coder]

🔧 Fix agent — iteration 1 (human-triggered)

No code changes made. Both review findings are process-level concerns, not code bugs. (1) AGENTS.md is a protected path — human approval is already required via the requires-manual-review label. (2) The PR body issue linkage (#373 → #343) requires gh pr edit, which the fix agent cannot use. The PR author should manually update the PR body.

Disagreed (2):

1. protected-path: AGENTS.md requires human approval: This is informational, not actionable by the fix agent. The PR intentionally modifies AGENTS.md (a protected governance file) and already carries the requires-manual-review label. Human approval is the correct gate — no code change is needed.
2. issue-linkage: PR body references closed [ARCHIVED] Benchmark issue 373 #373 instead of canonical [ARCHIVED] Benchmark issue 343 #343: The remediation (updating the PR body to reference Closes [ARCHIVED] Benchmark issue 343 #343) requires gh pr edit, which is outside the fix agent's permitted tools. This requires human action: the PR author should update the PR body to say Closes [ARCHIVED] Benchmark issue 343 #343 instead of Closes [ARCHIVED] Benchmark issue 373 #373.

Tests: passed

_{Updated by fullsend fix agent}

[guyoron1]

/fs-review

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 1:17 PM UTC · Completed 1:26 PM UTC
Commit: aa6585d · View workflow run →

[guyoron1]

/fs-fix

[fullsend-ai-coder]

🤖 Finished Fix · ✅ Success · Started 1:50 PM UTC · Completed 1:58 PM UTC
Commit: aa6585d · View workflow run →

[fullsend-ai-coder]

🔧 Fix agent — iteration 1 (human-triggered)

Updated README.md contributor table to mention the new backlink requirement, keeping it consistent with the AGENTS.md guidance. Disagreed with the protected-path finding (informational only, human approval already required).

Fixed (1):

1. stale-guidance: README contributor table missing backlink step (README.md): Updated the 'Where does my contribution go?' table row for new problem docs to mention adding backlinks from existing docs that reference the same topic, keeping the README summary consistent with the AGENTS.md guidance added by this PR.

Disagreed (1):

1. protected-path: AGENTS.md requires human approval: This is informational — AGENTS.md is intentionally modified by this PR and already carries the requires-manual-review label. Human approval is the correct gate; no code change addresses this finding.

Tests: passed

_{Updated by fullsend fix agent}

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 2:04 PM UTC · Completed 2:11 PM UTC
Commit: aa6585d · View workflow run →

[guyoron1]

/fs-review

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 6:25 AM UTC · Completed 6:31 AM UTC
Commit: e49ecd5 · View workflow run →