redhat-developer / redhat-developer/rhdh-plugins

Add mandatory API report regeneration instruction to repo-wide agent config

Open Beginner friendly
#4,392 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement feature fullsend Review effort 1/5 triaged
Dominant language
TypeScript
Stars
48
Forks
120
Avg merge
2d 6h
Merged PRs (30d)
337

Description

What happened

On PR #3746, the code agent modified public API exports in the boost plugin (added @backstage/plugin-permission-react dependency, new i18n keys, new utility exports) but did not regenerate report.api.md. This required two /fs-fix iterations (fix 1, fix 2) totaling approximately 25 minutes of agent compute time and two rounds of human intervention by mareklibra. The same pattern occurred on PR #3742 (ai-integrations workspace, 2 fix iterations) and PR #3743 (boost workspace). The boost workspace AGENTS.md lists yarn tsc:full && yarn build:api-reports:only as a build command, but this listing is descriptive rather than prescriptive — the code agent treats it as reference material, not as a mandatory verification step.

What could go better

The code agent should regenerate API reports as part of its verification phase whenever it modifies public exports. The existing workspace-specific AGENTS.md files list the command but don't frame it as mandatory. Issue #3757 proposes adding the instruction to the ai-integrations workspace AGENTS.md, but the problem recurs across multiple workspaces (boost, ai-integrations), making a repo-wide instruction more effective. Confidence: high — this is a clear, recurring pattern with three data points across two workspaces.

Proposed change

Add the following instruction to .fullsend/AGENTS.md, after the existing changeset guidance:

When adding, removing, or renaming public exports in any plugin package
(changes to `index.ts`, re-exported types, or API surface files), run
`yarn tsc:full && yarn build:api-reports:only` from the workspace root
(`workspaces/<workspace>/`) and include the updated `report.api.md`
files in your commit. CI will fail if API reports are stale.

This complements the workspace-specific fix proposed in #3757 by providing a repo-wide default that covers all current and future workspaces without requiring per-workspace AGENTS.md updates.

Validation criteria

The next 3 agent-authored PRs that modify public API exports (in any workspace) should include updated report.api.md files in their initial commit, without requiring /fs-fix iterations for API report regeneration.


Generated by retro agent from https://github.com/redhat-developer/rhdh-plugins/pull/3746

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

Open .fullsend/AGENTS.md and locate the existing changeset guidance. Add the proposed mandatory API report regeneration instruction after it, including the workspace-root command and updated report.api.md requirement. Done means the repo-wide agent guidance explicitly requires this verification for public export changes.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
developer-experience, documentation
Issue type
Documentation
Difficulty
1/5
Estimated time
Under an hour
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
85/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.