t1k:contribution-flush
| Field | Value |
|---|---|
| Module | t1k-kit-feedback |
| Version | 2.14.39 |
| Effort | low |
| Tools | — |
Keywords: contribution flush, contribution telemetry, flush contributions, record missed contributions
How to invoke
Section titled “How to invoke”/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.
When to use
Section titled “When to use”- Manual: user asks to “flush contributions” / “record missed contribution scores”.
- Auto-wired (recommended):
t1k:triageinvokes this at the END of a run, andt1k:my-scoreinvokes 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.
Workflow
Section titled “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:
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" && breakdoneUse 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)”bun "<resolved-path>" reconcileAsks 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.
Step 2 — AI-score each emitted entry
Section titled “Step 2 — AI-score each emitted entry”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).
Step 3 — Record
Section titled “Step 3 — Record”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 response | Disposition | Next run |
|---|---|---|
| 201 / 200 | drop-recorded | the worker holds it; reconcile will not re-offer it |
403 triage_requires_closed_artifact / pr_not_merged | keep (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 403 | drop | terminal — 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.
Step 4 — Report
Section titled “Step 4 — Report”## 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.
| Signal | Meaning | Action |
|---|---|---|
record exits non-zero, skipped:"scores-unusable" | the score file was absent, empty, unparseable, or had no parseable ref_url | STOP 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 queue | STOP — same class of failure. |
reconcile → added:0, candidates:0 | GitHub genuinely had nothing new in the window | healthy empty state; Nothing to flush. |
reconcile → added:0, candidates > 0 | candidates existed but were all subtracted as recorded | check 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.
Hard rules
Section titled “Hard rules”ghmust be authed — but read WHICH skip you got.recordself-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) → readdetailfirst. Until 2026-08-17 every failure reportedgh-auth, so a GitHub 503 sent people togh auth loginfor 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.