Add API report completeness validation instruction for review agents

[fullsend-ai-retro]

What happened

On PR #4417, the fix agent pushed commit 6e4e53b which included api-report changes. The review agent (run 33420007704) flagged report.api.md as stale — a correct but shallow finding. The human reviewer then discovered the problem was catastrophic: a prior commit had run api-extractor without --tsc, reading stale .d.ts files, which dropped the entire DeltaSyncManager public API surface (6 exported symbols) from the report. Three follow-up commits (88cc6bd, df74548/05ffd1f, b03bb6b) were needed to fix this, including reverting unintended reordering in unrelated packages.

What could go better

The review agent detected the api-report was stale but did not assess its structural completeness. It noticed field-level issues (like the updated optionality mismatch) but missed that entire classes and interfaces were absent from the report. If the review agent had cross-referenced the symbols exported from src/index.ts against the entries in report.api.md, it would have detected the missing DeltaSyncManager, CursorStore, CursorState, ApplyDeltaOptions, DeltaSyncManagerOptions, and InMemoryCursorStore entries. Confidence: high — the diff and human triage comments explicitly document this gap. This is complementary to existing issue #4392 (which covers code/fix agent regeneration); even if agents always regenerate the report, an incorrect regeneration (as happened here) would go undetected without review-side validation.

Proposed change

Add a review-focused instruction to .fullsend/AGENTS.md after the existing changeset guidance. The instruction should tell the review agent: when a PR adds, removes, or renames public exports in any plugin package, verify that report.api.md includes entries for all symbols re-exported from the package's src/index.ts. Flag missing or unexpectedly removed entries as a medium-severity finding. Example instruction text: "When reviewing PRs that change public API surface (exports in src/index.ts), cross-check report.api.md to confirm all exported symbols appear in the report. A report missing exported symbols indicates a broken api-extractor run."

Validation criteria

The next 3 agent-authored or agent-reviewed PRs in this repo that modify public API exports should have the review agent validate api-report completeness against src/index.ts exports. The review agent should flag any missing symbols rather than only noting staleness.

---

Generated by retro agent from #4417

[fullsend-ai-triage]

🤖 Finished Triage · ✅ Success · Started 11:15 PM UTC · Completed 11:19 PM UTC

Commit: 2b94dc0 · View workflow run →

Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $0.77

[fullsend-ai-triage]

Triage Summary

Severity: medium — incorrect api-reports can silently drop public API surface, but the impact is bounded to documentation accuracy and is recoverable.

Relationship to #4392: Complementary, not blocking. #4392 covers code-agent-side regeneration; this issue covers review-agent-side validation. Both can proceed independently — even if the code agent always regenerates correctly, review-side validation catches incorrect regenerations (as demonstrated by the PR #4417 incident).

Proposed test case:

Given a package where src/index.ts exports symbols A, B, C
And report.api.md only contains entries for A and B
When the review agent evaluates the PR
Then it should flag symbol C as missing from the api-report
And classify this as a medium-severity finding

---

Labels: Enhancement to fullsend review agent instructions, consistent with similar AGENTS.md instruction issues (#4392, #4354) which carry enhancement, feature, fullsend, and Review effort 1/5.

---

Next steps:

• /fs-code — agent creates a PR to implement this issue
• /fs-code <your instruction> — agent implements with your specific guidance