Skip to content
Skills Library
Programming · Analysis

tmn-debug

/tmn-debug

(tmn) Find the root cause of a bug or incident before changing code - reproduce it, narrow it with evidence, explain the mechanism, then fix it with a test that fails first. Use when something is broken, a test is failing, prod behaves differently from local, an error or stack trace appears, a deploy went wrong, or the user says "why is this happening", "it's flaky" or "this used to work".

Repository
tmn-fdekit ↗
Licence
MIT
Last repository change
09.11.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 09.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

(tmn) Find the root cause of a bug or incident before changing code - reproduce it, narrow it with evidence, explain the mechanism, then fix it with a test that fails first. Use when something is broken, a test is failing, prod behaves differently from local, an error or stack trace appears, a deploy went wrong, or the user says "why is this happening", "it's flaky" or "this used to work".

Triggers from the description

why is this happenings flakythis used to work
Original author description

(tmn) Find the root cause of a bug or incident before changing code - reproduce it, narrow it with evidence, explain the mechanism, then fix it with a test that fails first. Use when something is broken, a test is failing, prod behaves differently from local, an error or stack trace appears, a deploy went wrong, or the user says "why is this happening", "it's flaky" or "this used to work".

How it works

  1. 1. Reproduce first
  2. 2. Narrow it
  3. 3. Explain the mechanism
  4. 4. Fix the cause
  5. 5. Write it down
  6. During an incident
Original SKILL.md headings · 72 lines, 591 words
SKILL.md preview
---
name: tmn-debug
description: (tmn) Find the root cause of a bug or incident before changing code - reproduce it, narrow it with evidence, explain the mechanism, then fix it with a test that fails first. Use when something is broken, a test is failing, prod behaves differently from local, an error or stack trace appears, a deploy went wrong, or the user says "why is this happening", "it's flaky" or "this used to work".
---

# Debug

The expensive bug fix is the one that makes the symptom go away without
explaining it. It comes back, usually somewhere worse. Debugging is done when
you can say "X happens because Y, and here is the run that shows it", and
there is a test that fails without the fix.

> Checkpoints follow the run mode in `tmn-staff-bar`: standard stops and asks before each push, post, message or hand-off to the next skill; yolo runs through. The hard lines hold in both. Team rules from `config.py rules tmn-debug` override anything else in this skill.

## 1. Reproduce first

- Get the exact failure: the error text, the input, the environment, the time.
  Read logs in bounded slices (`tail -n 200`, `rg -n 'ERROR' | head`).
- Make it happen on demand: a failing test, a curl, a script. If you can't
  reproduce it, you're guessing. Say so, and gather more evidence before
  touching code.
- Flaky? Run it 20 times and count (`for i in $(seq 20); do <cmd> >/dev/null
  2>&1 && echo ok || echo FAIL; done | sort | uniq -c`). A rate is evidence; a
  single failure isn't.

## 2. Narrow it

Work from evidence, one variable at a time:

- **What changed?** `git log --since=<when it last worked>`, the deploy
  history, dependency bumps (`git diff <good>..<bad> -- '*lock*'`), config and
  secret changes. `git bisect run <repro>` finds the commit for you when the
  repro is scriptable.
- **Where does it diverge?** Compare a working and a failing case side by
  side: inputs, config, versions, data. The difference is the lead.
- **Check what the code actually receives**, not what you assume. Log or print
  the real value at the boundary, then remove the print.

Write each hypothesis down with the test that would rule it out. Run that test
before forming the next one. Three untested hypotheses at once is how a
two-hour bug takes two days.

## 3. Explain the mechanism

Before fixing, state the chain: trigger → path → wrong result. If part of the
chain is "somehow", you aren't done. Common real causes, worth checking early:

- an error turned into "no data" (a dead token returning an empty list)
- a fallback default that hides a missing setting
- state left behind by a previous run (cache, temp file, migration half-applied)
- two environments that differ in one setting nobody listed
- a test that mocks the very thing that broke

## 4. Fix the cause

- Write the test that reproduces it, watch it fail, then fix. Check with
  `scripts/redgreen.sh`.
- Look for the same mistake elsewhere. The same pattern usually exists in more
  than one place.
- Keep the fix as small as the cause. A refactor goes in its own PR.
- Run the `tmn-verify` skill, then the `tmn-ship-pr` skill.

## 5. Write it down

In the PR or incident note, in plain words: what users saw, the cause, the
fix, how you know it's fixed, and what would catch it sooner next time (a test,
an alert, a check). If the cause was a missing guard, add the guard. A lesson
in a doc is weaker than a check that runs.

## During an incident

Stabilise first, then diagnose. Roll back or turn off the flag if that's safe
and fast. Say what you're doing before you do it, in the incident channel, in
one line. Never run a destructive command (drop, delete, force-push, scale to
zero) to make an alert stop without the owner's go-ahead.

Versions

The database has no other skills named tmn-debug.

Database snapshot: 13.11.2026 · package version 0d4ce08ed810 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100debug
    Use before changing code to fix any bug, failing or flaky test, error, crash, wrong output, regression, or "works locally but not in staging/prod" — including when the user just says "X fails, fix it". Proves the root cause first, fixes it at the source with a regression test…
  • 92debug
    Find the root cause of a bug before you fix it. Read this skill before you fix any bug. Read it also when the fix looks obvious. Use it when the user says "fix", "broken", "not working", "error", "failing", or "bug". Use it also when a test fails unexpectedly during other work.
  • 90debug-a-failing-test
    Finds out why a test fails and fixes the cause, not the test: reproduce it alone, read the error, narrow it down, fix, and prove it with a run. Use when a test fails, a check is red, a test is flaky, or the owner says the tests broke.
  • 100sdlc-debug
    Bug track: reproduce, find the root cause with evidence, write a failing regression test, apply the smallest fix, check siblings, verify on the real surface. Use when something behaves wrongly, a test fails, an error is reported, or the user says 'debug', 'fix this bug' or 'why does X happen'.
  • 100debug-detective
    Find the root cause of a bug, crash, error message or failing test, then fix it. Use when the user says "this is broken", "why does this fail", "I get this error", "the test is failing", "it worked yesterday", or pastes a stack trace.
  • 100root-cause-debugging
    Debug by finding the root cause before changing code: reproduce, read the full error, check what changed, form one hypothesis at a time and test it, write the failing test, then fix; with a hard stop after three failed fixes to question the approach. Use when a test fails, a bug…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.