---
name: sp-debugging-4edede9945de
description: Use when a bug needs root-cause diagnosis and a written fix plan before implementation.
---

# Bug Diagnosis and Fix Planning

Diagnose from evidence, then persist the diagnosis and fix plan in FlickNote. Do not implement the fix.

## 1. Confirm the Symptom

Restate the observed behavior, expected behavior, affected surface, and known reproduction. Ask one focused question if the report is ambiguous.

## 2. Find the Root Cause

1. Reproduce the failure.
2. Read the complete errors and logs.
3. Check recent changes and working examples.
4. Trace bad state backward across component boundaries.
5. Form one hypothesis and test it with the smallest useful probe.

If three hypotheses fail, stop and question the model or architecture instead of stacking guesses.

Useful references in this directory:

- `root-cause-tracing.md`
- `defense-in-depth.md`
- `condition-based-waiting.md`

## 3. Confirm the Diagnosis

Tell the user:

- Root cause and supporting evidence
- Proposed fix boundary
- Main risk or trade-off

Get alignment before writing a detailed plan when the fix direction is not already approved.

## 4. Write the FlickNote

Save one note in `orientation`:

flicknote add --project orientation

Structure:

# Fix: <title>
## Symptom
## Root cause
## Evidence and reproduction
## Fix strategy
## Anti-goals
## Implementation stages
## Test strategy
## Exit criteria
## Risks

For behavior fixes, include TDD explicitly:

1. Add a focused regression test.
2. Run it and confirm it fails for the diagnosed reason.
3. Implement the minimum fix.
4. Run focused and broader tests.
5. Refactor while green.

Each stage must name exact files, commands, expected results, and dependencies.

## 5. Worker-Eye Check

Re-read the note as the implementer. Fix missing paths, hidden assumptions, unclear ordering, and unresolved decisions with FlickNote edits.

Return the FlickNote ID and a short diagnosis summary. Stop; do not start implementation or invoke another skill.


---
Source attribution: tta-lab
Original project: https://github.com/tta-lab/ttal-cli/blob/3576d21f223ff97eb258b868553b6266ad393847/skills/sp-debugging/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Mega AI Hub.

## Upstream license notice

MIT License

Copyright (c) 2026 GuionAI

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Mega AI Hub resource metadata

Creator / publisher: tta-lab
Original project: https://github.com/tta-lab/ttal-cli/blob/3576d21f223ff97eb258b868553b6266ad393847/skills/sp-debugging/SKILL.md
Attribution basis: Source repository record

Fields of work: Content & Media, Development & Engineering
Roles: Backend Developer, DevOps / SRE, QA / Test Engineer, Technical Writer
Specialties: Testing
Tools: Tool not specified
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: ddffe9bf251d0955c4de8b50b141ecff49d525c5ccdb29dd469e759e24af0bdf