docs(docs-review): add trigger phrase to description

[ralphbean]

Ran skillsaw (evaluating it per #188) against the repo's skills.
Adds a "Use when..." trigger phrase to the description so
description-based routing has a clear match condition.

Related to #188

Assisted-by: Claude Opus 4.6 noreply@anthropic.com
Signed-off-by: Ralph Bean rbean@redhat.com

---

_{Stack created with GitHub Stacks CLI • Give Feedback 💬}

[qodo-code-review]

PR Summary by Qodo

Clarify docs-review routing trigger phrase in skill description

📝 Documentation 🕐 Less than 5 minutes

AI Description

• Add an explicit “Use when…” trigger phrase to docs-review skill description
• Clarify when docs-review should run vs when it’s delegated from pr-review

Diagram

graph TD
  A["PR review workflow"] --> B["pr-review skill"] --> C["docs-review skill"] --> D["Doc findings"]
  C --> E[("Repository docs")]

  subgraph Legend
    direction LR
    _flow["Skill/step"] ~~~ _docs[("Docs content")]
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Add a dedicated routing metadata field (e.g., trigger/use_when)

• ➕ Avoids relying on free-form prose matching
• ➕ Enables consistent machine-readable routing across skills
• ➖ Requires updating the router/skill schema and any tooling that reads SKILL.md
• ➖ Larger change than a quick documentation clarification

2. Add a concrete example trigger sentence used by the router

• ➕ Makes the match condition unambiguous to humans and tooling
• ➕ Still low-effort within documentation-only scope
• ➖ May become stale if routing logic changes
• ➖ Can clutter the short description section

Recommendation: Given current “description-based routing” expectations, adding an explicit “Use when…” phrase in the description is the smallest, most compatible improvement. If routing becomes more central or brittle, consider moving match conditions to a dedicated, machine-readable field instead of prose.

Files changed (1) +2 / -1

Documentation (1) +2 / -1

SKILL.mdAdd “Use when…” trigger phrase to docs-review description +2/-1

Add “Use when…” trigger phrase to docs-review description

• Replaces the vague delegation note with an explicit “Use when…” condition to support description-based routing. Clarifies that the skill is applicable for checking whether code changes require doc updates and when delegated by pr-review.

skills/docs-review/SKILL.md

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 5:00 PM UTC · Completed 5:11 PM UTC

Commit: cb73aa3 · View workflow run →

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📜 Skill insights (1)

1. Protected skills/ file modified 📜 Skill insight § Compliance

Description

This PR modifies skills/docs-review/SKILL.md, which is a protected governance/infrastructure path
and must not be auto-approved. A human review is required to ensure the change is appropriate and
authorized.

Code

skills/docs-review/SKILL.md[R8-9]

+  Use when checking whether a PR's code changes require documentation
+  updates, or when delegated to by the pr-review skill.

Relevance

●●● Strong

Protected skills/ path touches are consistently flagged for mandatory human approval; similar
protected-path warnings appeared before.

PR-#157
PR-#59

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The compliance checklist explicitly treats any modifications under skills/ as protected-path
changes that must be flagged and not auto-approved. The diff shows new lines added to
skills/docs-review/SKILL.md, which is within the protected skills/ directory.

skills/docs-review/SKILL.md[8-9]
Skill: pr-review

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
This PR changes a file under `skills/`, which is a protected governance/infrastructure path. Protected-path changes must be explicitly surfaced to require human review and must not be auto-approved.

## Issue Context
The change appears documentation-only, but the protected-path rule still requires a finding to ensure proper review and authorization.

## Fix Focus Areas
- skills/docs-review/SKILL.md[8-9]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context

✅ Compliance rules (platform): 55 rules

✅ Skills: 4 invoked

  code-review

  code-implementation

  pr-review

  docs-review

Tip of the day

💡 Did you know, you can describe a rule in plain language on the Rules page and Qodo drafts it for you

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[fullsend-ai-review]

Review

Findings

Medium

• [protected-path] skills/docs-review/SKILL.md — This PR modifies a file under the skills/ protected path. The PR references issue Evaluate skillsaw for linting agent instructions #188 and explains the change rationale (adding a "Use when..." trigger phrase for description-based routing per skillsaw evaluation). Human approval is always required for protected-path changes, regardless of context.

Previous run

Review

Findings

Medium

• [protected-path] skills/docs-review/SKILL.md — This PR modifies a file under the skills/ protected path. The PR references issue Evaluate skillsaw for linting agent instructions #188 and explains the change rationale (adding a "Use when..." trigger phrase for description-based routing per skillsaw evaluation). Human approval is always required for protected-path changes, regardless of context.

Previous run (2)

Review

Findings

Medium

• [protected-path] skills/docs-review/SKILL.md — This PR modifies a file under the skills/ protected path. The PR references issue Evaluate skillsaw for linting agent instructions #188 and explains the change rationale (adding a "Use when..." trigger phrase for description-based routing per skillsaw evaluation). Human approval is always required for protected-path changes, regardless of context.

Previous run (3)

Review

Findings

Medium

• [protected-path] skills/docs-review/SKILL.md — This PR modifies a file under the skills/ protected path, which contains governance and agent instruction files. The PR links to issue Evaluate skillsaw for linting agent instructions #188 and explains the rationale for the change (adding a trigger phrase for description-based routing as recommended by skillsaw). Human approval is always required for protected-path changes, regardless of context.

---

Labels: PR modifies skill documentation metadata

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 9:40 PM UTC · Completed 9:51 PM UTC

Commit: 8db4ee5 · View workflow run →

[waynesun09]

Reviewed via 4-agent squad (claude-coder, claude-researcher, grok-review-agent, cursor-code-review) + verification pass at head 8db4ee5 — no CRITICAL/HIGH/MEDIUM findings survived verification.

[ralphbean]

/fs-fix move "Use when" phrase to the beginning of the description

[fullsend-ai-coder]

🤖 Finished Fix · ✅ Success · Started 10:47 PM UTC · Completed 10:52 PM UTC

Commit: 8db4ee5 · View workflow run →

[fullsend-ai-coder]

🔧 Fix agent — iteration 1 (human-triggered)

Moved the 'Use when' trigger phrase from the end to the beginning of the description field in skills/docs-review/SKILL.md per human instruction.

Fixed (1):

1. move Use when phrase to the beginning of the description: Moved the 'Use when checking whether a PR's code changes require documentation updates, or when delegated to by the pr-review skill' phrase from the end of the description field to the beginning, so description-based routing matches on the trigger condition first.

Tests: passed

Next steps:

• /fs-review — request a re-review of the changes
• /fs-fix <your instruction> — run another fix pass with specific guidance
• Push commits directly — review re-runs automatically on push
  _{Updated by fullsend fix agent}

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 10:53 PM UTC · Completed 11:02 PM UTC

Commit: c0b7a81 · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 3:38 PM UTC · Completed 3:50 PM UTC

Commit: defaa65 · View workflow run →

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 4:11 PM UTC · Completed 4:30 PM UTC

Commit: defaa65 · View workflow run →

[fullsend-ai-retro]

Retro: PR #750 — docs(docs-review): add trigger phrase to description

PR #750 was a 1-file, +6/−5 line documentation metadata change to skills/docs-review/SKILL.md, rewording the YAML description field to add a "Use when..." trigger phrase for description-based routing. The workflow completed successfully but with significant compute overhead for the scale of the change.

Timeline

1. Aug 11 16:59 — ralphbean opens PR. Automated reviews begin.
2. Aug 11 17:00–17:11 — Initial review (run 31515290959, ~12 min) dispatches 4 sub-agents (correctness, style-conventions, intent-coherence, security). All return zero findings. One medium [protected-path] finding emitted. Labels requires-manual-review and documentation applied.
3. Aug 13 21:38 — Force push (rebase onto updated base branch).
4. Aug 13 21:40 — Second review (run 31746560266, ~13 min) dispatches 4 sub-agents. All return zero findings. Same protected-path finding.
5. Aug 13 22:05 — waynesun09 approves (used an independent 4-agent squad review confirming zero issues).
6. Aug 13 22:46 — ralphbean runs /fs-fix move "Use when" phrase to the beginning of the description.
7. Aug 13 22:47–22:52 — Fix agent (run 31751336133, ~6 min) moves the trigger phrase to the start of the description, commits, and pushes.
8. Aug 13 22:53 — Post-fix review (run 31751721966, ~10 min) dispatches 2 sub-agents. Zero findings.
9. Aug 14 15:37 — Another force push (rebase).
10. Aug 14 15:38 — Final review (run 31815412859, ~13 min) dispatches 3 sub-agents. Zero findings.
11. Aug 14 16:09 — Merged via merge queue.

What went well

• Fix agent was efficient. Completed the human-directed reorder in ~6 minutes with clean commit, secret scanning, and linting.
• Review agent correctly identified protected-path. The skills/ directory is correctly flagged as requiring human approval, and the agent consistently deferred.
• Sub-agent scoping improved across runs. Review 3 (post-fix) narrowed to only 2 sub-agents; the agent recognized which dimensions were no longer relevant.
• No false positives beyond protected-path. The review agent did not generate spurious findings for this clean documentation change.

Compute overhead

4 review runs × ~12 min average = ~48 minutes of Opus compute for a 6-line description rewrite. Of these, 2 runs were triggered by rebases with no PR content changes, and 1 was a post-fix re-review. Only the initial review was strictly necessary. All sub-agents across all runs returned zero findings.

Evidence for existing issues

All improvement opportunities identified in this retro are already covered by open issues. No new proposals are warranted.

• Short-circuit review on rebase-only pushes to avoid redundant sub-agent dispatch #108 (short-circuit rebase-only reviews): Reviews 2 and 4 were triggered by rebases with zero PR content changes, costing ~26 minutes of compute for identical results.
• Skip irrelevant review dimensions for docs-only PRs to reduce token cost #373 (skip irrelevant dimensions for docs-only PRs): All reviews dispatched code-analysis sub-agents (correctness, security) for a YAML frontmatter description change — none could find issues.
• Scope re-review to finding verification when push only addresses prior findings #343 (scope re-review to finding verification after fix): Review 3 could have been limited to verifying the fix addressed the reorder request.
• Review agent should assess semantic significance of protected-path changes before assigning high severity #741 (assess semantic significance of protected-path changes): The protected-path finding was medium severity for a description text reorder with negligible semantic risk.
• Review agent should detect and analyze file-level scope changes between review iterations #378 (detect file-level scope changes between iterations): Reviews 2, 4, and 5 spent significant deliberation time on changed_since_prior lists inflated by base-branch changes (26–39 files from rebases), correctly identifying the noise but still dispatching sub-agents.