docs(issue-labels): 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

Add explicit trigger phrase to issue-labels skill description

📝 Documentation 🕐 Less than 5 minutes

AI Description

• Add a clear "Use when..." trigger phrase to the issue-labels skill description.
• Make description-based skill routing easier by providing an explicit match condition.

Diagram

graph TD
  A["SKILL.md description"] --> B{"Trigger phrase present?"} --> C(["Agent / router"]) --> D(["Select issue-labels skill"])
  subgraph Legend
    direction LR
    _doc["Text/metadata"] ~~~ _dec{"Decision"} ~~~ _proc(["Process"])
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Add a machine-readable routing field (e.g., `use_when` / `triggers`)

• ➕ Avoids relying on prose parsing and phrase conventions
• ➕ Enables stricter validation/testing of routing behavior
• ➖ Requires updating the skill schema and any tooling that reads it
• ➖ More invasive than a doc-only change

2. Add a dedicated "Routing" section with examples

• ➕ Keeps SKILL.md human-friendly while still improving clarity
• ➕ Can document multiple trigger examples without overloading the one-line description
• ➖ May still be harder for automated routing to consume than a structured field
• ➖ Longer docs can drift if not maintained

Recommendation: For the current goal (evaluating skillsaw and improving routing clarity with minimal risk), the PR’s approach is the best fit. If description-based routing becomes a long-term dependency, consider introducing a structured use_when/triggers field to make matching deterministic and tooling-friendly.

Files changed (1) +3 / -1

Documentation (1) +3 / -1

SKILL.mdClarify issue-labels skill trigger condition in description +3/-1

Clarify issue-labels skill trigger condition in description

• Extends the skill description to include a "Use when..." phrase, making it explicit when the skill should be applied. This supports description-based routing by providing a clear match condition.

skills/issue-labels/SKILL.md

[fullsend-ai-review]

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

Commit: 1706f1b · 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 a protected governance/infrastructure path under skills/, which must not be
auto-approved and requires explicit human review even if the change is documentation-only.

Code

skills/issue-labels/SKILL.md[R5-7]

+  on issues and pull requests. Produces label_actions in the agent result
+  JSON. Use when labeling an issue or pull request based on its content and
+  the repository's label conventions.

Relevance

●●● Strong

Repo has active protected-path enforcement; changes under protected prefixes are treated as
requiring manual review.

PR-#569

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

Compliance rule 1538392 requires raising a finding whenever protected governance/infrastructure
paths (including skills/) are modified. The diff shows added lines in
skills/issue-labels/SKILL.md, which is under the protected skills/ directory.

skills/issue-labels/SKILL.md[5-7]
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
The PR modifies a protected path (`skills/`), which must not be auto-approved and needs explicit human/CODEOWNERS review.

## Issue Context
Protected-path changes require heightened scrutiny regardless of whether the change is documentation-only.

## Fix Focus Areas
- skills/issue-labels/SKILL.md[5-7]

ⓘ 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 group findings by type and pick your Finding display, from Minimal to Full

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[fullsend-ai-review]

Review

Findings

Medium

• [protected-path] skills/issue-labels/github/SKILL.md, skills/issue-labels/gitlab/SKILL.md — These files are under the skills/ protected path, which requires human approval for changes. The PR links to issue Evaluate skillsaw for linting agent instructions #188 and explains the rationale (adding trigger phrases to descriptions for description-based routing after evaluating skillsaw). Human approval is always required for protected-path changes, regardless of context.

Previous run

Review

Findings

Medium

• [protected-path] skills/issue-labels/github/SKILL.md — This file is under the skills/ protected path, which requires human approval for changes. The PR links to issue Evaluate skillsaw for linting agent instructions #188 and explains the rationale (adding a trigger phrase to the description for description-based routing after evaluating skillsaw). Human approval is always required for protected-path changes, regardless of context.

Previous run (2)

Review

Findings

Medium

• [protected-path] skills/issue-labels/github/SKILL.md — This file is under the skills/ protected path, which requires human approval for changes. The PR links to issue Evaluate skillsaw for linting agent instructions #188 and explains the rationale (adding a trigger phrase for description-based routing after evaluating skillsaw). Human approval is always required for protected-path changes, regardless of context.

Previous run (3)

Review

Findings

Medium

• [protected-path] skills/issue-labels/SKILL.md — This file is under the skills/ protected path, which requires human approval for changes. The PR links to issue Evaluate skillsaw for linting agent instructions #188 and explains the rationale (adding a trigger phrase for description-based routing after evaluating skillsaw). Human approval is always required for protected-path changes, regardless of context.

Previous run (4)

Review

Findings

Medium

• [protected-path] skills/issue-labels/SKILL.md — This file is under the skills/ protected path, which requires human approval for changes. The PR links to issue Evaluate skillsaw for linting agent instructions #188 and explains the rationale (adding a trigger phrase for description-based routing after evaluating skillsaw). Human approval is always required for protected-path changes, regardless of context.

Previous run (5)

Review

Findings

Medium

• [protected-path] skills/issue-labels/SKILL.md — This file is under the skills/ protected path, which requires human approval for changes. The PR links to issue Evaluate skillsaw for linting agent instructions #188 and explains the rationale (adding a trigger phrase for description-based routing after evaluating skillsaw). Human approval is always required for protected-path changes, regardless of context.

---

Labels: PR modifies only a skill documentation file, adding a trigger phrase to the description frontmatter.

[waynesun09]

Review-only pass: 1 finding below.

[fullsend-ai-review]

🤖 Review · ⚠️ Cancelled · Started 9:39 PM UTC · Ended 9:48 PM UTC

Commit: d7364f5 · View workflow run →

[ralphbean]

/fs-fix address @waynesun09's finding

[fullsend-ai-coder]

🤖 Finished Fix · ✅ Success · Started 9:43 PM UTC · Completed 9:48 PM UTC

Commit: d7364f5 · View workflow run →

[fullsend-ai-coder]

🔧 Fix agent — iteration 1 (human-triggered)

Addressed waynesun09's finding: extended the trigger phrase to mention the skill's primary invocation path (delegation from review and triage agents), matching the convention established in sibling PR #750.

Fixed (1):

1. Trigger phrase omits delegation invocation path (skills/issue-labels/SKILL.md): Extended the trigger phrase to mention delegation from the review and triage agents, matching the convention in sibling PR docs(docs-review): add trigger phrase to description #750 (docs-review). The phrase now reads: 'Use when labeling an issue or pull request based on its content and the repository label conventions, or when delegated to by the review or triage agent.'

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 9:49 PM UTC · Completed 9:58 PM UTC

Commit: df8afe0 · View workflow run →

[ralphbean]

/fs-fix move the "Use when" trigger language to be the first sentence of the description

[fullsend-ai-coder]

🤖 Finished Fix · ✅ Success · Started 11:58 PM UTC · Completed 12:03 AM UTC

Commit: df8afe0 · View workflow run →

[fullsend-ai-coder]

🔧 Fix agent — iteration 2 (human-triggered)

Moved the 'Use when' trigger language to the beginning of the description per human instruction. The sentence order was reversed so the trigger phrase comes first for description-based routing.

Fixed (1):

1. move trigger phrase to first sentence of description: Reordered the SKILL.md description so the 'Use when' trigger language is the first sentence, followed by the existing description text about discovering labels and producing label_actions.

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 12:04 AM UTC · Completed 12:15 AM UTC

Commit: 7d3a5aa · View workflow run →

[waynesun09]

Trigger phrase now mentions delegation from the review/triage agent, addressing the earlier finding. CI is green.

[waynesun09]

Review-only pass: 2 findings below (1 inline, 1 in this summary since its file isn't part of this PR's diff).

MEDIUM: GitLab variant of issue-labels description would remain unfixed even after rebase (skills/issue-labels/gitlab/SKILL.md, near line 3)

Confirmed on main that both skills/issue-labels/github/SKILL.md and skills/issue-labels/gitlab/SKILL.md still carry the original description text with no "Use when..." trigger phrase — this PR's fix only touches the (now-deleted) flat file, so once rebased per the companion CRITICAL finding, applying the change to only the github variant would leave the gitlab variant's description without the same delegation-routing trigger phrase, and the two forge variants would drift out of sync on a field AGENTS.md requires (when/how to use).

Suggestion: when re-applying this fix post-rebase, update the description in both skills/issue-labels/github/SKILL.md and skills/issue-labels/gitlab/SKILL.md with equivalent trigger-phrase wording.

[fullsend-ai-review]

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

Commit: a9344d5 · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 4:10 PM UTC · Completed 4:19 PM UTC

Commit: 44b14dd · View workflow run →

[ralphbean]

/fs-fix rebase this on main and replicate the change across the github and gitlab variant

[fullsend-ai-coder]

🤖 Finished Fix · ✅ Success · Started 5:59 PM UTC · Completed 6:03 PM UTC

Commit: 44b14dd · View workflow run →

[fullsend-ai-coder]

🔧 Fix agent — iteration 3 (human-triggered)

Branch was already rebased on main. Replicated the trigger phrase change to the GitLab variant of issue-labels SKILL.md, adapting GitHub terminology (pull request, repository) to GitLab equivalents (merge request, project).

Fixed (2):

1. rebase on main: Verified branch is already rebased on main (d6e29fa is the fork point and tip of origin/main). No rebase operation needed.
2. replicate trigger phrase to gitlab variant: Added 'Use when labeling an issue or merge request...' trigger phrase to skills/issue-labels/gitlab/SKILL.md, adapting terminology from the github variant (merge request instead of pull request, project instead of repository) while preserving the GitLab-specific distinguishing text.

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 6:05 PM UTC · Completed 6:14 PM UTC

Commit: 1a1778d · View workflow run →

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 6:57 PM UTC · Completed 7:16 PM UTC

Commit: 1a1778d · View workflow run →

[fullsend-ai-retro]

Retro: PR #752 — docs(issue-labels): add trigger phrase to description

Workflow overview

This documentation PR added a "Use when..." trigger phrase to the issue-labels skill description for description-based routing. It was opened by ralphbean as part of evaluating the skillsaw tool (issue #188). The PR went through 3 fix iterations over 3 days before merging, all driven by human reviewer (waynesun09) findings that the review agent did not catch.

Review quality gap

The review agent ran 6 successful review passes and only ever produced the procedural MEDIUM [protected-path] finding (files under skills/ require human approval). All three substantive findings were caught exclusively by the human reviewer:

1. Delegation omission (MEDIUM) — The trigger phrase omitted the skill's primary invocation path: delegation from the review and triage agents. waynesun09 cited specific lines in agents/review.md and agents/triage.md and pointed to sibling PR docs(docs-review): add trigger phrase to description #750's convention.
2. Stale base / deleted file (CRITICAL) — The PR was editing a flat skills/issue-labels/SKILL.md that had been restructured into github/ and gitlab/ variants on main. The merge state was CONFLICTING.
3. GitLab variant parity (MEDIUM) — Only the GitHub variant would receive the trigger phrase fix; the GitLab variant would be left without it.

Notably, in review run 31815407032, the correctness sub-agent explicitly noticed the GitLab variant gap but classified it as "outside PR scope" and did not emit a finding. Per the sub-agent's own instructions, it does not own PR scope evaluation (that belongs to intent-coherence), and it is explicitly required to check beyond-diff files for correctness implications. This was an LLM self-censoring error, not a missing instruction.

Fix agent performance

All 3 fix runs completed successfully in ~5–6 minutes each with no errors or retries. The fix agent handled each /fs-fix command correctly, including adapting GitHub terminology to GitLab conventions for the variant replication in iteration 3.

Evidence for existing open issues

• agents#235 (review agent should detect significant base-branch divergence): This PR edited a file that had been deleted and restructured on main. The review agent did not flag the merge conflict across 6 runs.
• agents#108 (short-circuit review on rebase-only pushes): Two review runs were cancelled as superseded by rapid successive pushes, and several runs after rebases produced identical findings to prior runs.
• agents#338 (re-review should verify cross-file consistency of documentation fixes): Related to the GitLab variant gap, though that issue is specifically scoped to re-review passes.

Proposals filed

Two proposals below address the novel findings from this retro.

Proposals filed

• Review agent should detect cross-variant drift for forge-specific skills (in fullsend-ai/agents)
• Correctness sub-agent should not suppress beyond-diff findings under scope reasoning it does not own (in fullsend-ai/agents)