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

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

# 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 "

┌─────────────────────────────────────────────────────────────────┐
│                    /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 (merge = Close, unless --no-merge)                │
│  ├── Wait for review                                            │
│  ├── Squash merge                                               │
│  ├── Issue auto-Close via GitHub  " Closes # "   keyword             │
│  └── ⭐ Verify closed (GitHub + ZenHub) + fallback              │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

// 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
}

╔════════════════════════════════════════════════════════════════╗
║  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}                                              ║
╚════════════════════════════════════════════════════════════════╝

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

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

// 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),
};

// Generate branch name: fix/{number}-{slug}
// createSlug romanizes non-ASCII and never returns  ' '   (see issue-branch-agent.md)
const slug = createSlug(bugInfo.title,  " fix " );
const branchName = `fix/${bugInfo.number}-${slug}`;
// Defense-in-depth (LANG-05): a Korean-only title must not yield  " fix/30- " .
if (!slug || branchName.endsWith( " - " )) throw new Error(`빈 slug — 브랜치명 비정상(${branchName})`);

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

// Pipeline move: In Progress (fail-closed id 해석 — undefined silent no-op 방지)
const workspace = await mcp__zenhub__getWorkspacePipelinesAndRepositories();
const inProgress = workspace.pipelines.find(p = >   p.name ===  " In Progress " );
if (!inProgress) throw new Error(` ' In Progress '   파이프라인 없음. 라이브: ${workspace.pipelines.map(p = >   p.name).join( " ,  " )}`);
await mcp__zenhub__moveIssueToPipeline({ issueId: bugInfo.id, pipelineId: inProgress.id });

// 스프린트 배정(타임라인 가시성) — 버그 이슈를 활성 스프린트에 올려 로드맵/번다운에 노출.
// 기본 on, --no-sprint 로 opt-out. 셀렉터: rules/zenhub-conventions.md →  " Sprint Selector Resolution " .
if (!options.noSprint) {
  const sprint = options.sprint ===  " next " 
     ? await mcp__zenhub__getUpcomingSprint()
    : await mcp__zenhub__getSprint();            // id 없음 = 활성
  if (sprint?.id) await mcp__zenhub__addIssuesToSprints({ issueIds: [bugInfo.id], sprintIds: [sprint.id] });
}

// 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} " `);

// 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

// 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

// 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`);

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

// 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

// 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
});

// Squash merge → issue auto-Close via GitHub  " Closes # "   keyword → ZenHub syncs to Closed
// Never move to Done (Done ≠ closed)
await Bash(`gh pr merge --squash --delete-branch`);

// ⭐ Closure verification + fallback (ZenHub two-state model)
const ghState = (await Bash(`gh issue view ${bugInfo.number} --json state -q .state`)).trim();
if (ghState !==  " CLOSED " ) {
  await Bash(`gh issue close ${bugInfo.number} --reason completed`);
}
const closed = await mcp__zenhub__searchClosedIssues({ query: `#${bugInfo.number}` });
if (!closed.find(i = >   i.number === bugInfo.number)) {
  await mcp__zenhub__updateIssue({ issueId: bugInfo.id, state:  " CLOSED "   });
}

// ⭐ Post-merge: base 브랜치로 이동 + 최신화 + 서브모듈 동기화 (필수)
//   gh pr merge --delete-branch 는 base를 pull 하지 않고, git pull 은 서브모듈 포인터만
//   갱신할 뿐 워킹트리는 체크아웃하지 않는다. git submodule update 로 base가 가리키는
//   커밋에 정렬한다 (Serverpod/Melos 모노레포 빌드/코드젠 drift 방지). 서브모듈 없으면 no-op.
await Bash(`
  git checkout development
  git pull --ff-only origin development
  git submodule sync --recursive
  git submodule update --init --recursive
`);

╔════════════════════════════════════════════════════════════════╗
║  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)                             ║
║                                                                ║
╚════════════════════════════════════════════════════════════════╝

╔════════════════════════════════════════════════════════════════╗
║  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([
  { 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 "   },
]);