From 0243b6ec4ca02f5a188506d0c0342e3617a7dee1 Mon Sep 17 00:00:00 2001 From: Claude Sonnet 5 Date: Tue, 15 Sep 2026 10:36:19 +0000 Subject: [PATCH 1/2] retro: push mechanical coding-standards findings toward deterministic checks retro currently treats every reviewer-agent gap the same way: write a new CODING_STANDARDS.md line. That's fine for judgement calls, but for fixed syntactic patterns it just asks the reviewer agent to re-derive the same call on every future diff, forever, instead of paying once for a check. Adds two things to the Automated checks / Coding standards categories: - Automated checks now treats an un-linted repo (no pre-commit hook, no CI job running lint/typecheck/test) as a finding in its own right, not just a consequence of a specific mistake. - Coding standards now classifies a violation as mechanical (deterministic check) vs. judgement call (CODING_STANDARDS.md) before writing a finding, and defaults to building the check. Kept language-agnostic (no ESLint/ts-specific naming) since retro runs across repos in different languages. No em-dashes, per this repo's prose rule in CLAUDE.md. Co-Authored-By: Claude Sonnet 5 --- skills/in-progress/retro/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/in-progress/retro/SKILL.md b/skills/in-progress/retro/SKILL.md index f5fed82..12149ac 100644 --- a/skills/in-progress/retro/SKILL.md +++ b/skills/in-progress/retro/SKILL.md @@ -15,8 +15,8 @@ The user has asked for a **retrospective**. You are suggesting improvements to t 3. Look for candidates for improvement in these categories. - **Navigation**: how easy was it for the agent to find the right files? Are there hidden dependencies between files? Would a **navigation pointer** make it easier? _Use when_ the session took a long time to find a piece of information. -- **Automated checks**: are there automated checks that could catch errors the agent made? Linting, typing, tests, filesystem linters? _Use when_ the agent made a mistake that could have been caught by an automated check. -- **Coding standards**: should the **reviewer agent** be given a new rule to enforce? Should an existing rule be removed or clarified? _Use when_ the reviewer agent failed to catch a mistake. +- **Automated checks**: are there automated checks that could catch errors the agent made? Linting, typing, tests, filesystem linters? Read the repo's own check command first (its `package.json`/build-tool `lint`/`check` scripts, its CI workflow), so a check that already exists but sits unwired or silently broken is the finding, not a reinvention. A repo with no **guardrail** (no pre-commit hook and no CI job running its lint/typecheck/test command) is itself a finding: an un-linted repo is a standing missed opportunity, not a neutral default. _Use when_ the agent made a mistake an automated check could have caught, or the repo has no guardrail at all. +- **Coding standards**: should the **reviewer agent** be given a new rule to enforce? Should an existing rule be removed or clarified? Classify the violation first: a **mechanical** one (a fixed syntactic pattern, a banned API, an import shape, a file-location rule) gets a deterministic check, full stop: a custom rule in the repo's own linter, a new pre-commit hook, or a new CI job, whichever the repo's language and existing guardrail make cheapest. Default to building the check over writing the rule. Reserve `CODING_STANDARDS.md` for genuine **judgement calls** (cross-file consistency, "matches the surrounding style," anything no guardrail could ever substitute for). _Use when_ the reviewer agent failed to catch a mistake. - **Global AGENTS.md**: are there any steering instructions that should be moved to coding standards (or automated checks) instead? _Use when_ the AGENTS.md file is particularly large - in the repo OR the user's global scope. - **Tool economy**: did the agent make expensive tool calls that could be streamlined? Is there any custom tooling (CLI's, MCP's) that is particularly token-inefficient? _Use when_ the agent made an expensive tool call. - **No-ops**: look for instructions in steering files that don't modify the agent's behavior. _Use when_ the steering files are large and unwieldy. From 6942bff8a53666e83a2c621696d2a8e3022429e6 Mon Sep 17 00:00:00 2001 From: Claude Sonnet 5 Date: Tue, 15 Sep 2026 13:55:12 +0000 Subject: [PATCH 2/2] Add changeset for retro deterministic-checks update Co-Authored-By: Claude Sonnet 5 --- .changeset/retro-deterministic-checks.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/retro-deterministic-checks.md diff --git a/.changeset/retro-deterministic-checks.md b/.changeset/retro-deterministic-checks.md new file mode 100644 index 0000000..d4865b0 --- /dev/null +++ b/.changeset/retro-deterministic-checks.md @@ -0,0 +1,5 @@ +--- +"mattpocock-skills": patch +--- + +retro: classify coding-standards findings as mechanical or judgement calls before writing them. A mechanical violation (a fixed syntactic pattern, a banned API, an import shape, a file-location rule) now gets a deterministic check instead (a linter rule, a pre-commit hook, or a CI job), reserving `CODING_STANDARDS.md` for genuine judgement calls. Automated checks also now flags a repo with no guardrail at all (no pre-commit hook, no CI lint/typecheck/test job) as a finding in its own right.