t1k:fix
| Field | Value |
|---|---|
| Module | t1k-base |
| Version | 5.15.36 |
| Effort | medium |
| Tools | Agent, AskUserQuestion, Bash, Edit, Glob, Grep, MultiEdit, Read, Skill, Task, TodoWrite, Write |
Keywords: bug, error, fix, patch, repair, resolve, test-failure
How to invoke
Section titled “How to invoke”/t1k:fix[issue] [--auto|--review|--quick|--parallel] [--advice|--no-advice]TheOneKit Fix — Bug Fixing
Section titled “TheOneKit Fix — Bug Fixing”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 perrules/kit-wide-fix-discipline.md. Local-only patches regress for every other consumer on nextt1k 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):
- Verify
AskUserQuestionis in the loaded tool list. If not, run:ToolSearch(query="select:AskUserQuestion", max_results=1) - 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.
Decision tree — which path do I take?
Section titled “Decision tree — which path do I take?”Pick by intent; keep loading minimal.
| Intent | Path |
|---|---|
| Diagnose and fix one bug end-to-end | Default --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 failed | STOP — escalate to architecture discussion (HARD-GATE below) |
Arguments
Section titled “Arguments”| Flag | Description |
|---|---|
--auto | Autonomous mode (default). High-risk fixes stop for human approval before finalize/commit/ship (per artifact-gate). |
--review | Human-in-the-loop review mode |
--quick | Quick mode for trivial issues |
--parallel | Route to parallel implementer agents per issue |
--advice | Run under t1k-kongming advisory supervision (composes with every mode above) |
Advisory supervision (ON by default)
Section titled “Advisory supervision (ON by default)”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.
Anti-rationalization discipline: see rules/agent-anti-rationalization.md .
Process Flow (Authoritative)
Section titled “Process Flow (Authoritative)”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.
Agent Routing
Section titled “Agent Routing”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.
Skill Activation
Section titled “Skill Activation”Follow protocol: skills/t1k-cook/references/activation-protocol.md
Plane Work-Item Gate (MANDATORY)
Section titled “Plane Work-Item Gate (MANDATORY)”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.
Workflow Steps
Section titled “Workflow Steps”| Step | Name | Key Action | Reference |
|---|---|---|---|
| 0 | Mode Selection | Ask user for workflow mode if no --auto | references/mode-selection.md |
| 1 | Scout | Map per HARD-GATE-SCOUT-FIRST; emit 3-6 bullet summary | references/workflow-quick.md |
| 2 | Diagnose | Answer 6 slots per HARD-GATE-EXACT-ROOT-CAUSE | references/diagnosis-protocol.md |
| 3 | Complexity | Classify: Simple/Moderate/Complex/Parallel | references/complexity-assessment.md |
| 4 | Fix | Implement per selected workflow; minimal changes only | references/workflow-standard.md |
| 5 | Verify + Prevent | Run 5 proofs per HARD-GATE-NO-SIDE-EFFECTS + artifact gate | references/prevention-gate.md |
| 6 | Finalize | Report, t1k-docs-manager, commit offer | — |
Detailed workflow diagrams: references/fix-workflow-overview.md
Step 5 — Artifact Gate (harness)
Section titled “Step 5 — Artifact Gate (harness)”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.
Complexity Routing
Section titled “Complexity Routing”| Level | Indicators | Workflow (implementer) |
|---|---|---|
| Simple | Single file, clear error, type/lint | references/workflow-quick.md (implementer role) |
| Moderate | Multi-file, root cause unclear | references/workflow-standard.md (implementer role) |
| Complex | System-wide, architecture impact | references/workflow-deep.md (t1k-hard-coder, direct spawn) |
| Parallel | 2+ independent issues OR --parallel | Parallel 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
Always-Activate Skills
Section titled “Always-Activate Skills”/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 modulet1k-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.
Subagent Skill Injection
Section titled “Subagent Skill Injection”Follow protocol: skills/t1k-cook/references/subagent-injection-protocol.md
Sub-Agent Fork Hygiene
Section titled “Sub-Agent Fork Hygiene”Sub-agent forking: see skills/t1k-architecture/references/fork-hygiene.md.