diff --git a/internal/scaffold/fullsend-repo/skills/retro-analysis/SKILL.md b/internal/scaffold/fullsend-repo/skills/retro-analysis/SKILL.md index da1f54943a..1632bbf1b5 100644 --- a/internal/scaffold/fullsend-repo/skills/retro-analysis/SKILL.md +++ b/internal/scaffold/fullsend-repo/skills/retro-analysis/SKILL.md @@ -123,6 +123,59 @@ Use multiple searches with different keyword combinations if the first returns n When skipping, note the duplicate in your `summary` field so the human understands what was filtered and why. +### Evidence issue cap + +Evidence proposals use the title format `Evidence for #N` (where `N` is +the parent issue number). This convention is how the retro agent links +data points back to a systemic issue — always use this exact format +when filing evidence. + +Before filing an evidence proposal, check how many open evidence issues +already exist for that parent. + +Dispatch a subagent to count existing evidence issues: + +```bash +gh api \ + "search/issues?q=repo:+is:issue+is:open+in:title+%22Evidence+for+%23N%22&per_page=1" \ + --jq '.total_count' +``` + +Replace `` with the proposal's target repository and `N` +with the parent issue number. + +If the count query fails, returns a non-numeric result, or the +subagent errors out, treat the count as >= 5 (fail closed) and skip +the evidence proposal. Do not file evidence when the cap cannot be +verified. + +**If the count is >= 5:** + +1. **Skip the evidence proposal entirely.** Do not include it in the + `proposals` array. +2. **Note the cap in your summary.** Mention that the pattern is + already well-documented with sufficient data points. Include the + parent issue number and the current PR/issue as an additional data + point so the information is not lost — it just does not warrant a + new issue. + +Example summary note: + +> Pattern for #N is well-documented (≥5 evidence issues). This +> PR adds another data point but does not warrant a new evidence +> issue. + +**If the count is < 5:** proceed with filing the evidence proposal +normally. + +Only open evidence issues count toward the cap — closed issues do not. + +**Concurrency note:** Two retro runs triggered by different PRs can +both query the count before either files, causing both to see the same +value and potentially exceeding the cap by one. This is an accepted +limitation — the cap is advisory and a brief overshoot does not +meaningfully harm the issue tracker. + ## Localization guidance When deciding where a proposed change belongs: