t1k:triage
| Field | Value |
|---|---|
| Module | t1k-maintainer |
| Version | 4.10.58 |
| Effort | high |
| Tools | Agent, AskUserQuestion, Bash, Edit, Glob, Grep, Read, Skill, Task, WebFetch, Write |
Keywords: backlog, classify, github, issues, prioritize, process, triage
How to invoke
Section titled “How to invoke”/t1k:triage[--dry-run|--ask|--yolo] [--advice|--no-advice]TheOneKit Triage — Issue and PR Review
Section titled “TheOneKit Triage — Issue and PR Review”Structured triage workflow across the whole T1K ecosystem at github.com/The1Studio, discovered live from GitHub.
Usage (compressed)
Section titled “Usage (compressed)”Default behavior is AUTO. Bare /t1k:triage runs the action phase end-to-end without prompting per item.
| Invocation | Behavior |
|---|---|
/t1k:triage | AUTO (default) — report, act, verify per item |
/t1k:triage --ask | Interactive — AskUserQuestion per partition |
/t1k:triage --dry-run | Report only, no action |
/t1k:triage --yolo | Maximum autonomy — investigate deeply, decide, MERGE in-session |
Full mode matrix, safety contracts: references/usage-modes.md.
Default merge command: gh pr merge {n} --repo {REPO} --auto --squash --delete-branch. Admin-bypass (--admin) is escalation-only — see Step 5a.5 (auto path) vs Step 5b (admin fallback) for the full rule. Before ANY --delete-branch merge, run the stacked-PR guard: references/completion-verification.md § “Stacked-PR guard”. A home-branch head is the second guard — a PR from a linked worktree’s home branch merges WITHOUT --delete-branch: § “Home-branch guard”.
Routing
Section titled “Routing”- Query GitHub for the ecosystem repo list — never a local clone scan, never
t1k-config-*.json: Run thegh repo list The1Studiodiscovery pipeline (command:references/scaling-handoff.md§ “Repo discovery command”). - Deduplicate
- Fetch issues/PRs from ALL repos in parallel
- Label each item with source repo
Scaling — when to hand off
Section titled “Scaling — when to hand off”Single-agent triage works for small backlogs. Past the four hand-off triggers (> 20 items; > 15 in one repo; orthogonal categories; the same skill/file in 3+ PRs) delegate to /t1k:team: references/scaling-handoff.md.
Advisory supervision (ON by default)
Section titled “Advisory supervision (ON by default)”Advisory supervision is ON by default at advisorySupervision.level (--advice / --no-advice per run); the contract, the three triage checkpoints and the consult rules are in references/advisory-checkpoints.md. Counsel never authorizes what Guardrails forbids.
Per-item triage patterns
Section titled “Per-item triage patterns”Apply to EVERY item, regardless of single-agent or team-fanout mode. Full pattern detail: references/per-item-patterns.md.
5-verdict vocabulary: merge / close-superseded / close-obsolete / needs-fix / defer
Adversarial evidence requirement: every verdict line MUST cite evidence in one of: file:line / commit SHA / 1-line excerpt / workflow run-job ID. No verdict without evidence — if you can’t cite, the verdict is defer.
Other patterns covered in the reference: dup-cluster handling (3+ PRs on same skill), CI failure classification (infra-vs-real), tracker-issue verification (grep for the named artifact), and reasoning rules.
Workflow
Section titled “Workflow”[Fetch] → [Classify] → [Analyze] → [Review PRs] → [Report] → [Cook] → [Verify]Step 1 — Fetch (parallel per repo)
Section titled “Step 1 — Fetch (parallel per repo)”Fetch open issues and PRs per repo in parallel (gh issue list / gh pr list with --json; commands: references/scaling-handoff.md § “Fetch commands”).
Quota: many-repo runs: skills/t1k-git/references/github-api-limits.md.
Step 1b — Repo discovery (module-aware)
Section titled “Step 1b — Repo discovery (module-aware)”Run the Routing query (§ Routing) → the full ecosystem repo list. For modular kits, note which modules exist per kit.
Step 1c-pre — High-impact candidates (optional)
Section titled “Step 1c-pre — High-impact candidates (optional)”If gh auth token works, fetch the top-5 score-ranked candidates and render them at the top of the Step 5 report; on any failure skip silently — never fail triage. Issues labeled critical/P0/security always appear first. Command: references/high-impact-candidates.md.
Steps 1c, 1d, 2, 2b, 2c, 2d — comment enrichment and classification
Section titled “Steps 1c, 1d, 2, 2b, 2c, 2d — comment enrichment and classification”These steps fetch comments + reviews per item, run effort estimation, and apply the InfoStatus completeness check that gates solve/merge decisions. infoStatus: insufficient items MUST decision = defer — never silently solve them.
Full procedural detail: references/comment-enrichment-and-classification.md (covers Step 1c throttling/privacy/sanitization, Step 1d backfill, Step 2 classification fields, Step 2b effort heuristics, Step 2c comment classifier signals, Step 2d completeness gate).
Step 3 — Analyze issues
Section titled “Step 3 — Analyze issues”For each issue: read body + enriched comments, run Step 2d completeness check, check if skill/agent exists, check for duplicates, determine decision (close / merge / solve / defer). Do NOT mark an item solve without infoStatus: complete or partial.
Step 3-claim — Claim check on needs-fix decisions
Section titled “Step 3-claim — Claim check on needs-fix decisions”When an issue is classified needs-fix (decision = solve), run a claim check via the SSOT script BEFORE scheduling any cook work:
Run the claim check and act on its state (free / held / stale / skip): references/claim-check.md.
Constraint: never call gh issue edit, gh pr create, or any inline gh claim mutation here. All claim state changes go through t1k-issue-claim.cjs.
Step 3-dup — Duplicate-PR detection backstop
Section titled “Step 3-dup — Duplicate-PR detection backstop”When check returns a competingPRs array (≥2 draft PRs reference the same issue), recommend close-later for the higher PR number and surface it in the triage report. Shared procedure (also used by t1k-babysit-pr), full detail: skills/t1k-triage/references/competing-pr-backstop.md.
Step 3-Y — --yolo defer-rationale guard (MANDATORY when --yolo)
Section titled “Step 3-Y — --yolo defer-rationale guard (MANDATORY when --yolo)”When --yolo is set, before finalizing any decision=defer, you MUST audit the defer rationale against this forbidden-phrase list. If the rationale uses ANY of these phrases for an issue whose infoStatus is complete or partial, the classification is invalid and MUST be reclassified as decision=solve with plan→cook chain.
Forbidden defer rationales under --yolo (match by intent): any variant of “needs maintainer/human UX/design/policy decision”, “N candidate fixes” as the sole reason, or “route to /t1k:plan” posted as a comment instead of actually spawning the plan. Verbatim list: references/yolo-defer-guard.md.
If you find yourself writing any of the above for an item with documented options, STOP. The presence of documented options IS the context — there is no missing data. Reclassify and execute the plan→cook chain per references/yolo-decision-matrix.md § “Plan→Cook chain”. The Conservative-Pick algorithm selects among options without human input.
defer remains valid under --yolo ONLY for the allowlisted causes (infoStatus: insufficient, calendar gate, upstream prerequisite missing, external fork, out-of-scope repo; evidence per references/yolo-defer-guard.md).
Do not rubber-stamp prior triage defers. If a previous run deferred for a now-forbidden rationale, the current run MUST re-evaluate against this rule. The new triage’s decision supersedes the prior comment — the new rule is the SSOT. Cite the rule activation in the report.
Step 3.5 — Stale-base auto-rebase (--yolo only)
Section titled “Step 3.5 — Stale-base auto-rebase (--yolo only)”Trigger (--yolo, proactive): BEHIND (rebase even when CI is green) or DIRTY / CONFLICTING (attempt the rebase; a real conflict defers). Details: references/stale-base-rebase.md.
Preconditions, action and logging (all must hold: PR branch not checked out in a worktree, --yolo, base file exists on main; a conflicting rebase is aborted and deferred; a clean one is pushed with --force-with-lease and CI re-fetched after ~30s): references/stale-base-rebase.md.
Step 4 — Review PRs
Section titled “Step 4 — Review PRs”Spawn t1k-code-reviewer agent per PR. If fixable issues found, push review comments via gh pr review.
Skill file gate: If a PR modifies $HOME/.claude/skills/ files (SKILL.md, references/, scripts/), run /t1k:skill-creator validate <skill-name> before recommending merge. Skillmark conventions (frontmatter, progressive disclosure, effort tags, gotcha format, body tightness §K) MUST be verified.
Body-tightness check (auto, when SKILL.md is in diff): scan added lines for incident-marker patterns (dates, PR refs, Originating incident:, Verified failure, commit hashes, Real-world miss). If detected, mark merge-blocked: tightness-violation and recommend moving content to references/. Per skills/t1k-skill-creator/references/architecture-rules.md §K — body bloat ships to ~50 consumers × every session. CI gate validate-skill-body-tightness.cjs will surface gate output.
Step 4a — Sync-back PR regression detection (all modes)
Section titled “Step 4a — Sync-back PR regression detection (all modes)”Sync-back PRs that fail CI are prima facie evidence that t1k-sync-back produced output the kit’s quality gates reject. For each detected sync-back PR with red CI: emit [t1k:skill-bug ...] marker, add to “Sync-Back Regressions” section of report, mark merge-blocked: sync-back-regression-<check>.
Full identification rules, fetch commands, sanitization, and suppression conditions: references/sync-back-regression.md.
Steps 4b / 4c / 4d — --yolo merit pipeline
Section titled “Steps 4b / 4c / 4d — --yolo merit pipeline”When --yolo is set, run a 3-step pipeline that turns AI judgement into real GitHub state changes (instead of internal bypasses): 4b Risk Classification (low/medium/high) → 4c Auto-Fix On PR Head (origin markers, t1k-modules.json regen, markdownlint) → 4d Self-Approve via gh pr review --approve. After 4d, reviewDecision === APPROVED is genuinely true; the unmodified Step 5b strict gate passes.
Merit-pass requires ALL of: t1k-code-reviewer = approve, risk = low, PR author ≠ self, Step 4c auto-fix clean, Step 4d API call OK. Any failure → defer to human, none silent.
Full pipeline detail (risk thresholds, fixable categories, push protocol, body template, rollback semantics): references/yolo-merit-pipeline.md.
Step 5 — Report
Section titled “Step 5 — Report”Save to: plans/reports/triage-{YYMMDD}-{HHMM}-triage.md
Module-aware report format (# | Repo | Module | Type | Effort | S/M/L | Priority | Title): references/report-format.md.
Required report sections (in order):
- Triage summary — counts per decision
- 🎯 High-Impact Candidates (Step 1c-pre, optional)
- Items by decision — full classification table
- Sync-Back Regressions (Step 4a) — only if any sync-back PRs failed CI
- Actions taken (in-session merges, closes, cook PR URLs)
- Deferred items (with reasons)
- Contribution Score (Step 8) — appended at the very end
Step 5a.5 — Mark auto-merge after merit approval (--yolo + non-draft only)
Section titled “Step 5a.5 — Mark auto-merge after merit approval (--yolo + non-draft only)”Trigger — ALL of the following must hold:
- Triage classified the PR as
merge - Merit-pipeline approval succeeded (Step 4d
gh pr review --approvereturned OK) isDraft: false— calendar-gated or author-WIP PRs NEVER receive the auto-merge flag- Running in
--yolomode
Action — this REPLACES today’s Step 5b admin-bypass for routine non-draft cases:
gh pr merge {n} --repo {REPO} --auto --squash --delete-branchRun the stacked-PR guard (references/completion-verification.md § “Stacked-PR guard”) — plus the home-branch guard (§ “Home-branch guard”) — before this call. This sets GitHub’s native auto-merge flag. GitHub will squash-merge and delete the branch automatically once all REQUIRED checks pass. Non-required checks (e.g., Claude Code Review) do NOT block auto-merge.
Prerequisite: the repo MUST have allow_auto_merge: true; probe required checks via rulesets (gh api repos/{REPO}/rules/branches/main), never classic branch protection alone. Check any later-required check does not stall the flag. --admin (Step 5b) stays an emergency-only last resort. Symptoms, probe commands and rationale: references/auto-merge-marking.md.
Step 5b — Auto-merge gate
Section titled “Step 5b — Auto-merge gate”Before any merge action, every PR with decision: merge MUST pass the strict gate (isDraft=false, reviewDecision=APPROVED, all checks SUCCESS, mergeable=MERGEABLE, mergeStateStatus ∈ {CLEAN, BEHIND}, skill-file gate). Anything ambiguous defers to human; never relax the gate to chase throughput.
Admin escalation (yolo only): when the operating user holds admin role on the target repo AND Steps 4b–4d cannot land an approval (e.g., self-authored PR where GitHub forbids self-approve, or branch protection won’t accept bot APPROVE alone), gh pr merge --admin --squash --delete-branch is permitted as a final escalation IFF all other gates pass (checks green, mergeable, no requested changes). The merge MUST still satisfy the strict gate except for reviewDecision=APPROVED. Cite “admin-override (yolo)” in any output that records the merge. Step 5a.5 is preferred over this escalation for non-draft PRs where merit-pipeline approval succeeded. Never from a worktree’s home branch — that one merges without --delete-branch (skills/t1k-git/references/worktree-home-branch.md).
Full gate spec, --yolo flow into the gate, and Step 5c BEHIND-branch handling: references/auto-merge-gate.md.
Step 6 — Action phase
Section titled “Step 6 — Action phase”The classifier output is partitioned by decision. By default (no flag) triage runs the auto path for every partition; --ask switches to interactive prompts; --dry-run reports only.
Run partitions in parallel where possible. Key merge concurrency to repos, not to a flat PR list: one worker per repo merging that repo’s PRs sequentially, parallelized across repos — each repo’s main is independent, so cross-repo concurrency is safe and still bounded. Two concurrent merges into the same repo both write its main, so the second’s base-branch read is invalidated and aborts (Base branch was modified) — a retry condition, never merge-blocked. Mechanism and the --delete-branch/worktree guard: references/completion-verification.md § “Repo-keyed merge batching”.
Per-decision partition table (merge / solve / close / the three defer rows; auto path vs --ask): references/action-partition-table.md. Key rules: close = post the reason comment FIRST, then close; defer under --yolo caused by a policy/UX choice among documented fixes auto-escalates to solve.
| defer (--yolo, cause = infoStatus: insufficient / calendar gate / upstream prerequisite missing) | NO action — same as default-auto. These are data/time/external gates, not policy gates. Re-running cannot move them | Same as auto |
NEVER auto-merge defer items. They lack the information required to verify safety. NEVER cook defer or close items — except the explicit yolo policy-decision auto-escalation row above, which is a re-classification to solve BEFORE cook, not a cook-on-defer.
Cook prerequisite — ensure the owning repo is workable (--yolo)
Section titled “Cook prerequisite — ensure the owning repo is workable (--yolo)”Before cooking a solve item, resolve the owning kit repo’s local clone, verify it is clean and on main, cook per the standard flow (one PR per fix, Fixes #N); if the repo cannot be made workable report solve-blocked: repo-unavailable — never classify solve then merely comment fix-sketches. Steps: references/cook-prerequisite.md.
Closing anything — HARD rule: a close with no comment is forbidden. Every close (close decision, Step 6d sweep, any path) posts a reason comment first, or uses --comment. It MUST state the reason category (duplicate of #N / superseded by #N / fixed in #N or <sha> / won’t fix + why / stale / out of scope + where it belongs), the one-line why, and what the author can do to disagree (reopen, or comment). Guard + full template: references/close-requires-comment.md. Never close via bare gh issue close / gh pr close.
--ask mode “do all” shortcut: when user replies “do all” / “yes to everything” to the partition prompt, run that partition’s auto path immediately.
Step 6b / 6c / 6d — --yolo decision matrix, active merge and Issue Disposition Sweep
Section titled “Step 6b / 6c / 6d — --yolo decision matrix, active merge and Issue Disposition Sweep”Under --yolo each default-auto defer becomes a structured investigation (reviewer for merges, blocker resolution for tracking issues, plan→cook for large issues); a disposition sweep runs first when ≥3 issues would exceed 30 min. Wholesale deferral is never valid when the sweep can run. Decision matrix, polling, close criteria and taxonomy: references/yolo-decision-matrix.md and references/yolo-issue-disposition-sweep.md.
Step 7 — Definition of Done
Section titled “Step 7 — Definition of Done”After Step 6 dispatches all actions, triage runs a completion-verification loop. Triage MUST NOT report completion until every classified item is in a terminal state.
| Decision | Terminal state |
|---|---|
merge | PR MERGED in GitHub OR merge-blocked: <reason> recorded |
solve | Cook PR URL recorded OR solve-failed: <reason> recorded |
close | Issue/PR CLOSED in GitHub |
defer | Missing-fields comment posted (Step 2d) |
Polling: every 60s with a 30-minute total budget (configurable via T1K_TRIAGE_TIMEOUT_MIN) and 10-attempt per-item cap. Final report MUST include the terminal_marker for every item. --dry-run skips Step 7. --ask runs Step 7 only against items the user approved.
Full algorithm, verification commands, interaction rules: references/completion-verification.md.
Step 8 — Contribution Score Report (this run only)
Section titled “Step 8 — Contribution Score Report (this run only)”After Step 7, render the contribution-score table for this run’s items only (never the lifetime aggregate): references/contribution-score-report.md.
Step 9 — Branch cleanup (post-merge sweep)
Section titled “Step 9 — Branch cleanup (post-merge sweep)”When the run merged ≥1 PR, sweep local stale branches across the repos triage actually touched THIS run. Each repo: fetch --prune, checkout main, pull --ff-only, then git branch -D <branch> for each local branch whose remote PR is MERGED (or CLOSED + --yolo). Hard-skip on local divergence, worktree-checked-out branches, unmerged commits, sync-back artifacts from other sessions, and repos with no local clone (discovery is GitHub-only — no clone is created for this sweep). Never git reset --hard. Emit [t1k:triage-cleanup] summary. Skipped in --dry-run.
Full algorithm, safety contract, anti-patterns: references/usage-modes.md § Ecosystem post-merge branch cleanup.
Guardrails — Auto-Rebase and Auto-Merge
Section titled “Guardrails — Auto-Rebase and Auto-Merge”These invariants apply to Steps 3.5 and 5a.5. Any failure collapses to defer; nothing is silent.
Invariants (full table with reasons: references/guardrails.md): NEVER auto-rebase a branch checked out in a worktree; NEVER auto-rebase outside --yolo; NEVER auto-merge a DRAFT PR; NEVER use --auto on a PR that failed the merit pipeline; NEVER admin-bypass as a shortcut when Step 5a.5 applies; watch for newly-required checks after the flag is set.
Executed by
Section titled “Executed by”| Phase | Agent |
|---|---|
Mechanical close/claim (scripts/t1k-close-item.cjs, .claude/scripts/t1k-issue-claim.cjs) | t1k-git-manager |
| PR review (default + yolo) | t1k-code-reviewer |
| Skill validation | t1k-skills-manager |
| Implementation | /t1k:cook (registry-routed) |
| Yolo: large-issue planning | /t1k:plan (registry-routed) |
| Sync-back regression filing (Step 4a) | /t1k:issue (auto-spawned by lesson pipeline) |
Self-improving AI integration: references/self-improving-ai.md.