/dev:bugfix

This workflow automates the entire bug issue fix cycle:

Full bug fix cycle automation (issue creation → branch → fix → PR)

Overview#

This workflow automates the entire bug issue fix cycle:

Bug report creation (optional)
Branch creation
Bug fix work
Unit test writing (frontend + backend)
Test execution and verification
PR creation and merge

Usage#

# 기존 버그 이슈로 시작
/dev:bugfix {issue_number}

# 새 버그 리포트부터 시작
/dev:bugfix --new [이미지_경로]  " 버그 설명 "

Parameters#

Parameter	Required	Description
`issue_number`	✅*	Existing bug issue number
`--new`	✅*	New bug report creation mode
`--no-merge`	❌	PR creation only (no merge)
`--skip-tests`	❌	Skip tests (for urgent hotfixes)
`--base`	❌	Base branch (default: development)

*Either issue_number or --new is required

Option Examples#

# PR only (no merge)
/dev:bugfix 123 --no-merge

# Skip tests (urgent)
/dev:bugfix 123 --skip-tests

# Change base branch
/dev:bugfix 123 --base main

# New bug + image analysis
/dev:bugfix --new /tmp/screenshot.png  " App crash "

Execution Flow#

┌─────────────────────────────────────────────────────────────────┐
│                    /dev:bugfix                                   │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Step 0: Blast Radius Analysis (before fix)                     │
│  ├── Identify all callers/dependents of affected code (Grep)    │
│  ├── Map test coverage of affected areas                        │
│  ├── Flag untested areas that could regress                     │
│  └── Risk assessment:                                           │
│       LOW  (≤5 files)  → proceed                                │
│       MED  (5-15 files or multi-layer) → confirm with user      │
│       HIGH ( > 15 files or core module)  → suggest /plan → /build │
│                                                                 │
│  Step 1: Bug Report Creation (with --new option)                │
│  ├── Call /bug-report (image analysis)                          │
│  ├── Create ZenHub issue                                        │
│  └── Result: obtain issue_number                                │
│                                                                 │
│  Step 2: Query Issue Info                                        │
│  ├── mcp__zenhub__searchLatestIssues                           │
│  ├── Extract issue type, title, body                            │
│  └── Analyze bug cause                                          │
│                                                                 │
│  Step 3: Branch Creation                                         │
│  ├── fix/{number}-{slug} format                                 │
│  ├── issue-state-agent →  " In Progress "                           │
│  └── Based on development branch                                │
│                                                                 │
│  Step 4: Bug Fix Work                                            │
│  ├── Analyze issue body → identify cause                        │
│  ├── Search related code                                        │
│  ├── Fix code                                                    │
│  └── Create incremental commits                                 │
│                                                                 │
│  Step 4.5: Existing Test Verification (Baseline)                 │
│  ├── Run existing tests for related packages                    │
│  ├── On failure → fix code or existing tests first              │
│  └── Record baseline pass rate                                  │
│                                                                 │
│  Step 5: Test Writing (required, delegated to cc-flutter-dev)    │
│  ├── Frontend tests                                              │
│  │   ├── unit-test-agent → UseCase parameter passing tests      │
│  │   ├── bloc-test-agent → BLoC state transition verification   │
│  │   └── widget-test-agent → State copyWith rendering tests     │
│  ├── Backend tests                                               │
│  │   ├── Endpoint auth/permission tests                         │
│  │   ├── Filter parameter passing integration tests             │
│  │   └── Service logic unit tests (if applicable)               │
│  └── Create test commits                                        │
│                                                                 │
│  Step 6: Test Execution and Regression Verification              │
│  ├── Run all tests (existing + new)                             │
│  ├── Attempt auto-fix on failure (up to 3 times)                │
│  └── Verify baseline pass rate maintained                       │
│                                                                 │
│  Step 7: PR Creation                                             │
│  ├── gh pr create                                               │
│  ├── issue-state-agent →  " Review "                                │
│  └── Auto-link issue (Closes #{number})                         │
│                                                                 │
│  Step 8: Merge (unless --no-merge)                               │
│  ├── Wait for review                                            │
│  ├── Squash merge                                               │
│  └── Issue auto-Close via GitHub  " Closes # "   keyword             │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Detailed Implementation#

Step 0: Blast Radius Analysis#

Run before creating a branch to assess fix complexity and risk:

// 1. Identify affected code area from issue description
const affectedFiles = await Grep({ pattern: bugPattern, output_mode:  " files_with_matches "   });

// 2. Find all callers/dependents
const dependents = [];
for (const file of affectedFiles) {
  const exports = extractExports(file); // classes, functions, mixins
  for (const symbol of exports) {
    const callers = await Grep({ pattern: symbol, output_mode:  " files_with_matches "   });
    dependents.push(...callers);
  }
}
const uniqueDependents = [...new Set(dependents)];

// 3. Map test coverage
const testFiles = await Glob({ pattern:  " test/**/*_test.dart "   });
const coveredFiles = matchSourceToTest(uniqueDependents, testFiles);
const uncoveredFiles = uniqueDependents.filter(f = >   !coveredFiles.includes(f));

// 4. Risk assessment
const fileCount = uniqueDependents.length;
const layerCount = countLayers(uniqueDependents); // presentation, domain, data, backend

let riskLevel;
if (fileCount  < = 5  & &   layerCount  < = 1) {
  riskLevel =  " LOW " ;  // → proceed directly
} else if (fileCount  < = 15 || layerCount  < = 2) {
  riskLevel =  " MEDIUM " ;  // → confirm with user
} else {
  riskLevel =  " HIGH " ;  // → suggest /plan → /build workflow
}

Output:

╔════════════════════════════════════════════════════════════════╗
║  Blast Radius Analysis                                         ║
╠════════════════════════════════════════════════════════════════╣
║  Affected files: {fileCount}                                   ║
║  Layers touched: {layers}                                      ║
║  Test coverage: {coveredCount}/{totalCount} files covered       ║
║  Uncovered areas:                                              ║
║    - {uncoveredFile1}                                          ║
║    - {uncoveredFile2}                                          ║
║  Risk Level: {LOW|MEDIUM|HIGH}                                 ║
║                                                                ║
║  {recommendation}                                              ║
╚════════════════════════════════════════════════════════════════╝

LOW: 자동 진행
MEDIUM: 사용자에게 확인 요청 ("Proceed with bugfix?" / "Switch to /plan → /build?")
HIGH: /plan → /build 워크플로우 권장 (구조적 변경이 필요할 가능성 높음)

Step 1: Bug Report Creation (Optional)#

When --new option is provided:

// /bug-report 스킬 호출
const bugReport = await Skill({
  skill:  " bug-report " ,
  args: `${imagePath}  " ${description} " `
});

// Extract created issue number
const issueNumber = bugReport.issue_number;

Step 2: Query Issue Info#

// Query issue info
const issueResult = await mcp__zenhub__searchLatestIssues({
  query: issue_number.toString()
});

const issue = issueResult.find(i = >   i.number === issue_number);

// Extract bug info
const bugInfo = {
  id: issue.id,
  number: issue.number,
  title: issue.title,
  body: issue.body,           // Includes reproduction steps, expected/actual results
  severity: extractSeverity(issue.labels),
  area: extractArea(issue.labels),
};

Step 3: Branch Creation#

// Generate branch name: fix/{number}-{slug}
const slug = createSlug(bugInfo.title);
const branchName = `fix/${bugInfo.number}-${slug}`;

// Create branch
await Bash(`git checkout -b ${branchName} origin/development`);

// Pipeline move: In Progress
await mcp__zenhub__moveIssueToPipeline({
  issueId: bugInfo.id,
  pipelineId: inProgressPipelineId
});

Step 4: Bug Fix Work#

// Bug cause analysis
// 1. Identify reproduction steps from issue body
// 2. Search related code (Grep, Glob)
// 3. Infer cause

// Code fix
// - Modify related files
// - Create incremental commits

await Bash(`git commit -m  " fix(${scope}): 🐛 ${bugInfo.title} " `);

Step 5: Unit Test Writing (Required)#

Frontend + backend unit tests must be written before PR creation.

5-1. Frontend Tests

Write the following tests depending on the changed code area:

// State tests: copyWith, nullable field clearing, Equatable, etc.
// File: test/presentation/bloc/{feature}_state_test.dart
// - Verify initial state default values
// - Verify copyWith updates
// - Verify nullable field clearing (clearXxx flags)
// - Verify value preservation (existing values maintained on copyWith() call)

// BLoC tests: event handlers → state transitions
// File: test/presentation/bloc/{feature}_bloc_test.dart
// - Verify per-event state transitions with blocTest()
// - Mock Repository setUp
// - Set initial state with seed()
// - Verify sequential state changes with expect()

// UseCase tests: parameter passing and error handling
// File: test/domain/usecase/{usecase}_test.dart
// - Verify correct parameter passing on Repository calls (verify)
// - Separate success/failure cases
// - Verify Params Equatable

5-2. Backend Tests

// Integration tests: using withServerpod()
// File: backend/kobic_server/test/integration/{feature}_test.dart
// - Auth test: reject unauthenticated access to requireLogin endpoints
// - Filter parameter passing test: verify correct calls per filter
// - Combined filter test: apply all filters simultaneously
// - Pagination test: pass limit/offset parameters

// Service unit tests (on business logic changes)
// File: backend/kobic_server/test/unit/{feature}/{service}_test.dart

5-3. Test Fixture Writing Rules

// Serverpod generated DTO classes have many required fields
// → Create test fixtures via helper functions
// e.g.: _createTestBook(), _createCategory()

// Mock generation: @GenerateNiceMocks + build_runner
// → Must regenerate mocks after writing test files
await Bash(`melos exec --scope=${package} -- dart run build_runner build -d`);

5-4. Test Commit

await Bash(`git commit -m  " test(${scope}): ✅ ${bugInfo.title} 테스트 추가 " `);

Step 6: Test Execution and Verification#

// Run all tests
await Bash(`melos exec --scope=${package} -- flutter test`);

// Attempt auto-fix on failure
if (testFailed) {
  // Fix fixtures (generated class signature mismatches, etc.)
  // Build transitive dependencies (missing .g.dart, .module.dart)
  // Regenerate mocks
  // Re-run
}

// Verify all tests pass (required)
// Do not proceed with PR creation if tests fail

Step 7: PR Creation#

// Create PR
const prTitle = `fix(${scope}): 🐛 ${bugInfo.title}`;
const prBody = `
## Summary
- ${bugInfo.title} bug fix

## Changes
- ${changesSummary}

## Test Plan
- [ ] Reproduction steps verified
- [ ] Tests passed

Closes #${bugInfo.number}

🤖 Generated with [Claude Code](https://claude.com/claude-code)
`;

await Bash(`gh pr create --title  " ${prTitle} "   --body  " ${prBody} " `);

// Pipeline move: Review
await mcp__zenhub__moveIssueToPipeline({
  issueId: bugInfo.id,
  pipelineId: reviewPipelineId
});

Step 8: Merge#

// Squash merge → issue auto-Close via GitHub  " Closes # "   keyword
// No Done pipeline move needed (merge = complete)
await Bash(`gh pr merge --squash --delete-branch`);

Output Format#

On Success#

╔════════════════════════════════════════════════════════════════╗
║  Bug Cycle Complete: #123                                      ║
╠════════════════════════════════════════════════════════════════╣
║                                                                ║
║  🐛 Bug: [Bug] 로그인: 소셜 로그인 버튼 미동작                  ║
║  🌿 Branch: fix/123-social-login-button                        ║
║                                                                ║
║  📝 Commits:                                                   ║
║    1. fix(auth): 🐛 소셜 로그인 버튼 클릭 핸들러 수정           ║
║    2. test(auth): ✅ 소셜 로그인 버튼 테스트 추가               ║
║                                                                ║
║  ✅ Tests:                                                     ║
║    - FE State: 16/16 passed                                    ║
║    - FE BLoC: 10/10 passed                                     ║
║    - FE UseCase: 10/10 passed                                  ║
║    - BE Integration: 10/10 passed                              ║
║                                                                ║
║  🔀 PR: #456                                                   ║
║    - URL: https://github.com/coco-de/kobic/pull/456            ║
║    - Status: Merged ✅                                         ║
║                                                                ║
║  📊 Duration: 8m 15s                                           ║
║  🏁 Final State: CLOSED (by merge)                             ║
║                                                                ║
╚════════════════════════════════════════════════════════════════╝

On Failure#

╔════════════════════════════════════════════════════════════════╗
║  Bug Cycle Failed: #123                                        ║
╠════════════════════════════════════════════════════════════════╣
║                                                                ║
║  ❌ Failed at: Step 4 (Bug fix work)                             ║
║                                                                ║
║  Error Details:                                                ║
║    - Cause identification failed: additional info needed       ║
║    - Related code not found                                    ║
║                                                                ║
║  Current State:                                                ║
║    - Branch: fix/123-social-login (exists)                     ║
║    - Commits: 0                                                ║
║    - Pipeline: In Progress                                     ║
║    - PR: Not created                                           ║
║                                                                ║
║  Recovery Options:                                             ║
║    1. Request additional info on the issue                     ║
║    2. Manually analyze cause then retry                        ║
║    3. /dev:bugfix 123 --skip-tests                     ║
║                                                                ║
╚════════════════════════════════════════════════════════════════╝

TodoWrite Integration#

Progress Tracking#

TodoWrite([
  { content:  " Bug report creation " , status:  " completed " , activeForm:  " Bug report creation complete "   },
  { content:  " Issue info query " , status:  " in_progress " , activeForm:  " Querying issue info "   },
  { content:  " Branch creation " , status:  " pending " , activeForm:  " Branch creation pending "   },
  { content:  " Bug fix work " , status:  " pending " , activeForm:  " Bug fix pending "   },
  { content:  " Unit test writing (FE+BE) " , status:  " pending " , activeForm:  " Test writing pending "   },
  { content:  " Test execution and verification " , status:  " pending " , activeForm:  " Test execution pending "   },
  { content:  " PR creation " , status:  " pending " , activeForm:  " PR creation pending "   },
  { content:  " Merge and close " , status:  " pending " , activeForm:  " Merge pending "   },
]);

Error Handling#

Step-by-Step Recovery Strategy#

Failed Step	State	Recovery Method
Blast radius	No changes	Retry or switch to `/plan` → `/build`
Bug report	No changes	Retry `/bug-report`
Branch creation	Issue exists	Retry
Bug fix	Branch exists	Manual fix then retry
Test writing	Code modified	Fix fixtures, regenerate mocks, build transitive deps
Test execution	Tests written	Manual test fix or `--skip-tests`
PR creation	Tests passed	Run `gh pr create` manually
Merge	PR exists	Wait for CI pass then retry

Key Rules#

Verify Bug Issue Type: Only process Bug type issues
Branch Naming: Follow fix/{number}-{slug} format
Commit Message: fix({scope}): 🐛 {description} format
Tests Required (before PR): Frontend (State/BLoC/UseCase) + Backend (integration/unit) tests must be written and passed before PR creation
Separate Test Commits: Separate fix commits from test commits for easier review
Issue Link: Include Closes #{number} in PR
State Tracking: Update Pipeline state at every step

/bug-report: Bug report creation
/dev:issue: General issue cycle
/zenhub:manage: ZenHub pipeline management

issue-state-agent: Issue state management
implementation-agent: Code implementation
test-runner-agent: Test execution
pr-lifecycle-agent: PR management