Driver

The /debug skill is for bugs that resisted naïve fix attempts — explicitly NOT for every bug. The gate ("resisted naïve fix") lives only in the skill description (.claude/skills/debug/SKILL.md); it's nowhere in the bug-workflow guidance an adopter walks through (workflows/sdlc.md's Phase 3 Build section).

Today an adopter reading the SDLC docs sees /bug as the only ticketing skill mentioned and may reasonably infer "I should use /debug whenever I work on a bug." That's framework over-ceremony — /debug is hypothesis-tree + architecture-first reading + evidence-before-fix work that's pure friction for a one-line typo fix.

The 3-tier bug-class ceremony is real, defensible, and currently invisible to the adopter unless they happen to read both /debug and /investigation skill specs side-by-side and infer the relationship.

Scope

Single-file edit to workflows/sdlc.md. Add a callout box / sidebar to Phase 3 (Build) — sibling shape to the existing /spike callout that already lives there — covering when to invoke /debug vs just fix vs /investigation. Match the existing callout style.

Concrete content to add (around the Build phase entry-criteria section):

Sidebar — when to invoke /debug (and when NOT to)

The /debug skill is for bugs that resisted naïve fix attempts, not every bug. Three tiers, matched to bug class:

Class	Workflow
Simple bug — clear repro, obvious cause, one-line fix	/bug → fix → PR. No /debug. The cost of hypothesis-tree ceremony exceeds the fix cost.
Resistant bug — naïve fix didn't hold OR cause unclear after grep+Read	/bug → /debug → fix → PR. Forces architecture-first reading + evidence-before-fix. Prevents shotgun debugging.
Sustained mystery — multi-session, archaeology, performance puzzle, incident retro	/investigation (live-doc) — different skill entirely. Days of effort, cross-session continuity matters.

Self-check before /debug: have I tried the obvious fix? Did it work? If NO → /debug. If didn't try yet → try the obvious thing first.

Same shape as /spike (file when you genuinely don't know; just code when you do).

Also: add /debug to the workflows index of skills referenced by the SDLC (if such an index exists in workflows/sdlc.md or workflows/code-review.md).

Acceptance Criteria

• workflows/sdlc.md Phase 3 Build section has a /debug sidebar callout matching the existing /spike sidebar shape
• The 3-tier table (Simple / Resistant / Sustained) is included verbatim or in a tightened equivalent form
• Self-check ("have I tried the obvious fix?") is captured as the operator-facing decision rule
• Cross-references /investigation as the sustained-mystery sibling
• Cross-references /spike as the analogous pattern ("file when uncertain; just code when sure")
• No regression on existing Phase 3 content — additive only
• Lint clean (npx markdownlint-cli2@0.13.0 workflows/sdlc.md returns 0 errors)

Out of scope

• Modifying the /debug skill spec itself (.claude/skills/debug/SKILL.md) — the gate is correct there; it's the SDLC doc that's missing the cross-reference
• Adding a mechanical hook that requires /debug for tickets labelled bug — that would be over-enforcement; this is genuinely an operator-judgement call
• Backporting the sidebar pattern to other skill-when-to-invoke gaps (could be its own ticket if a few more surface)

Glossary

Refs workflows/sdlc.md (target file) / .claude/skills/debug/SKILL.md (skill spec where the gate currently lives) / .claude/skills/investigation/SKILL.md (sustained-mystery sibling) / .claude/skills/spike/SKILL.md (analogous pattern)