What happened
On PR #126, the author added two new hierarchy entries to AGENTS.md using markdown link syntax. Starting in round 1 (2026-09-16T14:13Z), fullsend-ai-review's style-conventions finding argued this was inconsistent formatting because 'AGENTS.md is not a Skillsaw content-path' — reasoning from .skillsaw.yaml's content-paths: list, which enumerates only docs/vision.md and docs/architecture.md. The agent repeated this unchanged finding across rounds 2, 3, and 4 despite the author's pushback. In round 5 (~16:32-16:54Z), the agent finally checked .skillsaw-baseline.json and discovered its premise was backwards: the checked-in baseline already records 13 baselined content-unlinked-internal-reference violations for AGENTS.md's existing plain-backtick references, and the skillsaw pre-commit hook (.pre-commit-config.yaml lines 64-67) runs with the tool's default pass_filenames: false, i.e. a whole-repo scan that ignores content-paths scoping entirely. Under this repo's strict: true, fail-on: info config, the author's original markdown-link choice was correct — it avoided introducing new, non-baselined violations that would fail CI — and the agent retracted the finding, explicitly stating the 'not a content-path' counter-argument used in rounds 1-4 'does not [hold], since the baseline proves the file is scanned regardless' (see PR #126, sticky comment #126 (comment), round-5 entry).
What could go better
I'm highly confident this cost 4 wasted review rounds on a finding that was wrong from round 1, because the review agent (and, by the same misreading, a human skimming the config) could reasonably conclude content-paths scopes the whole hook's file coverage — it does not, and nothing in .skillsaw.yaml says so. I'm less certain whether this is best fixed by clarifying the config (this proposal) versus changing review-agent behavior (see the companion proposal to the agents repo) — both are worth doing, and they're complementary: the config comment prevents the specific confusion that occurred here; the agent-behavior change generalizes to other lint tools with similarly non-obvious scoping.
Proposed change
Add an inline comment above content-paths: in .skillsaw.yaml stating that this list does not restrict which files the skillsaw pre-commit hook scans (the hook runs whole-repo via the tool's default pass_filenames: false), and that .skillsaw-baseline.json — not content-paths — is the source of truth for whether a given file/pattern is already exempted from a rule. This is a one-line comment change in a config file already tracked in this repo.
Validation criteria
Re-run this exact review scenario (a markdown-link vs. plain-backtick formatting question about a file outside content-paths) on the next PR that touches AGENTS.md or another non-content-paths file with existing baselined Skillsaw violations. The review agent (or a human reviewer reading the comment) should reference .skillsaw-baseline.json directly rather than reasoning from content-paths scope, and should not take more than 1 round to reach the correct conclusion about whether new formatting introduces a non-baselined violation.
Generated by retro agent from #126
What happened
On PR #126, the author added two new hierarchy entries to AGENTS.md using markdown link syntax. Starting in round 1 (2026-09-16T14:13Z), fullsend-ai-review's style-conventions finding argued this was inconsistent formatting because 'AGENTS.md is not a Skillsaw content-path' — reasoning from
.skillsaw.yaml'scontent-paths:list, which enumerates onlydocs/vision.mdanddocs/architecture.md. The agent repeated this unchanged finding across rounds 2, 3, and 4 despite the author's pushback. In round 5 (~16:32-16:54Z), the agent finally checked.skillsaw-baseline.jsonand discovered its premise was backwards: the checked-in baseline already records 13 baselinedcontent-unlinked-internal-referenceviolations for AGENTS.md's existing plain-backtick references, and the skillsaw pre-commit hook (.pre-commit-config.yamllines 64-67) runs with the tool's defaultpass_filenames: false, i.e. a whole-repo scan that ignorescontent-pathsscoping entirely. Under this repo'sstrict: true, fail-on: infoconfig, the author's original markdown-link choice was correct — it avoided introducing new, non-baselined violations that would fail CI — and the agent retracted the finding, explicitly stating the 'not a content-path' counter-argument used in rounds 1-4 'does not [hold], since the baseline proves the file is scanned regardless' (see PR #126, sticky comment #126 (comment), round-5 entry).What could go better
I'm highly confident this cost 4 wasted review rounds on a finding that was wrong from round 1, because the review agent (and, by the same misreading, a human skimming the config) could reasonably conclude
content-pathsscopes the whole hook's file coverage — it does not, and nothing in.skillsaw.yamlsays so. I'm less certain whether this is best fixed by clarifying the config (this proposal) versus changing review-agent behavior (see the companion proposal to the agents repo) — both are worth doing, and they're complementary: the config comment prevents the specific confusion that occurred here; the agent-behavior change generalizes to other lint tools with similarly non-obvious scoping.Proposed change
Add an inline comment above
content-paths:in.skillsaw.yamlstating that this list does not restrict which files the skillsaw pre-commit hook scans (the hook runs whole-repo via the tool's defaultpass_filenames: false), and that.skillsaw-baseline.json— notcontent-paths— is the source of truth for whether a given file/pattern is already exempted from a rule. This is a one-line comment change in a config file already tracked in this repo.Validation criteria
Re-run this exact review scenario (a markdown-link vs. plain-backtick formatting question about a file outside
content-paths) on the next PR that touches AGENTS.md or another non-content-paths file with existing baselined Skillsaw violations. The review agent (or a human reviewer reading the comment) should reference.skillsaw-baseline.jsondirectly rather than reasoning fromcontent-pathsscope, and should not take more than 1 round to reach the correct conclusion about whether new formatting introduces a non-baselined violation.Generated by retro agent from #126