claude-code-workflow 6.3.37 → 6.3.39

package/.codex/skills/ccw-loop/phases/actions/action-complete.md

@@ -0,0 +1,269 @@
+# Action: COMPLETE
+
+Complete CCW Loop session and generate summary report.
+
+## Purpose
+
+- Generate completion report
+- Aggregate all phase results
+- Provide follow-up recommendations
+- Offer expansion to issues
+- Mark status as completed
+
+## Preconditions
+
+- [ ] state.status === 'running'
+- [ ] state.skill_state !== null
+
+## Execution Steps
+
+### Step 1: Verify Control Signals
+
+```javascript
+const state = JSON.parse(Read(`.workflow/.loop/${loopId}.json`))
+
+if (state.status !== 'running') {
+  return {
+    action: 'COMPLETE',
+    status: 'failed',
+    message: `Cannot complete: status is ${state.status}`,
+    next_action: state.status === 'paused' ? 'PAUSED' : 'STOPPED'
+  }
+}
+```
+
+### Step 2: Aggregate Statistics
+
+```javascript
+const stats = {
+  // Time statistics
+  duration: Date.now() - new Date(state.created_at).getTime(),
+  iterations: state.current_iteration,
+
+  // Development statistics
+  develop: {
+    total_tasks: state.skill_state.develop.total,
+    completed_tasks: state.skill_state.develop.completed,
+    completion_rate: state.skill_state.develop.total > 0
+      ? ((state.skill_state.develop.completed / state.skill_state.develop.total) * 100).toFixed(1)
+      : 0
+  },
+
+  // Debug statistics
+  debug: {
+    iterations: state.skill_state.debug.iteration,
+    hypotheses_tested: state.skill_state.debug.hypotheses.length,
+    root_cause_found: state.skill_state.debug.confirmed_hypothesis !== null
+  },
+
+  // Validation statistics
+  validate: {
+    runs: state.skill_state.validate.test_results.length,
+    passed: state.skill_state.validate.passed,
+    coverage: state.skill_state.validate.coverage,
+    failed_tests: state.skill_state.validate.failed_tests.length
+  }
+}
+```
+
+### Step 3: Generate Summary Report
+
+```javascript
+const timestamp = getUtc8ISOString()
+
+const summaryReport = `# CCW Loop Session Summary
+
+**Loop ID**: ${loopId}
+**Task**: ${state.description}
+**Started**: ${state.created_at}
+**Completed**: ${timestamp}
+**Duration**: ${formatDuration(stats.duration)}
+
+---
+
+## Executive Summary
+
+${state.skill_state.validate.passed
+  ? 'All tests passed, validation successful'
+  : state.skill_state.develop.completed === state.skill_state.develop.total
+    ? 'Development complete, validation not passed - needs debugging'
+    : 'Task partially complete - pending items remain'}
+
+---
+
+## Development Phase
+
+| Metric | Value |
+|--------|-------|
+| Total Tasks | ${stats.develop.total_tasks} |
+| Completed | ${stats.develop.completed_tasks} |
+| Completion Rate | ${stats.develop.completion_rate}% |
+
+### Completed Tasks
+
+${state.skill_state.develop.tasks.filter(t => t.status === 'completed').map(t => `
+- ${t.description}
+  - Files: ${t.files_changed?.join(', ') || 'N/A'}
+  - Completed: ${t.completed_at}
+`).join('\n')}
+
+### Pending Tasks
+
+${state.skill_state.develop.tasks.filter(t => t.status !== 'completed').map(t => `
+- ${t.description}
+`).join('\n') || '_None_'}
+
+---
+
+## Debug Phase
+
+| Metric | Value |
+|--------|-------|
+| Iterations | ${stats.debug.iterations} |
+| Hypotheses Tested | ${stats.debug.hypotheses_tested} |
+| Root Cause Found | ${stats.debug.root_cause_found ? 'Yes' : 'No'} |
+
+${stats.debug.root_cause_found ? `
+### Confirmed Root Cause
+
+${state.skill_state.debug.confirmed_hypothesis}: ${state.skill_state.debug.hypotheses.find(h => h.id === state.skill_state.debug.confirmed_hypothesis)?.description}
+` : ''}
+
+---
+
+## Validation Phase
+
+| Metric | Value |
+|--------|-------|
+| Test Runs | ${stats.validate.runs} |
+| Status | ${stats.validate.passed ? 'PASSED' : 'FAILED'} |
+| Coverage | ${stats.validate.coverage || 'N/A'}% |
+| Failed Tests | ${stats.validate.failed_tests} |
+
+---
+
+## Recommendations
+
+${generateRecommendations(stats, state)}
+
+---
+
+## Session Artifacts
+
+| File | Description |
+|------|-------------|
+| \`develop.md\` | Development progress timeline |
+| \`debug.md\` | Debug exploration and learnings |
+| \`validate.md\` | Validation report |
+| \`test-results.json\` | Test execution results |
+
+---
+
+*Generated by CCW Loop at ${timestamp}*
+`
+
+Write(`${progressDir}/summary.md`, summaryReport)
+```
+
+### Step 4: Update State to Completed
+
+```javascript
+state.status = 'completed'
+state.completed_at = timestamp
+state.updated_at = timestamp
+state.skill_state.last_action = 'COMPLETE'
+state.skill_state.summary = stats
+
+Write(`.workflow/.loop/${loopId}.json`, JSON.stringify(state, null, 2))
+```
+
+## Output Format
+
+```
+ACTION_RESULT:
+- action: COMPLETE
+- status: success
+- message: Loop completed. Duration: {duration}, Iterations: {N}
+- state_updates: {
+    "status": "completed",
+    "completed_at": "{timestamp}"
+  }
+
+FILES_UPDATED:
+- .workflow/.loop/{loopId}.json: Status set to completed
+- .workflow/.loop/{loopId}.progress/summary.md: Summary report generated
+
+NEXT_ACTION_NEEDED: COMPLETED
+```
+
+## Expansion Options
+
+After completion, offer expansion to issues:
+
+```
+## Expansion Options
+
+Would you like to create follow-up issues?
+
+1. [test] Add more test cases
+2. [enhance] Feature enhancements
+3. [refactor] Code refactoring
+4. [doc] Documentation updates
+5. [none] No expansion needed
+
+Select options (comma-separated) or 'none':
+```
+
+## Helper Functions
+
+```javascript
+function formatDuration(ms) {
+  const seconds = Math.floor(ms / 1000)
+  const minutes = Math.floor(seconds / 60)
+  const hours = Math.floor(minutes / 60)
+
+  if (hours > 0) {
+    return `${hours}h ${minutes % 60}m`
+  } else if (minutes > 0) {
+    return `${minutes}m ${seconds % 60}s`
+  } else {
+    return `${seconds}s`
+  }
+}
+
+function generateRecommendations(stats, state) {
+  const recommendations = []
+
+  if (stats.develop.completion_rate < 100) {
+    recommendations.push('- Complete remaining development tasks')
+  }
+
+  if (!stats.validate.passed) {
+    recommendations.push('- Fix failing tests')
+  }
+
+  if (stats.validate.coverage && stats.validate.coverage < 80) {
+    recommendations.push(`- Improve test coverage (current: ${stats.validate.coverage}%)`)
+  }
+
+  if (recommendations.length === 0) {
+    recommendations.push('- Consider code review')
+    recommendations.push('- Update documentation')
+    recommendations.push('- Prepare for deployment')
+  }
+
+  return recommendations.join('\n')
+}
+```
+
+## Error Handling
+
+| Error Type | Recovery |
+|------------|----------|
+| Report generation failed | Show basic stats, skip file write |
+| Issue creation failed | Log error, continue completion |
+
+## Next Actions
+
+- None (terminal state)
+- To continue: Use `/ccw-loop --loop-id={loopId}` to reopen (will set status back to running)

package/.codex/skills/ccw-loop/phases/actions/action-debug.md

@@ -0,0 +1,286 @@
+# Action: DEBUG
+
+Hypothesis-driven debugging with understanding evolution documentation.
+
+## Purpose
+
+- Locate error source
+- Generate testable hypotheses
+- Add NDJSON instrumentation
+- Analyze log evidence
+- Correct understanding based on evidence
+- Apply fixes
+
+## Preconditions
+
+- [ ] state.status === 'running'
+- [ ] state.skill_state !== null
+
+## Mode Detection
+
+```javascript
+const understandingPath = `${progressDir}/debug.md`
+const debugLogPath = `${progressDir}/debug.log`
+
+const understandingExists = fs.existsSync(understandingPath)
+const logHasContent = fs.existsSync(debugLogPath) && fs.statSync(debugLogPath).size > 0
+
+const debugMode = logHasContent ? 'analyze' : (understandingExists ? 'continue' : 'explore')
+```
+
+## Execution Steps
+
+### Mode: Explore (First Debug)
+
+#### Step E1: Get Bug Description
+
+```javascript
+// From test failures or user input
+const bugDescription = state.skill_state.validate?.failed_tests?.[0]
+  || await getUserInput('Describe the bug:')
+```
+
+#### Step E2: Search Codebase
+
+```javascript
+// Use ACE search_context to find related code
+const searchResults = mcp__ace-tool__search_context({
+  project_root_path: '.',
+  query: `code related to: ${bugDescription}`
+})
+```
+
+#### Step E3: Generate Hypotheses
+
+```javascript
+const hypotheses = [
+  {
+    id: 'H1',
+    description: 'Most likely cause',
+    testable_condition: 'What to check',
+    logging_point: 'file.ts:functionName:42',
+    evidence_criteria: {
+      confirm: 'If we see X, hypothesis confirmed',
+      reject: 'If we see Y, hypothesis rejected'
+    },
+    likelihood: 1,
+    status: 'pending',
+    evidence: null,
+    verdict_reason: null
+  },
+  // H2, H3...
+]
+```
+
+#### Step E4: Create Understanding Document
+
+```javascript
+const initialUnderstanding = `# Understanding Document
+
+**Loop ID**: ${loopId}
+**Bug Description**: ${bugDescription}
+**Started**: ${getUtc8ISOString()}
+
+---
+
+## Exploration Timeline
+
+### Iteration 1 - Initial Exploration (${getUtc8ISOString()})
+
+#### Current Understanding
+
+Based on bug description and code search:
+
+- Error pattern: [identified pattern]
+- Affected areas: [files/modules]
+- Initial hypothesis: [first thoughts]
+
+#### Evidence from Code Search
+
+[Search results summary]
+
+#### Hypotheses
+
+${hypotheses.map(h => `
+**${h.id}**: ${h.description}
+- Testable condition: ${h.testable_condition}
+- Logging point: ${h.logging_point}
+- Likelihood: ${h.likelihood}
+`).join('\n')}
+
+---
+
+## Current Consolidated Understanding
+
+[Summary of what we know so far]
+`
+
+Write(understandingPath, initialUnderstanding)
+Write(`${progressDir}/hypotheses.json`, JSON.stringify({ hypotheses, iteration: 1 }, null, 2))
+```
+
+#### Step E5: Add NDJSON Logging Points
+
+```javascript
+// For each hypothesis, add instrumentation
+for (const hypothesis of hypotheses) {
+  const [file, func, line] = hypothesis.logging_point.split(':')
+
+  const logStatement = `console.log(JSON.stringify({
+    hid: "${hypothesis.id}",
+    ts: Date.now(),
+    func: "${func}",
+    data: { /* relevant context */ }
+  }))`
+
+  // Add to file using Edit tool
+}
+```
+
+### Mode: Analyze (Has Logs)
+
+#### Step A1: Parse Debug Log
+
+```javascript
+const logContent = Read(debugLogPath)
+const entries = logContent.split('\n')
+  .filter(l => l.trim())
+  .map(l => JSON.parse(l))
+
+// Group by hypothesis ID
+const byHypothesis = entries.reduce((acc, e) => {
+  acc[e.hid] = acc[e.hid] || []
+  acc[e.hid].push(e)
+  return acc
+}, {})
+```
+
+#### Step A2: Evaluate Evidence
+
+```javascript
+const hypothesesData = JSON.parse(Read(`${progressDir}/hypotheses.json`))
+
+for (const hypothesis of hypothesesData.hypotheses) {
+  const evidence = byHypothesis[hypothesis.id] || []
+
+  // Evaluate against criteria
+  if (matchesConfirmCriteria(evidence, hypothesis.evidence_criteria.confirm)) {
+    hypothesis.status = 'confirmed'
+    hypothesis.evidence = evidence
+    hypothesis.verdict_reason = 'Evidence matches confirm criteria'
+  } else if (matchesRejectCriteria(evidence, hypothesis.evidence_criteria.reject)) {
+    hypothesis.status = 'rejected'
+    hypothesis.evidence = evidence
+    hypothesis.verdict_reason = 'Evidence matches reject criteria'
+  } else {
+    hypothesis.status = 'inconclusive'
+    hypothesis.evidence = evidence
+    hypothesis.verdict_reason = 'Insufficient evidence'
+  }
+}
+```
+
+#### Step A3: Update Understanding
+
+```javascript
+const iteration = hypothesesData.iteration + 1
+const timestamp = getUtc8ISOString()
+
+const analysisEntry = `
+### Iteration ${iteration} - Evidence Analysis (${timestamp})
+
+#### Log Analysis Results
+
+${hypothesesData.hypotheses.map(h => `
+**${h.id}**: ${h.status.toUpperCase()}
+- Evidence: ${JSON.stringify(h.evidence?.slice(0, 3))}
+- Reasoning: ${h.verdict_reason}
+`).join('\n')}
+
+#### Corrected Understanding
+
+[Any corrections to previous assumptions]
+
+${confirmedHypothesis ? `
+#### Root Cause Identified
+
+**${confirmedHypothesis.id}**: ${confirmedHypothesis.description}
+` : `
+#### Next Steps
+
+[What to investigate next]
+`}
+
+---
+`
+
+const existingUnderstanding = Read(understandingPath)
+Write(understandingPath, existingUnderstanding + analysisEntry)
+```
+
+### Step: Update State
+
+```javascript
+state.skill_state.debug.active_bug = bugDescription
+state.skill_state.debug.hypotheses = hypothesesData.hypotheses
+state.skill_state.debug.hypotheses_count = hypothesesData.hypotheses.length
+state.skill_state.debug.iteration = iteration
+state.skill_state.debug.last_analysis_at = timestamp
+
+if (confirmedHypothesis) {
+  state.skill_state.debug.confirmed_hypothesis = confirmedHypothesis.id
+}
+
+state.skill_state.last_action = 'DEBUG'
+state.updated_at = timestamp
+Write(`.workflow/.loop/${loopId}.json`, JSON.stringify(state, null, 2))
+```
+
+## Output Format
+
+```
+ACTION_RESULT:
+- action: DEBUG
+- status: success
+- message: {Mode description} - {result summary}
+- state_updates: {
+    "debug.iteration": {N},
+    "debug.confirmed_hypothesis": "{id or null}"
+  }
+
+FILES_UPDATED:
+- .workflow/.loop/{loopId}.progress/debug.md: Understanding updated
+- .workflow/.loop/{loopId}.progress/hypotheses.json: Hypotheses updated
+- [Source files]: Instrumentation added
+
+NEXT_ACTION_NEEDED: {DEBUG | VALIDATE | DEVELOP | MENU}
+```
+
+## Next Action Selection
+
+```javascript
+if (confirmedHypothesis) {
+  // Root cause found, apply fix and validate
+  return 'VALIDATE'
+} else if (allRejected) {
+  // Generate new hypotheses
+  return 'DEBUG'
+} else {
+  // Need more evidence - prompt user to reproduce bug
+  return 'WAITING_INPUT'  // User needs to trigger bug
+}
+```
+
+## Error Handling
+
+| Error Type | Recovery |
+|------------|----------|
+| Empty debug.log | Prompt user to reproduce bug |
+| All hypotheses rejected | Generate new hypotheses |
+| >5 iterations | Suggest escalation |
+
+## Next Actions
+
+- Root cause found: `VALIDATE`
+- Need more evidence: `DEBUG` (after reproduction)
+- All rejected: `DEBUG` (new hypotheses)