diff --git a/.claude/commands/issue/execute.md b/.claude/commands/issue/execute.md index d3d1d409..e7ee1055 100644 --- a/.claude/commands/issue/execute.md +++ b/.claude/commands/issue/execute.md @@ -1,7 +1,7 @@ --- name: execute description: Execute queue with DAG-based parallel orchestration (one commit per solution) -argument-hint: "[--worktree []] [--queue ]" +argument-hint: "--queue [--worktree []]" allowed-tools: TodoWrite(*), Bash(*), Read(*), AskUserQuestion(*) --- @@ -19,14 +19,57 @@ Minimal orchestrator that dispatches **solution IDs** to executors. Each executo - **Executor handles all tasks within a solution sequentially** - **Single worktree for entire queue**: One worktree isolates ALL queue execution from main workspace +## Queue ID Requirement (MANDATORY) + +**Queue ID is REQUIRED.** You MUST specify which queue to execute via `--queue `. + +### If Queue ID Not Provided + +When `--queue` parameter is missing, you MUST: + +1. **List available queues** by running: +```javascript +const result = Bash('ccw issue queue list --brief --json'); +const index = JSON.parse(result); +``` + +2. **Display available queues** to user: +``` +Available Queues: +ID Status Progress Issues +----------------------------------------------------------- +→ QUE-20251215-001 active 3/10 ISS-001, ISS-002 + QUE-20251210-002 active 0/5 ISS-003 + QUE-20251205-003 completed 8/8 ISS-004 +``` + +3. **Stop and ask user** to specify which queue to execute: +```javascript +AskUserQuestion({ + questions: [{ + question: "Which queue would you like to execute?", + header: "Queue", + multiSelect: false, + options: index.queues + .filter(q => q.status === 'active') + .map(q => ({ + label: q.id, + description: `${q.status}, ${q.completed_solutions || 0}/${q.total_solutions || 0} completed, Issues: ${q.issue_ids.join(', ')}` + })) + }] +}) +``` + +4. **After user selection**, continue execution with the selected queue ID. + +**DO NOT auto-select queues.** Explicit user confirmation is required to prevent accidental execution of wrong queue. + ## Usage ```bash -/issue:execute # Execute active queue(s) -/issue:execute --queue QUE-xxx # Execute specific queue -/issue:execute --worktree # Execute entire queue in isolated worktree -/issue:execute --worktree --queue QUE-xxx -/issue:execute --worktree /path/to/existing/worktree # Resume in existing worktree +/issue:execute --queue QUE-xxx # Execute specific queue (REQUIRED) +/issue:execute --queue QUE-xxx --worktree # Execute in isolated worktree +/issue:execute --queue QUE-xxx --worktree /path/to/existing/worktree # Resume ``` **Parallelism**: Determined automatically by task dependency DAG (no manual control) @@ -44,13 +87,18 @@ Minimal orchestrator that dispatches **solution IDs** to executors. Each executo ## Execution Flow ``` -Phase 0 (if --worktree): Setup Queue Worktree +Phase 0: Validate Queue ID (REQUIRED) + ├─ If --queue provided → use specified queue + ├─ If --queue missing → list queues, prompt user to select + └─ Store QUEUE_ID for all subsequent commands + +Phase 0.5 (if --worktree): Setup Queue Worktree ├─ Create ONE worktree for entire queue: .ccw/worktrees/queue- ├─ All subsequent execution happens in this worktree └─ Main workspace remains clean and untouched Phase 1: Get DAG & User Selection - ├─ ccw issue queue dag [--queue QUE-xxx] → { parallel_batches: [["S-1","S-2"], ["S-3"]] } + ├─ ccw issue queue dag --queue ${QUEUE_ID} → { parallel_batches: [["S-1","S-2"], ["S-3"]] } └─ AskUserQuestion → executor type (codex|gemini|agent), dry-run mode, worktree mode Phase 2: Dispatch Parallel Batch (DAG-driven) @@ -75,11 +123,65 @@ Phase 4 (if --worktree): Worktree Completion ## Implementation +### Phase 0: Validate Queue ID + +```javascript +// Check if --queue was provided +let QUEUE_ID = args.queue; + +if (!QUEUE_ID) { + // List available queues + const listResult = Bash('ccw issue queue list --brief --json').trim(); + const index = JSON.parse(listResult); + + if (index.queues.length === 0) { + console.log('No queues found. Use /issue:queue to create one first.'); + return; + } + + // Filter active queues only + const activeQueues = index.queues.filter(q => q.status === 'active'); + + if (activeQueues.length === 0) { + console.log('No active queues found.'); + console.log('Available queues:', index.queues.map(q => `${q.id} (${q.status})`).join(', ')); + return; + } + + // Display and prompt user + console.log('\nAvailable Queues:'); + console.log('ID'.padEnd(22) + 'Status'.padEnd(12) + 'Progress'.padEnd(12) + 'Issues'); + console.log('-'.repeat(70)); + for (const q of index.queues) { + const marker = q.id === index.active_queue_id ? '→ ' : ' '; + console.log(marker + q.id.padEnd(20) + q.status.padEnd(12) + + `${q.completed_solutions || 0}/${q.total_solutions || 0}`.padEnd(12) + + q.issue_ids.join(', ')); + } + + const answer = AskUserQuestion({ + questions: [{ + question: "Which queue would you like to execute?", + header: "Queue", + multiSelect: false, + options: activeQueues.map(q => ({ + label: q.id, + description: `${q.completed_solutions || 0}/${q.total_solutions || 0} completed, Issues: ${q.issue_ids.join(', ')}` + })) + }] + }); + + QUEUE_ID = answer['Queue']; +} + +console.log(`\n## Executing Queue: ${QUEUE_ID}\n`); +``` + ### Phase 1: Get DAG & User Selection ```javascript -// Get dependency graph and parallel batches -const dagJson = Bash(`ccw issue queue dag`).trim(); +// Get dependency graph and parallel batches (QUEUE_ID required) +const dagJson = Bash(`ccw issue queue dag --queue ${QUEUE_ID}`).trim(); const dag = JSON.parse(dagJson); if (dag.error || dag.ready_count === 0) { @@ -298,8 +400,8 @@ ccw issue done ${solutionId} --fail --reason '{"task_id": "TX", "error_type": "t ### Phase 3: Check Next Batch ```javascript -// Refresh DAG after batch completes -const refreshedDag = JSON.parse(Bash(`ccw issue queue dag`).trim()); +// Refresh DAG after batch completes (use same QUEUE_ID) +const refreshedDag = JSON.parse(Bash(`ccw issue queue dag --queue ${QUEUE_ID}`).trim()); console.log(` ## Batch Complete @@ -309,9 +411,9 @@ console.log(` `); if (refreshedDag.ready_count > 0) { - console.log('Run `/issue:execute` again for next batch.'); + console.log(`Run \`/issue:execute --queue ${QUEUE_ID}\` again for next batch.`); // Note: If resuming, pass existing worktree path: - // /issue:execute --worktree + // /issue:execute --queue ${QUEUE_ID} --worktree } ``` @@ -367,10 +469,12 @@ if (useWorktree && refreshedDag.ready_count === 0 && refreshedDag.completed_coun ┌─────────────────────────────────────────────────────────────────┐ │ Orchestrator │ ├─────────────────────────────────────────────────────────────────┤ -│ 0. (if --worktree) Create ONE worktree for entire queue │ +│ 0. Validate QUEUE_ID (required, or prompt user to select) │ +│ │ +│ 0.5 (if --worktree) Create ONE worktree for entire queue │ │ → .ccw/worktrees/queue-exec- │ │ │ -│ 1. ccw issue queue dag │ +│ 1. ccw issue queue dag --queue ${QUEUE_ID} │ │ → { parallel_batches: [["S-1","S-2"], ["S-3"]] } │ │ │ │ 2. Dispatch batch 1 (parallel, SAME worktree): │ @@ -405,8 +509,19 @@ if (useWorktree && refreshedDag.ready_count === 0 && refreshedDag.completed_coun ## CLI Endpoint Contract -### `ccw issue queue dag` -Returns dependency graph with parallel batches (solution-level): +### `ccw issue queue list --brief --json` +Returns queue index for selection (used when --queue not provided): +```json +{ + "active_queue_id": "QUE-20251215-001", + "queues": [ + { "id": "QUE-20251215-001", "status": "active", "issue_ids": ["ISS-001"], "total_solutions": 5, "completed_solutions": 2 } + ] +} +``` + +### `ccw issue queue dag --queue ` +Returns dependency graph with parallel batches (solution-level, **--queue required**): ```json { "queue_id": "QUE-...", diff --git a/.codex/prompts/issue-execute.md b/.codex/prompts/issue-execute.md index 9868911c..db1fb137 100644 --- a/.codex/prompts/issue-execute.md +++ b/.codex/prompts/issue-execute.md @@ -1,6 +1,6 @@ --- description: Execute all solutions from issue queue with git commit after each solution -argument-hint: "[--worktree []] [--queue ]" +argument-hint: "--queue [--worktree []]" --- # Issue Execute (Codex Version) @@ -9,6 +9,49 @@ argument-hint: "[--worktree []] [--queue ]" **Serial Execution**: Execute solutions ONE BY ONE from the issue queue via `ccw issue next`. For each solution, complete all tasks sequentially (implement → test → verify), then commit once per solution with formatted summary. Continue autonomously until queue is empty. +## Queue ID Requirement (MANDATORY) + +**Queue ID is REQUIRED.** You MUST specify which queue to execute via `--queue `. + +### If Queue ID Not Provided + +When `--queue` parameter is missing, you MUST: + +1. **List available queues** by running: +```javascript +const result = shell_command({ command: "ccw issue queue list --brief --json" }) +``` + +2. **Parse and display queues** to user: +``` +Available Queues: +ID Status Progress Issues +----------------------------------------------------------- +→ QUE-20251215-001 active 3/10 ISS-001, ISS-002 + QUE-20251210-002 active 0/5 ISS-003 + QUE-20251205-003 completed 8/8 ISS-004 +``` + +3. **Stop and ask user** to specify which queue to execute: +```javascript +AskUserQuestion({ + questions: [{ + question: "Which queue would you like to execute?", + header: "Queue", + multiSelect: false, + options: [ + // Generate from parsed queue list - only show active/pending queues + { label: "QUE-20251215-001", description: "active, 3/10 completed, Issues: ISS-001, ISS-002" }, + { label: "QUE-20251210-002", description: "active, 0/5 completed, Issues: ISS-003" } + ] + }] +}) +``` + +4. **After user selection**, continue execution with the selected queue ID. + +**DO NOT auto-select queues.** Explicit user confirmation is required to prevent accidental execution of wrong queue. + ## Worktree Mode (Recommended for Parallel Execution) When `--worktree` is specified, create or use a git worktree to isolate work. @@ -77,7 +120,8 @@ cd "${WORKTREE_PATH}" **Worktree Execution Pattern**: ``` -1. [WORKTREE] ccw issue next → auto-redirects to main repo's .workflow/ +0. [MAIN REPO] Validate queue ID (--queue required, or prompt user to select) +1. [WORKTREE] ccw issue next --queue → auto-redirects to main repo's .workflow/ 2. [WORKTREE] Implement all tasks, run tests, git commit 3. [WORKTREE] ccw issue done → auto-redirects to main repo 4. Repeat from step 1 @@ -177,10 +221,12 @@ echo "Branch '${WORKTREE_NAME}' kept. Merge manually when ready." ## Execution Flow ``` -INIT: Fetch first solution via ccw issue next +STEP 0: Validate queue ID (--queue required, or prompt user to select) + +INIT: Fetch first solution via ccw issue next --queue WHILE solution exists: - 1. Receive solution JSON from ccw issue next + 1. Receive solution JSON from ccw issue next --queue 2. Execute all tasks in solution.tasks sequentially: FOR each task: - IMPLEMENT: Follow task.implementation steps @@ -188,7 +234,7 @@ WHILE solution exists: - VERIFY: Check task.acceptance criteria 3. COMMIT: Stage all files, commit once with formatted summary 4. Report completion via ccw issue done - 5. Fetch next solution via ccw issue next + 5. Fetch next solution via ccw issue next --queue WHEN queue empty: Output final summary @@ -196,11 +242,14 @@ WHEN queue empty: ## Step 1: Fetch First Solution +**Prerequisite**: Queue ID must be determined (either from `--queue` argument or user selection in Step 0). + Run this command to get your first solution: ```javascript // ccw auto-detects worktree and uses main repo's .workflow/ -const result = shell_command({ command: "ccw issue next" }) +// QUEUE_ID is required - obtained from --queue argument or user selection +const result = shell_command({ command: `ccw issue next --queue ${QUEUE_ID}` }) ``` This returns JSON with the full solution definition: @@ -494,11 +543,12 @@ shell_command({ ## Step 5: Continue to Next Solution -Fetch next solution: +Fetch next solution (using same QUEUE_ID from Step 0/1): ```javascript // ccw auto-detects worktree -const result = shell_command({ command: "ccw issue next" }) +// Continue using the same QUEUE_ID throughout execution +const result = shell_command({ command: `ccw issue next --queue ${QUEUE_ID}` }) ``` **Output progress:** @@ -567,18 +617,28 @@ When `ccw issue next` returns `{ "status": "empty" }`: | Command | Purpose | |---------|---------| -| `ccw issue next` | Fetch next solution from queue (auto-selects from active queues) | -| `ccw issue next --queue QUE-xxx` | Fetch from specific queue | +| `ccw issue queue list --brief --json` | List all queues (for queue selection) | +| `ccw issue next --queue QUE-xxx` | Fetch next solution from specified queue (**--queue required**) | | `ccw issue done ` | Mark solution complete with result (auto-detects queue) | | `ccw issue done --fail --reason "..."` | Mark solution failed with structured reason | | `ccw issue retry --queue QUE-xxx` | Reset failed items in specific queue | ## Start Execution -Begin by running: +**Step 0: Validate Queue ID** + +If `--queue` was NOT provided in the command arguments: +1. Run `ccw issue queue list --brief --json` +2. Display available queues to user +3. Ask user to select a queue via `AskUserQuestion` +4. Store selected queue ID for all subsequent commands + +**Step 1: Fetch First Solution** + +Once queue ID is confirmed, begin by running: ```bash -ccw issue next +ccw issue next --queue ``` Then follow the solution lifecycle for each solution until queue is empty. diff --git a/README.md b/README.md index 796012f6..cf04fe56 100644 --- a/README.md +++ b/README.md @@ -281,6 +281,9 @@ CCW provides comprehensive documentation to help you get started quickly and mas - [**Dashboard Guide**](DASHBOARD_GUIDE.md) - Dashboard user guide and interface overview - [**Dashboard Operations**](DASHBOARD_OPERATIONS_EN.md) - Detailed operation instructions +### 🔄 **Workflow Guides** +- [**Issue Loop Workflow**](docs/workflows/ISSUE_LOOP_WORKFLOW.md) - Batch issue processing with two-phase lifecycle (accumulate → resolve) + ### 🏗️ **Architecture & Design** - [**Architecture Overview**](ARCHITECTURE.md) - System design and core components - [**Project Introduction**](PROJECT_INTRODUCTION.md) - Detailed project overview diff --git a/docs/workflows/ISSUE_LOOP_WORKFLOW.md b/docs/workflows/ISSUE_LOOP_WORKFLOW.md new file mode 100644 index 00000000..0ed22c01 --- /dev/null +++ b/docs/workflows/ISSUE_LOOP_WORKFLOW.md @@ -0,0 +1,435 @@ +# CCW Issue Loop 工作流完全指南 + +> 两阶段生命周期设计，支持在项目迭代中积累问题并集中解决 + +--- + +## 目录 + +1. [什么是 Issue Loop 工作流](#什么是-issue-loop-工作流) +2. [核心架构](#核心架构) +3. [两阶段生命周期](#两阶段生命周期) +4. [命令详解](#命令详解) +5. [使用场景](#使用场景) +6. [推荐策略](#推荐策略) +7. [串行无监管执行](#串行无监管执行) +8. [最佳实践](#最佳实践) + +--- + +## 什么是 Issue Loop 工作流 + +Issue Loop 是 CCW (Claude Code Workflow) 中的批量问题处理工作流，专为处理项目迭代过程中积累的多个问题而设计。与单次修复不同，Issue Loop 采用 **"积累 → 规划 → 队列 → 执行"** 的模式，实现问题的批量发现和集中解决。 + +### 核心理念 + +``` +传统模式：发现问题 → 立即修复 → 发现问题 → 立即修复 → ... + ↓ +Issue Loop：持续积累 → 集中规划 → 队列优化 → 批量执行 +``` + +**优势**： +- 避免频繁上下文切换 +- 冲突检测和依赖排序 +- 并行执行支持 +- 完整的追踪和审计 + +--- + +## 核心架构 + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ Issue Loop Workflow │ +├─────────────────────────────────────────────────────────────────┤ +│ Phase 1: Accumulation (积累) │ +│ /issue:discover, /issue:discover-by-prompt, /issue:new │ +├─────────────────────────────────────────────────────────────────┤ +│ Phase 2: Batch Resolution (批量解决) │ +│ /issue:plan → /issue:queue → /issue:execute │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### 数据流转 + +``` +issues.jsonl → solutions/.jsonl → queues/.json → 执行 + ↓ ↓ ↓ + Issue 记录 解决方案 优先级排序 + 冲突检测 +``` + +--- + +## 两阶段生命周期 + +### Phase 1: Accumulation (积累阶段) + +在项目正常迭代过程中，持续发现和记录问题： + +| 触发场景 | 对应命令 | 说明 | +|----------|----------|------| +| 任务完成后 Review | `/issue:discover` | 自动分析代码发现潜在问题 | +| 代码审查发现 | `/issue:new` | 手动创建结构化 Issue | +| 测试失败 | `/issue:discover-by-prompt` | 根据描述创建 Issue | +| 用户反馈 | `/issue:new` | 手动录入反馈问题 | + +**Issue 状态流转**： +``` +registered → planned → queued → executing → completed + ↓ + issue-history.jsonl +``` + +### Phase 2: Batch Resolution (批量解决阶段) + +积累足够 Issue 后，集中处理： + +``` +Step 1: /issue:plan --all-pending # 为所有待处理 Issue 生成解决方案 +Step 2: /issue:queue # 形成执行队列（冲突检测 + 排序） +Step 3: /issue:execute # 批量执行（串行或并行） +``` + +--- + +## 命令详解 + +### 积累阶段命令 + +#### `/issue:new` +手动创建结构化 Issue： +```bash +ccw issue init --title "Issue 标题" --priority P2 +``` + +#### `/issue:discover` +自动分析代码发现问题： +```bash +# 使用 gemini 进行多视角分析 +# 发现：bug、安全问题、性能问题、代码规范等 +``` + +#### `/issue:discover-by-prompt` +根据描述创建 Issue： +```bash +# 输入问题描述，自动生成结构化 Issue +``` + +### 批量解决阶段命令 + +#### `/issue:plan` +为 Issue 生成解决方案： +```bash +ccw issue plan --all-pending # 规划所有待处理 Issue +ccw issue plan ISS-001 # 规划单个 Issue +``` + +**输出**：每个 Issue 生成包含以下内容的解决方案： +- 修改点 (modification_points) +- 实现步骤 (implementation) +- 测试要求 (test) +- 验收标准 (acceptance) + +#### `/issue:queue` +形成执行队列： +```bash +ccw issue queue # 创建新队列 +ccw issue queue add # 添加到当前队列 +ccw issue queue list # 查看队列历史 +``` + +**关键功能**： +- 冲突检测：使用 Gemini CLI 分析解决方案间的文件冲突 +- 依赖排序：根据依赖关系确定执行顺序 +- 优先级加权：高优先级 Issue 优先执行 + +#### `/issue:execute` +执行队列中的解决方案： +```bash +ccw issue next # 获取下一个待执行解决方案 +ccw issue done # 标记完成 +ccw issue done --fail # 标记失败 +``` + +### 管理命令 + +```bash +ccw issue list # 列出活跃 Issue +ccw issue status # 查看 Issue 详情 +ccw issue history # 查看已完成 Issue +ccw issue update --from-queue # 从队列同步状态 +``` + +--- + +## 使用场景 + +### 场景 1: 项目迭代后的技术债务清理 + +``` +1. 完成 Sprint 功能开发 +2. 执行 /issue:discover 发现技术债务 +3. 积累一周后，执行 /issue:plan --all-pending +4. 使用 /issue:queue 形成队列 +5. 使用 codex 执行 /issue:execute 批量处理 +``` + +### 场景 2: 代码审查后的批量修复 + +``` +1. 完成 PR 代码审查 +2. 对每个发现执行 /issue:new 创建 Issue +3. 积累本次审查的所有发现 +4. 执行 /issue:plan → /issue:queue → /issue:execute +``` + +### 场景 3: 测试失败的批量处理 + +``` +1. 运行测试套件 +2. 对失败的测试执行 /issue:discover-by-prompt +3. 一次性规划所有失败修复 +4. 串行执行确保不引入新问题 +``` + +### 场景 4: 安全漏洞批量修复 + +``` +1. 安全扫描发现多个漏洞 +2. 每个漏洞创建 Issue 并标记 P1 优先级 +3. 使用 /issue:queue 自动按严重度排序 +4. 执行修复并验证 +``` + +--- + +## 推荐策略 + +### 何时使用 Issue Loop + +| 条件 | 推荐 | +|------|------| +| 问题数量 >= 3 | Issue Loop | +| 问题涉及多个模块 | Issue Loop | +| 问题间可能有依赖 | Issue Loop | +| 需要冲突检测 | Issue Loop | +| 单个简单 bug | `/workflow:lite-fix` | +| 紧急生产问题 | `/workflow:lite-fix --hotfix` | + +### 积累策略 + +**推荐阈值**： +- 积累 5-10 个 Issue 后集中处理 +- 或按时间周期（如每周五下午）统一处理 +- 紧急问题除外，立即标记 P1 并单独处理 + +### 队列策略 + +```javascript +// 冲突检测规则 +if (solution_A.files ∩ solution_B.files !== ∅) { + // 存在文件冲突，需要串行执行 + queue.addDependency(solution_A, solution_B) +} + +// 优先级排序 +sort by: + 1. priority (P1 > P2 > P3) + 2. dependencies (被依赖的先执行) + 3. complexity (低复杂度先执行) +``` + +--- + +## 串行无监管执行 + +**推荐使用 Codex 命令进行串行无监管执行**： + +```bash +codex -p "@.codex/prompts/issue-execute.md" +``` + +### 执行流程 + +``` +INIT: ccw issue next + ↓ +WHILE solution exists: + ├── 1. 解析 solution JSON + ├── 2. 逐个执行 tasks: + │ ├── IMPLEMENT: 按步骤实现 + │ ├── TEST: 运行测试验证 + │ └── VERIFY: 检查验收标准 + ├── 3. 提交代码 (每个 solution 一次 commit) + ├── 4. 报告完成: ccw issue done + └── 5. 获取下一个: ccw issue next + ↓ +COMPLETE: 输出最终报告 +``` + +### Worktree 模式（推荐并行执行） + +```bash +# 创建隔离的工作树 +codex -p "@.codex/prompts/issue-execute.md --worktree" + +# 恢复中断的执行 +codex -p "@.codex/prompts/issue-execute.md --worktree /path/to/existing" +``` + +**优势**： +- 并行执行器不冲突 +- 主工作目录保持干净 +- 执行完成后易于清理 +- 支持中断恢复 + +### 执行规则 + +1. **永不中途停止** - 持续执行直到队列为空 +2. **一次一个解决方案** - 完全完成（所有任务 + 提交 + 报告）后继续 +3. **解决方案内串行** - 每个任务的实现/测试/验证按顺序完成 +4. **测试必须通过** - 任何任务测试失败则修复后继续 +5. **每解决方案一次提交** - 所有任务共享一次 commit +6. **自我验证** - 所有验收标准必须通过 +7. **准确报告** - 使用 `ccw issue done` 报告完成 +8. **优雅处理失败** - 失败时报告并继续下一个 + +### Commit 格式 + +``` +[commit_type](scope): [solution.description] + +## Solution Summary +- **Solution-ID**: SOL-ISS-20251227-001-1 +- **Issue-ID**: ISS-20251227-001 +- **Risk/Impact/Complexity**: low/medium/low + +## Tasks Completed +- [T1] 实现用户认证: Modify src/auth/ +- [T2] 添加测试覆盖: Add tests/auth/ + +## Files Modified +- src/auth/login.ts +- tests/auth/login.test.ts + +## Verification +- All unit tests passed +- All acceptance criteria verified +``` + +--- + +## 最佳实践 + +### 1. Issue 质量 + +创建高质量的 Issue 描述： +```json +{ + "title": "清晰简洁的标题", + "context": { + "problem": "具体问题描述", + "impact": "影响范围", + "reproduction": "复现步骤（如适用）" + }, + "priority": "P1-P5" +} +``` + +### 2. Solution 审查 + +在执行前审查生成的解决方案： +```bash +ccw issue status # 查看解决方案详情 +``` + +检查点： +- 修改点是否准确 +- 测试覆盖是否充分 +- 验收标准是否可验证 + +### 3. 队列监控 + +```bash +ccw issue queue # 查看当前队列状态 +ccw issue queue list # 查看队列历史 +``` + +### 4. 失败处理 + +```bash +# 单个失败 +ccw issue done --fail --reason '{"task_id": "T1", "error": "..."}' + +# 重试失败项 +ccw issue retry --queue QUE-xxx +``` + +### 5. 历史追溯 + +```bash +ccw issue history # 查看已完成 Issue +ccw issue history --json # JSON 格式导出 +``` + +--- + +## 工作流对比 + +| 维度 | Issue Loop | lite-fix | coupled | +|------|------------|----------|---------| +| **适用场景** | 批量问题 | 单个 bug | 复杂功能 | +| **问题数量** | 3+ | 1 | 1 | +| **生命周期** | 两阶段 | 单次 | 多阶段 | +| **冲突检测** | 有 | 无 | 无 | +| **并行支持** | Worktree 模式 | 无 | 无 | +| **追踪审计** | 完整 | 基础 | 完整 | + +--- + +## 快速参考 + +### 完整流程命令 + +```bash +# 1. 积累阶段 +/issue:new # 手动创建 +/issue:discover # 自动发现 + +# 2. 规划阶段 +/issue:plan --all-pending + +# 3. 队列阶段 +/issue:queue + +# 4. 执行阶段（推荐使用 codex） +codex -p "@.codex/prompts/issue-execute.md" + +# 或手动执行 +/issue:execute +``` + +### CLI 命令速查 + +```bash +ccw issue list # 列出 Issue +ccw issue status # 查看详情 +ccw issue plan --all-pending # 批量规划 +ccw issue queue # 创建队列 +ccw issue next # 获取下一个 +ccw issue done # 标记完成 +ccw issue history # 查看历史 +``` + +--- + +## 总结 + +Issue Loop 工作流是 CCW 中处理批量问题的最佳选择，通过两阶段生命周期设计，实现了问题的高效积累和集中解决。配合 Codex 的串行无监管执行能力，可以在保证质量的同时大幅提升效率。 + +**记住**： +- 积累足够数量（5-10 个）后再集中处理 +- 使用 Codex 进行串行无监管执行 +- 利用 Worktree 模式实现并行执行 +- 保持 Issue 描述的高质量