What happened
On PR #748, ralphbean added a "Use when..." trigger phrase to the code-implementation skill description, appending it at the end of the description frontmatter field. The review agent ran on the initial commit (run 31515289059) and produced only a protected-path governance finding. The style-conventions sub-agent did not flag the placement.
Two days later, human reviewer waynesun09 cross-referenced 5 peer skills (merge-queue, finding-agent-runs, agent-scaffolding, autonomy-readiness, retro-analysis) and found that every one places "Use when..." as the first sentence of the description. The PR's end-of-description placement was a convention violation. The fix agent moved the phrase to the front in commit b89aa07 (run 31758710230).
What could go better
The style-conventions sub-agent is designed to derive expected patterns from the existing codebase. However, its exploration budget for trivial diffs (under 20 changed lines, single concern) caps reading at "the changed files plus at most 3 sibling files in the same directory." Skill files live in separate subdirectories under skills/ (e.g., skills/code-implementation/, skills/merge-queue/), so peer SKILL.md files are not in the same directory — they are in sibling directories. The sub-agent could not discover the convention even if it tried.
This PR had 24 changed lines (+12/−12) but a single concern, placing it at the boundary of the trivial/non-trivial classification. Even under the non-trivial budget ("3–5 existing files in the same package/directory"), the same-directory constraint would exclude peer skill files.
Confidence: medium-high. The exploration budget is the most likely cause. It is also possible the sub-agent lacked specific guidance to check SKILL.md frontmatter field ordering as a convention.
Proposed change
In skills/pr-review/sub-agents/style-conventions.md, extend the exploration budget rules to cover files with the same basename in sibling directories, not just files in the same directory. Add a clause like:
When the changed file has a standardized name (e.g., SKILL.md, AGENTS.md, README.md) that appears in multiple sibling directories, read at least 3 peer files with the same basename to check for structural conventions (field ordering, section presence, description phrasing patterns).
This ensures the sub-agent can detect conventions established across peer files without requiring a blanket increase to the exploration budget for all trivial diffs.
Validation criteria
On the next 3 PRs that modify a SKILL.md file in this repo, the style-conventions sub-agent should read at least 2 peer SKILL.md files and flag any structural pattern deviations (e.g., description field ordering, trigger phrase placement). If no such PRs occur within 30 days, validate by confirming the sub-agent definition includes the added guidance.
Generated by retro agent from #748
What happened
On PR #748, ralphbean added a "Use when..." trigger phrase to the
code-implementationskill description, appending it at the end of thedescriptionfrontmatter field. The review agent ran on the initial commit (run 31515289059) and produced only a protected-path governance finding. The style-conventions sub-agent did not flag the placement.Two days later, human reviewer waynesun09 cross-referenced 5 peer skills (merge-queue, finding-agent-runs, agent-scaffolding, autonomy-readiness, retro-analysis) and found that every one places "Use when..." as the first sentence of the description. The PR's end-of-description placement was a convention violation. The fix agent moved the phrase to the front in commit
b89aa07(run 31758710230).What could go better
The style-conventions sub-agent is designed to derive expected patterns from the existing codebase. However, its exploration budget for trivial diffs (under 20 changed lines, single concern) caps reading at "the changed files plus at most 3 sibling files in the same directory." Skill files live in separate subdirectories under
skills/(e.g.,skills/code-implementation/,skills/merge-queue/), so peerSKILL.mdfiles are not in the same directory — they are in sibling directories. The sub-agent could not discover the convention even if it tried.This PR had 24 changed lines (+12/−12) but a single concern, placing it at the boundary of the trivial/non-trivial classification. Even under the non-trivial budget ("3–5 existing files in the same package/directory"), the same-directory constraint would exclude peer skill files.
Confidence: medium-high. The exploration budget is the most likely cause. It is also possible the sub-agent lacked specific guidance to check SKILL.md frontmatter field ordering as a convention.
Proposed change
In
skills/pr-review/sub-agents/style-conventions.md, extend the exploration budget rules to cover files with the same basename in sibling directories, not just files in the same directory. Add a clause like:This ensures the sub-agent can detect conventions established across peer files without requiring a blanket increase to the exploration budget for all trivial diffs.
Validation criteria
On the next 3 PRs that modify a
SKILL.mdfile in this repo, the style-conventions sub-agent should read at least 2 peerSKILL.mdfiles and flag any structural pattern deviations (e.g., description field ordering, trigger phrase placement). If no such PRs occur within 30 days, validate by confirming the sub-agent definition includes the added guidance.Generated by retro agent from #748