SuperAPI AI Directory

debug

Coding & development

View repository

Updated 11-06 06:28

About this skill

Debug

Deterministic 7-phase debugging workflow. Walk the phases in order. If a phase's gate cannot be satisfied, go back rather than skipping ahead.

Phase 1 — Symptom Capture

Collect the symptom completely before touching any code.

Record:

  • Error message (exact text, not paraphrase)
  • Stack trace or log excerpt
  • Affected route / component / module
  • Environment: local | CI | production
  • First-seen commit or deployment (if known)

Gate: One-paragraph incident description in working notes before Phase 2.

Phase 2 — Git Archaeology

Find the most likely causal change.

git log --oneline -20
git diff HEAD~5..HEAD -- <suspected-path>
git log --oneline --all -- <suspected-path>

Gate: Most likely causal commit named, or ambiguity noted.

Phase 3 — Reproduce With a Targeted Test

Do not skip to Phase 4 without a reproducible failure.

Choose the smallest command that reproduces the symptom. If no existing test covers it, write a minimal failing test first — this is the TDD Red step and it is non-negotiable.

# Targeted test
<test-runner> <specific-test-file>

# Broader search
<test-runner>

Gate: Exact test name and failure message recorded. If no red test can be produced, return to Phase 1.

Phase 4 — Log Inspection

Now that the symptom is pinned, read the logs.

# Local
<dev-server-command> 2>&1 | tee /tmp/debug.log

# Production
<log-command> --tail 100

Look for: missing env vars, API error codes, unhandled rejections, database errors, timing drift.

Gate: Relevant log excerpts captured.

Phase 5 — Hypothesis + Minimal Verification

State a single falsifiable hypothesis before changing anything:

"I believe the bug is caused by X because Y. I will verify by Z."

Write a minimal test or probe that confirms or disproves. Do not fix anything in this phase.

If disproved, return to Phase 2 with new evidence.

Gate: Hypothesis survived verification.

Phase 6 — Fix + Green Confirmation

Apply the smallest code change that turns the Phase 3 test green. Nothing more.

Then run full checks:

<typecheck-command>
<test-command>

Baseline comparison table (required):

Metric Before After
Tests passing ??? ???
Tests failing ??? ???
New tests added 0 ???

Gate: Failure count must not increase versus baseline.

Phase 7 — Regression Test + Commit

  1. Confirm the Phase 3 reproduction test is green and committed
  2. Write the commit message:
fix(<area>): <short description>

Root cause: <why>
Symptom: <what the user saw>
Fix: <what changed>
Regression: tests/<path>

Closes #<issue-number>
  1. Push to a branch and open a PR. Never push directly to main.

Phase-Gate Checklist

  • Phase 1: symptom captured with exact error text
  • Phase 2: most likely causal commit named
  • Phase 3: red test exists and was observed failing
  • Phase 4: relevant log excerpts captured
  • Phase 5: hypothesis stated before any fix
  • Phase 6: before/after baseline table filled; failure count did not increase
  • Phase 7: regression test committed; PR opened on a branch