Skip to content

docs: add re-scope-after-a-regression rule to task-writing.md - #226

Merged
bborbe merged 1 commit into
masterfrom
fix/criterion-regression-remedy
Sep 27, 2026
Merged

bborbe merged 1 commit into
masterfrom
fix/criterion-regression-remedy

Conversation

@bborbe

@bborbe bborbe commented Sep 27, 2026

Copy link
Copy Markdown
Owner

What

Adds a rule to docs/task-writing.md § Audit: re-scope after a regression, never patch.

A criterion that has reached a passing verdict and then regresses is re-scoped or cut, not repaired again. The trigger is the first regression after a held verdict; the action is to cut the criterion back to what the evidence can carry, or replace the claim with one the artifact supports — never to add a clause narrowing the failing one.

Why

Measured on two independent task rows in one manager session (2026-09-26) that cycled 14 and 5 audit rounds without converging. Neither reached the 9/10 bar, and both were ended by a re-scope, not by a successful patch.

The rejected alternatives are recorded in the section, each with the failure it would produce:

  • A clause budget — satisfiable by deletion, so it measures length rather than convergence. The fatal defect is typically a single clause inside an otherwise reasonable criterion, so a budget flags it and then watches it cycle.
  • Delete at least as many clauses as you add — bounds the growth rate rather than the duration, and a round that changes nothing satisfies it while making no progress.
  • Re-scope after N rounds — no value of N works. N=3 discards a cycle that reached 8/10 by patching; N=5 still misses the actual failure. Both rows improved by patching before they broke by patching, so a count cannot separate the productive rounds from the destructive ones.

Hence a regression after a held verdict rather than a count. Checked against both rows before shipping: it fires at round 10 of 14 in the first — four rounds before the re-scope that actually ended it — and at the last round of 5 in the second, where it ratifies rather than accelerates.

Verification

make precommit green — all 8 Go packages ok, scenario suites 0 failed, golangci-lint 0 issues, CHANGELOG structure OK.

@bborbe
bborbe marked this pull request as ready for review September 27, 2026 12:14

@ben-s-pull-request-reviewer ben-s-pull-request-reviewer Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The review is complete. This is a clean docs-only PR with no issues.

Summary: A docs-only PR adding a well-reasoned "re-scope after a regression, never patch" rule to task-writing.md § Audit. The section is correctly placed as a sub-section under Audit, grounded in empirical evidence (two observed cycling rows of 14 and 5 rounds), and clearly distinguishes the rule from rejected alternatives (clause budget, delete-symmetry). Version alignment is verified across all four required files.

{
  "verdict": "approve",
  "summary": "Docs-only PR adds a well-integrated 're-scope after a regression' rule to task-writing.md § Audit, with empirical grounding and clear rejection of alternatives. Version alignment verified across all four required files. No concerns.",
  "comments": [],
  "concerns_addressed": []
}

@bborbe
bborbe merged commit 64f9214 into master Sep 27, 2026
5 checks passed
@bborbe
bborbe deleted the fix/criterion-regression-remedy branch September 27, 2026 12:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant