Skip to content

Commit 9b1655b

Browse files
author
catlog22
committed
Add phases for issue resolution: From Brainstorm and Form Execution Queue
- Implement Phase 3: From Brainstorm to convert brainstorm session output into executable issues and solutions. - Implement Phase 4: Form Execution Queue to analyze bound solutions, resolve conflicts, and create an ordered execution queue. - Introduce new data structures for Issue and Solution schemas. - Enhance CLI commands for issue creation and queue management. - Add error handling and quality checklist for queue formation.
1 parent 248daa1 commit 9b1655b

42 files changed

Lines changed: 2844 additions & 4643 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.claude/skills/issue-resolve/SKILL.md‎

Lines changed: 277 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,277 @@
1+
---
2+
name: issue-resolve
3+
description: Unified issue resolution pipeline with source selection. Plan issues via AI exploration, convert from artifacts, import from brainstorm sessions, or form execution queues. Triggers on "issue:plan", "issue:queue", "issue:convert-to-plan", "issue:from-brainstorm", "resolve issue", "plan issue", "queue issues", "convert plan to issue".
4+
allowed-tools: Task, AskUserQuestion, TodoWrite, Read, Write, Edit, Bash, Glob, Grep, Skill
5+
---
6+
7+
# Issue Resolve
8+
9+
Unified issue resolution pipeline that orchestrates solution creation from multiple sources and queue formation for execution.
10+
11+
## Architecture Overview
12+
13+
```
14+
┌─────────────────────────────────────────────────────────────────┐
15+
│ Issue Resolve Orchestrator (SKILL.md) │
16+
│ → Source selection → Route to phase → Execute → Summary │
17+
└───────────────┬─────────────────────────────────────────────────┘
18+
│
19+
├─ AskUserQuestion: Select issue source
20+
│
21+
┌───────────┼───────────┬───────────┬───────────┐
22+
↓ ↓ ↓ ↓ │
23+
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
24+
│ Phase 1 │ │ Phase 2 │ │ Phase 3 │ │ Phase 4 │ │
25+
│ Explore │ │ Convert │ │ From │ │ Form │ │
26+
│ & Plan │ │Artifact │ │Brainstorm│ │ Queue │ │
27+
└─────────┘ └─────────┘ └─────────┘ └─────────┘ │
28+
↓ ↓ ↓ ↓ │
29+
Solutions Solutions Issue+Sol Exec Queue │
30+
(bound) (bound) (bound) (ordered) │
31+
│
32+
┌────────────────────────────────┘
33+
↓
34+
/issue:execute
35+
```
36+
37+
## Key Design Principles
38+
39+
1. **Source-Driven Routing**: AskUserQuestion selects workflow, then load single phase
40+
2. **Progressive Phase Loading**: Only read the selected phase document
41+
3. **CLI-First Data Access**: All issue/solution CRUD via `ccw issue` CLI commands
42+
4. **Auto Mode Support**: `-y` flag skips source selection (defaults to Explore & Plan)
43+
44+
## Auto Mode
45+
46+
When `--yes` or `-y`: Skip source selection, use Explore & Plan for issue IDs, or auto-detect source type for paths.
47+
48+
## Usage
49+
50+
```
51+
Skill(skill="issue-resolve", args="<task description or issue IDs>")
52+
Skill(skill="issue-resolve", args="[FLAGS] \"<input>\"")
53+
54+
# Flags
55+
-y, --yes Skip all confirmations (auto mode)
56+
--source <type> Pre-select source: plan|convert|brainstorm|queue
57+
--batch-size <n> Max issues per agent batch (plan mode, default: 3)
58+
--issue <id> Bind to existing issue (convert mode)
59+
--supplement Add tasks to existing solution (convert mode)
60+
--queues <n> Number of parallel queues (queue mode, default: 1)
61+
62+
# Examples
63+
Skill(skill="issue-resolve", args="GH-123,GH-124") # Explore & plan issues
64+
Skill(skill="issue-resolve", args="--source plan --all-pending") # Plan all pending issues
65+
Skill(skill="issue-resolve", args="--source convert \".workflow/.lite-plan/my-plan\"") # Convert artifact
66+
Skill(skill="issue-resolve", args="--source brainstorm SESSION=\"BS-rate-limiting\"") # From brainstorm
67+
Skill(skill="issue-resolve", args="--source queue") # Form execution queue
68+
Skill(skill="issue-resolve", args="-y GH-123") # Auto mode, plan single issue
69+
```
70+
71+
## Execution Flow
72+
73+
```
74+
Input Parsing:
75+
└─ Parse flags (--source, -y, --issue, etc.) and positional args
76+
77+
Source Selection:
78+
├─ --source flag provided → Route directly
79+
├─ Auto-detect from input:
80+
│ ├─ Issue IDs (GH-xxx, ISS-xxx) → Explore & Plan
81+
│ ├─ SESSION="..." → From Brainstorm
82+
│ ├─ File/folder path → Convert from Artifact
83+
│ └─ No input or --all-pending → Explore & Plan (all pending)
84+
└─ Otherwise → AskUserQuestion to select source
85+
86+
Phase Execution (load one phase):
87+
├─ Phase 1: Explore & Plan → phases/01-issue-plan.md
88+
├─ Phase 2: Convert Artifact → phases/02-convert-to-plan.md
89+
├─ Phase 3: From Brainstorm → phases/03-from-brainstorm.md
90+
└─ Phase 4: Form Queue → phases/04-issue-queue.md
91+
92+
Post-Phase:
93+
└─ Summary + Next steps recommendation
94+
```
95+
96+
### Phase Reference Documents
97+
98+
| Phase | Document | Load When | Purpose |
99+
|-------|----------|-----------|---------|
100+
| Phase 1 | [phases/01-issue-plan.md](phases/01-issue-plan.md) | Source = Explore & Plan | Batch plan issues via issue-plan-agent |
101+
| Phase 2 | [phases/02-convert-to-plan.md](phases/02-convert-to-plan.md) | Source = Convert Artifact | Convert lite-plan/session/markdown to solutions |
102+
| Phase 3 | [phases/03-from-brainstorm.md](phases/03-from-brainstorm.md) | Source = From Brainstorm | Convert brainstorm ideas to issue + solution |
103+
| Phase 4 | [phases/04-issue-queue.md](phases/04-issue-queue.md) | Source = Form Queue | Order bound solutions into execution queue |
104+
105+
## Core Rules
106+
107+
1. **Source Selection First**: Always determine source before loading any phase
108+
2. **Single Phase Load**: Only read the selected phase document, never load all phases
109+
3. **CLI Data Access**: Use `ccw issue` CLI for all issue/solution operations, NEVER read files directly
110+
4. **Content Preservation**: Each phase contains complete execution logic from original commands
111+
5. **Auto-Detect Input**: Smart input parsing reduces need for explicit --source flag
112+
113+
## Input Processing
114+
115+
### Auto-Detection Logic
116+
117+
```javascript
118+
function detectSource(input, flags) {
119+
// 1. Explicit --source flag
120+
if (flags.source) return flags.source;
121+
122+
// 2. Auto-detect from input content
123+
const trimmed = input.trim();
124+
125+
// Issue IDs pattern (GH-xxx, ISS-xxx, comma-separated)
126+
if (trimmed.match(/^[A-Z]+-\d+/i) || trimmed.includes(',')) {
127+
return 'plan';
128+
}
129+
130+
// --all-pending or empty input → plan all pending
131+
if (flags.allPending || trimmed === '') {
132+
return 'plan';
133+
}
134+
135+
// SESSION="..." pattern → brainstorm
136+
if (trimmed.includes('SESSION=')) {
137+
return 'brainstorm';
138+
}
139+
140+
// File/folder path → convert
141+
if (trimmed.match(/\.(md|json)$/) || trimmed.includes('.workflow/')) {
142+
return 'convert';
143+
}
144+
145+
// Cannot auto-detect → ask user
146+
return null;
147+
}
148+
```
149+
150+
### Source Selection (AskUserQuestion)
151+
152+
```javascript
153+
// When source cannot be auto-detected
154+
const answer = AskUserQuestion({
155+
questions: [{
156+
question: "How would you like to create/manage issue solutions?",
157+
header: "Source",
158+
multiSelect: false,
159+
options: [
160+
{
161+
label: "Explore & Plan (Recommended)",
162+
description: "AI explores codebase and generates solutions for issues"
163+
},
164+
{
165+
label: "Convert from Artifact",
166+
description: "Convert existing lite-plan, workflow session, or markdown to solution"
167+
},
168+
{
169+
label: "From Brainstorm",
170+
description: "Convert brainstorm session ideas into issue with solution"
171+
},
172+
{
173+
label: "Form Execution Queue",
174+
description: "Order bound solutions into execution queue for /issue:execute"
175+
}
176+
]
177+
}]
178+
});
179+
180+
// Route based on selection
181+
const sourceMap = {
182+
"Explore & Plan": "plan",
183+
"Convert from Artifact": "convert",
184+
"From Brainstorm": "brainstorm",
185+
"Form Execution Queue": "queue"
186+
};
187+
```
188+
189+
## Data Flow
190+
191+
```
192+
User Input (issue IDs / artifact path / session ID / flags)
193+
↓
194+
[Parse Flags + Auto-Detect Source]
195+
↓
196+
[Source Selection] ← AskUserQuestion (if needed)
197+
↓
198+
[Read Selected Phase Document]
199+
↓
200+
[Execute Phase Logic]
201+
↓
202+
[Summary + Next Steps]
203+
├─ After Plan/Convert/Brainstorm → Suggest /issue:queue or /issue:execute
204+
└─ After Queue → Suggest /issue:execute
205+
```
206+
207+
## TodoWrite Pattern
208+
209+
```json
210+
[
211+
{"content": "Select issue source", "status": "completed"},
212+
{"content": "Execute: [selected phase name]", "status": "in_progress"},
213+
{"content": "Summary & next steps", "status": "pending"}
214+
]
215+
```
216+
217+
Phase-specific sub-tasks are attached when the phase executes (see individual phase docs for details).
218+
219+
## Core Guidelines
220+
221+
**Data Access Principle**: Issues and solutions files can grow very large. To avoid context overflow:
222+
223+
| Operation | Correct | Incorrect |
224+
|-----------|---------|-----------|
225+
| List issues (brief) | `ccw issue list --status pending --brief` | `Read('issues.jsonl')` |
226+
| Read issue details | `ccw issue status <id> --json` | `Read('issues.jsonl')` |
227+
| Update status | `ccw issue update <id> --status ...` | Direct file edit |
228+
| Bind solution | `ccw issue bind <id> <sol-id>` | Direct file edit |
229+
| Batch solutions | `ccw issue solutions --status planned --brief` | Loop individual queries |
230+
231+
**Output Options**:
232+
- `--brief`: JSON with minimal fields (orchestrator use)
233+
- `--json`: Full JSON (agent use only)
234+
235+
**ALWAYS** use CLI commands for CRUD operations. **NEVER** read entire `issues.jsonl` or `solutions/*.jsonl` directly.
236+
237+
## Error Handling
238+
239+
| Error | Resolution |
240+
|-------|------------|
241+
| No source detected | Show AskUserQuestion with all 4 options |
242+
| Invalid source type | Show available sources, re-prompt |
243+
| Phase execution fails | Report error, suggest manual intervention |
244+
| No pending issues (plan) | Suggest `/issue:new` to create issues first |
245+
| No bound solutions (queue) | Suggest running plan/convert/brainstorm first |
246+
247+
## Post-Phase Next Steps
248+
249+
After successful phase execution, recommend next action:
250+
251+
```javascript
252+
// After Plan/Convert/Brainstorm (solutions created)
253+
AskUserQuestion({
254+
questions: [{
255+
question: "Solutions created. What next?",
256+
header: "Next",
257+
multiSelect: false,
258+
options: [
259+
{ label: "Form Queue", description: "Order solutions for execution (/issue:queue)" },
260+
{ label: "Plan More Issues", description: "Continue creating solutions" },
261+
{ label: "View Issues", description: "Review issue details" },
262+
{ label: "Done", description: "Exit workflow" }
263+
]
264+
}]
265+
});
266+
267+
// After Queue (queue formed)
268+
// → Suggest /issue:execute directly
269+
```
270+
271+
## Related Skills & Commands
272+
273+
- `issue-manage` - Interactive issue CRUD operations
274+
- `/issue:new` - Create structured issue from GitHub or text
275+
- `/issue:execute` - Execute queue with DAG-based parallel orchestration
276+
- `ccw issue list` - List all issues
277+
- `ccw issue status <id>` - View issue details

0 commit comments

Comments
 (0)