[sabind]

Why

Closes #6
Closes #7
Closes #15

The workflow rule carried a bullet per skill that restated the skill's trigger and narrated what it did, and those sentences went stale when a skill changed: the pull request bullet still said the pr skill drafts "to the team template" after the skill learned to prefer the repository's own. Rules should say "if you're doing this, start here" and otherwise not duplicate what the skills already say; skills exist for uses, check them, and only then default to answering. Measured, the rules are valuable in some cases, where a session is tempted to shortcut, and the branch leans on that. Alongside: a merged spec is a record, a discovery outside the work is stated with its size and the author chooses between keeping it in the branch and filing an issue, and every session reads the repository's own guide before changing code.

What

The workflow rule has one routing bullet, pointing at the skill descriptions with the four guards folded in, plus the standing rules, including that a merged spec is a closed record. A discovery found during work lands in the hand-back's Problems with a size and two options, and implement-spec acts on the author's answer. The code-changes rule reads the README and contributing guide before the code, start-task's description and fit question stand on their own, and six eval cases prove each of these.

Changes

• Rewrite rules/workflow.md: one bullet says to check the skill descriptions first and run the skill that fits, carrying the guards (no bare gh pr create, no code before bugfix has reproduced the bug, no spec task skipped or merged, no sizing a change yourself); the small-change exception stays; a yes to a skill's offer counts as the author asking; a merged spec is a record, not work in hand, not edited, not read for current behaviour. Rules should say where to start and not duplicate the skills; the no-rule run shows the descriptions route the plain cases on their own and the rule catches the shortcuts, so the branch leans on the rule where it is valuable.
• Discoveries are the author's call: the code-changes rule's smallest-change bullet says to state what was found and roughly how much it would add, and let the author choose between the branch and an issue; the handback template's Problems item carries that size; implement-spec step 6 lists a discovery under the report's problems with its options and step 7 turns the answer into a tasks.md proposal or a drafted issue, never listing it again. Sending every discovery to an issue is a trade-off, not a rule; the agent states it and its likely size, and the author chooses. Executors report under unsure and do not size; the reviewer and the session assess, since executors focus on execution and findings.
• Add the repository's README and contributing guide to the head of the code-changes rule's "Read before you write" list, and the README row to match. New skill: develop the handbook plugin itself #15 triaged to one sentence rather than a new skill; "look at" is the same strength the bullet already uses for the code.
• start-task: the description names the requests it does not take instead of pointing at the workflow rule, in parentheses so the frontmatter stays valid YAML; step 3 places the route statement with the task and branch names before the Fit question in the same message.
• Docs: the README's rows for the workflow rule, the code-changes rule and implement-spec describe them as they now read; the README's eval paragraph, the pr stub README, the agents sentence, the report-templates sentence and the contributing guide's forms and labels stop enumerating names and counts and point at the source of truth instead, so they cannot go stale when something is added.
• Eval tooling: evals/fixtures/setup.sh copies a fixture file only where the workspace has none, so a case's files/ overlay wins and lands in the one commit, and the evals README says so; the Makefile's workflow rule target runs scaffolds; the no-new-dependency prompt says the change is already decided, since the workflow rule was routing it to start-task before the rule it grades could be exercised.
• Six eval cases: closed-spec-is-a-record, reads-contributing-guide, follows-repo-template, offers-commit-on-dirty-tree, offers-choice-on-discovery, and names-task-and-asks moved onto the calc fixture so it tests the spec route it describes, with wrong-repo-asks-fit gaining the task-name grader.
• The spec under .claude/specs/workflow-rule-wording/, the record of the work, closed on merge.
• Bump the version to 0.12.0.

Testing

make validate passes: 19 checks and both plugin validations; the hook prints 7,967 of 10,000 characters.

Evals, default three runs per case, with-plugin scores; baselines were taken before any edit.

Rule targets with the no-plugin arm, after the edits:

CASE                           WITH  W/OUT Δ      RUNS COST
bug-routes-to-bugfix           1.00  0.50  +0.50  6    $0.59
closed-spec-is-a-record        1.00  0.50  +0.50  6    $1.00
feature-routes-to-start-task   1.00  0.00  +1.00  6    $0.63
pr-routes-to-pr-skill          1.00  0.00  +1.00  6    $0.41
small-change-skips-spec        1.00  1.00  0.00   6    $0.51
spec-routes-to-implement-spec  1.00  0.00  +1.00  6    $0.82

no-new-dependency              1.00  1.00  0.00   6    $0.98
reads-contributing-guide       1.00  0.50  +0.50  6    $0.77
smallest-change                1.00  0.75  +0.25  6    $0.63
test-with-change               1.00  0.50  +0.50  6    $0.67

The workflow table matches the baseline exactly; no-new-dependency was 0.50 with the plugin at baseline. Without the plugin, every run of reads-contributing-guide added the function and none added the README row the guide asks for.

Skill targets after the edits and after rebasing onto #32 and #42:

CASE                              SCORE PASS% RUNS COST
hands-off-to-pr                   1.00  100%  3    $1.18
reads-ticket-first                1.00  100%  3    $0.55
bug-offers-bugfix                 1.00  100%  3    $0.44
contained-change-offers-executor  1.00  100%  3    $0.44
names-task-and-asks               1.00  100%  3    $0.46
wrong-repo-asks-fit               1.00  100%  3    $0.45
follows-repo-template             1.00  100%  3    $0.77
offers-branch-on-default          1.00  100%  3    $0.55
offers-commit-on-dirty-tree       1.00  100%  3    $0.52
opens-pr-with-stub-gh             1.00  100%  3    $0.81
opens-pr-with-ticket              1.00  100%  3    $0.79
stops-at-starting-checks          1.00  100%  3    $0.57
invalid-graph-stops               1.00  100%  3    $0.74
no-spec-recommends-start-task     1.00  100%  3    $0.60
offers-choice-on-discovery        1.00  100%  3    $1.73
works-all-waves                   1.00  100%  3    $3.02
works-one-wave                    1.00  100%  3    $1.64

Before the rebase, works-all-waves missed one run in three with the turn ending on wave 0's report, which #42 fixed, and names-task-and-asks missed one run in three on phrasing because it hit the Fit path in an empty sandbox; both are 1.00 after the fixes above. Two earlier attempts at the wave 3 tables were discarded for API stalls, 300-second timeouts at near-zero cost in both arms; the evidence is on #41.

What the skill descriptions route on their own, plugin loaded but rules/workflow.md removed, two runs per case:

CASE                           SCORE PASS% RUNS COST
bug-routes-to-bugfix           0.80  0%    2    $0.19
closed-spec-is-a-record        0.33  0%    2    $0.55
feature-routes-to-start-task   1.00  100%  2    $0.28
pr-routes-to-pr-skill          1.00  100%  2    $0.16
small-change-skips-spec        1.00  100%  2    $0.20
spec-routes-to-implement-spec  1.00  100%  2    $0.36

The descriptions route a feature, a PR and a spec without the rule; the rule's guards and the record rule are what hold on the bug and closed-spec cases.

Risk and rollout

Version 0.12.0; teammates pick it up with claude plugin update freethinking@freethinkingit. The rules and the handback template are loaded into every session and sub-agent by the hooks. The setup-script change affects every scaffolded case; no existing case overlays a fixture file, and the works-one-wave scaffold builds the same file list before and after.

Notes for reviewers

• The "Read before you write" bullet says "look at" the README and contributing guide, the same strength as for the code; a long guide costs reading in every session, and the rule leaves how much to the session's judgment, as it does for the code.
• The discovery case's graders are permissive: its size grader matches "line" in a location as well as in a size, and any Problems grader can be satisfied by a different problem in the same section. Six for six runs so far.
• The start-task description is 893 of the 1,024 characters the new check allows.
• The spec's design records the implement-spec hand-back as the report skill wrote it before [#33] Write implement-spec's hand-back inline, not in a fork #42 made the invocation inline, and its baseline table predates [#33] Write implement-spec's hand-back inline, not in a fork #42; both were true when written and are left as the record.
• Follow-ups outside this branch: the bugfix skill's old follow-up wording, raised on [#12] bugfix: approach question, CX block, hand-off to pr or the ticket #32; an eval broker with a measured concurrency cap, Eval runner: queue make eval-* calls machine-wide, at most three at once #41.

🤖 Generated with Claude Code