Add PR triage skills: status labeller + Mon/Wed/Fri digest

[daimon-pymclabs]

What

A two-layer, agent-assisted PR triage system to help work down the review backlog without removing human judgment from reviews. This is the Tier 1 ("recommend, don't act") slice: the digest is read-only, and the only GitHub writes are a tightly-scoped label namespace behind an explicit --apply flag.

Design: labels, not states

Every open PR carries several orthogonal, non-exclusive facts (it can be conflicting and have changes requested and be stale at once). So the model is a set of independent labels, plus a single derived next-action computed via an explicit precedence order used only for grouping.

Layer 1 — shared deterministic core

.agents/skills/_shared/pr_triage/labels.py is the single source of truth. It fetches open PRs via gh (forcing the lazily-computed mergeable field), computes per-PR facts — lifecycle, conflict, ci, review, decision-needed, risk, idle-band, author-class — and derives one next_action. No LLM judgment; it is a pure function of the GitHub API. All tunables (maintainer/labs handles, idle thresholds, precedence order, managed labels) live at the top of the file.

Layer 2 — two thin skills sharing that core

They call the same function, so they can never disagree.

• pr-status-labeller reconciles a status:* label namespace on GitHub (conflicting, ci-failing, waiting-on-author, ready-for-review, aging, stale). Dry-run by default; --apply to write. Touches only status:* — never review:*, major, needs:maintainer-decision, or any human-owned label. Drafts stay out of reviewer-facing statuses.
• pr-digest produces a read-only Mon/Wed/Fri digest. It surfaces exactly one hard decision per run, a short clean-review queue (external contributors first), and collapses everything else under a "no action needed" divider. It recommends only; it never writes to GitHub.

Why one hard item per digest

The digest is shaped to counter decision paralysis, not just capacity: it recommends a default to veto rather than asking an open question, frames each hard item as a small reversible step, and names the cost of not deciding. Surfacing one deep-focus decision per run (rather than the full high-risk list) keeps the queue from being deferred wholesale.

Idle thresholds

Aging nudge at 30d, stale warning at 90d. The digest recomputes state live rather than trusting the labeller's last run, so a missed labeller run degrades GitHub visibility but never corrupts the digest.

Triggering

The logic is trigger-agnostic: an automation can run either skill on a schedule, or a maintainer can run them locally. Only the posting step differs.

Checks run locally

ruff check (clean), ruff format (clean), codespell (clean), pymarkdown against the repo config (clean), py_compile, and both scripts smoke-tested against the live repo (42 open PRs classify without error; labeller dry-run produces a sane add/remove diff).

Not in this PR

Mechanical execution (auto-nudges, branch syncs) and any agent-authored reviews. Those are later tiers, deliberately gated behind this read-only slice earning trust first.

🤖 Generated with Claude Code

[cursor]

PR Summary

Medium Risk
reconcile_labels.py --apply mutates open PR labels on GitHub; misclassification could mis-route the backlog, though writes are limited to status:* and dry-run is the default.

Overview
Introduces a Tier 1 PR triage stack under .agents/skills/: a shared gh-driven core classifies every open PR into orthogonal facts plus one precedence-ordered next_action, with no LLM in the classification path.

pr-status-labeller reconciles only the six status:* labels on GitHub (dry-run by default; --apply creates labels and patches PRs). pr-digest builds a Mon/Wed/Fri Discord markdown skeleton via build_digest.py—one hard decision, quick-review queue (externals first), merge-ready list, and an FYI block—leaving {{HARD_ITEM_FRAMING}} for light agent prose per format.md.

The core deliberately avoids updatedAt for idle time (so label edits do not reset aging), treats failed per-PR gh pr view as detail_incomplete (withholds or carries idle labels), and handles CI rollup edge cases (e.g. CANCELLED, STALE) so digest and labeller stay aligned.

^{Reviewed by Cursor Bugbot for commit b3645e9. Bugbot is set up for automated code reviews on this repo. Configure here.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.98%. Comparing base (79c0a87) to head (b3645e9).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1090   +/-   ##
=======================================
  Coverage   95.98%   95.98%           
=======================================
  Files         104      104           
  Lines       16277    16277           
  Branches      912      912           
=======================================
  Hits        15623    15623           
  Misses        488      488           
  Partials      166      166           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[daimon-pymclabs]

Pushed 1058868 addressing all three Bugbot findings and the failing prek (ruff) check:

• Precedence list never applied — the CLI table now sorts by NEXT_ACTION_RANK derived from NEXT_ACTION_ORDER instead of alphabetically, so the list is genuinely the single place to tune display precedence. (The if/elif in _next_action still encodes the branch logic, but reordering the list now actually reorders output.)
• Managed labels set unused — _status_labels_for now asserts its emitted set stays within STATUS_LABELS, and reconcile_labels.py asserts set(LABEL_DEFS) == STATUS_LABELS. Editing one without the other now trips at import instead of silently drifting.
• Hard items listed as quick reviews — reviews now excludes the hard lead PR and every other_hard number, so major/decision PRs no longer double-count in the quick-review list and header.
• prek — fixed E741 (l→lab) in labels.py/reconcile_labels.py and E731 (lambda→def by) in build_digest.py; ruff check and ruff format both clean locally.

[daimon-pymclabs]

Addressed the BugBot findings (commit e26d69f):

Finding 2 (MEDIUM — NEXT_ACTION_ORDER not the source of truth) — FIXED.
The CLI table already sorted by NEXT_ACTION_RANK (derived from NEXT_ACTION_ORDER), but _next_action still hardcoded an independent if/elif chain, so reordering the list would not change classification precedence. _next_action now maps each action to a predicate and walks NEXT_ACTION_ORDER, returning the first action whose predicate holds — genuine first-match-wins, with ready-for-review as the always-true fallback that must stay last. Added a drift-guard assert that the predicate keys equal NEXT_ACTION_ORDER, and corrected the docstring. Verified behavior-identical to the old chain across all 576 input combinations (decision_needed × lifecycle × idle_band × review × conflict × ci); 0 mismatches. NEXT_ACTION_ORDER is now the single source of truth for both classification and display ordering.

Finding 1 (MEDIUM — quick-review double-count) — already resolved (no change needed).
The current code already excludes hard-item PRs from the quick-review list: hard_numbers is built from the lead hard item plus other_hard, reviews filters on f["number"] not in hard_numbers, and the header count uses len(reviews). This was fixed in the prior pass (1058868); nothing left to do.

Finding 3 (LOW — STATUS_LABELS dead constant) — already resolved (no change needed).
STATUS_LABELS is no longer dead: _status_labels_for asserts its emitted set is a subset of STATUS_LABELS (drift guard), and reconcile_labels.py asserts set(LABEL_DEFS) == core.STATUS_LABELS, tying both emission and label creation to the one managed set. Single source of truth is enforced. Also fixed in 1058868.

No unit tests exist for these scripts; validated via the exhaustive equivalence check above plus --help/py_compile on all three scripts. No lines exceed the 88-char limit.

[daimon-pymclabs]

Addressed the BugBot idle-timer finding and the failing prek check (commit c62eb0d).

BugBot (High): label writes reset the idle timer. FIXED.
Confirmed real. idle_days/idle_band were computed from GitHub's updatedAt, which a label-only gh pr edit bumps. So every --apply run of the labeller reset the idle clock; the next reconcile then saw a "fresh" PR and stripped the status:aging/status:stale label it had just written, meaning aging/stale state could never persist and the live idle figures the digest reads were corrupted.

Fix lives in the shared core (_shared/pr_triage/labels.py) so the digest and the labeller read the exact same number:

• New _last_activity(pr): the most recent of PR creation, commit push times (committedDate), and comment timestamps (createdAt). None of these are moved by a label edit, so idleness is now stable across labeller runs.
• idle_days derives from _last_activity(pr) instead of updatedAt.
• comments is fetched in the bulk pr list; commits is fetched per-PR inside the existing gh pr view poke loop. commits cannot go in the bulk listing: each commit carries an authors connection, which pushes a 200-PR query past GitHub's 500k GraphQL node limit (verified: it errors). The per-PR fetch piggy-backs on the same gh pr view already used to resolve lazy mergeable, so it adds no extra API call.

Verified end to end against the live repo: labels.py, reconcile_labels.py (dry-run), and build_digest.py all run clean, and PR #1090 now reports idle 0d from its latest commit rather than a label bump.

prek CI. FIXED.
The failing hook was ruff-format (not lint). Ran the hooks locally; ruff-format reformatted labels.py. prek run across every file this PR touches is now green.

[drbenvincent]

Automated triage

Recommendation: review:high — maintainer decision needed.

Why:

• Adds two new triage automation skills (.agents/skills/pr-digest/, .agents/skills/pr-status-labeller/) and a shared core — this is a workflow and agent-tooling change, not a CausalPy library change.
• A shared core module (labels.py) that would read/write GitHub labels via gh — this is an operational concern with permissions and automation implications.
• The PR description explicitly frames this as a "read-only" Tier 1 slice, but the status-labeller script writes labels to GitHub.
• All CI checks pass.

Review focus:

1. Decide whether PR triage automation belongs in this repo at all — the description calls for a maintainer to "earn trust" before later tiers are added.
2. Verify the status:* label namespace does not conflict with existing label conventions or review workflows.
3. Confirm the shared cores gh-based API calls handle authentication and rate-limiting gracefully in CI.

Confidence: medium — the PR adds non-trivial tooling that needs a maintainer to decide on direction before a code review can settle it.

[daimon-pymclabs]

Addressed the 4 remaining BugBot findings in c62eb0d..HEAD:

• Cancelled checks counted as failing — _ci_state now filters CANCELLED/SKIPPED/NEUTRAL out of the rollup before evaluating. With cancel-in-progress concurrency, superseded runs linger as CANCELLED next to their replacement, which was marking green PRs status:ci-failing and routing them to mechanical.
• Startup failure treated as green — STARTUP_FAILURE added to the failure set.
• Unknown mergeable marked ready — added a mergeability-unknown next_action (just above ready-for-review in NEXT_ACTION_ORDER) for the case where GitHub never resolves mergeable even after the per-PR gh pr view retry. Those PRs no longer get status:ready-for-review, and the digest gained a below-the-line bucket so they don't silently disappear.
• Reviews ignored in idle calculation — reviews is now fetched in the same per-PR gh pr view pass as commits (kept out of the bulk list for the node-budget reason already documented) and folded into _last_activity, so a just-reviewed PR can't immediately pick up status:aging/status:stale.

ruff check and ruff format --check are clean. @drbenvincent your triage comment recommends review:high / maintainer decision — that's still yours to call, nothing blocking from my side.

[daimon-pymclabs]

Addressed the BugBot finding Silent fetch failure corrupts idle (high severity) in e676d44.

The per-PR gh pr view was wrapped in contextlib.suppress(CalledProcessError), so a transient failure left commits/reviews unset while classification carried on. _last_activity then fell back to createdAt plus issue comments, overstating idleness for any PR whose recent activity was pushes or reviews, and --apply could write a wrong status:aging/status:stale.

Now: retry the view once (these are usually rate-limit/network blips), warn on stderr if it still fails, flag the PR detail_incomplete (surfaced on PRFacts and in the JSON payload), and withhold the idle-derived labels for that PR. mergeable stuck at UNKNOWN already routes to the mergeability-unknown bucket and never gets status:ready-for-review, so that half of the finding was covered.

[read-the-docs-community]

Documentation build overview

📚 causalpy | 🛠️ Build #33887605 | 📁 Comparing b3645e9 against latest (7e23946)

  🔍 Preview build  

29 files changed · + 1 added · ± 28 modified

+ Added

• references.html

± Modified

• 404.html
• knowledgebase/design_notation.html
• knowledgebase/estimands.html
• knowledgebase/index.html
• knowledgebase/quasi_dags.html
• knowledgebase/structural_causal_models.html
• notebooks/difference-in-differences-banks-pymc.html
• notebooks/geolift-single-cell.html
• notebooks/instrumental-variables-pymc.html
• notebooks/instrumental-variables-variable-selection-priors.html
• and 18 more...

[daimon-pymclabs]

Both follow-up findings were right, and the first one is a regression I introduced in e676d44. Fixed in 04834ea.

Incomplete fetch strips idle labels (high). Correct, and worse than the bug it was meant to fix. reconcile_labels.py diffs want against have, so a label omitted from status_labels is a label it removes: one unlucky gh pr view would have wiped correct status:aging/status:stale off a PR. _status_labels_for now takes the PR's existing status:* labels and, in the unknown band, carries the idle ones through unchanged. The reconcile becomes a no-op for them, so a failed fetch neither writes a new idle verdict nor erases the last good one. Only IDLE_LABELS carry over; a stale status:conflicting is still removed normally.

Draft action ignores incomplete idle (medium). Also correct: the labeller refused to trust the number while the digest happily bucketed a draft as stale on it. Rather than add a second detail_incomplete guard, the fix collapses both call sites onto one signal: _idle_band now returns unknown when the detail fetch failed. The draft predicates test the band by equality, so they no longer match and the draft falls through to in-flight-draft; label derivation branches on the same value. One source of truth for "do not act on this idle figure" instead of two places to keep in sync.

Verified across the matrix: healthy stale still labels stale; incomplete with an existing status:stale keeps it; incomplete with no idle label adds none; incomplete draft routes to in-flight-draft; incomplete does not resurrect status:conflicting.

[daimon-pymclabs]

BugBot pass addressed — b3645e9

Fixed (3)

• _ci_state treated STALE as green (medium) — correct, and the worst of the three: STALE was in neither the ignored set nor the failure set, so it fell through to green and a PR could reach ready-to-merge on a check GitHub had given up on. Now failing. Worth saying why red and not pending: ready-to-merge only excludes ci == "red", so pending would not have closed the hole. And unlike CANCELLED — which is ignored precisely because cancel-in-progress leaves a superseded run next to the run that replaced it — a STALE check has no sibling success in the rollup, so it really does need a re-run. mechanical is the right bucket.
• Digest printed untrusted idle_days (medium) — correct. The hard-item line rendered idle_days as fact even under detail_incomplete, which is the exact figure the core already refuses to derive labels from (idle_band == "unknown"). It now prints idle unknown. The review queue also sorts untrusted-idle PRs after trusted ones within their author-class group. Minor correction to the report: the sort is ascending by idle, so an inflated figure demoted a PR rather than overstating its urgency — the ordering was noisy, not urgency-inflating.
• Brackets broke digest markdown links (medium) — correct. [WIP]/[RFC] prefixes are common here and the raw ] closed the link on the wrong character, corrupting the rest of the line. Titles are now escaped via a _md helper.

Rejected as already fixed (2) — both were filed against e676d44 and 04834ea (Make an incomplete fetch neutral, not destructive) landed the fixes before the comments posted. No code change needed:

• "Incomplete fetch strips idle labels" (high) — _status_labels_for already takes the PR's existing status:* labels and, on idle_band == "unknown", carries existing & IDLE_LABELS through unchanged, making the set-difference reconcile a no-op for the idle labels. Verified: _status_labels_for({... "idle_band": "unknown" ...}, {"status:stale"}) returns ['status:stale', 'status:ready-for-review'] — the durable state is preserved, not stripped.
• "Draft action ignores incomplete idle" (medium) — _idle_band already returns "unknown" when detail_incomplete, and the stale-draft/aging-draft predicates test the band by equality, so an incomplete draft matches neither and falls through. Verified: a draft with idle_band == "unknown" classifies as in-flight-draft.

All 9 earlier cursor[bot] threads on this PR are resolved. ruff check and ruff format clean on both touched files.

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit b3645e9. Configure here.}

[cursor]

Review queue starves old PRs

Medium Severity

The quick-review list sorts by ascending idle_days, so freshest PRs appear first. Longer-waiting external PRs sink as new ones arrive. The shared CLI table already ranks by descending idle, so the digest backlog order fights the triage goal of working down neglected reviews.

Additional Locations (1)

• .agents/skills/_shared/pr_triage/labels.py#L465-L471

 

^{Reviewed by Cursor Bugbot for commit b3645e9. Configure here.}

[cursor]

Queued decisions out of order

Medium Severity

other_hard keeps gh pr list order (newest created first) instead of sorting by age_days like pick_hard_item. The “queued behind this one” line then shows the newest remaining hard items, not the next-oldest by cost-of-waiting.

Additional Locations (1)

• .agents/skills/pr-digest/scripts/build_digest.py#L144-L150

 

^{Reviewed by Cursor Bugbot for commit b3645e9. Configure here.}