---

name: hotfix description: Quick bug fix workflow with rollback plan. Use when fixing bugs, hotfixes, urgent issues, production bugs, or when user says "fix bug", "hotfix", "urgent fix", "production issue".

Hotfix Workflow

Fast-track workflow for fixing bugs with safety rollback plan.

IMPORTANT: Read Architecture First

Before fixing, you MUST read the appropriate architecture reference:

Global Architecture Files

Copy~/.claude/architecture/
├── clean-architecture.md    # Core principles for all projects
├── flutter-mobile.md        # Flutter + Riverpod
├── react-frontend.md        # React + Vite + TypeScript
├── go-backend.md            # Go + Gin
├── laravel-backend.md       # Laravel + PHP
├── remix-fullstack.md       # Remix fullstack
└── monorepo.md              # Monorepo structure

Project-specific (if exists)

Copy.claude/architecture/        # Project overrides

Understand the codebase structure before making changes.

Recommended Agents

Workflow Overview

Copy┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐
│1. IDENTIFY──▶│2. REPRODUCE──▶│ 3. FIX   │──▶│4. VERIFY │──▶│5. DEPLOY │
└──────────┘   └──────────┘   └──────────┘   └──────────┘   └──────────┘
                    │                              │
                    │              Fail?           │
                    │         ┌────────────────────┘
                    ▼         ▼
              ┌──────────────────┐
              │    6. ROLLBACK   │
              │   (if needed)    │
              └──────────────────┘

---

Phase 1: IDENTIFY

Goal: Identify exactly what the bug is

Actions

1. Gather information:

   • Error message / stack trace
   • Steps to reproduce
   • Expected vs actual behavior
   • Environment (prod/staging/dev)
   • Affected users/scope

2. Identify project stack and read architecture doc

3. Assess severity:

   Copy🔴 CRITICAL - Production down, data loss
   🟠 HIGH     - Major feature broken, many users affected
   🟡 MEDIUM   - Feature degraded, workaround exists
   🟢 LOW      - Minor issue, cosmetic
   

Output

Copy## Bug Report
**Severity**: [CRITICAL/HIGH/MEDIUM/LOW]
**Stack**: [Flutter/React/Go/Laravel/Remix]
**Architecture Doc**: [path]
**Error**: [error message]
**Steps**:
1. ...
2. ...
**Expected**: [what should happen]
**Actual**: [what happens]
**Environment**: [prod/staging/dev]

Gate

• Bug clearly described
• Architecture doc identified
• Severity assessed
• Scope understood

---

Phase 2: REPRODUCE & ANALYZE

Goal: Reproduce the bug and find root cause

Actions

1. Read architecture doc to understand codebase structure

2. Reproduce locally following architecture patterns

3. Find root cause using 5 Whys:

   CopyWhy did it fail? → [answer]
   Why? → [deeper answer]
   Why? → [even deeper]
   Why? → [root cause emerging]
   Why? → [ROOT CAUSE]
   

4. Identify fix location based on architecture:

   • Which layer? (from architecture doc)
   • Which file(s)?
   • What's the minimal change?

5. Check git blame:

   Copygit log --oneline -10 -- [affected_file]
   git blame [affected_file] | grep -A5 -B5 "[problem_area]"
   

Analysis Output

Copy## Root Cause Analysis
**Architecture Reference**: [path to doc]
**Affected Layer**: [layer from architecture doc]
**Root Cause**: [description]
**Introduced**: [commit/PR if known]
**Affected Files**:
- file1:123
- file2:456

**Fix Strategy**: [brief description following architecture patterns]

Gate

• Bug reproduced locally
• Root cause identified
• Fix location known (per architecture)

---

Phase 3: FIX

Goal: Implement minimal fix following architecture

Principles

1. Minimal change - Fix only what's broken
2. Follow architecture - Respect layer boundaries from doc
3. No refactoring - Save for later
4. No new features - Stay focused
5. Preserve behavior - Don't change anything else

Actions

1. Create hotfix branch:

   Copygit checkout -b hotfix/[issue-id]-[short-description]
   

2. Read architecture doc for the affected layer

3. Implement fix following architecture patterns:

   • Use correct patterns from doc
   • Follow naming conventions from doc
   • Respect layer boundaries

4. Add inline comment explaining fix:

   Copy// HOTFIX: [issue-id] - [brief description]
   // Root cause: [why this fixes it]
   [your fix code]
   

Gate

• Fix follows architecture doc
• Fix implemented minimally
• Code compiles
• No unrelated changes

---

Phase 4: VERIFY

Goal: Confirm fix works without breaking other things

Actions

1. Test the fix:

   • Original bug no longer occurs
   • Related functionality still works
   • Edge cases handled

2. Run existing tests (use command from architecture doc):

   Copyflutter test           # Flutter
   go test ./...          # Go
   bun test               # React/Remix
   php artisan test       # Laravel
   

3. Add regression test following architecture patterns:

   Copy// Test to prevent regression
   it('should [expected behavior] - fixes #[issue-id]', () => {
     // Arrange: setup that caused bug
     // Act: trigger the bug scenario
     // Assert: verify correct behavior
   });
   

4. Manual verification:

   • Reproduce original steps
   • Confirm bug is fixed
   • Test happy path
   • Test edge cases

Gate

• Original bug fixed
• All tests pass
• Regression test added (following arch patterns)
• No new issues introduced

Feedback Loop

If verification fails:

1. Note what failed
2. Return to FIX phase
3. Adjust fix (following architecture)
4. Re-verify

---

Phase 5: DEPLOY

Goal: Ship the fix safely

Actions

1. Commit with clear message:

   Copygit add .
   git commit -m "fix: [short description] (#[issue-id])
   
   Root cause: [brief explanation]
   Fix: [what was changed]
   
   Fixes #[issue-id]"
   

2. Create PR:

   Copygh pr create --title "fix: [description]" --body "$(cat <<'EOF'
   ## Summary
   Fixes #[issue-id]
   
   ## Root Cause
   [explanation]
   
   ## Fix
   [what was changed, following architecture patterns]
   
   ## Testing
   - [ ] Original bug no longer occurs
   - [ ] Regression test added
   - [ ] All tests pass
   
   ## Rollback Plan
   Revert commit: `git revert [commit-sha]`
   EOF
   )"
   

3. Deploy (if applicable):

   Copy# Follow your deployment process
   # Monitor for issues
   

Gate

• PR created/merged
• Deployed (if applicable)
• Monitoring in place

---

Phase 6: ROLLBACK (If Needed)

Goal: Quickly revert if fix causes more problems

When to Rollback

• Fix introduced new bugs
• Performance degraded
• Unexpected side effects
• Users reporting new issues

Rollback Actions

1. Quick Revert:

   Copy# Find the hotfix commit
   git log --oneline -5
   
   # Revert it
   git revert [hotfix-commit-sha]
   git push
   

2. Feature Flag (if available):

   Copy// Disable the fix temporarily
   if (!featureFlags.hotfix_123_enabled) {
     // Original behavior
   }
   

3. Redeploy previous version:

   Copy# Deploy previous known-good version
   git checkout [previous-tag]
   # Run deploy
   

Post-Rollback

1. Document what went wrong
2. Return to REPRODUCE phase
3. Analyze why fix failed (check architecture compliance)
4. Create better fix

---

Quick Reference

Architecture Docs

Hotfix vs Feature

Severity Response Time

Commit Message Format

Copyfix: [short description] (#issue-id)

Root cause: [why it happened]
Fix: [what was changed]

Fixes #[issue-id]

Rollback Checklist

• Identify rollback commit
• Test rollback locally
• Execute rollback
• Verify system stable
• Notify stakeholders
• Document learnings

---

Emergency Contacts

Add your team's emergency contacts here:

CopyOn-call: [contact]
Backend lead: [contact]
DevOps: [contact]