tk-diagnosing-bugs

Bug diagnosis

Use it when there are symptoms but the cause is unknown, or for intermittent or environment-specific failures, performance regressions, repeated recurrences, or cases requiring reproduction, minimization, and hypothesis verification. Do not use it for changes whose cause and fix are already confirmed, such as inverted conditionals, missing props, or clearly missing branches.

Workflow

1. feedback loop: The input is the user's symptoms, environment, and permissions, and the output is a red-capable artifact that can be rerun.
2. reproduce: The input is the loop artifact, and the output is the actual execution result and the red | not reproduced verdict.
3. minimize: The input is the reproduction result, and the output is the minimal input, environment, and execution command that preserve the symptoms.
4. ranked hypotheses: The input is the observational evidence from the minimal reproduction, and the output is 3–5 hypotheses and a falsifiable prediction for each.
5. instrument: The input is the prioritized hypothesis and the minimal reproduction, and the output is observational evidence that can distinguish one variable at a time.
6. fix: The input is the falsification result and the confirmed cause, and the output is the minimal-scope fix or a finding of no seam.
7. regression verification: The input is the fix and the original reproduction, and the output is the original symptoms and the regression seam's green | failed result.
8. cleanup/receipt: The input is the verification result and the list of temporary artifacts, and the output is a receipt linking the cleanup result, status, unverified items, and references to the preceding root cause, fix, and regression outputs. Do not copy the preceding body text.

If the required input, environment, or permissions are missing and you cannot proceed to the next step, Blocked, if you executed it but could not obtain reproduction or regression evidence, Unverifiable, if it is confirmed that the root cause or fix failed, Fail. Do not report any status as resolved.

Default loop:

feedback loop
→ reproduce
→ minimize
→ ranked hypotheses
→ instrument
→ fix
→ regression verification
→ cleanup

Feedback loop gate

Before forming hypotheses, create a red-capable feedback loop that captures the user's symptoms. You can use a failing test, curl/HTTP script, CLI fixture, browser script, trace replay, throwaway harness, repeated reproduction loop, differential comparison, or deterministic performance measurement.

The feedback loop must satisfy all of the following.

1. It captures the user's actual symptoms.
2. The agent can run it again.
3. Run it for real at least once.
4. A red/green verdict is possible.
5. It is as fast and repeatable as possible.

If you cannot reproduce it, report the methods attempted, the missing environment or artifacts, and the required logs/HAR/fixture/trace/permissions. Do not patch based on guesswork or present hypotheses as confirmed facts.

🔴 CHECKPOINT · 🛑 STOP hypothesis/patch boundary

Do not confirm a hypothesis or patch before verifying the five conditions of the feedback loop through actual execution. If the conditions are not met, stop with the necessary evidence as Blocked or Unverifiable.

Hypotheses and fixes

Establish 3–5 priority hypotheses and attach a falsifiable prediction to each hypothesis. Change only one variable at a time and eliminate hypotheses based on observation results. Separate symptoms from root causes and fix the common cause.

If a correct regression seam exists, turn the minimal reproduction into a failing regression test, observe red, then verify in the order of fix, green, rerun the original reproduction.

If there is no correct seam, do not create a shallow false-confidence test. Record as findings the absence of a public boundary that reproduces the actual bug pattern, the fact that the current structure hinders regression locking, and the fact that structural improvement is a separate follow-up task after the bug fix. Do not start an architecture refactor first during diagnosis.

Clean up temporary instrumentation and throwaway debug artifacts. For detailed procedures, see investigation loop.

Clean verification gate

A green obtained while instrumentation remains is not final evidence. Record the command, input, fixture, seed/iteration count, and environment needed for judgment of the original reproduction that produced red, remove temporary artifacts, and confirm that no instrumentation remains in the work diff. Then rerun the original reproduction and regression seam under the same premises, and use only this clean-state result as the basis for completion and commit.

If the reproduction premises or target source changed before or after cleanup, or if failure or intermittency returns after cleanup, discard the previous green. If you cannot recreate a loop comparable to the original red, Unverifiable, and if clean-state verification fails, Failand do not commit.

Commit boundary

If the user explicitly invoked tk-diagnosing-bugsas a standalone call and actual code was modified, commit to the current branch when all of the following conditions are met.

• Root cause fix complete
• Original reproduction green
• Regression verification successful
• Clean-state verification successful after removing temporary instrumentation
• Work diff can be separated from existing user changes

If tk-implement work is still in progress, do not make a separate commit; return the diagnosis results and fixes to the current implementation. tk-implementhandles final verification and commit.

Merely applying diagnostic discipline automatically in ordinary conversation does not grant standalone commit authority. Follow the commit contract of the existing work, and obtain an explicit request if an independent commit is needed.

Do not push, PR, merge, tag, release, or publish without a separate request.

Completion report

Report the original symptom, root cause, fix, regression evidence, whether a seam is absent, cleanup, and the reason for commit or non-commit, each only once. In the Receipt, record only the status (Pass | Fail | Blocked | Unverifiable), unverified items, and references to the corresponding report items, and do not repeat the root cause, fix, or evidence body.

DO NOT / ANTI-PATTERNS

• Do not make speculative patches before reproduction, confirm causes without falsification, or create false-confidence tests.
• Do not leave temporary instrumentation or throwaway debug artifacts.
• tk-implement Do not commit or push separately within the task.