AGENTS.md should document the code-review to pr-review sub-agent propagation requirement

[fullsend-ai-retro]

What happened

The code agent on fullsend#2133 (predecessor to agents#445) added a new mandatory-finding rule for agent behavior definition changes to skills/code-review/SKILL.md. However, it did not add a corresponding procedural section to skills/pr-review/sub-agents/security.md. In the production pipeline, pr-review dispatches dimension-specific sub-agents that never receive code-review/SKILL.md content — so the rule was inert during orchestrated reviews. The review agent flagged this gap in every review cycle from June 10 through July 30 (run 30583297797), and the fix agent's third iteration (June 29, commit 2be0d71) only partially addressed it by adding an Own: clause without a procedural section. Human reviewer waynesun09 independently confirmed this gap on July 29. The result was 6+ review cycles and 3 fix iterations all driven by the same structural omission.

What could go better

The code agent didn't understand the relationship between code-review/SKILL.md (standalone review) and the pr-review orchestrator that delegates to sub-agents in skills/pr-review/sub-agents/. This architectural relationship is not documented anywhere agents can reference. If AGENTS.md explained that changes to review rules in code-review/SKILL.md must be mirrored with procedural sections in the corresponding pr-review sub-agent, the code agent would have produced a complete implementation on the first attempt. Confidence: high — the code agent's reasoning trace (per the review body) showed no awareness of the sub-agent delegation model, and the fix agent's partial fix confirms neither agent understood the full propagation requirement.

Proposed change

Add a section to AGENTS.md (or a dedicated CONTRIBUTING.md section) documenting the review pipeline architecture. Specifically:

1. Explain that skills/code-review/SKILL.md defines review dimensions for standalone use, while skills/pr-review/SKILL.md orchestrates parallel sub-agents that each receive only their own definition file (from skills/pr-review/sub-agents/).
2. State the propagation rule: when adding or modifying a review rule in code-review/SKILL.md, the corresponding pr-review sub-agent must receive a matching procedural section with the category name, severity guidance, and file pattern matching instructions.
3. Reference the routing table in pr-review/SKILL.md (section 3a) that maps categories to sub-agents, and note that new categories must be added to this table.
4. Use the existing "Permission and role changes" section in skills/pr-review/sub-agents/security.md as the model for what a complete procedural section looks like.

This is repo-specific architectural documentation, not an agent definition change.

Validation criteria

The next code agent PR that modifies review rules in code-review/SKILL.md should also include corresponding changes to the relevant pr-review sub-agent definition. Verify by checking the next 3 PRs that touch skills/code-review/SKILL.md — each should include changes to the corresponding sub-agent file if the rule introduces a new category or mandatory-finding directive. Additionally, the review agent should stop flagging 'missing procedural section' as a persistent finding on such PRs.

---

Generated by retro agent from #445

[fullsend-ai-triage]

🤖 Finished Triage · ✅ Success · Started 11:45 PM UTC · Completed 11:48 PM UTC
Commit: 13154d9 · View workflow run →

[fullsend-ai-triage]

Triage Summary

Severity: Medium · Category: Documentation

Problem

The review pipeline has a two-layer architecture: skills/code-review/SKILL.md defines review dimensions for standalone use, while skills/pr-review/SKILL.md orchestrates parallel sub-agents that each receive only their own definition file from skills/pr-review/sub-agents/. This relationship is not documented in AGENTS.md, so agents modifying review rules in code-review/SKILL.md don't know they must also add corresponding procedural sections to the relevant pr-review sub-agent definition.

This gap caused 6+ review cycles and 3 fix iterations on PR #445 — the code agent added a mandatory-finding rule to code-review/SKILL.md but missed the corresponding security.md sub-agent update.

Recommended Fix

Add a section to AGENTS.md documenting the propagation requirement:

1. Explain the two-layer architecture (standalone code-review vs orchestrated pr-review with parallel sub-agents)
2. State the propagation rule: new/modified rules in code-review/SKILL.md require matching procedural sections in the corresponding pr-review sub-agent file
3. Reference the sub-agent roster table in pr-review/SKILL.md for category-to-sub-agent mapping
4. Point to the "Permission and role changes" section in skills/pr-review/sub-agents/security.md as the model

Proposed Test Case

Verification:
1. AGENTS.md contains a section explaining the code-review / pr-review
   sub-agent relationship and the propagation rule
2. The section references the sub-agent roster table in pr-review/SKILL.md
3. The section references security.md as a procedural-section example

Functional validation:
- On the next 3 PRs touching skills/code-review/SKILL.md to add a new
  category or mandatory-finding directive, the code agent should also
  include changes to the corresponding sub-agent file

---

Labels: This is a documentation improvement to AGENTS.md, matching the 'documentation' label. It is ready for implementation.

---

Next steps:

• /fs-code — agent creates a PR to implement this issue
• /fs-code <your instruction> — agent implements with your specific guidance

[fullsend-ai-coder]

🤖 Finished Code · ✅ Success · Started 11:50 PM UTC · Completed 11:55 PM UTC
Commit: 13154d9 · View workflow run →

[fullsend-ai-prioritize]

RICE Priority Score: 2.4

Score breakdown

Dimension	Score	Reasoning
Reach	1	This affects all agents (code agent and review agent) that modify review rules in skills/code-review/SKILL.md. While not user-facing, every PR touching that file triggers the gap, causing repeated review cycles. The affected population is the internal agent workflow and team members dealing with the churn — a moderate number of users/workflows.
Impact	1.5	The missing documentation caused 6+ review cycles and 3 fix iterations on PR #445, with the review agent flagging the same gap from June 10 through July 30. Documenting the propagation requirement would eliminate this repeated churn, representing a significant efficiency gain for future PRs that touch review rules.
Confidence	0.8	High confidence — the issue is exceptionally well-documented with specific commit references (2be0d71), PR links (#445), workflow run IDs, and independent human confirmation from waynesun09. The proposed change is clearly scoped to adding a documentation section to AGENTS.md, and the triage agent confirmed readiness.
Effort	0.5	This is a documentation-only change to AGENTS.md. The issue itself provides a detailed outline of the four points to document, references the existing model (security.md's 'Permission and role changes' section), and specifies the routing table location. A well-scoped, small addition.

Formula: (1 x 1.5 x 0.8) / 0.5 = 2.4