Skip to content

t1k:fix

FieldValue
Modulet1k-base
Version5.15.36
Effortmedium
ToolsAgent, AskUserQuestion, Bash, Edit, Glob, Grep, MultiEdit, Read, Skill, Task, TodoWrite, Write

Keywords: bug, error, fix, patch, repair, resolve, test-failure

/t1k:fix
[issue] [--auto|--review|--quick|--parallel] [--advice|--no-advice]

Fix issues with intelligent classification and registry-based routing. Investigate before patching; harness over hope.

Kit-wide discipline: every fix to kit-owned content (anything under .claude/) lands in the owning kit source repo per rules/kit-wide-fix-discipline.md. Local-only patches regress for every other consumer on next t1k modules update.

Pre-flight Step 0 — Fuzzy plan/path arg resolution (MANDATORY)

Section titled “Pre-flight Step 0 — Fuzzy plan/path arg resolution (MANDATORY)”

If the user provides a fuzzy plan/path/phase arg (e.g. chaosforge-demo, plans/chaosforge-demo, phase-3), an empty arg, or natural-language ref like “active plan” / “current plan” / “this plan”, run the Fuzzy Plan / Path Resolution Protocol at skills/t1k-cook/references/fuzzy-plan-resolution.md BEFORE bail. Skill MUST NOT emit “no path matching” / “exact path required” until that protocol has been applied and Step 6 reached.

Tool guard — AskUserQuestion is deferred

Section titled “Tool guard — AskUserQuestion is deferred”

AskUserQuestion is a deferred tool: its name appears in the deferred-tools system-reminder but its schema is NOT loaded at session start. Direct invocation fails with InputValidationError.

Operational pre-step (mandatory before drafting any structured multi-option question):

  1. Verify AskUserQuestion is in the loaded tool list. If not, run:
    ToolSearch(query="select:AskUserQuestion", max_results=1)
  2. THEN draft and invoke the tool with batched options.

Failure mode this guard prevents: assistant remembers the rule, drafts the question correctly in its head, then because the tool isn’t loaded, falls back to “I’ll just write the options as prose, and call the tool next time.” Drafting prose bullets first is a violation — see rules/always-ask-on-unresolved.md “Forbidden prose” table.

Step 0.5 — Issue Claim Gate (fires ONLY when a target GitHub issue is supplied)

Section titled “Step 0.5 — Issue Claim Gate (fires ONLY when a target GitHub issue is supplied)”

Before Scout/Diagnose, claim the issue via the SSOT script — never gh issue edit/gh pr create for claiming yourself: bun .claude/scripts/t1k-issue-claim.cjs check <owner/repo#N>. On state:"held" → HARD BLOCK (surface holder+PR; --steal to override). On "free"/--steal → acquire + open the WIP draft PR (the draft IS the claim), then re-run acquire … --pr <N> for the deterministic tie-break. release marks it ready when the fix lands. Full state table + tie-break + finalize: references/issue-claim-gate.md. Enforcement: skills/t1k-git/references/issue-claim-discipline.md.

Pick by intent; keep loading minimal.

IntentPath
Diagnose and fix one bug end-to-endDefault --auto (Steps 1–6 below)
Trivial issue (lint, single type error)--quick (skips deep diagnose)
Want human checkpoint before applying fix--review
Multiple unrelated bugs at once--parallel (sub-agents per issue)
3+ fix attempts already failedSTOP — escalate to architecture discussion (HARD-GATE below)
FlagDescription
--autoAutonomous mode (default). High-risk fixes stop for human approval before finalize/commit/ship (per artifact-gate).
--reviewHuman-in-the-loop review mode
--quickQuick mode for trivial issues
--parallelRoute to parallel implementer agents per issue
--adviceRun under t1k-kongming advisory supervision (composes with every mode above)

Supervision runs at advisorySupervision.level (default forks) without being asked for. forks fires the stall trigger — the 3+-failed-attempt gate in skills/t1k-cook/references/workflow-gates.md § 4. --advice raises this run to full; --no-advice turns it off and forward-carries the opt-out. Contract: skills/t1k-cook/references/advisory-supervision.md.

Fix checkpoints (after diagnosis, on the 3+-failed-attempt gate, on an artifact-gate high-risk flag), the --advice forward-carry and the full contract (skills/t1k-cook/references/advisory-supervision.md): references/advisory-supervision.md. Counsel never lowers the risk gate, the issue-claim gate, or the human-approval stop on a high-risk fix.

Auto mode contract: --auto is NOT “AI does whatever it wants.” --auto runs when there is enough evidence (5 artifacts validated by the artifact-gate hook) AND risk is in the allowed zone (risk-gate.json highRisk: false). High-risk changes always stop for human approval, even in auto mode. Full rules: skills/t1k-cook/references/artifact-gate-rules.md.

HARD-GATE contract: see skills/t1k-cook/references/workflow-gates.md.

Full enforceable detail for all four gates: references/hard-gates.md. Markers below are the machine-readable contract; the one-line summaries are authoritative-by-reference.

No fixes before Steps 1–2 (Scout + Diagnose). Symptom fixes = failure; find the cause, never guess. 3+ failed attempts → STOP, question the architecture with the user. Override: `--quick` (trivial lint/type). Detail: `references/hard-gates.md` § HARD-GATE. Scan the codebase BEFORE questions/hypotheses; emit the 5 mandatory scout outputs (project type, symptom file+callers, covering tests, recent commits, existing patterns) + a 3–6 bullet context summary. Kills the "imagined context" failure. Detail: `references/hard-gates.md` § Scout-First. No fix until all 6 slots are answered in one concrete sentence each: symptom (verbatim), repro, expected-vs-actual, root-cause (`file:line`), why-now, blast-radius. Any vague slot → `AskUserQuestion` or more scout, never guess. Detail: `references/hard-gates.md` § Root-Cause. Not done until Step 5 proves all 5: repro gone, affected tests pass, no blast-radius regression, no new lint/type/build errors, public contracts unchanged (or intentional + noted). Side effect found → STOP, `AskUserQuestion` with concrete options. Detail: `references/hard-gates.md` § No-Side-Effects.

Anti-rationalization discipline: see rules/agent-anti-rationalization.md .

flowchart TD
    A[Issue Input] --> B[Step 0: Mode Selection]
    B --> C[Step 1: Scout — HARD-GATE-SCOUT-FIRST]
    C --> D[Step 2: Diagnose — HARD-GATE-EXACT-ROOT-CAUSE]
    D --> E[Step 3: Complexity Assessment]
    E -->|Simple| F[Quick Workflow]
    E -->|Moderate| G[Standard Workflow]
    E -->|Complex| H[Deep Workflow]
    E -->|Parallel| I[Multi-Agent Fix]
    F --> J[Step 4: Fix Implementation]
    G --> J
    H --> J
    I --> J
    J --> K[Step 5: Verify + Prevent — HARD-GATE-NO-SIDE-EFFECTS + artifact gate]
    K -->|All 5 proofs PASS + artifact gate green| L[Step 6: Finalize]
    K -->|Fail, <3 attempts| D
    K -->|Fail, 3+ attempts| M[Question Architecture → User]
    L --> N[Report + Docs + Commit via subagents]

This diagram is authoritative. If prose in this skill or its references conflicts with this flow, follow the diagram.

Evidence Step (MANDATORY, before Step 2 spawns the debugger role)

Section titled “Evidence Step (MANDATORY, before Step 2 spawns the debugger role)”

Step 2 (Diagnose) runs the mandatory Evidence step before it ever spawns the resolved debugger role: ../t1k-debug/references/evidence-step.md. It spawns t1k-investigator (haiku, routable) with the symptom, the failing command, and the Step 1 Scout paths; only once that report exists does the debugger role spawn, with the evidence path in its brief. Skip the step when the incoming request already carries an evidence report path.

Decision line. The orchestrating model decides whether the evidence spawn earns its keep for THIS bug and leaves the one-line evidence decision. A model of tier below opus (sonnet, haiku) or an unknown model runs the step. --quick, the 3-failure escalation and the HARD-GATE-EXACT-ROOT-CAUSE six slots are untouched. The line format and tier rule live in ../t1k-debug/references/evidence-step.md § “Decision line”; the decide-and-state contract in docs/gate-decision-contract.md.

Follow protocol: skills/t1k-cook/references/routing-protocol.md This command uses roles: implementer, debugger — resolve the ROLE, never the literal agent name t1k-debugger (see the Evidence Step section above and ../t1k-debug/references/evidence-step.md § “Kit debuggers get this for free”).

Hard tail — direct spawn, not role resolution. Step 4 spawns t1k-hard-coder (native, diagnoses AND fixes, proves RED-then-GREEN) instead of implementer for Complex/deep-workflow fixes, a fix that already failed once, or a multi-file/cross-service/edge-case-dominated bug — see references/complexity-assessment.md § Complex and references/error-recovery.md § Stuck Detection. t1k-debugger stays diagnosis-only in every mode — it never edits.

Follow protocol: skills/t1k-cook/references/activation-protocol.md

Fires BEFORE the first fix edit. Full contract — do not restate or reimplement it here: skills/t1k-plane/references/workflow-enforcement.md (../t1k-plane/references/workflow-enforcement.md) § Stage 0 + Stage 2. Governing rule: modules/t1k-plane/rules/plane-workitem-workflow.md.

Auto-match the bug against existing Plane work items in the repo-bound project; no confident match → AskUserQuestion offering match existing alongside create new (never auto-create), then advance to In Progress (started state group — resolve by group, never by name).

Independent of the GitHub Issue Claim Gate above — both run when both apply. Plane enforcement now blocks, not warns, on an unbound repo or absent plane server — see the cited Stage 0 contract. Escapes: T1K_PLANE_MODE=advisory|off, --no-plane, recorded optout.

StepNameKey ActionReference
0Mode SelectionAsk user for workflow mode if no --autoreferences/mode-selection.md
1ScoutMap per HARD-GATE-SCOUT-FIRST; emit 3-6 bullet summaryreferences/workflow-quick.md
2DiagnoseAnswer 6 slots per HARD-GATE-EXACT-ROOT-CAUSEreferences/diagnosis-protocol.md
3ComplexityClassify: Simple/Moderate/Complex/Parallelreferences/complexity-assessment.md
4FixImplement per selected workflow; minimal changes onlyreferences/workflow-standard.md
5Verify + PreventRun 5 proofs per HARD-GATE-NO-SIDE-EFFECTS + artifact gatereferences/prevention-gate.md
6FinalizeReport, t1k-docs-manager, commit offer—

Detailed workflow diagrams: references/fix-workflow-overview.md

After verifying the fix, write the 5 required artifacts and validate via the workflow-artifact-gate hook. Full rules, schemas, kill switch, and engine-kit extension contract: skills/t1k-cook/references/artifact-gate-rules.md. SSOT shared with t1k:cook.

LevelIndicatorsWorkflow (implementer)
SimpleSingle file, clear error, type/lintreferences/workflow-quick.md (implementer role)
ModerateMulti-file, root cause unclearreferences/workflow-standard.md (implementer role)
ComplexSystem-wide, architecture impactreferences/workflow-deep.md (t1k-hard-coder, direct spawn)
Parallel2+ independent issues OR --parallelParallel implementer agents

Kit-owned files (.claude/) → kit-developer, any tier. Specialized: references/workflow-ci.md, references/workflow-logs.md, references/workflow-test.md, references/workflow-types.md, references/workflow-ui.md

  • /t1k:scout (Step 1) — understand before diagnosing
  • /t1k:debug (Step 2) — systematic root cause investigation
  • /t1k:think (Step 2) — structured hypothesis formation
  • /t1k:problem-solve (Step 2, conditional) — auto-activate when 2+ hypotheses fail (optional module t1k-reasoning; absent: skip this step)
  • When you find that the skill content led you astray, emit a [t1k:skill-bug kit="..." skill="..." bug="..." evidence="..."] marker in your final message. The lesson-collector hook will queue a GitHub issue on the owning kit repo.

Full activation matrix: references/skill-activation-matrix.md

Subagent Delegation — when Verify/Finalize run, they delegate

Section titled “Subagent Delegation — when Verify/Finalize run, they delegate”

Whether the tester step in Step 5 runs is the model’s call — decide from the diff in front of you (see skills/t1k-cook/references/workflow-steps.md § “Step Decision Format”; t1k-cook and t1k-fix share the same decision contract). Test when the fix changes behavior or has no regression test covering it yet. The reviewer is NOT a model decision: it runs only when the user asked for a review in this conversation (--review counts as asking; docs/no-unrequested-review.md). Otherwise leave Step 5 (Review): skipped (no review requested). Leave a decision line for Testing too: ran (<reason>) / skipped (<reason>).

When a step DOES run, it runs via the Task tool, never inline — the value of multi-agent is the cognitive separation of powers (the implementer is not the reviewer; the diagnoser is not the patcher). Same context = same blind spots.

Which subagent runs each phase (hard-coder, reviewer, tester, docs, git): references/subagent-delegation.md.

Follow protocol: skills/t1k-cook/references/subagent-injection-protocol.md

Sub-agent forking: see skills/t1k-architecture/references/fork-hygiene.md.