From bee-default
Four-phase debugging framework - root cause investigation, pattern analysis, hypothesis testing, implementation. Ensures understanding before attempting fixes.
npx claudepluginhub luanrodrigues/ia-frmwrk --plugin bee-defaultThis skill uses the workspace's default tool permissions.
**Core principle:** NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.
Generates design tokens/docs from CSS/Tailwind/styled-components codebases, audits visual consistency across 10 dimensions, detects AI slop in UI.
Records polished WebM UI demo videos of web apps using Playwright with cursor overlay, natural pacing, and three-phase scripting. Activates for demo, walkthrough, screen recording, or tutorial requests.
Delivers idiomatic Kotlin patterns for null safety, immutability, sealed classes, coroutines, Flows, extensions, DSL builders, and Gradle DSL. Use when writing, reviewing, refactoring, or designing Kotlin code.
Core principle: NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.
Use for ANY technical issue: test failures, bugs, unexpected behavior, performance problems, build failures, integration issues.
Especially when:
Complete each phase before proceeding to the next.
MUST complete ALL before Phase 2 (copy to TodoWrite):
□ Error message copied verbatim | □ Reproduction confirmed | □ Recent changes reviewed (git diff) | □ Evidence from ALL components | □ Data flow traced (origin → error)
git diff, recent commits, new dependencies, config changes.Phase 1 Summary: Error: [exact] | Reproduces: [steps] | Recent changes: [commits] | Component evidence: [each] | Data origin: [source]
H#1: [what] → [result] | H#2: [what] → [result] | H#3: [what] → [STOP if fails]
If 3 hypotheses fail: STOP immediately → "3 hypotheses failed, architecture review required" → Discuss with partner before more attempts.Fix root cause, not symptom:
Debugging time boxes:
STOP and return to Phase 1 if thinking:
User signals you're wrong:
When you see these: STOP. Return to Phase 1.
| Phase | Key Activities | Success Criteria |
|---|---|---|
| 1. Root Cause | Read errors, reproduce, check changes, gather evidence, trace data flow | Understand WHAT and WHY |
| 2. Pattern | Find working examples, compare differences, understand dependencies | Identify what's different |
| 3. Hypothesis | Form theory, test minimally, verify one at a time | Confirmed or new hypothesis |
| 4. Implementation | Create test, fix root cause, verify | Bug resolved, tests pass |
Circuit breakers:
Required sub-skills:
Complementary:
STOP and report if:
| Decision Type | Blocker Condition | Required Action |
|---|---|---|
| Cannot reproduce issue | Bug is intermittent and no consistent reproduction steps | STOP and gather more data before proceeding |
| 3 hypotheses failed | Three consecutive hypotheses tested and all failed | STOP and escalate for architecture review |
| 3 fixes failed | Three fix attempts made but issue persists | STOP and question fundamental assumptions |
| 30 minutes without root cause | Extended investigation without identifying root cause | STOP and escalate for help |
| Fix reveals new problem | Each attempted fix creates different symptoms | STOP and request architecture review |
The following requirements CANNOT be waived:
| Severity | Condition | Required Action |
|---|---|---|
| CRITICAL | Production system affected | MUST prioritize and escalate immediately |
| CRITICAL | Data corruption or loss risk | MUST stop other work and focus exclusively |
| HIGH | User-facing functionality broken | MUST investigate before other tasks |
| HIGH | Tests failing on main branch | MUST resolve before merging new code |
| MEDIUM | Non-critical feature affected | Should investigate within current session |
| LOW | Minor behavior deviation | Fix in next iteration if time permits |
| Rationalization | Why It's WRONG | Required Action |
|---|---|---|
| "Quick fix for now, investigate later" | Later never comes. Quick fixes mask root causes. | MUST complete Phase 1 before any code change |
| "Just try changing X and see" | Guessing wastes time and introduces new bugs | MUST form hypothesis with evidence first |
| "I'm confident this is the issue" | Confidence without evidence is guessing | MUST verify with reproduction steps |
| "One more fix attempt" (after 2+) | Pattern indicates architecture issue, not bug | STOP and escalate for architecture review |
| "Each fix reveals new problem" | Symptom of deeper structural issue | STOP: architecture review REQUIRED |
| "I don't fully understand but this might work" | Partial understanding = partial fix = new bugs | MUST understand root cause before fixing |
| "Skip the test, I'll manually verify" | Manual verification is unreliable and non-repeatable | MUST create failing test (Phase 4, Step 1) |
| "Previous run showed it works" | Stale evidence is not evidence | MUST re-verify with fresh execution |
| User Says | Your Response |
|---|---|
| "Just fix it quickly, we don't have time" | "MUST follow the phases - skipping investigation causes more delays through repeated fixes" |
| "Try this change, I think it'll work" | "I'll add that as a hypothesis and test it properly in Phase 3" |
| "We've tried 5 fixes, try one more" | "CANNOT proceed - 3+ failed fixes requires architecture review before more attempts" |
| "Skip the investigation, the cause is obvious" | "MUST verify the obvious before acting - obvious causes are often wrong" |
This skill uses these universal patterns:
skills/shared-patterns/state-tracking.mdskills/shared-patterns/failure-recovery.mdskills/shared-patterns/exit-criteria.mdskills/shared-patterns/todowrite-integration.mdApply ALL patterns when using this skill.