go-linter-driven-development v2.8.0 — Comment Value Toolbox + comment-critic

The comment-quality release: v2.7.0 + v2.8.0 together. Godoc comments get a hard tiered budget, a named value standard (the Comment Value Toolbox), and an adversarial reviewer — the comment-critic joins the hunter/skeptic review architecture. Field-tested against the real PR review that motivated it: 3/3 human-flagged comments caught, 0 false positives.

[2.8.0] - 2026-07-20

Added

• Comment Value Toolbox + comment-critic — comments now have an adversarial
  reviewer. Reviewers reported ldd-written comments as noise: restated code,
  filled templates, no context. Root cause was architectural: @pre-commit-review
  runs in Phase 4, @documentation writes godocs in Phase 5 — comments were never
  adversarially reviewed, only self-checked by their writer.
  • The Comment Value Toolbox: a named, growable catalog of the ways a comment
    delivers value — WHY-not-WHAT, wider context, use cases/flows, boundary
    contract, guarantees, network edge. Normative kinds list in R9's comment
    policy; the catalog with worked examples lives in @documentation's
    reference.md and is designed to grow.
  • Three-test standard (normative in R9): toolbox-value (floor: a prose line
    delivering no toolbox value is cut; ceiling: the comment must carry the
    highest-value items for its symbol's tier — short-but-dodging fails too),
    tier budget (from v2.7.0), and plain English (everyday words, short
    sentences — not all readers are native speakers; applies to godocs AND
    feature docs). The floor names provenance a failure mode — PR numbers,
    review items, "the previous behavior" narration — under the 5-year reader
    lens: readers care how the product behaves now, not which review round
    produced it; history is rewritten as present-tense rationale, and
    incident/ticket refs survive only as rationale. Falsifying questions
    unchanged.
  • New comment-critic agent: read-only, single obsession — comment value.
    Judges every comment in the diff (godoc, in-body, test) against the three
    tests; verdicts KEEP / TRIM / REWRITE / DELETE with evidence; every rewrite
    names the toolbox item it delivers. In-body block-narration comments route to
    R3 (extraction candidates). Adversarial default: uncertain → fails.
  • @documentation closes the timing gap: write-time three-test gate in
    step 3, then a critique loop — spawn the critic on the full diff, auto-apply
    every non-KEEP verdict, re-critique once to confirm; report carries the delta
    (N deleted · M trimmed · K rewritten). Philosophy gains "plain words over
    clever words".
  • @pre-commit-review spawns the critic on the standalone/PR path whenever
    the diff contains comments; verdicts land as 🟡 Readability Debt, advisory.

Changed

• Task → Agent tool rename across all skill and command frontmatter and
  prose: Claude Code renamed the subagent-spawning tool in v2.1.63; Task still
  works as a backward-compat alias, but the plugin now uses the canonical name.

[2.7.0] - 2026-07-20

Changed

• Tiered godoc budget — R9's comment policy now has hard numbers. Generated
  godoc comments were verbose enough to slow human review; "menus, not forms" was
  guidance without a bound. R9's rung-1 comment policy is now a 1–5 prose-line
  budget scaled by the symbol's role: helpers 0–1 line, contract types (parsing
  constructors, self-validating types) 2–3, crossroads (entry points, orchestrators,
  feature front doors) up to 5. Blank // lines, the See docs/<feature>.md edge,
  and short inline examples (2–4 lines) are free; overflow moves to the feature
  doc — the placement rule made operational at write time. Two bounded escape
  hatches: a package that genuinely earns more moves its godoc to a dedicated
  doc.go (~20–30 lines), and a crossroads that deserves richer inline godoc gets
  an optional expand recommendation in @documentation's FEATURE report instead
  of extra lines — a human decides. Guidance-only: falsifying questions, hunters,
  and the skeptic are unchanged.
  • @documentation FEATURE step 3 applies the budget; its report format gains an
    optional Expand recommendations section.
  • reference.md godoc menus annotated with tier budgets; new doc.go hatch note,
    checklist budget items, and an over-budget → trimmed-to-tier worked example.
  • Root coding_rules.md Comments section aligned with the budget.