redhat-developer / redhat-developer/rhdh-plugins
Add API report regeneration command to ai-integrations workspace AGENTS.md
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 #3742 (https://github.com/redhat-developer/rhdh-plugins/pull/3742), the code agent's initial commit added new public exports (AIResourceScopeValidator, VALID_AI_RESOURCE_SCOPES, AIResourceScope type) to the catalog-backend-module-ai-resource-extensions plugin but did not regenerate report.api.md. CI failed on the api-reports check. The human triggered '/fs-fix Fix the failing API reports error on the CI check' at 20:52 UTC on July 13 (fix iteration 2, ~13 min to resolve). Later, after the human pushed a rename commit at 19:01 UTC on July 14, the api-report needed regeneration again, requiring fix iteration 4 (~13 min). The workspace AGENTS.md at workspaces/ai-integrations/AGENTS.md lists build, test, lint, and type-check commands but does not mention 'yarn build:api-reports'. The repo's CONTRIBUTING.md (lines 316-325) documents this as mandatory for API changes, but that file is not in the agent's primary instruction path.
What could go better
If the workspace AGENTS.md included 'yarn build:api-reports' in the Build & Test Commands section, both the code agent and fix agent would have clear guidance to regenerate API reports after modifying public exports. This would have prevented fix iterations 2 and 4 entirely, saving ~26 minutes of agent compute time and eliminating 2 of the 4 human-triggered fix requests. Confidence is high that documenting the command would help — the code agent already successfully follows other commands listed in the same AGENTS.md (e.g., it ran tests). Uncertainty: the code agent may not run all listed commands before submitting (see fullsend-ai/fullsend#1719 for the platform-level issue), but having the command documented is a necessary prerequisite for it to be run. Issue #3745 in this repo covers adding changeset instructions to .fullsend/AGENTS.md but does not cover adding api-report regeneration to the workspace-level AGENTS.md.
Proposed change
Add 'yarn build:api-reports' to the Build & Test Commands section in workspaces/ai-integrations/AGENTS.md. Also add a 'CI Requirements' subsection with guidance: 'When adding or modifying public exports in index.ts, run yarn build:api-reports from the workspace root and commit the updated report.api.md files. This is a required CI check that will fail if reports are stale.' Example addition to the commands list: '- API reports: yarn build:api-reports (run after modifying public exports)'.
Validation criteria
On the next agent-authored PR in the ai-integrations workspace that adds or modifies public API exports: the code agent includes an updated report.api.md in its initial commit without requiring a human-triggered /fs-fix, OR the fix agent addresses the failing api-reports check autonomously using the documented command without requiring the human to diagnose the problem.
Generated by retro agent from https://github.com/redhat-developer/rhdh-plugins/pull/3742
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
Update workspaces/ai-integrations/AGENTS.md in the Build & Test Commands section. Document yarn build:api-reports and add the stated CI guidance for public exports in index.ts, including committing updated report.api.md files. Verify that the command and required behavior are clearly described.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 1/5
- Estimated time
- Under an hour
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 88/100