Add AGENTS.md guidance on user-guide document audience and content scope

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

Nobody has claimed this yet.

Assessment

Difficulty
1/5
Estimated time
1-3 hours
Newbie friendliness
88/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Domain
documentation

Research direction

Start in the existing Documentation section of AGENTS.md and review the listed user-guide files: 01-getting-started.md, 03-plugin-owner-responsibilities.md, 04-metadata-synchronization.md, and 07-plugin-catalog-index.md. Add their intended audiences and content boundaries, including how to handle business-process material; done means the guidance covers the proposed scope and can be checked against the next three documentation PRs touching user-guide files.

Written by the indexing model from the issue text.

Description

documentation ready-to-code stale

What happened

On PR #2902, the review agent ran 5 successful reviews and approved the PR, finding valid mechanical issues (typos, formatting). However, human reviewer jasperchui raised a substantive content-scope concern: business-process requirements (PM approvals, JIRA ticket creation) were being added to technical how-to guides (01-getting-started.md, 03-plugin-owner-responsibilities.md) intended for developers who have already completed the approval process. The agent never flagged this mismatch because AGENTS.md does not describe the intended audience or content scope of user-guide documents.

What could go better

The review agent could have flagged the content-scope mismatch if AGENTS.md described each user-guide document's purpose and target audience. Currently, the Documentation section in AGENTS.md lists user-guide files but provides no guidance on what content belongs in each document or who the intended reader is. Without this context, the agent treated the PR content at face value — the changes were factually correct and well-formatted, so it approved.

This is a reasonable miss given the available context, but it is addressable with repo-specific guidance. The agent is demonstrably responsive to AGENTS.md guidance (it correctly applies workspace/metadata review criteria from existing sections). Confidence: medium-high.

Note: Related agent-capability issues exist (agents#261, fullsend#4838) but those address the agent's general doc-review skill, not repo-specific context. This proposal is complementary — it provides the repo-level context those capabilities would need.

Proposed change

Add a subsection under the existing ## Documentation section in AGENTS.md that describes the user-guide documents' intended audience and content boundaries:

### User Guide Content Scope

The `user-guide/` documents target plugin developers who are already cleared to contribute to this repo. Each document has a specific technical scope:

- `01-getting-started.md` — Technical setup: CLI installation, source.json configuration, workspace creation. Assumes business approvals are already complete.
- `03-plugin-owner-responsibilities.md` — Ongoing technical maintenance tasks: metadata sync, version bumps, deprecation procedures.
- `04-metadata-synchronization.md` — Package metadata YAML format and sync workflow.
- `07-plugin-catalog-index.md` — Catalog index pipeline: how indexes are built, published, and consumed.

When reviewing documentation PRs that modify user-guide files, flag additions of business-process requirements (approvals, JIRA workflows, stakeholder agreements) to technically-scoped documents for human discussion. These may belong in a separate onboarding or governance document.

Validation criteria

On the next documentation PR that adds process or governance content to a technical user-guide document, the review agent should flag the content-scope concern as a finding (any severity) rather than approving without comment. Verify against the next 3 documentation PRs touching user-guide files.


Generated by retro agent from https://github.com/redhat-developer/rhdh-plugin-export-overlays/pull/2902

Dominant language
TypeScript
Stars
9
Forks
72
Avg merge
3d 9h
Merged PRs (30d)
133

Contributor guide

No contributing guide indexed for this repository

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.

More from redhat-developer/rhdh-plugin-export-overlays

All issues in redhat-developer/rhdh-plugin-export-overlays

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.