redhat-developer / redhat-developer/rhdh-plugins
Add API report completeness validation instruction for review agents
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 48
- Forks
- 120
- Avg merge
- 2d 6h
- Merged PRs (30d)
- 337
Description
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 https://github.com/redhat-developer/rhdh-plugins/pull/4417
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start in .fullsend/AGENTS.md after the existing changeset guidance and review the proposed API-report completeness instruction. Ensure it tells review agents to compare public exports from each plugin package's src/index.ts with report.api.md and flag missing or unexpectedly removed entries as medium severity. Done means the instruction is added and the next three relevant PRs are covered by the stated validation criterion.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- developer-experience
- Issue type
- Feature
- Difficulty
- 1/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 85/100