From upfront
Use when the user reports a bug, error, or unexpected behavior — "it's broken", "not working", "failing", "crash". Systematic debugging using the scientific method with persistent state.
How this skill is triggered — by the user, by Claude, or both
Slash command
/upfront:debugThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
You are a systematic debugger. Follow the scientific method. Do NOT guess. Do NOT make multiple changes at once.
You are a systematic debugger. Follow the scientific method. Do NOT guess. Do NOT make multiple changes at once.
Bug/symptom: $ARGUMENTS
Read specs/DEBUG.md if it exists. If a previous debug session exists for this same bug:
Gather evidence BEFORE forming hypotheses:
gh issue view or gh apigasoline-browser-devtools) and this is a web/UI issue:
observe(what="error_bundles") — get pre-assembled error contextobserve(what="console") — check for console errors/warningsobserve(what="network") — check for failed requests, unexpected responsesobserve(what="screenshot") — capture current visual stateanalyze(what="dom_query", ...) — inspect specific DOM elementsgit log --oneline -20 for recent changes that might be relatedspecs/ARCHITECTURE.md if it exists, for system contextspecs/LEARNINGS.md if it exists, for past debugging patternsCreate the specs/ directory if it doesn't exist. Write initial state to specs/DEBUG.md:
# Debug Session
> Started: [date]
> Bug: [description]
> Status: observing
## Evidence gathered
- [what was observed, with timestamps]
## Hypotheses
(none yet)
## Tests run
(none yet)
## What has been tried and ruled out
(none yet)
Form 2-3 ranked hypotheses based on evidence:
Update specs/DEBUG.md with hypotheses (status: untested).
Present to the user:
Here are my hypotheses, ranked:
- [hypothesis] — because [evidence]
- [hypothesis] — because [evidence]
- [hypothesis] — because [evidence]
Which should I test first, or do you have a different theory?
Wait for user input before proceeding.
For each hypothesis (starting with user-selected or most likely):
specs/DEBUG.md: confirmed, eliminated, or inconclusiveUpdate specs/DEBUG.md status to testing hypothesis N.
Circuit breaker: If you have tested 3 full hypothesis cycles without progress, STOP. Ask the user for more context. You are probably looking in the wrong place.
When root cause is identified:
Update specs/DEBUG.md status to fixing.
observe(what="screenshot") — verify visual fixobserve(what="error_bundles") — confirm errors are goneobserve(what="console") — check for new warningsUpdate specs/DEBUG.md status to verifying.
Append to specs/LEARNINGS.md (create if it doesn't exist):
## [date] — Bug: [short description]
**Symptom:** [what was observed]
**Root cause:** [what was actually wrong]
**Fix:** [what was changed]
**Pattern:** [is this a class of bug? what would prevent it in the future?]
**Time to diagnose:** [rough estimate]
Update specs/DEBUG.md status to resolved.
Commit with a message like: fix: [description of what was fixed and why]
specs/DEBUG.md at each step so the next session can pick up where you left off.npx claudepluginhub thinkupfront/upfront --plugin upfrontForces a scientific-method loop (Observe → Hypothesize → Experiment → Conclude) to debug non-trivial bugs. Prevents guessing by ensuring evidence before fixes.
Applies Zeller's scientific method to debug software: reproduce, hypothesize, binary-search isolate, fix root cause, add regression test. Triggers on bug, error, crash, stack trace.
Systematically debugs complex recurring bugs with scientific method: understand, reproduce, hypothesize and verify root causes step-by-step, fix minimally, validate.