What happened
PR #540 started as a 44-line conceptual addition to skills/retro-analysis/SKILL.md describing three flapping patterns (file oscillation, test result flipping, cycle count), when to flag them, and how to report them. Over 7 review rounds spanning 18 days, the section progressively expanded into a detailed engineering specification: specific gh CLI commands with flags, API pagination logic, cross-repo filtering strategies, and run-to-commit correlation algorithms. Each round of review correctly identified edge cases in the growing implementation detail, but each fix introduced new surface area that generated new findings. The PR author observed that "the scope shifted from 'what patterns to detect' to an increasingly detailed engineering spec for querying GitHub Actions logs" while the core value stayed stable from commit 1. The PR was closed and replaced by PR #834 which stays at the same altitude as the rest of the skill.
What could go better
AGENTS.md's existing guidance — "Simplicity first" and "Surgical changes" — applies to code changes generally but does not address the specific altitude question for skill documentation. Skill SKILL.md files serve a distinct purpose: they teach agents how to approach tasks, not how to implement specific API integrations. When skill docs descend into engineering specifics (exact CLI flags, pagination strategies, cross-repo correlation algorithms), they create fragile coupling to platform internals and balloon the surface area that reviewers must verify. The 7-round cycle on PR #540 was a direct consequence of this altitude mismatch. Confidence: moderate — the pattern is clear from this PR, but it's a single data point. The guidance could prevent recurrence for both human and agent authors of skill documentation.
Proposed change
Add a short subsection to AGENTS.md under or after the existing "Simplicity first" section, titled something like "Skill documentation altitude." The guidance should state that SKILL.md files should stay at the directive altitude: describe what to detect, what patterns to match, and what to report — but delegate data-gathering implementation to subagent prompts or existing skill sections rather than prescribing specific CLI commands, API queries, or pagination strategies. When a skill section needs to reference external data, it should name the data source and the fields needed, not the exact commands to retrieve them. This keeps skill docs stable across platform changes and reduces review surface area.
Validation criteria
Future PRs modifying SKILL.md files in this repo should be reviewable in 1–2 rounds when the changes stay at the directive altitude. The guidance should be citable by reviewers when a skill PR drifts into engineering specifics, providing a concrete standard rather than relying on subjective judgment about scope.
Generated by retro agent from #540
What happened
PR #540 started as a 44-line conceptual addition to
skills/retro-analysis/SKILL.mddescribing three flapping patterns (file oscillation, test result flipping, cycle count), when to flag them, and how to report them. Over 7 review rounds spanning 18 days, the section progressively expanded into a detailed engineering specification: specificghCLI commands with flags, API pagination logic, cross-repo filtering strategies, and run-to-commit correlation algorithms. Each round of review correctly identified edge cases in the growing implementation detail, but each fix introduced new surface area that generated new findings. The PR author observed that "the scope shifted from 'what patterns to detect' to an increasingly detailed engineering spec for querying GitHub Actions logs" while the core value stayed stable from commit 1. The PR was closed and replaced by PR #834 which stays at the same altitude as the rest of the skill.What could go better
AGENTS.md's existing guidance — "Simplicity first" and "Surgical changes" — applies to code changes generally but does not address the specific altitude question for skill documentation. Skill SKILL.md files serve a distinct purpose: they teach agents how to approach tasks, not how to implement specific API integrations. When skill docs descend into engineering specifics (exact CLI flags, pagination strategies, cross-repo correlation algorithms), they create fragile coupling to platform internals and balloon the surface area that reviewers must verify. The 7-round cycle on PR #540 was a direct consequence of this altitude mismatch. Confidence: moderate — the pattern is clear from this PR, but it's a single data point. The guidance could prevent recurrence for both human and agent authors of skill documentation.
Proposed change
Add a short subsection to AGENTS.md under or after the existing "Simplicity first" section, titled something like "Skill documentation altitude." The guidance should state that SKILL.md files should stay at the directive altitude: describe what to detect, what patterns to match, and what to report — but delegate data-gathering implementation to subagent prompts or existing skill sections rather than prescribing specific CLI commands, API queries, or pagination strategies. When a skill section needs to reference external data, it should name the data source and the fields needed, not the exact commands to retrieve them. This keeps skill docs stable across platform changes and reduces review surface area.
Validation criteria
Future PRs modifying SKILL.md files in this repo should be reviewable in 1–2 rounds when the changes stay at the directive altitude. The guidance should be citable by reviewers when a skill PR drifts into engineering specifics, providing a concrete standard rather than relying on subjective judgment about scope.
Generated by retro agent from #540