playbooks

home / skills / jjuidev / jss / fix

fix skill

/.claude/skills/fix

This skill automates and guides bug fixing across modes, optimizing root-cause analysis and verification to accelerate reliable resolutions.

npx playbooks add skill jjuidev/jss --skill fix

Review the files below or copy the command above to add this skill to your agents.

Files (14)
SKILL.md
3.8 KB
---
name: fix
description: ALWAYS activate this skill before fixing ANY bug, error, test failure, CI/CD issue, type error, lint, log error, UI issue, code problem.
version: 1.1.0
---

# Fixing

Unified skill for fixing issues of any complexity with intelligent routing.

## Arguments

- `--auto` - Activate autonomous mode (**default**)
- `--review` - Activate human-in-the-loop review mode
- `--quick` - Activate quick mode

## Workflow

### Step 1: Mode Selection

**First action:** If there is no "auto" keyword in the request, use `AskUserQuestion` to determine workflow mode:

| Option | Recommend When | Behavior |
|--------|----------------|----------|
| **Autonomous** (default) | Simple/moderate issues | Auto-approve if score >= 9.5 & 0 critical |
| **Human-in-the-loop Review** | Critical/production code | Pause for approval at each step |
| **Quick** | Type errors, lint, trivial bugs | Fast debug → fix → review cycle |

See `references/mode-selection.md` for AskUserQuestion format.

### Step 2: Debug

- Activate `debug` skill.
- Guess all possible root causes.
- Spawn multiple `Explore` subagents in parallel to verify each hypothesis.
- Create report with all findings for the next step.

### Step 3: Complexity Assessment & Fix Implementation

Classify before routing. See `references/complexity-assessment.md`.

| Level | Indicators | Workflow |
|-------|------------|----------|
| **Simple** | Single file, clear error, type/lint | `references/workflow-quick.md` |
| **Moderate** | Multi-file, root cause unclear | `references/workflow-standard.md` |
| **Complex** | System-wide, architecture impact | `references/workflow-deep.md` |
| **Parallel** | 2+ independent issues | Parallel `fullstack-developer` agents |

### Step 4: Fix Verification & Prevent Future Issues

- Read and analyze all the implemented changes.
- Spawn multiple `Explore` subagents to find possible related code for verification.
- Make sure these fixes don't break other parts of the codebase.
- Prevent future issues by adding comprehensive validation.

### Step 5: Finalize

- Report summary to user with confidence level/score, all the changes and related files.
- Ask to commit via `git-manager` subagent and update docs if needed via `docs-manager` subagent (in parallel).

---

## IMPORTANT: Skill/Subagent Activation Matrix

See `references/skill-activation-matrix.md` for complete matrix.

**Always activate:** `debug` (all workflows)
**Conditional:** `problem-solving`, `sequential-thinking`, `brainstorming`, `context-engineering`
**Subagents:** `debugger`, `researcher`, `planner`, `code-reviewer`, `tester`, `Bash`
**Parallel:** Multiple `Explore` agents for scouting, `Bash` agents for verification

## Output Format

Unified step markers:
```
✓ Step 0: [Mode] selected - [Complexity] detected
✓ Step 1: Root cause identified - [summary]
✓ Step 2: Fix implemented - [N] files changed
✓ Step 3: Tests [X/X passed]
✓ Step 4: Review [score]/10 - [status]
✓ Step 5: Complete - [action taken]
```

## References

Load as needed:
- `references/mode-selection.md` - AskUserQuestion format for mode
- `references/complexity-assessment.md` - Classification criteria
- `references/workflow-quick.md` - Quick: debug → fix → review
- `references/workflow-standard.md` - Standard: full pipeline
- `references/workflow-deep.md` - Deep: research + brainstorm + plan
- `references/review-cycle.md` - Review logic (autonomous vs HITL)
- `references/skill-activation-matrix.md` - When to activate each skill
- `references/parallel-exploration.md` - Parallel Explore/Bash subagents patterns

**Specialized Workflows:**
- `references/workflow-ci.md` - GitHub Actions/CI failures
- `references/workflow-logs.md` - Application log analysis
- `references/workflow-test.md` - Test suite failures
- `references/workflow-types.md` - TypeScript type errors
- `references/workflow-ui.md` - Visual/UI issues (requires design skills)

Overview

This skill always activates before fixing any bug, error, test failure, CI/CD issue, type error, lint, log error, UI issue, or code problem. It provides an end-to-end, disciplined workflow that selects an operating mode, performs deep debugging, assesses complexity, implements fixes, verifies impact, and finalizes changes with a confidence score. The skill coordinates specialized subagents and parallel exploration to reduce blind spots and speed resolution.

How this skill works

On invocation the skill selects a mode (autonomous, human-in-the-loop review, or quick) and runs a mandatory debug phase that enumerates and tests root-cause hypotheses. It classifies issue complexity (simple, moderate, complex, or parallel) to choose an appropriate workflow and activates required subagents (debugger, researcher, planner, code-reviewer, tester, Bash, and parallel Explore agents). After implementing fixes it runs verification, searches for related risks, produces a summary with confidence score, and can request commits or documentation updates.

When to use it

  • Before attempting any fix to ensure consistent, auditable workflow
  • When a failing test, CI job, or lint/type error appears
  • For production or critical code where human review may be required
  • On multi-file or system-wide bugs that need coordinated investigation
  • When you want automated verification and a confidence score

Best practices

  • Always run in autonomous mode for trivial issues and quick mode for type/lint fixes
  • Choose human-in-the-loop for production-impacting or safety-critical changes
  • Use parallel Explore/Bash agents to validate multiple hypotheses simultaneously
  • Require full verification and related-code scouting before finalizing changes
  • Report confidence, files changed, and test results in the unified step format

Example use cases

  • A failing CI pipeline due to a recent dependency upgrade — detect, isolate, and propose rollback or patch
  • A unit test regression after refactor — find root cause, implement minimal fix, and re-run tests
  • Type errors from static analysis — quick mode to correct annotations and rerun type checks
  • Flaky production logs showing intermittent exceptions — deep investigation and preventative validation
  • UI rendering bug affecting multiple components — classify as complex and coordinate design-aware fixes

FAQ

What mode should I pick by default?

Autonomous is the default for simple or moderate issues; use human-in-the-loop for critical production changes and quick for trivial type/lint fixes.

Which subagents are always activated?

The debug skill is always activated. Other subagents (problem-solving, planner, code-reviewer, tester, Bash, Explore) are activated conditionally based on complexity.