Skip to content

t1k:contribution-flush

FieldValue
Modulet1k-kit-feedback
Version2.14.39
Effortlow
Tools—

Keywords: contribution flush, contribution telemetry, flush contributions, record missed contributions

/t1k:contribution-flush
(no args)

t1k:contribution-flush — Flush Missed Contribution Telemetry

Section titled “t1k:contribution-flush — Flush Missed Contribution Telemetry”

The AI half of the pipeline. Reconcile is the capture layer: it asks GitHub what the operator actually did (gh pr merge / gh issue close / authored PRs and issues) and emits an outcome-derived set of artifacts rather than a list of commands that happened to be observed. This skill AI-scores each emitted artifact against the shared rubric, and POSTs the scores to the telemetry worker — closing the gap when the originating skill (t1k:issue / t1k:sync-back / t1k:triage) skipped its live t1k:contribution-score POST.

No local state file or queue: GitHub and the worker are the state. The score file is a temp file the skill deletes; cross-run memory and record’s retry state live in the worker (references/design-rationale.md).

The deterministic half cannot judge quality; this skill can. That split is the whole design: reconcile guarantees capture, this skill supplies the score.

Reconcile runs first, so what gets scored reflects the outcome, not the commands that happened to be observed. The rationale (#745): references/design-rationale.md.

  • Manual: user asks to “flush contributions” / “record missed contribution scores”.
  • Auto-wired (recommended): t1k:triage invokes this at the END of a run, and t1k:my-score invokes it at the START (so lifetime totals reflect freshly-flushed items). Nothing nudges on a threshold any more — the prompt-time nudge hook went with the retired capture hook, and reconcile runs as the first step of this skill.

This skill is fire-and-forget for callers: any failure is logged and never blocks the caller’s primary workflow.

Step 0 — Resolve the script path (BOTH install scopes)

Section titled “Step 0 — Resolve the script path (BOTH install scopes)”

Resolve the path, do not assume it. Test each candidate for runnability, not mere existence: a stale project-local copy can win the race over a working global install beside it, and [ -f ] cannot tell them apart. The load-and-call check and its rationale: references/step0-resolution.md:

Terminal window
for c in "$CLAUDE_PROJECT_DIR/.claude/scripts/contribution-flush.cjs" \
".claude/scripts/contribution-flush.cjs" \
"$HOME/.claude/scripts/contribution-flush.cjs"; do
[ -f "$c" ] && bun -e "require(require('path').resolve(process.argv[1])).resolvePaths()" "$c" 2>/dev/null && echo "$c" && break
done

Use the printed path verbatim in Steps 1 and 3 (each Bash call is a fresh shell, so a variable does not survive between steps — substitute the literal path). Empty output → STOP and report contribution-flush.cjs not found at project or global scope — is t1k-maintainer installed?

Step 1 — Reconcile against GitHub (#745)

Section titled “Step 1 — Reconcile against GitHub (#745)”
Terminal window
bun "<resolved-path>" reconcile

Asks GitHub what the authed user actually merged/closed/authored in the in-scope repos over the last 7 days, subtracts what the worker has already recorded, and emits the unrecorded survivors — each already enriched with its artifact’s title and body_excerpt so it can be scored without a second lookup. Output (JSON): { reconciled, user, days, dryRun, reposScanned, repos, candidates, added, alreadyKnown, deferred, entries, truncatedRepos, truncated, omittedRepos, workerList, recordedTruncated, filterMode, filterCalls, enriched, errors }.

entries[] is { ref_url, repo, kind, action, type, title, body_excerpt } — self-contained, ready to score. This is the single entry point: the list subcommand was folded into it, and invoking list now exits non-zero.

Read the envelope field by field before reporting. Branch on reconciled and skipped first: gh-auth is the only skip a login fixes, and gh-unreachable means wait and retry. added:0 with candidates:0 is the healthy empty state; added:0 with candidates > 0 is not. The per-field rules for filterMode, workerList, recordedTruncated, enriched, deferred and errors[]: references/reconcile-envelope.md.

Options (--days, --repo, --dry-run) and what each does: references/reconcile-envelope.md.

This step writes nothing locally. It is read-only against local state: attribution is filtered on mergedBy / the closing actor, never “everything closed today” — an artifact someone else merged is not the operator’s credit.

Apply the shared 1–5 rubric (SSOT in t1k:contribution-score — do NOT redefine it here) to each entry’s title + body_excerpt. Score by the entry’s action:

  • action:"merge"|"close" → triage credit (type:"triage-backfill"): score the artifact’s quality as merged/closed work.
  • action:"create" → authored credit (type:"issue" or "sync-back-pr"): score the artifact as filed.

Be conservative — when between two tiers, pick the lower one.

Build the scored array — one object per entry, carrying that entry’s action and type through verbatim:

[ { "ref_url": "https://github.com/<owner>/<repo>/(issues|pull)/<n>", "ai_score": 1-5, "ai_rationale": "<=300 chars", "action": "<entry.action>", "type": "<entry.type>" } ]

Copy action and type straight off the entries[] row you scored — do not re-derive them, and do not omit them. record expands one ref_url into both possible credits when the row is silent, and the row is the only place the artifact’s provenance survives: kind + ref_url cannot tell a CLOSED issue from an OPEN authored one. A silent row therefore re-creates the over-production this contract removes — the inapplicable credit is refused (403 author_mismatch / triage_requires_closed_artifact), every refusal still spends the worker’s per-window POST budget, and a large flush throttles itself at 429 with the tail of scored refs never attempted.

Both fields are optional; a row supplying neither keeps the old expand-both behaviour. That is the fallback for a hand-written score file, not a licence to drop them here.

Write it to a temp file, e.g. <claudeDir>/telemetry/.flush-scores.json. This file is also record’s work queue, so it must be written even when the array is short — do not write an empty array and treat that as “nothing to flush” (Step 3).

Terminal window
bun "<resolved-path>" record --input <tmpfile>

Output (JSON): { recorded, kept, dropped, throttled, retryAfterSeconds, results: [ { ref_url, disposition, reason, status, retry_after_seconds } ], submitMode, submitCalls }. reason / status are present on every POSTed row; retry_after_seconds only when the worker advertised one. submitMode / submitCalls report which transport ran (see “How the credits are sent” below).

record re-derives its work queue from the same file: each ref_url is parsed back into repo / kind / action / type. A row whose action / type you carried through from Step 2 narrows to exactly that one credit; a row carrying neither expands into both possible credits (a pull ref → merge + create; an issues ref → create + merge). See Step 2 — pass the fields through so the expansion stays narrow.

An action/type that names no credit the ref can earn (a close on a pull, or an unrecognised value) is skipped and reported on stderr, never silently expanded — a row that parsed cleanly but narrowed to nothing still exits non-zero rather than emitting {recorded:0}.

A failure here is not a zero. On an absent, empty, unparseable, or all-unparseable score file, record exits non-zero with skipped:"scores-unusable", a detail naming the path, and source. It does NOT emit {recorded:0}. Never read a zero as success — see “Zero vs failure” below.

The script POSTs via the SSOT body shape and applies disposition:

Worker responseDispositionNext run
201 / 200drop-recordedthe worker holds it; reconcile will not re-offer it
403 triage_requires_closed_artifact / pr_not_mergedkeep (lifecycle-not-yet)re-offered by the next reconcile
429 (worker’s per-window POST cap)keep (throttled)re-offered; the run stops early (see below)
0 / 5xx (transient network/server error)keep (transient)re-offered by the next reconcile
400 / other 403dropterminal — not re-offered

There is no local write-back: disposeResult still classifies every status, but nothing is persisted. recorded means the server holds the credit, keep means it will be re-offered, drop means it is terminal.

Three different causes share the keep disposition, so read reason and status, never disposition alone — keep: pr_not_merged (403, lifecycle-not-yet) and keep: transient(429) retry_after=1800s are different situations with different operator actions. The 403 reasons are SSOT’d as NOT_YET_REASONS in hooks/lib/contribution-telemetry.cjs. Throttling is also summarised at the top level as throttled / retryAfterSeconds, and a 429 stops the run — every remaining entry would hit the same spent window, so the run stops rather than burning calls.

The transport: one batch POST in chunks of about 100, a per-credit fallback for workers that predate the route, and outages kept rather than fallen back. Read submitMode to see which ran: references/record-transport.md.

Delete the temp scores file afterward.

## Contribution Flush
**Reconciled in:** {added} (of {candidates} found on GitHub)
**Recorded:** {recorded} **Kept (awaiting merge / transient):** {kept} **Dropped:** {dropped}
| Ref | Type | Score | Disposition | Reason |
|-----|------|-------|-------------|--------|
| ... one row per results[] entry, `reason` verbatim ... |

If recorded == 0 && kept == 0 && dropped == 0: print Nothing to flush. — but only if record exited 0 and emitted no skipped field. Read “Zero vs failure” below before printing that line.

If throttled > 0, say so explicitly — {throttled} throttled by the worker's per-window cap, retry in {retryAfterSeconds}s — instead of reporting those rows as “not yet mergeable”. Never report a bare keep count with no reason breakdown: that is the exact unactionable output #890 fixed.

Zero vs failure — never read a zero as success

Section titled “Zero vs failure — never read a zero as success”

This distinction is the point of the current design. With the local ledger gone, count:0 / recorded:0 is no longer the healthy state — it is the signature a broken pipeline produces. A pipeline that POSTs nothing and a pipeline with nothing to POST used to be the same output, so a green here could not go red.

SignalMeaningAction
record exits non-zero, skipped:"scores-unusable"the score file was absent, empty, unparseable, or had no parseable ref_urlSTOP and report the detail. The scoring step did not run, or wrote elsewhere. Nothing was POSTed.
record exits non-zero, skipped:"queue-empty"the loader returned no work queueSTOP — same class of failure.
reconcile → added:0, candidates:0GitHub genuinely had nothing new in the windowhealthy empty state; Nothing to flush.
reconcile → added:0, candidates > 0candidates existed but were all subtracted as recordedcheck alreadyKnown, then filterMode / workerList — a complete subtraction and an over-match look identical otherwise

So: check the exit status and the skipped field BEFORE interpreting any count. skipped:"scores-unusable" means the input was missing or unusable; a genuine empty result is a different outcome and must never be reported as the same thing.

Notes (idempotency, attribution to the authed gh user, no local retry state, and the rubric SSOT): references/notes.md.

  • gh must be authed — but read WHICH skip you got. record self-skips on three distinct causes, and only one of them is fixed by logging in: gh-auth (no token, or credentials rejected) → gh auth login; gh-unreachable (5xx / 429 / DNS / timeout) → wait and retry, auth is fine; gh-unavailable (unrecognised) → read detail first. Until 2026-08-17 every failure reported gh-auth, so a GitHub 503 sent people to gh auth login for a problem login could not fix.
  • Over-production is not free, and no longer the default. Every refused POST spends the worker’s per-window budget and the run stops at the first 429 — measured 2026-09-22, expand-both produced 43 refused rows out of 101 and left 40 of 91 scored refs never attempted. Step 2’s pass-through is what removes that cost.