askill
fix-issue

fix-issueSafety 95Repository

Fix GitHub issue with parallel analysis and implementation. Use when fixing issues, resolving bugs, closing GitHub issues.

7 stars
1.2k downloads
Updated 2/8/2026

Package Files

Loading files...
SKILL.md

Fix Issue

Systematic issue resolution with hypothesis-based root cause analysis, similar issue detection, and prevention recommendations.

Quick Start

/fix-issue 123
/fix-issue 456

Task Management (CC 2.1.16)

# Create main fix task
TaskCreate(
  subject="Fix issue #{number}",
  description="Systematic issue resolution with hypothesis-based RCA",
  activeForm="Fixing issue #{number}"
)

# Create subtasks for 11-phase process
phases = ["Understand issue", "Search similar issues", "Form hypotheses",
          "Analyze root cause", "Design fix", "Implement fix", "Validate fix",
          "Generate prevention", "Create runbook", "Capture lessons", "Commit and PR"]
for phase in phases:
    TaskCreate(subject=phase, activeForm=f"{phase}ing")

Workflow Overview

PhaseActivitiesOutput
1. Understand IssueRead GitHub issue detailsProblem statement
2. Similar Issue DetectionSearch for related past issuesRelated issues list
3. Hypothesis FormationForm hypotheses with confidence scoresRanked hypotheses
4. Root Cause Analysis5 parallel agents investigateConfirmed root cause
5. Fix DesignDesign approach based on RCAFix specification
6. ImplementationApply fix with testsWorking code
7. ValidationVerify fix resolves issueEvidence
8. PreventionHow to prevent recurrencePrevention plan
9. RunbookCreate/update runbook entryRunbook
10. Lessons LearnedCapture knowledgePersisted learnings
11. Commit and PRCreate PR with fixMerged PR

Phase 1: Understand the Issue

gh issue view $ARGUMENTS --json title,body,labels,assignees,comments
gh pr list --search "issue:$ARGUMENTS"
gh issue view $ARGUMENTS --comments

Phase 2: Similar Issue Detection

See Similar Issue Search for patterns.

gh issue list --search "[key error message]" --state all
mcp__memory__search_nodes(query="issue [error type] fix")
Similar IssueSimilarityStatusRelevant?
#10185%ClosedYes

Determine: Regression? Variant? New issue?


Phase 3: Hypothesis Formation

See Hypothesis-Based RCA for confidence scoring.

## Hypothesis 1: [Brief name]
**Confidence:** [0-100]%
**Description:** [What might cause the issue]
**Test:** [How to verify]
ConfidenceMeaning
90-100%Near certain
70-89%Highly likely
50-69%Probable
30-49%Possible
0-29%Unlikely

Phase 4: Root Cause Analysis (5 Agents)

Launch ALL 5 agents in parallel with run_in_background=True:

  1. debug-investigator: Root cause tracing
  2. debug-investigator: Impact analysis
  3. backend-system-architect: Backend fix design
  4. frontend-ui-developer: Frontend fix design
  5. test-generator: Test requirements

Each agent outputs structured JSON with findings and SUMMARY line.


Phase 5: Fix Design

## Fix Design for Issue #$ARGUMENTS

### Root Cause (Confirmed)
[Description]

### Proposed Fix
[Approach]

### Files to Modify
| File | Change | Reason |
|------|--------|--------|
| [file] | MODIFY | [why] |

### Risks
- [Risk 1]

### Rollback Plan
[How to revert]

Phase 6: Implementation

CRITICAL: Feature Branch Required

NEVER commit directly to main or dev. Always create a feature branch:

# Determine base branch
BASE_BRANCH=$(git remote show origin | grep 'HEAD branch' | cut -d: -f2 | tr -d ' ')

# Create feature branch (MANDATORY)
git checkout $BASE_BRANCH && git pull origin $BASE_BRANCH
git checkout -b issue/$ARGUMENTS-fix

CRITICAL: Regression Test Required

A fix without a test is incomplete. Add test BEFORE implementing fix:

# 1. Write test that reproduces the bug (should FAIL)
# 2. Implement the fix
# 3. Verify test now PASSES

Guidelines:

  • Make minimal, focused changes
  • Add proper error handling
  • Add regression test FIRST (MANDATORY)
  • DO NOT over-engineer
  • DO NOT commit directly to protected branches

Phase 7: Validation

# Backend
poetry run ruff format --check app/
poetry run pytest tests/unit/ -v --tb=short

# Frontend
npm run lint && npm run typecheck && npm run test

Phase 8: Prevention Recommendations

CRITICAL: Prevention must include at least one of:

  1. Automated test - CI catches similar issues (PREFERRED)
  2. Validation rule - Schema/lint rule prevents bad state
  3. Process check - Review checklist item

See Prevention Patterns for full template.

CategoryExamplesEffectiveness
Automated testUnit/integration test in CIHIGH - catches before merge
Validation ruleSchema check, lint ruleHIGH - catches on save/commit
ArchitectureBetter error boundariesMEDIUM
ProcessReview checklist itemLOW - human-dependent

Phase 9: Runbook Generation

# Runbook: [Issue Type]

## Symptoms
- [Observable symptom]

## Diagnosis Steps
1. Check [X] by running: `[command]`

## Resolution Steps
1. [Step 1]

## Prevention
- [How to prevent]

Store in memory for future reference.


Phase 10: Lessons Learned

mcp__memory__create_entities(entities=[{
  "name": "lessons-issue-$ARGUMENTS",
  "entityType": "LessonsLearned",
  "observations": [
    "root_cause: [brief]",
    "key_learning: [most important]",
    "prevention: [recommendation]"
  ]
}])

Phase 11: Commit and PR

git add .
git commit -m "fix(#$ARGUMENTS): [Brief description]

Root cause: [one line]
Prevention: [recommendation]"

git push -u origin issue/$ARGUMENTS-fix
gh pr create --base dev --title "fix(#$ARGUMENTS): [description]"

Key Decisions

DecisionChoiceRationale
Feature branchMANDATORYNever commit to main/dev directly
Regression testMANDATORYFix without test is incomplete
Hypothesis confidence0-100% scaleQuantifies certainty
Similar issue searchBefore hypothesisLeverage past solutions
Prevention analysisMandatory phaseBreak recurring issue cycle
Runbook generationTemplate-basedConsistent documentation

Related Skills

  • commit - Commit issue fixes
  • debug-investigator - Debug complex issues
  • issue-progress-tracking - Auto-updates from commits
  • remember - Store lessons learned

Version: 2.0.0 (January 2026)

Install

Download ZIP
Requires askill CLI v1.0+

AI Quality Score

95/100Analyzed 2/10/2026

An exceptionally detailed and actionable skill for resolving GitHub issues. It covers the full lifecycle from root cause analysis to prevention and documentation, using specific tools and structured phases.

95
100
90
100
95

Metadata

Licenseunknown
Version2.0.1
Updated2/8/2026
PublisherNeverSight

Tags

ci-cdgithubgithub-actionslintingobservabilitytesting