{"id":"1804ec0c-e8e0-4cdb-b61c-8b27e274d1f2","shortId":"C355jW","kind":"skill","title":"debug","tagline":">-","description":"!../principles/SKILL_BODY.md\n\n!../tool-gitnexus/SKILL_BODY.md\n\n---\n\n# Debugging Workflow\n\n## Disambiguation Gate\n\n> **Before starting:** Can you point to a specific function or line and say \"the bug is here\"?\n> → **Yes** → Stop. Use `sextant:fix-bug` — the location is known, that skill handles the fix.\n> → **No** → Continue here. This skill is for \"symptom known, location unknown.\"\n\n## Core Principle\n\nDebug by **bisection, not inspection**. Form a hypothesis about which boundary separates correct from incorrect behavior, then eliminate layers until only the root cause remains.\n\n---\n\n## Complete Execution Workflow\n\n### Step 1: Capture the Symptom\n\nBefore forming any hypothesis, establish a precise symptom record:\n\n- **Error message** (exact text, stack trace if available)\n- **Reproduction steps** (what sequence of actions triggers it?)\n- **Frequency** (always / intermittent / environment-specific)\n- **Regression** (did this ever work? What changed recently?)\n\n```\n─── Symptom Record ──────────────────────────────────\nError / unexpected output: <exact message or behavior>\nTrigger steps:             <reproducible sequence>\nFrequency:                 Always / Intermittent (~X%) / Specific environment only\nRegression:                Yes (last known good: <commit/date>) / No / Unknown\n─────────────────────────────────────────────────────\n```\n\n### Step 2: Identify Paradigm + Select Isolation Strategy\n\nIdentify which architecture paradigm applies (per §6.0), then use the corresponding isolation strategy:\n\n| Paradigm | Isolation Direction | Isolation Technique |\n|----------|---------------------|---------------------|\n| **Backend layered** | Entry → Logic → Data (inward) | Add logging at each layer boundary; find the first layer that returns incorrect data |\n| **Frontend component tree** | Page → Feature → Atom (downward) | Props injection test: pass hardcoded data directly to component, bypass store |\n| **CLI / Script** | Entry → Command handler → Core logic (inward) | Print intermediate values at each function boundary |\n| **Functional (FP)** | I/O boundary → Pure core (inward) | Test pure functions in isolation; side effects confined to boundaries |\n| **Concurrent / Async** | Reconstruct timing diagram; locate shared state | Add timestamps/sequence numbers to logs; inspect lock points on shared state |\n| **Event-driven** | Trace event publish → handler chain | Log each consumed event; verify handler receives correct payload |\n\n🔗 When GitNexus is available, use `context` / `trace` MCP tools to map the call chain automatically.\n\n### Step 3: Form and Validate Hypotheses\n\n**Bisection protocol:** Find the boundary between \"working correctly\" and \"already wrong.\"\n\n1. Identify the layer / module where the symptom surfaces — this is the **observation point**\n2. Ask: \"Is the input to this layer already wrong, or does this layer corrupt correct input?\"\n3. Move the observation point inward (toward the source) until you find the first layer that produces incorrect output\n4. That boundary is your root cause hypothesis\n\n**For intermittent bugs (concurrency / async):**\n- Add sequence numbers or timestamps to logs before the symptom point\n- Identify the shared state that changes between passing and failing runs\n- Hypothesis format: `\"Thread A reads X before Thread B writes the updated value\"`\n\n**For environment-specific bugs:**\n- List all environmental differences (OS, config, versions, data state)\n- Eliminate variables one by one until the failing condition is isolated\n\n```\n─── Hypothesis Log ──────────────────────────────────\nHypothesis 1: <the bug is in X because Y>\n  Test:   <what to check / add / isolate>\n  Result: ✅ Confirmed / ❌ Eliminated / ⏳ Pending\n\nHypothesis 2: ...\n─────────────────────────────────────────────────────\n```\n\n**Hypothesis limit gate — trigger when 3+ hypotheses have been eliminated without confirming root cause:**\n\nStop the bisection loop. Do not generate more hypotheses. Instead, choose one of the following escalation paths:\n\n1. **Request more context** — ask the user for: a minimal reproduction case, relevant logs or stack traces at the failure point, or the last known-good commit/state\n2. **Suggest `git bisect`** — if the bug is a regression with an unknown introduction point, `git bisect` identifies the exact commit; ask the user to run it and share the result\n3. **Add structured logging** — propose specific log statements at the current observation point boundary; ask the user to re-run and share the output before resuming bisection\n4. **Widen the symptom map** — if only one symptom was captured, ask whether the bug manifests differently under other conditions (different inputs, environments, users)\n\n```\n─── Escalation Decision ─────────────────────────────\nHypotheses eliminated: N\nRoot cause: ⏳ not yet confirmed\nEscalation chosen: <context request / git bisect / structured logging / symptom widening>\nInformation needed from user: <specific artifact or action>\n─────────────────────────────────────────────────────\n```\n\n### Step 4: Confirm Root Cause → Hand Off to Fix\n\nWhen you can answer all three:\n1. **Which function / line** produces the incorrect output?\n2. **Under what exact input or state** does the failure occur?\n3. **Why** does that code produce incorrect output (logic error, missing guard, race condition, wrong assumption)?\n\n→ Root cause is confirmed. **Hand off: switch to `sextant:fix-bug`.**\n\nProvide the fix-bug workflow with pre-filled context:\n- Root cause location (file + function)\n- Trigger conditions\n- Impact scope already identified (skip fix-bug Step 2 if already covered here)\n\n---\n\n## Forbidden Actions\n\n- Do not apply a workaround (`try/except` swallowing, hardcoded fallback value) before the root cause is confirmed — this hides the bug\n- Do not generate a list of all possible causes without narrowing — work by elimination, not enumeration\n- Do not start fixing while the location is still uncertain — confirm first, then hand off to `sextant:fix-bug`\n\n---\n\n## Reply Format\n\nDebug Summary:\n\n| # | Item | Detail |\n|---|------|--------|\n| [1] | Symptom | <exact error + reproduction conditions + frequency> |\n| [2] | Paradigm | <detected paradigm> → isolation strategy: <strategy name> |\n| [3] | Hypotheses tested | <list with ✅ Confirmed / ❌ Eliminated result for each> |\n| [4] | Root cause | <file:function — what and why> / ⏳ Not yet confirmed (next step: <action>) |\n| [5] | Next action | Switch to sextant:fix-bug with pre-filled context / <specific investigation step> |","tags":["debug","sextant","hellotern","agent-skills","claude-code","skill-md"],"capabilities":["skill","source-hellotern","skill-debug","topic-agent-skills","topic-claude-code","topic-skill-md"],"categories":["Sextant"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/hellotern/Sextant/debug","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add hellotern/Sextant","source_repo":"https://github.com/hellotern/Sextant","install_from":"skills.sh"}},"qualityScore":"0.457","qualityRationale":"deterministic score 0.46 from registry signals: · indexed on github topic:agent-skills · 14 github stars · SKILL.md body (6,510 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-04-22T19:06:44.444Z","embedding":null,"createdAt":"2026-04-18T23:07:26.998Z","updatedAt":"2026-04-22T19:06:44.444Z","lastSeenAt":"2026-04-22T19:06:44.444Z","tsv":"'/principles/skill_body.md':2 '/tool-gitnexus/skill_body.md':3 '1':83,311,437,476,618,761 '2':149,325,444,504,626,692,768 '3':295,342,450,535,637,772 '4':361,563,604,782 '5':795 '6.0':161 'action':109,698,797 'add':179,251,374,536 'alreadi':309,333,685,694 'alway':113,134 'answer':615 'appli':159,701 'architectur':157 'ask':326,480,525,549,574 'assumpt':652 'async':244,373 'atom':198 'automat':293 'avail':103,282 'b':404 'backend':173 'behavior':69 'bisect':56,300,461,507,520,562 'boundari':64,184,225,229,242,304,363,548 'bug':22,31,371,413,510,577,664,669,690,718,754,803 'bypass':209 'call':291 'captur':84,573 'case':487 'caus':77,367,458,593,607,654,677,712,727,784 'chain':269,292 'chang':124,390 'choos':469 'chosen':598 'cli':211 'code':641 'command':214 'commit':524 'commit/date':145 'commit/state':503 'complet':79 'compon':194,208 'concurr':243,372 'condit':431,582,650,682,766 'config':419 'confin':240 'confirm':440,456,596,605,656,714,745,777,792 'consum':272 'context':284,479,675,808 'continu':42 'core':52,216,231 'correct':66,277,307,340 'correspond':165 'corrupt':339 'cover':695 'current':545 'data':177,192,205,421 'debug':1,4,54,757 'decis':588 'detail':760 'diagram':247 'differ':417,579,583 'direct':170,206 'disambigu':6 'downward':199 'driven':264 'effect':239 'elimin':71,423,441,454,590,732,778 'entri':175,213 'enumer':734 'environ':116,138,411,585 'environment':416 'environment-specif':115,410 'error':96,128,646,764 'escal':474,587,597 'establish':91 'event':263,266,273 'event-driven':262 'ever':121 'exact':98,523,629,763 'execut':80 'fail':394,430 'failur':495,635 'fallback':707 'featur':197 'file':679,785 'fill':674,807 'find':185,302,353 'first':187,355,746 'fix':30,40,611,663,668,689,738,753,802 'fix-bug':29,662,667,688,752,801 'follow':473 'forbidden':697 'form':59,88,296 'format':397,756 'fp':227 'frequenc':112,133,767 'frontend':193 'function':16,224,226,235,620,680,786 'gate':7,447 'generat':465,721 'git':506,519 'gitnexus':280 'good':144,502 'guard':648 'hand':608,657,748 'handl':38 'handler':215,268,275 'hardcod':204,706 'hide':716 'hypothes':299,451,467,589,773 'hypothesi':61,90,368,396,434,436,443,445 'i/o':228 'identifi':150,155,312,385,521,686 'impact':683 'incorrect':68,191,359,624,643 'inform':599 'inject':201 'input':329,341,584,630 'inspect':58,256 'instead':468 'intermedi':220 'intermitt':114,135,370 'introduct':517 'inward':178,218,232,347 'isol':153,166,169,171,237,433,770 'item':759 'known':35,49,143,501 'known-good':500 'last':142,499 'layer':72,174,183,188,314,332,338,356 'limit':446 'line':18,621 'list':414,723,775 'locat':33,50,248,678,741 'lock':257 'log':180,255,270,380,435,489,538,541 'logic':176,217,645 'loop':462 'manifest':578 'map':289,567 'mcp':286 'messag':97 'minim':485 'miss':647 'modul':315 'move':343 'n':591 'narrow':729 'need':600 'next':793,796 'number':253,376 'observ':323,345,546 'occur':636 'one':425,427,470,570 'os':418 'output':130,360,559,625,644 'page':196 'paradigm':151,158,168,769 'pass':203,392 'path':475 'payload':278 'pend':442 'per':160 'point':12,258,324,346,384,496,518,547 'possibl':726 'pre':673,806 'pre-fil':672,805 'precis':93 'principl':53 'print':219 'produc':358,622,642 'prop':200 'propos':539 'protocol':301 'provid':665 'publish':267 'pure':230,234 'race':649 're':554 're-run':553 'read':400 'receiv':276 'recent':125 'reconstruct':245 'record':95,127 'regress':118,140,513 'relev':488 'remain':78 'repli':755 'reproduct':104,486,765 'request':477 'result':439,534,779 'resum':561 'return':190 'root':76,366,457,592,606,653,676,711,783 'run':395,529,555 'say':20 'scope':684 'script':212 'select':152 'separ':65 'sequenc':107,375 'sextant':28,661,751,800 'share':249,260,387,532,557 'side':238 'skill':37,45 'skill-debug' 'skip':687 'sourc':350 'source-hellotern' 'specif':15,117,137,412,540 'stack':100,491 'start':9,737 'state':250,261,388,422,632 'statement':542 'step':82,105,132,148,294,603,691,794 'still':743 'stop':26,459 'store':210 'strategi':154,167,771 'structur':537 'suggest':505 'summari':758 'surfac':319 'swallow':705 'switch':659,798 'symptom':48,86,94,126,318,383,566,571,762 'techniqu':172 'test':202,233,438,774 'text':99 'thread':398,403 'three':617 'time':246 'timestamp':378 'timestamps/sequence':252 'tool':287 'topic-agent-skills' 'topic-claude-code' 'topic-skill-md' 'toward':348 'trace':101,265,285,492 'tree':195 'trigger':110,131,448,681 'try/except':704 'uncertain':744 'unexpect':129 'unknown':51,147,516 'updat':407 'use':27,163,283 'user':482,527,551,586,602 'valid':298 'valu':221,408,708 'variabl':424 'verifi':274 'version':420 'whether':575 'widen':564 'without':455,728 'work':122,306,730 'workaround':703 'workflow':5,81,670 'write':405 'wrong':310,334,651 'x':136,401 'yes':25,141 'yet':595,791","prices":[{"id":"9c2ea655-7ec3-4173-bc8e-210fbb85fe43","listingId":"1804ec0c-e8e0-4cdb-b61c-8b27e274d1f2","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"hellotern","category":"Sextant","install_from":"skills.sh"},"createdAt":"2026-04-18T23:07:26.998Z"}],"sources":[{"listingId":"1804ec0c-e8e0-4cdb-b61c-8b27e274d1f2","source":"github","sourceId":"hellotern/Sextant/debug","sourceUrl":"https://github.com/hellotern/Sextant/tree/main/skills/debug","isPrimary":false,"firstSeenAt":"2026-04-18T23:07:26.998Z","lastSeenAt":"2026-04-22T19:06:44.444Z"}],"details":{"listingId":"1804ec0c-e8e0-4cdb-b61c-8b27e274d1f2","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"hellotern","slug":"debug","github":{"repo":"hellotern/Sextant","stars":14,"topics":["agent-skills","claude-code","skill-md"],"license":"mit","html_url":"https://github.com/hellotern/Sextant","pushed_at":"2026-04-07T00:57:27Z","description":"init","skill_md_sha":"784a88b5a94f9877b54cafe83c7b801fe387bbdb","skill_md_path":"skills/debug/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/hellotern/Sextant/tree/main/skills/debug"},"layout":"multi","source":"github","category":"Sextant","frontmatter":{"description":">-"},"skills_sh_url":"https://skills.sh/hellotern/Sextant/debug"},"updatedAt":"2026-04-22T19:06:44.444Z"}}