Skip to content

t1k:triage

FieldValue
Modulet1k-maintainer
Version4.10.58
Efforthigh
ToolsAgent, AskUserQuestion, Bash, Edit, Glob, Grep, Read, Skill, Task, WebFetch, Write

Keywords: backlog, classify, github, issues, prioritize, process, triage

/t1k:triage
[--dry-run|--ask|--yolo] [--advice|--no-advice]

Structured triage workflow across the whole T1K ecosystem at github.com/The1Studio, discovered live from GitHub.

Default behavior is AUTO. Bare /t1k:triage runs the action phase end-to-end without prompting per item.

InvocationBehavior
/t1k:triageAUTO (default) — report, act, verify per item
/t1k:triage --askInteractive — AskUserQuestion per partition
/t1k:triage --dry-runReport only, no action
/t1k:triage --yoloMaximum 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”.

  1. Query GitHub for the ecosystem repo list — never a local clone scan, never t1k-config-*.json: Run the gh repo list The1Studio discovery pipeline (command: references/scaling-handoff.md § “Repo discovery command”).
  2. Deduplicate
  3. Fetch issues/PRs from ALL repos in parallel
  4. Label each item with source repo

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 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.

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.

[Fetch] → [Classify] → [Analyze] → [Review PRs] → [Report] → [Cook] → [Verify]

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.

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).

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.

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.

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):

  1. Triage summary — counts per decision
  2. 🎯 High-Impact Candidates (Step 1c-pre, optional)
  3. Items by decision — full classification table
  4. Sync-Back Regressions (Step 4a) — only if any sync-back PRs failed CI
  5. Actions taken (in-session merges, closes, cook PR URLs)
  6. Deferred items (with reasons)
  7. 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 --approve returned OK)
  • isDraft: false — calendar-gated or author-WIP PRs NEVER receive the auto-merge flag
  • Running in --yolo mode

Action — this REPLACES today’s Step 5b admin-bypass for routine non-draft cases:

Terminal window
gh pr merge {n} --repo {REPO} --auto --squash --delete-branch

Run 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.

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.

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.

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.

DecisionTerminal state
mergePR MERGED in GitHub OR merge-blocked: <reason> recorded
solveCook PR URL recorded OR solve-failed: <reason> recorded
closeIssue/PR CLOSED in GitHub
deferMissing-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.

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.

PhaseAgent
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 validationt1k-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.