Claude-Code-Workflow/.codex/prompts/issue-queue.md

---
description: Form execution queue from bound solutions (orders solutions, detects conflicts, assigns groups)
argument-hint: "[--issue <id>]"
---

# Issue Queue (Codex Version)

## Goal

Create an ordered execution queue from all bound solutions. Analyze inter-solution file conflicts, calculate semantic priorities, and assign parallel/sequential execution groups.

This workflow is **ordering only** (no execution): it reads bound solutions, detects conflicts, and produces a queue file that `issue-execute.md` can consume.

## Inputs

- **All planned**: Default behavior → queue all issues with `planned` status and bound solutions
- **Specific issue**: `--issue <id>` → queue only that issue's solution

## Output Requirements

**Generate Files (EXACTLY 2):**
1. `.workflow/issues/queues/{queue-id}.json` - Full queue with solutions, conflicts, groups
2. `.workflow/issues/queues/index.json` - Update with new queue entry

**Return Summary:**
```json
{
  "queue_id": "QUE-YYYYMMDD-HHMMSS",
  "total_solutions": 3,
  "total_tasks": 12,
  "execution_groups": [{ "id": "P1", "type": "parallel", "count": 2 }],
  "conflicts_resolved": 1,
  "issues_queued": ["ISS-xxx", "ISS-yyy"]
}
```

## Workflow

### Step 1: Generate Queue ID

Generate queue ID ONCE at start, reuse throughout:

```bash
# Format: QUE-YYYYMMDD-HHMMSS (UTC)
QUEUE_ID="QUE-$(date -u +%Y%m%d-%H%M%S)"
```

### Step 2: Load Planned Issues

Get all issues with bound solutions:

```bash
ccw issue list --status planned --json
```

For each issue in the result:
- Extract `id`, `bound_solution_id`, `priority`
- Read solution from `.workflow/issues/solutions/{issue-id}.jsonl`
- Find the bound solution by matching `solution.id === bound_solution_id`
- Collect `files_touched` from all tasks' `modification_points.file`

Build solution list:
```json
[
  {
    "issue_id": "ISS-xxx",
    "solution_id": "SOL-xxx",
    "task_count": 3,
    "files_touched": ["src/auth.ts", "src/utils.ts"],
    "priority": "medium"
  }
]
```

### Step 3: Detect File Conflicts

Build a file → solutions mapping:

```javascript
fileModifications = {
  "src/auth.ts": ["SOL-ISS-001-1", "SOL-ISS-003-1"],
  "src/api.ts": ["SOL-ISS-002-1"]
}
```

Conflicts exist when a file has multiple solutions. For each conflict:
- Record the file and involved solutions
- Will be resolved in Step 4

### Step 4: Resolve Conflicts & Build DAG

**Resolution Rules (in priority order):**
1. Higher issue priority first: `critical > high > medium > low`
2. Foundation solutions first: fewer dependencies
3. More tasks = higher priority: larger impact

For each file conflict:
- Apply resolution rules to determine order
- Add dependency edge: later solution `depends_on` earlier solution
- Record rationale

**Semantic Priority Formula:**
```
Base: critical=0.9, high=0.7, medium=0.5, low=0.3
Boost: task_count>=5 → +0.1, task_count>=3 → +0.05
Final: clamp(base + boost, 0.0, 1.0)
```

### Step 5: Assign Execution Groups

- **Parallel (P1, P2, ...)**: Solutions with NO file overlaps between them
- **Sequential (S1, S2, ...)**: Solutions that share files must run in order

Group assignment:
1. Start with all solutions in potential parallel group
2. For each file conflict, move later solution to sequential group
3. Assign group IDs: P1 for first parallel batch, S2 for first sequential, etc.

### Step 6: Generate Queue Files

**Queue file structure** (`.workflow/issues/queues/{QUEUE_ID}.json`):

```json
{
  "id": "QUE-20251228-120000",
  "status": "active",
  "issue_ids": ["ISS-001", "ISS-002"],
  "solutions": [
    {
      "item_id": "S-1",
      "issue_id": "ISS-001",
      "solution_id": "SOL-ISS-001-1",
      "status": "pending",
      "execution_order": 1,
      "execution_group": "P1",
      "depends_on": [],
      "semantic_priority": 0.8,
      "files_touched": ["src/auth.ts"],
      "task_count": 3
    }
  ],
  "conflicts": [
    {
      "type": "file_conflict",
      "file": "src/auth.ts",
      "solutions": ["S-1", "S-3"],
      "resolution": "sequential",
      "resolution_order": ["S-1", "S-3"],
      "rationale": "S-1 creates auth module, S-3 extends it"
    }
  ],
  "execution_groups": [
    { "id": "P1", "type": "parallel", "solutions": ["S-1", "S-2"], "solution_count": 2 },
    { "id": "S2", "type": "sequential", "solutions": ["S-3"], "solution_count": 1 }
  ]
}
```

**Update index** (`.workflow/issues/queues/index.json`):

```json
{
  "active_queue_id": "QUE-20251228-120000",
  "queues": [
    {
      "id": "QUE-20251228-120000",
      "status": "active",
      "issue_ids": ["ISS-001", "ISS-002"],
      "total_solutions": 3,
      "completed_solutions": 0,
      "created_at": "2025-12-28T12:00:00Z"
    }
  ]
}
```

### Step 7: Update Issue Statuses

For each queued issue, update status to `queued`:

```bash
ccw issue update <issue-id> --status queued
```

## Queue Item ID Format

- Solution items: `S-1`, `S-2`, `S-3`, ...
- Sequential numbering starting from 1

## Done Criteria

- [ ] Exactly 2 files generated: queue JSON + index update
- [ ] Queue has valid DAG (no circular dependencies)
- [ ] All file conflicts resolved with rationale
- [ ] Semantic priority calculated for each solution (0.0-1.0)
- [ ] Execution groups assigned (P* for parallel, S* for sequential)
- [ ] Issue statuses updated to `queued`
- [ ] Summary JSON returned with correct shape

## Validation Rules

1. **No cycles**: If resolution creates a cycle, abort and report
2. **Parallel safety**: Solutions in same P* group must have NO file overlaps
3. **Sequential order**: Solutions in S* group must be in correct dependency order
4. **Single queue ID**: Use the same queue ID throughout (generated in Step 1)

## Error Handling

| Situation | Action |
|-----------|--------|
| No planned issues | Return empty queue summary |
| Circular dependency detected | Abort, report cycle details |
| Missing solution file | Skip issue, log warning |
| Index file missing | Create new index |

## Start Execution

Begin by listing planned issues:

```bash
ccw issue list --status planned --json
```

Then follow the workflow to generate the queue.