From a5ab3f8b267641e5a8c7056eb7f74831704670fa Mon Sep 17 00:00:00 2001 From: catlog22 Date: Tue, 30 Dec 2025 22:15:16 +0800 Subject: [PATCH] feat(docs): enhance issue planning and queue documentation with new guidelines and commands --- .codex/prompts/issue-plan.md | 47 +++++++++++++++++++++++++++++++++- .codex/prompts/issue-queue.md | 48 ++++++++++++++++++++++++++++++++--- 2 files changed, 91 insertions(+), 4 deletions(-) diff --git a/.codex/prompts/issue-plan.md b/.codex/prompts/issue-plan.md index 730b62d6..8d4ed6db 100644 --- a/.codex/prompts/issue-plan.md +++ b/.codex/prompts/issue-plan.md @@ -11,6 +11,23 @@ Create executable solution(s) for issue(s) and bind the selected solution to eac This workflow is **planning + registration** (no implementation): it explores the codebase just enough to produce a high-quality task breakdown that can be executed later (e.g., by `issue-execute.md`). +## Core Guidelines + +**⚠️ Data Access Principle**: Issues and solutions files can grow very large. To avoid context overflow: + +| Operation | Correct | Incorrect | +|-----------|---------|-----------| +| List issues (brief) | `ccw issue list --status pending --brief` | `Read('issues.jsonl')` | +| Read issue details | `ccw issue status --json` | `Read('issues.jsonl')` | +| Update status | `ccw issue update --status ...` | Direct file edit | +| Bind solution | `ccw issue bind ` | Direct file edit | + +**Output Options**: +- `--brief`: JSON with minimal fields (id, title, status, priority, tags) +- `--json`: Full JSON (for detailed processing) + +**ALWAYS** use CLI commands for CRUD operations. **NEVER** read entire `issues.jsonl` or `solutions/*.jsonl` directly. + ## Inputs - **Explicit issues**: comma-separated IDs, e.g. `ISS-123,ISS-124` @@ -91,10 +108,38 @@ ccw issue solution --data '{"description":"...", "approach":"...", "t ### Step 6: Detect cross-issue file conflicts (best-effort) Across the issues planned in this run: -- Build a set of touched files from each solution’s `modification_points.file` (and/or task `scope` when explicit files are missing). +- Build a set of touched files from each solution's `modification_points.file` (and/or task `scope` when explicit files are missing). - If the same file appears in multiple issues, add it to `conflicts` with all involved issue IDs. - Recommend a safe execution order (sequential) when conflicts exist. +### Step 7: Update issue status + +After binding, update issue status to `planned`: +```bash +ccw issue update --status planned +``` + +## Quality Checklist + +Before completing, verify: + +- [ ] All input issues have solutions in `solutions/{issue-id}.jsonl` +- [ ] Single solution issues are auto-bound (`bound_solution_id` set) +- [ ] Multi-solution issues returned in `pending_selection` for user choice +- [ ] Each solution has executable tasks with `modification_points` +- [ ] Task acceptance criteria are quantified (not vague) +- [ ] Conflicts detected and reported (if multiple issues touch same files) +- [ ] Issue status updated to `planned` after binding + +## Error Handling + +| Error | Resolution | +|-------|------------| +| Issue not found | Auto-create via `ccw issue init` | +| No solutions generated | Display error, suggest manual planning | +| User cancels selection | Skip issue, continue with others | +| File conflicts | Detect and suggest resolution order | + ## Done Criteria - A bound solution exists for each issue unless explicitly deferred for user selection. diff --git a/.codex/prompts/issue-queue.md b/.codex/prompts/issue-queue.md index b77a0085..c13be7c2 100644 --- a/.codex/prompts/issue-queue.md +++ b/.codex/prompts/issue-queue.md @@ -1,6 +1,6 @@ --- description: Form execution queue from bound solutions (orders solutions, detects conflicts, assigns groups) -argument-hint: "[--issue ]" +argument-hint: "[--issue ] [--append ]" --- # Issue Queue (Codex Version) @@ -11,10 +11,32 @@ Create an ordered execution queue from all bound solutions. Analyze inter-soluti This workflow is **ordering only** (no execution): it reads bound solutions, detects conflicts, and produces a queue file that `issue-execute.md` can consume. +**Design Principle**: Queue items are **solutions**, not individual tasks. Each executor receives a complete solution with all its tasks. + +## Core Guidelines + +**⚠️ Data Access Principle**: Issues and queue files can grow very large. To avoid context overflow: + +| Operation | Correct | Incorrect | +|-----------|---------|-----------| +| List issues (brief) | `ccw issue list --status planned --brief` | `Read('issues.jsonl')` | +| List queue (brief) | `ccw issue queue --brief` | `Read('queues/*.json')` | +| Read issue details | `ccw issue status --json` | `Read('issues.jsonl')` | +| Get next item | `ccw issue next --json` | `Read('queues/*.json')` | +| Update status | `ccw issue update --status ...` | Direct file edit | +| Sync from queue | `ccw issue update --from-queue` | Direct file edit | + +**Output Options**: +- `--brief`: JSON with minimal fields (id, status, counts) +- `--json`: Full JSON (for detailed processing) + +**ALWAYS** use CLI commands for CRUD operations. **NEVER** read entire `issues.jsonl` or `queues/*.json` directly. + ## Inputs - **All planned**: Default behavior → queue all issues with `planned` status and bound solutions - **Specific issue**: `--issue ` → queue only that issue's solution +- **Append mode**: `--append ` → append issue to active queue (don't create new) ## Output Requirements @@ -176,18 +198,27 @@ Group assignment: ### Step 7: Update Issue Statuses -For each queued issue, update status to `queued`: +**MUST use CLI command** (NOT direct file operations): ```bash +# Option 1: Batch update from queue (recommended) +ccw issue update --from-queue # Use active queue +ccw issue update --from-queue QUE-xxx # Use specific queue + +# Option 2: Individual issue update ccw issue update --status queued ``` +**⚠️ IMPORTANT**: Do NOT directly modify `issues.jsonl`. Always use CLI command to ensure proper validation and history tracking. + ## Queue Item ID Format - Solution items: `S-1`, `S-2`, `S-3`, ... - Sequential numbering starting from 1 -## Done Criteria +## Quality Checklist + +Before completing, verify: - [ ] Exactly 2 files generated: queue JSON + index update - [ ] Queue has valid DAG (no circular dependencies) @@ -212,6 +243,16 @@ ccw issue update --status queued | Circular dependency detected | Abort, report cycle details | | Missing solution file | Skip issue, log warning | | Index file missing | Create new index | +| Index not updated | Auto-fix: Set active_queue_id to new queue | + +## Done Criteria + +- [ ] All planned issues with `bound_solution_id` are included +- [ ] Queue JSON written to `queues/{queue-id}.json` +- [ ] Index updated in `queues/index.json` with `active_queue_id` +- [ ] No circular dependencies in solution DAG +- [ ] Parallel groups have no file overlaps +- [ ] Issue statuses updated to `queued` ## Start Execution @@ -222,3 +263,4 @@ ccw issue list --status planned --json ``` Then follow the workflow to generate the queue. +