redhat-developer / redhat-developer/rhdh-plugins

Add API report regeneration command to ai-integrations workspace AGENTS.md

Open Beginner friendly
#3,757 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement feature fullsend Review effort 1/5 stale triaged workspace/ai-integrations
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.