t1k:contribution-flush

Field	Value
Module	`t1k-maintainer`
Version	`2.18.3`
Effort	`low`
Tools	—

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

How to invoke

/t1k:contribution-flush
(no args)

t1k:contribution-flush — Flush Missed Contribution Telemetry

The AI half of the deterministic-capture pipeline. The contribution-capture.cjs PostToolUse:Bash hook deterministically records every gh issue|pr create|merge|close against a T1K repo to a tracking file (<claudeDir>/telemetry/contribution-tracking.jsonl). This skill reads that file, AI-scores each un-recorded 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.

A hook cannot judge quality; this skill can. That split is the whole design: the hook guarantees capture, this skill supplies the score.

When to use

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). The contribution-capture hook also nudges (N contributions pending — run /t1k:contribution-flush) once the tracking file reaches its threshold.

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

Workflow

Step 1 — List pending

node "$CLAUDE_PROJECT_DIR/.claude/scripts/contribution-flush.cjs" list

Output (JSON): { endpoint, pending: [ { ref_url, repo, kind, action, type, title, body_excerpt } ], count }.

endpoint:false → no telemetry endpoint configured → STOP, report No telemetry endpoint configured — nothing to flush.
count:0 → STOP, report No pending contributions to flush.

(The script self-skips and prunes out-of-bounds entries — anything past MAX_ATTEMPTS retries or older than MAX_AGE_DAYS is dropped, not listed.)

Step 2 — AI-score each pending entry

Apply the shared 1–5 rubric (SSOT in t1k:contribution-score — do NOT redefine it here) to each pending entry’s title + body_excerpt. Map by 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 pending entry you chose to score):

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

Write it to a temp file, e.g. <claudeDir>/telemetry/.flush-scores.json.

Step 3 — Record

node "$CLAUDE_PROJECT_DIR/.claude/scripts/contribution-flush.cjs" record --input <tmpfile>

Output (JSON): { recorded, kept, dropped, results: [ { ref_url, disposition } ] }.

The script joins each score back to its tracking entry, POSTs via the SSOT body shape, and applies disposition:

Worker response	Disposition	Tracking file
201 / 200	`drop-recorded`	removed + added to recorded ledger
403 `triage_requires_closed_artifact`	`keep`	retained, `attempts++` (retry next flush)
0 / 5xx (transient)	`keep`	retained (attempts NOT bumped)
400 / other 403	`drop`	removed (terminal)

Delete the temp scores file afterward.

Step 4 — Report

## Contribution Flush

**Recorded:** {recorded}   **Kept (awaiting merge / transient):** {kept}   **Dropped:** {dropped}

| Ref | Type | Score | Disposition |
|-----|------|-------|-------------|
| ... one row per results[] entry ...                  |

If recorded == 0 && kept == 0 && dropped == 0: print Nothing to flush.

Notes

Idempotent — the worker dedups on (user, ref_url); re-flushing a recorded ref returns 200 and is dropped. The skill’s own t1k:issue / t1k:sync-back live POSTs and this flush can both fire safely — first wins.
Attribution — the script resolves the authed gh user (the kit operator), NOT the GitHub artifact author, so triage/merge credit lands on the operator.
Scoring is the skill’s job — the rubric SSOT is t1k:contribution-score. This skill orchestrates; it must not inline the POST body shape (the script owns that) nor redefine the rubric.

Gotchas

gh must be authed — record self-skips (skipped:"gh-auth") if not. Run gh auth login first.
triage-backfill needs a CLOSED/MERGED artifact — open auto-armed PRs return 403 and are KEPT for the next flush; they record once they merge. This is expected, not an error.
Do NOT call /api/contributors/me — that’s t1k:my-score (lifetime totals). This skill only records this-batch scores.