diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 4229b828c..42a799634 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -334,7 +334,7 @@ "name": "re-anchor", "source": "./plugins/re-anchor", "category": "quality", - "tags": ["re-anchor", "discipline", "corrector", "research", "standards", "duplication", "incumbency", "terseness", "upstream", "conformance", "selection", "communication", "audit", "skill"] + "tags": ["re-anchor", "discipline", "corrector", "research", "standards", "duplication", "incumbency", "terseness", "upstream", "conformance", "selection", "communication", "determinism", "audit", "skill"] }, { "name": "education", diff --git a/README.md b/README.md index e8f8b18bb..3634ed581 100644 --- a/README.md +++ b/README.md @@ -95,7 +95,7 @@ user opts in with `/plugin enable`; an existing install is never flipped by cata - [`mcp-tools`](plugins/mcp-tools) — Audits MCP server tool definitions against MCP-specification and Anthropic tool-design criteria and reports a per-tool PASS/WARN/FAIL scorecard covering description, parameters, naming, and annotations. Language-agnostic — Python (FastMCP), TypeScript, and .NET. - [`review`](plugins/review) — Code-review toolkit: six read-only reviewer agents (code, security, architecture, doc drift, build/test/lint, CI-log audit) plus two orchestration skills — a single-lens quality gate and a multi-surface review fan-out with severity-ranked, deduplicated findings. - [`codebase-health`](plugins/codebase-health) — Repo-wide drift audit between docs, config, code, and architecture: verifies every factual claim against reality via parallel subagent fan-out, severity-rates findings, and fixes or presents for review. Audit dimensions are configurable through a tracked .claude/codebase-health.md config file written by the setup skill. -- [`re-anchor`](plugins/re-anchor) — Discipline correctors that re-anchor a standing rule mid-session, then audit both the work in flight and the pre-existing state and choices it trusts, and correct what has drifted: do-your-research (research and no-assumptions discipline; sibling do-your-research-deep escalates to a subagent-fanned verification pass over every load-bearing claim), follow-our-standards (alignment to the consuming org's engineering conventions), point-dont-copy (pointer-over-copy discipline — no copied content, internal-name coupling, or closed capability lists), reason-dont-recite (interrogate inherited content — precedent is evidence of what is, never self-justifying authority), tighten-your-output (terseness discipline — fewer words or lines with no loss of meaning or correctness), recheck-against-upstream (existing state is not evidence of its own correctness — audit config, code, and infra against current official upstream docs; sibling recheck-against-upstream-deep fans subagents doc-by-doc over a whole subsystem), pick-for-the-problem (tool, library, framework, and approach selection fitted to the problem, not reached for out of habit, availability, incumbency, or preconception), and mind-your-maxims (cooperative-communication discipline per Grice plus the AI-augmented transparency maxim). Firing one is a re-anchor, not an accusation; the audit may return clean. +- [`re-anchor`](plugins/re-anchor) — Discipline correctors that re-anchor a standing rule mid-session, then audit both the work in flight and the pre-existing state and choices it trusts, and correct what has drifted: do-your-research (research and no-assumptions discipline; sibling do-your-research-deep escalates to a subagent-fanned verification pass over every load-bearing claim), follow-our-standards (alignment to the consuming org's engineering conventions), point-dont-copy (pointer-over-copy discipline — no copied content, internal-name coupling, or closed capability lists), reason-dont-recite (interrogate inherited content — precedent is evidence of what is, never self-justifying authority), tighten-your-output (terseness discipline — fewer words or lines with no loss of meaning or correctness), recheck-against-upstream (existing state is not evidence of its own correctness — audit config, code, and infra against current official upstream docs; sibling recheck-against-upstream-deep fans subagents doc-by-doc over a whole subsystem), pick-for-the-problem (tool, library, framework, and approach selection fitted to the problem, not reached for out of habit, availability, incumbency, or preconception), mind-your-maxims (cooperative-communication discipline per Grice plus the AI-augmented transparency maxim), and script-the-deterministic-work (offload deterministic sub-work — counts, diffs, sorts, transforms, and scaffolds — to a script that runs, reserving model output for judgment over its real output). Firing one is a re-anchor, not an accusation; the audit may return clean. ### Maintenance diff --git a/plugins/re-anchor/.claude-plugin/plugin.json b/plugins/re-anchor/.claude-plugin/plugin.json index 783f4f6f4..3c8960d65 100644 --- a/plugins/re-anchor/.claude-plugin/plugin.json +++ b/plugins/re-anchor/.claude-plugin/plugin.json @@ -1,12 +1,12 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "re-anchor", - "version": "0.2.0", - "description": "Discipline correctors that re-anchor a standing rule mid-session, then audit both the work in flight and the pre-existing state and choices it trusts, and correct what has drifted: do-your-research (research and no-assumptions discipline; sibling do-your-research-deep escalates to a subagent-fanned verification pass over every load-bearing claim), follow-our-standards (alignment to the consuming org's engineering conventions), point-dont-copy (pointer-over-copy discipline — no copied content, internal-name coupling, or closed capability lists), reason-dont-recite (interrogate inherited content — precedent is evidence of what is, never self-justifying authority), tighten-your-output (terseness discipline — fewer words or lines with no loss of meaning or correctness), recheck-against-upstream (existing state is not evidence of its own correctness — audit config, code, and infra against current official upstream docs; sibling recheck-against-upstream-deep fans subagents doc-by-doc over a whole subsystem), pick-for-the-problem (tool, library, framework, and approach selection fitted to the problem, not reached for out of habit, availability, incumbency, or preconception), and mind-your-maxims (cooperative-communication discipline per Grice plus the AI-augmented transparency maxim). Firing one is a re-anchor, not an accusation; the audit may return clean.", + "version": "0.3.0", + "description": "Discipline correctors that re-anchor a standing rule mid-session, then audit both the work in flight and the pre-existing state and choices it trusts, and correct what has drifted: do-your-research (research and no-assumptions discipline; sibling do-your-research-deep escalates to a subagent-fanned verification pass over every load-bearing claim), follow-our-standards (alignment to the consuming org's engineering conventions), point-dont-copy (pointer-over-copy discipline — no copied content, internal-name coupling, or closed capability lists), reason-dont-recite (interrogate inherited content — precedent is evidence of what is, never self-justifying authority), tighten-your-output (terseness discipline — fewer words or lines with no loss of meaning or correctness), recheck-against-upstream (existing state is not evidence of its own correctness — audit config, code, and infra against current official upstream docs; sibling recheck-against-upstream-deep fans subagents doc-by-doc over a whole subsystem), pick-for-the-problem (tool, library, framework, and approach selection fitted to the problem, not reached for out of habit, availability, incumbency, or preconception), mind-your-maxims (cooperative-communication discipline per Grice plus the AI-augmented transparency maxim), and script-the-deterministic-work (offload deterministic sub-work — counts, diffs, sorts, transforms, and scaffolds — to a script that runs, reserving model output for judgment over its real output). Firing one is a re-anchor, not an accusation; the audit may return clean.", "author": { "name": "Melodic Software", "email": "info@melodicsoftware.com" }, "license": "MIT", - "keywords": ["re-anchor", "discipline", "corrector", "research", "standards", "duplication", "incumbency", "terseness", "upstream", "conformance", "selection", "dependencies", "communication", "skill"] + "keywords": ["re-anchor", "discipline", "corrector", "research", "standards", "duplication", "incumbency", "terseness", "upstream", "conformance", "selection", "dependencies", "communication", "determinism", "scripting", "skill"] } diff --git a/plugins/re-anchor/CHANGELOG.md b/plugins/re-anchor/CHANGELOG.md index fcc4ef865..260861ca9 100644 --- a/plugins/re-anchor/CHANGELOG.md +++ b/plugins/re-anchor/CHANGELOG.md @@ -3,6 +3,25 @@ All notable changes to the `re-anchor` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.3.0] + +### Added + +- `/re-anchor:script-the-deterministic-work` — offload-the-deterministic + discipline: purely deterministic sub-work (counting, diffing, sorting, + transforming, matching, sweeping, arithmetic) gets a script that runs and + returns real output, and the model reasons only afterward over that output. + The tier boundary — deterministic (script it), detect-then-judge (script + the detect half; the verdict stays judgement), reasoning-only (never + script) — re-anchors the consuming org's enforceability-tiers convention; + the in-task "script it now" application has no standards doc yet, so the + skill flags that gap rather than inventing a rubric. Runs in both + directions: analysis reasons over a script's output; generation emits a + deterministic scaffold (PR body, issue, report, config boilerplate) from a + script or native template so model output is reserved for the judgment + slots. Distinct from a standing-automation capability: recurring checks + route to a hook, this corrector owns the one-off, session-time script. + ## [0.2.0] ### Added diff --git a/plugins/re-anchor/README.md b/plugins/re-anchor/README.md index a297d155e..d94dd9824 100644 --- a/plugins/re-anchor/README.md +++ b/plugins/re-anchor/README.md @@ -27,6 +27,7 @@ first-class use, and the audit may honestly return clean. | `/re-anchor:recheck-against-upstream-deep` | The fan-out tier of recheck-against-upstream — subagents compare a whole subsystem against upstream, doc-by-doc | | `/re-anchor:pick-for-the-problem` | Selection fitted to the problem — not reached for out of habit, availability, incumbency, or preconception | | `/re-anchor:mind-your-maxims` | Cooperative communication — Grice's maxims plus the AI-augmented transparency maxim | +| `/re-anchor:script-the-deterministic-work` | Script deterministic sub-work — run it, then reason over the output | The shared method — re-anchor, audit the work in flight, correct forward, report — lives once at plugin scope in @@ -202,6 +203,28 @@ as posture-setting anytime and as an audit once output exists. /re-anchor:mind-your-maxims # re-anchor + audit + correct ``` +### script-the-deterministic-work + +Re-anchors the discipline of offloading deterministic sub-work to a script: +when a sub-task's answer follows mechanically from its input (counting, +diffing, sorting, transforming, matching, sweeping, arithmetic), write and +run a script, read its real output, and reason only afterward over that +output. The tier boundary re-anchors the consuming org's enforceability-tiers +convention — deterministic work gets scripted, detect-then-judge gets only +its detect half scripted while the verdict stays judgement, and +reasoning-only is never scripted. The in-task "script it now" application has +no standards doc yet, so the skill flags that gap. The discipline runs in +both directions: analysis reasons over a script's output, and generation +emits a deterministic scaffold (a PR body, an issue, a report, config +boilerplate) from a script or a native template so model output is reserved +for the judgment slots. Distinct from a standing-automation capability: +recurring checks belong in a hook, this corrector owns the one-off, +session-time script. + +```shell +/re-anchor:script-the-deterministic-work # re-anchor + audit + correct +``` + ## Consumer conventions The correctors adapt to the consuming repo rather than imposing a source diff --git a/plugins/re-anchor/skills/script-the-deterministic-work/SKILL.md b/plugins/re-anchor/skills/script-the-deterministic-work/SKILL.md new file mode 100644 index 000000000..1d0ae2714 --- /dev/null +++ b/plugins/re-anchor/skills/script-the-deterministic-work/SKILL.md @@ -0,0 +1,140 @@ +--- +name: script-the-deterministic-work +description: "Re-anchor the discipline that purely deterministic sub-work — counting, diffing, sorting, transforming, matching, sweeping, arithmetic — gets a script that runs and returns real output, and the model reasons only afterward over that output — then audit the work in flight for transforms executed by hand and re-derive them from a script's result. Use when: 'script the deterministic work', 'you should have scripted that', 'don't eyeball that', 'you counted that by hand', 'compute that, don't estimate', 'diff it with a tool', 'stop hand-tallying', 'run it instead of guessing', or at conversation start on count-, diff-, or transform-heavy work. Not for authoring a requested script or migration ('script it' as a work order is script-writing, not this corrector), and not for a first-turn count/diff/transform work order ('diff these files', 'count the routes', 'convert all of these') — doing that task with a tool is just doing the task; this corrector fires on drift, mid-flight or retrospective, or as posture at the start of transform-heavy work." +user-invocable: true +disable-model-invocation: false +--- + +# Script the deterministic work + +A drift corrector for the discipline of offloading deterministic sub-work to +a script instead of performing it in your head. The method — re-anchor, audit +the work in flight, correct forward, report, and the tone that firing this is +not an accusation — lives in +[`${CLAUDE_PLUGIN_ROOT}/context/re-anchor-audit-correct.md`](../../context/re-anchor-audit-correct.md). +Read it; this file adds only what is specific to scripting deterministic work. + +## The discipline this re-anchors + +When a sub-task is purely deterministic — its answer follows mechanically +from its input with no judgement in the middle — write a script (or invoke a +tool) that produces the answer, run it, read the output, and reason only +**after**, over that output. Counting, diffing, sorting, transforming, +matching, sweeping across files, and arithmetic are the recurring shapes. The +model is a poor calculator and a worse line-counter; a hand-tallied count or +an eyeballed diff carries a silent error the script would not. + +The boundary of *what* to script is not "anything tedious" — it is set by +which enforcement tier the sub-work belongs to. + +### The tier vocabulary — a standards convention owns this + +The source of truth for the tier distinction is the consuming organization's +enforceability-tiers convention, which classifies work by who can decide it. +Resolve it per the method doc's ladder — the consumer's own instruction layer +first, then that standards convention, then the portable baseline below — and +re-anchor the distinction rather than restating the doc's criteria: + +- **Deterministic** — the answer is pass/fail, exact, or countable with no + judgement. **Script it, run it, reason over the output.** This is the core + of the discipline. +- **Detect-then-judge** — a mechanical pass narrows the candidates, but the + verdict needs meaning or context. **Script only the detect half**; the + judgement stays with the model. A script's flag is a candidate, never the + ruling. +- **Reasoning-only** — meaning, intent, fit, abstraction quality. **Never + script it.** A script here manufactures false confidence — it dresses a + judgement call as a computed fact. + +When the consuming project declares no such convention, re-anchor that same +three-tier shape as the portable baseline: script the deterministic, script +only the detection of the detect-then-judge, and leave the reasoning-only to +reasoning. + +### The in-task application — no standards doc yet (flagged gap) + +The enforceability-tiers convention classifies *conventions* by tier and +routes a *recurring* finding to the mechanism its tier permits; it does not +speak to the in-task move this skill re-anchors — "this task needs a count or +a diff **now**, so script it now." That application has **no dedicated +standards convention** to cite. When the consuming project's standards source +declares one, route through it; when it does not, treat that as a flagged gap +(a candidate upstream standards addition), not license to invent a rubric +here beyond the portable baseline above. + +### Generation, not just analysis + +The discipline runs in both directions. Analysis feeds input to a script and +reasons over its output; generation emits deterministic *structure* from a +script or template and fills only the judgment slots by hand. A PR body, an +issue body, a report, a skill skeleton, or config boilerplate is mostly fixed +scaffold — the model's output belongs in the slots that need judgment, not in +re-typing the frame each time. Prefer a native mechanism where one exists: a +repo's pull-request or issue templates, for instance, already emit the +scaffold with no generation cost. Same rule as the analysis side — reserve +model output for judgment; the structure is deterministic. + +## Audit — what to look for + +Name concrete, located findings (per the method doc's step 2): + +- a count, total, or tally produced by reading and adding in prose rather + than by a command whose output was read back; +- two files, lists, or versions compared by eye where a diff or a set + operation would be exact; +- a sort, dedupe, filter, or reformat performed inline in the answer instead + of by a tool, so the result cannot be reproduced or trusted; +- a sweep — "every file that matches", "all call sites of X" — asserted from + memory of what was read rather than from a search that enumerated them; +- arithmetic or a mechanical transform worked through by hand mid-answer; +- a deterministic scaffold — a PR body, an issue, a report, config + boilerplate — hand-typed frame and all, where a script or a native template + would emit the structure and leave only the judgment slots to fill. + +Correct each forward now: write and run the script or tool, read its real +output, and re-derive the conclusion from that output — do not keep the +hand-computed figure alongside it. Where the sub-work is detect-then-judge, +script the detection and keep the verdict; where it is reasoning-only, leave +it un-scripted and say why. + +## Distinct from standing automation + +The enforceability-tiers convention's own routing sends a **recurring** +deterministic finding to a **standing** mechanism — a linter, analyzer, or +commit hook that fires on every change. That is the territory of an +automation-gaps capability (`/claude-config:automation-gaps` when that +plugin is installed; prose guidance otherwise): institutionalize the check +so it never reaches review again. + +This skill owns the complementary case: the **one-off, session-time** need. +The current task needs a count, a diff, or a transform right now; the answer +is to make a script *now* — often throwaway — feed it the input, and reason +over its output. Recurring → a standing hook; one-off in flight → script it +this turn. + +## What this skill does NOT do + +- **Does not script a judgement call.** Scripting reasoning-only work, or + treating a detect-then-judge script's flag as the verdict, is + over-application — it converts a judgement into a false computed fact. The + tiers set the boundary; honour it in both directions. +- **Does not demand a permanent tool for a one-off.** A short throwaway + script that runs and returns real output satisfies the discipline; building + standing automation is the other capability's job. +- **Does not fabricate a finding.** Work whose deterministic parts were + already scripted audits clean; say so rather than inventing hand-work to + correct. + +## Gotchas + +- "Reason after over results" here means *where the computation happens* — let + the tool compute, then reason over what it returned. It is a different sense + of "reason" from `/re-anchor:reason-dont-recite`, which is about + interrogating inherited content. Same word, unrelated axis. +- The subtle miss is the detect-then-judge trap: a script that flags + candidates is doing the deterministic half correctly, but its output is a + shortlist for judgement, not the answer. Reading the flag as the ruling + re-hides the judgement the tier split exists to protect. +- A script that was never actually run is worse than hand-work: it looks + rigorous while its output is imagined. The discipline is script **and run** + — reason over real output, not over what the script would presumably print. diff --git a/plugins/re-anchor/skills/script-the-deterministic-work/evals/evals.json b/plugins/re-anchor/skills/script-the-deterministic-work/evals/evals.json new file mode 100644 index 000000000..f0dc854c2 --- /dev/null +++ b/plugins/re-anchor/skills/script-the-deterministic-work/evals/evals.json @@ -0,0 +1,65 @@ +{ + "skill_name": "script-the-deterministic-work", + "evals": [ + { + "id": 1, + "name": "deterministic-work-scripted-then-reasoned", + "prompt": "script the deterministic work — I need the total line count across these twelve files and which three are largest; you were about to add them up from what you read.", + "expected_output": "The skill re-anchors the discipline, names the hand-tally as a located finding, and corrects forward by running a command that counts and sorts, reading its real output, and deriving the total and the top three from that output rather than from memory of the files.", + "files": [], + "expectations": [ + "Runs a script/tool to produce the count and sort instead of adding or ranking by hand", + "Reasons over the tool's actual output rather than an eyeballed estimate", + "Corrects the in-flight hand-computed figure rather than only noting it" + ] + }, + { + "id": 2, + "name": "over-application-guarded", + "prompt": "script the deterministic work — write me a script that decides whether each of these modules has the right abstraction boundaries.", + "expected_output": "The skill declines to script the judgement: 'is this the right abstraction' is reasoning-only, so a script would manufacture false confidence. It offers to script only any deterministic detect step (e.g. flag modules over a size or fan-out threshold as candidates) while keeping the boundary verdict as model judgement.", + "files": [], + "expectations": [ + "Refuses to reduce a reasoning-only judgement to a script's output", + "Distinguishes a deterministic detect step (advisory flag) from the judgement verdict", + "Does not treat a flagged candidate as the ruling" + ] + }, + { + "id": 3, + "name": "in-task-scripting-gap-flagged-not-invented", + "prompt": "script the deterministic work — and which standards convention says I have to script my in-task counts and diffs?", + "expected_output": "The skill re-anchors the enforceability-tiers vocabulary for what 'deterministic' means but is honest that the in-task 'script it now' rule has no dedicated standards convention: it flags that as a gap / candidate upstream addition rather than fabricating one, and cites the tier convention only for the tier distinction it actually owns.", + "files": [], + "expectations": [ + "Cites the enforceability-tiers convention for the tier vocabulary, not for an in-task scripting mandate", + "Flags the missing in-task-scripting convention as a gap / candidate upstream addition", + "Does not fabricate or assert a standards rule that does not exist" + ] + }, + { + "id": 4, + "name": "distinct-from-standing-automation", + "prompt": "script the deterministic work — we keep re-checking this same forbidden-import rule by hand every review; script it.", + "expected_output": "The skill recognizes a recurring deterministic check as standing-automation territory (a linter/hook via a config/automation-gaps capability), not the one-off session-time case it owns. It routes the recurring rule to a standing mechanism while still scripting any one-off count/diff needed in this conversation.", + "files": [], + "expectations": [ + "Recognizes a recurring check as standing-automation (hook/linter) territory", + "Routes the recurring rule to a config/automation-gaps capability rather than absorbing it", + "Reserves its own scope for the one-off, session-time script" + ] + }, + { + "id": 5, + "name": "generation-scaffold-from-template-not-hand-typed", + "prompt": "script the deterministic work — draft the PR body for this branch; you were about to type the whole thing out section by section.", + "expected_output": "The skill applies the discipline in the generation direction: the fixed scaffold is deterministic, so it emits the structure from a script or a native template (preferring the repo's PR template when one exists) and reserves its own output for the judgment slots — the summary, rationale, and risk call — rather than re-typing the frame by hand.", + "files": [], + "expectations": [ + "Emits the deterministic scaffold from a template/script rather than hand-typing the frame", + "Prefers a native mechanism (repo PR/issue template) when one exists", + "Reserves model-authored output for the judgment slots, not the fixed structure" + ] + } + ] +}