From ttal
Diagnoses bugs systematically by confirming understanding, investigating root causes via reproduction and evidence gathering, then writes clear fix plans for execution without coding.
npx claudepluginhub tta-lab/ttal-cli --plugin ttalThis skill uses the workspace's default tool permissions.
Diagnose bugs by tracing from symptom to root cause, then write a fix plan clear enough for a worker to execute without guessing. No fixes without diagnosis. No diagnosis without evidence.
Fixes bugs via root cause diagnosis with debugger/gap-analyzer, requirements.md generation, /execute delegation, 3-retry circuit breaker, and QA.
Guides evidence-first debugging: clarify behavior diffs, reproduce issues with env details, test hypotheses, plan verified fixes before code changes.
Systematically debugs by tracing root causes with predictions before test-first fixes. Use for errors, test failures, GitHub/Linear/Jira issues, stack traces.
Share bugs, ideas, or general feedback.
Diagnose bugs by tracing from symptom to root cause, then write a fix plan clear enough for a worker to execute without guessing. No fixes without diagnosis. No diagnosis without evidence.
Core principle: ALWAYS find root cause before writing the fix plan. Symptom fixes are failure.
Announce at start: "I'm using the debugging skill to diagnose this bug and write a fix plan."
Before investigating, confirm you've understood the bug description correctly.
⛔ STOP here. End your message after presenting your understanding and question. Do not begin Phase 1 until the human responds and confirms alignment.
BEFORE writing ANY fix plan:
Read Error Messages Carefully
Reproduce Consistently
Check Recent Changes
Gather Evidence in Multi-Component Systems
WHEN system has multiple components (CI → build → signing, API → service → database):
For EACH component boundary:
- Log what data enters component
- Log what data exits component
- Verify environment/config propagation
- Check state at each layer
Run once to gather evidence showing WHERE it breaks
THEN analyze evidence to identify failing component
THEN investigate that specific component
Trace Data Flow
See root-cause-tracing.md in this directory for the complete backward tracing technique.
Quick version:
After completing the investigation (Phases 1–3), discuss your findings before writing the fix plan.
⛔ STOP here. End your message after presenting your diagnosis and question. Do not begin Phase 4 until the human responds and confirms alignment.
Once root cause is confirmed, write the fix plan.
# Fix: [Bug Title]
> **For Claude:** Workers implement this plan using the coder agent identity.
## Symptom
[What the user/system sees — error messages, unexpected behavior]
## Root Cause
[What's actually broken and why — the diagnosis, not the symptom]
## Reproduction
[Exact steps to trigger the bug]
## Fix Strategy
[What needs to change and why this approach over alternatives]
## Implementation Tasks
### Task 1: [Component Name]
**Files:**
- Modify: `exact/path/to/file.go`
- Test: `tests/exact/path/to/test.go`
**Step 1: Write the failing test**
[exact test code]
**Step 2: Run test to verify it fails**
Run: `go test ./path/... -run TestName -v`
Expected: FAIL
**Step 3: Write minimal fix**
[exact code change — before/after]
**Step 4: Run test to verify it passes**
Run: `go test ./path/... -run TestName -v`
Expected: PASS
**Step 5: Commit**
`fix(scope): description`
## Verification
[How the worker confirms the bug is actually fixed — beyond just tests passing]
Every task in the plan MUST have:
If a task fails this checklist, it's not ready.
Each step is one action (2-5 minutes):
Small fixes (≤6 steps, single file or mechanical changes): Use inline plans — annotate the task directly. No flicknote needed.
task <uuid> annotate 'Fix (inline): Root cause: nil pointer in auth middleware. Fix: 1. Add nil check in middleware.go:42 2. Add test 3. Run tests'
Large fixes (multi-file, needs diagnosis context, trade-off analysis): Use flicknote — save full fix plan, annotate task with hex ID.
flicknote add 'full fix plan content' --project fixes
task <uuid> annotate 'Fix plan: flicknote <hex-id>'
Decision rule: If the plan fits in 1-2 task annotations and a worker can execute it without ambiguity, inline it. If it needs headings, code examples, trade-off analysis, or context sections — use flicknote.
Save the plan first (inline annotation or flicknote — see "Inline vs Flicknote Fix Plans" above), create the task if it doesn't already exist, and annotate it with the plan reference.
Then chain into the completion phase — it handles self-review, open questions, summary, and review handoff with proper output-channel partitioning:
skill get sp-complete-design
The completion steps are the same for a fix plan as for a design plan: re-review as a worker, surface open questions, update state, summarize to Neil, request review. Do not duplicate the logic here.
If you catch yourself thinking:
ALL of these mean: STOP. Go back to diagnosis.
Available in this directory:
root-cause-tracing.md — trace bugs backward through call stack to find original triggerdefense-in-depth.md — add validation at multiple layers after finding root causecondition-based-waiting.md — replace arbitrary timeouts with condition polling