Add AGENTS.md guidance on user-guide document audience and content scope
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
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
- 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.
More from redhat-developer/rhdh-plugin-export-overlays
-
documentation non-workspace-changes ready-for-triage ready-to-code
Difficulty 1/5 1-3 hours Newbie friendliness 88/100
redhat-developer/rhdh-plugin-export-overlays#3815 · 3 comments ·
-
documentation non-workspace-changes ready-for-triage ready-to-code
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
redhat-developer/rhdh-plugin-export-overlays#3810 · 3 comments ·
-
Add AGENTS.md review guidance: Prettier/ESLint/TypeScript violations in e2e-tests are CI-blocking Opendocumentation ready-for-triage ready-to-code
Difficulty 1/5 Under an hour Newbie friendliness 88/100
redhat-developer/rhdh-plugin-export-overlays#3792 · 3 comments ·
-
e2e-failure ready-to-code
Difficulty 1/5 Under an hour Newbie friendliness 88/100
redhat-developer/rhdh-plugin-export-overlays#3789 · 1 comment ·
-
e2e-failure ready-to-code
Difficulty 1/5 Under an hour Newbie friendliness 88/100
redhat-developer/rhdh-plugin-export-overlays#3788 · 1 comment ·
All issues in redhat-developer/rhdh-plugin-export-overlays
Similar issues
-
calcite-components needs triage refactor
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
Esri/calcite-design-system#15203 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 91/100
-
community first-timers-only good first issue hacktoberfest help wanted low hanging fruit up-for-grabs
Difficulty 1/5 Under an hour Newbie friendliness 95/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
Automattic/studio#4908 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 90/100