redhat-developer / redhat-developer/rhdh-plugins

ai-integrations AGENTS.md: add processor-behavior verification instructions for doc tasks

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

Nobody has claimed this yet.

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

Description

What happened

The code agent produced PR #3859 documenting AIResource entity registration and schema fields. Two major accuracy issues required a fix cycle:

  1. Schema table marked fields as "Required" that the processors (AIResourceExtensionsProcessor, AIResourceOciProcessor) don't actually enforce — they only validate spec.scope enum values and oci:// URI format (human review).
  2. Claimed UrlReaderProcessor uses backstage.io/source-location for ingestion — this is inaccurate; the annotation is source metadata, not what drives entity ingestion.

The code agent's workspace AGENTS.md mentions checking openspec/changes/ specs but has no instruction to verify behavioral claims against actual processor source code. The fix agent (run) addressed all findings correctly in one iteration, confirming the processor source code is readable and checkable.

What could go better

The code agent wrote documentation about processor behavior without reading the processor source files to verify its claims. The workspaces/ai-integrations/AGENTS.md file directs agents to check openspec/changes/ for specs but doesn't instruct them to cross-reference documentation claims against the actual plugin source code under plugins/catalog-backend-module-*/src/.

This is a high-confidence assessment: the fix agent demonstrated that reading the processor source and correcting the claims was straightforward. The workspace AGENTS.md is the natural place for this guidance because it's already the entry point agents read before working in this workspace.

This complements but does not duplicate #3745 (changeset/doc-update instructions) — that issue covers mechanical PR conventions, not behavioral accuracy verification.

Proposed change

Add a "Documentation Tasks" section to workspaces/ai-integrations/AGENTS.md with instructions like:

## Documentation Tasks

- When documenting processor behavior (validation rules, required fields,
  ingestion behavior, error handling), read the relevant processor source
  files under `plugins/catalog-backend-module-*/src/` to verify claims.
  Do not infer behavior from field names or conventions alone.
- Cross-reference schema field documentation against the actual processor
  code to confirm which fields are validated/enforced vs. merely consumed.
- When writing examples, ensure field values (e.g., `spec.type`,
  `spec.scope`) are consistent with the asset description in the example.

This is repo-specific guidance that complements the platform-level improvements tracked in fullsend-ai/fullsend #3497 and #2199.

Validation criteria

The next 3 documentation PRs in the ai-integrations workspace produced by the code agent should not require human review feedback about inaccurate processor behavior claims. Specifically: documentation about what fields are required/enforced, what processors do, and what side effects they have should match the actual source code.


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

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

Start with workspaces/ai-integrations/AGENTS.md and inspect the processor source under plugins/catalog-backend-module-*/src/. Add a Documentation Tasks section covering source verification for processor behavior, enforced fields, and consistent examples. Done means the workspace guidance includes these checks and distinguishes validated behavior from assumptions.

Written by the indexing model from the issue text.

Assessment

Tech stack
markdown, typescript
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
78/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.