Skip to content

[docs] metrics-baseline denominator note misstates the ~12% figure's basis — claims consistency where populations differ #1419

Closed

Description

@don-petry

Story

As a maintainer who will compare the post-rollout noise measurement against the pre-rollout baseline,
I want docs/metrics-baseline.md to state the ~12% figure's actual denominator rather than an incorrect claim that it matches the classifier's,
so that the first measured value is interpreted correctly instead of a real population difference being explained away as agreement.

Problem

docs/metrics-baseline.md (landed in #1414, story #1411) closes its denominator-scope note with:

"The AC #4 ~12% figure cited in issue #1411 was also measured over first-party markers only (it pre-dates the classifier and was an estimate, not a live all-comments count), so the denominators are consistent."

That claim is incorrect. The ~12% figure was derived over all PR comments, third-party reviewer bots included. Its provenance: a 10-PR sample (#1355, #1366, #1372, #1359, #1351, #1357, #1356, #1347, #1346, #1345) where total comments (issue + review) = 180 and est. no-action/advisory = 21 → 21/180 ≈ 12%. That 180 counted every comment on those PRs — CodeRabbit, Qodo, CodeAnt, SonarCloud, Codex and Gemini among them — and the no-action classification was a phrase scan ("no action", "no issues", "LGTM", "no blocking", "advisory") across all of them, not a marker-bearing subset. In the same sample, 254/254 comments+reviews were machine-authored and 0 were human, which is only meaningful because third-party bots were in scope.

The classifier's denominator is first-party marker-bearing comments only. So the two populations genuinely differ, and the baseline doc now asserts they do not.

Why this matters. The note's purpose was to satisfy #1411 AC #4 — "any discrepancy with those figures is explained rather than quietly overwritten." The mechanism is right and the rest of the note is good (it names the excluded bots, points at the reviewer scorecard, and asks that future all-comments comparisons be labelled). But the concluding claim pre-emptively explains away any divergence on the first scheduled run as "consistent denominators", when a divergence is in fact the expected consequence of measuring a narrower population. That converts a real measurement correction into an apparent non-event — the outcome AC #4 exists to prevent, reached by an incorrect factual claim rather than by silence.

This is a documentation-accuracy fix. No classifier change is implied — first-party-only remains a defensible primary metric (it is the part we control), and F1/F2 of the review on #1414 were correctly fixed before merge.

Acceptance Criteria

  1. The denominator-scope note in docs/metrics-baseline.md states the ~12% figure's actual basis: all PR comments in the sampled window, third-party reviewer bots included, classified by phrase scan — and records the sample (10 PRs, 21/180).
  2. The sentence asserting the denominators are consistent is removed or corrected; the note states plainly that the classifier measures a narrower population than the ~12% estimate, so the first measured value is expected to differ, and that such a difference is a population change and not a regression or an improvement.
  3. The note gives the reader a rule for interpreting the first scheduled run: what would count as a genuine measurement correction versus the known population difference.
  4. Either a second all-comments noise figure is reported alongside the first-party metric, or the doc states explicitly that no all-comments series is maintained and names the reviewer scorecard as the only third-party view — so a future reader cannot mistake the first-party series for total reviewer noise.
  5. The correction is recorded as a dated append (the doc's own convention for measurement corrections), not a silent edit of the original text.

Tasks / Subtasks

Dev Notes

  • Provenance for AC test issue from agent #1, quotable directly: sample = the 10 PRs listed above; total comments (issue + review) = 180; est. no-action/advisory = 21; bot/agent-authored comments+reviews = 254, human = 0. The per-PR bot column spanned codeant-ai, coderabbitai, qodo-code-review, sonarqubecloud, chatgpt-codex-connector, gemini-code-assist.
  • Live corroboration that third-party volume is material and would be excluded: on PR feat: implement issue #1403 — [Phase 1] Write docs/agentic-interaction-model.md — the event-first standard, three trigger classes, the GITHUB_TOKEN bridge rule, and the timer contract #1413 within one hour, the comment stream included a Codex quota notice, a Qodo "Bugs (0)" summary, a CodeAnt review-status table and a SonarCloud quality-gate banner — all classify non-agent under the current classifier, all are clutter a human scrolls past.
  • Do not widen the classifier to fix this. First-party-only is the right primary metric; the defect is the doc's claim about the baseline, not the code's scope choice.
  • The rest of docs/metrics-baseline.md is sound — the bimodal convergence split, the "record a dated row, never silently overwrite" convention, and the no-new-cron property should all be preserved.

Project Structure Notes

docs/metrics-baseline.md only. No script, workflow, or test changes expected.

References

Likely target surface

  • docs/metrics-baseline.md

Filed after PR #1414 merged. F1 and F2 from that review were correctly fixed before merge; F3's mechanism was implemented but its concluding factual claim is wrong. Filed under epic #1402.

Activity

  1. github-actions commented on Aug 2, 2026

    @github-actions
    Contributor

    Thanks for the thorough write-up and for tracing the provenance of the ~12% figure so precisely — this is exactly the kind of correction AC #4 was designed to catch. Before we proceed with the fix: can you confirm whether you'd like the all-comments series actively maintained going forward (i.e., add a second figure alongside the first-party metric), or simply document that none is maintained and point to the reviewer scorecard as the only third-party view?

  2. don-petry commented on Aug 2, 2026

    @don-petry
    CollaboratorAuthor

    Dev-Lead Implementation Plan

    Issue: #1419 — [docs] metrics-baseline denominator note misstates the ~12% figure's basis — claims consistency where populations differ

    Scope

    Documentation-accuracy fix in docs/metrics-baseline.md: correct the denominator-scope note so it states the ~12% figure's actual all-comments basis, remove the wrong "denominators are consistent" claim, and record the correction as a dated append.

    Implementation Checklist

    Tests to Write

    • None. Pure documentation change with no observable behavioral change (Phase 2 exception). No script/workflow/test changes are implied — the classifier scope is intentionally unchanged.

    Test Command

    bash .dev-lead/scripts/dev-lead-lint.sh (shellcheck + agent frontmatter validation; the repo's lint gate)

  3. don-petry commented on Aug 2, 2026

    @don-petry
    CollaboratorAuthor

    Dev-Lead: Implementation Complete

    Plan Execution

    • Marked the incorrect "so the denominators are consistent" sentence as corrected — struck in place with a dated [Corrected 2026-08-02 …] annotation, original text retained not deleted. (AC Go-live improvements for PR review agent #2, feat: add Copilot engine support via REVIEW_ENGINE toggle #5)
    • Appended a dated Correction (2026-08-02) section stating the ~12% figure's actual basis: all PR comments in the sampled window, third-party reviewer bots included, phrase-scan classified; recorded the sample (10 PRs, 21/180, 254/254 machine-authored, named bot columns). (AC test issue from agent #1)
    • Stated the classifier measures a narrower first-party population, so the first measured value is expected to differ — a population change, not a regression or improvement. (AC Go-live improvements for PR review agent #2)
    • Gave the interpretation rule for the first scheduled run: genuine measurement correction (classifier vs. hand-count disagreement, or share moving at a fixed denominator) versus the known population difference. (AC Add @claude delegation, auto-merge, and rebase handling #3)
    • Stated that no all-comments series is maintained and named the reviewer scorecard (scripts/reviewer_report.sh) as the only third-party view. (AC Optimize review: small-PR and incremental fast paths #4)
    • Preserved the sound parts (bimodal split, named excluded bots, scorecard pointer, labelling requirement, dated-append convention, no-new-cron property). Classifier scope left unchanged — no script/workflow/test changes.

    Test Results

    Phase 2 (TDD) exception: pure documentation change, no observable behavioral change. No script/workflow/test changes are implied by the issue (classifier cn_marker_pattern scope intentionally unchanged). Verification was via the repo lint gates:

    $ bash .dev-lead/scripts/dev-lead-lint.sh
      [lint] shellcheck on 101 file(s)...
      [lint] validating 4 agent profile(s)...
      [lint] validating .github/CODEOWNERS...
      [lint] all checks passed
    
    $ npx markdownlint-cli2 docs/metrics-baseline.md
    markdownlint-cli2 v0.23.2 (markdownlint v0.41.1)
    Linting: 1 file
    Summary: 0 issues in 0 files
    

    Files Changed

    • docs/metrics-baseline.md: Corrected the denominator-scope reconciliation note — struck the wrong "denominators are consistent" claim in place (dated annotation, original retained) and appended a dated Correction (2026-08-02) section covering AC test issue from agent #1–Optimize review: small-PR and incremental fast paths #4 (actual all-comments basis + sample, narrower-population statement, first-run interpretation rule, no-all-comments-series statement naming the reviewer scorecard).

    Notes

    • No classifier change: first-party-only remains the defensible primary metric, per the issue's explicit instruction not to widen cn_marker_pattern.
    • The strikethrough retains the original wrong sentence rather than deleting it, satisfying AC feat: add Copilot engine support via REVIEW_ENGINE toggle #5's "dated append, not silent edit" requirement; the GFM ~~…~~ wraps correctly around the inner literal ~12%.
    • No follow-up issues needed.
  4. added a commit that references this issue on Aug 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    dev-leadFor dev-lead agent pickupdocumentationDocumentation changesinitiativeEpic / initiative tracking issue

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions