Skip to content

JordanGunn/nunchuck / skills/doctor

doctor

Verified

Diagnoses software failures by combining deterministic evidence gathering with agent judgment. Models failures as medical cases. Idempotent — run repeatedly until confident diagnosis, then generate schema-based treatment.

references/06_FAILURES.md

View on GitHub
---
description: What to do when things go wrong.
index:
  - Common Failure Cases
  - When to Abort
  - When to Continue
  - Surfacing Uncertainty
  - The Final Rule
---

# Failures

Handling uncertainty and errors in the doctor skill.

## Common Failure Cases

### No Matches Found

When `grep` returns no results:

1. Verify the search term is correct
2. Try broader patterns or different file types
3. Ask user for alternative terms
4. Document the negative result (absence of evidence is data)

### Multiple Viable Hypotheses

When confidence is spread across hypotheses:

1. Identify the key differentiator between them
2. Search for evidence that would falsify one
3. Present both to user for domain knowledge input
4. Do not force a single diagnosis

### Conflicting Evidence

When evidence supports contradictory conclusions:

1. Document both pieces of evidence explicitly
2. Consider whether the problem is multi-causal
3. Reduce confidence accordingly
4. Recommend targeted testing to resolve

### Stale Session

When resuming after context loss:

1. Run `./skill.sh status` to check session state
2. Review evidence files in `.doctor/evidence/`
3. Do not assume previous conversation context
4. Continue from recorded session state

## When to Abort

- User explicitly abandons investigation
- Problem is determined to be out of scope
- Required access is unavailable (logs, systems)
- Time constraints prevent proper investigation

## When to Continue

- Low confidence is normal early in investigation
- Negative search results are informative
- User frustration does not mean failure

## Surfacing Uncertainty

Always tell the user:

- Current confidence level
- What evidence would increase confidence
- What alternative explanations remain
- Whether more investigation is needed

## The Final Rule

> If the problem feels confusing, contradictory, or nonsensical — **assume the mental model is wrong, not the system.**
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 323kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 323kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 323kUpdated Claude CodeCodexVerifiedInstall