claude-code-workflow 7.2.27 → 7.2.28

package/.claude/skills/investigate/phases/03-hypothesis-testing.md

@@ -0,0 +1,177 @@
+# Phase 3: Hypothesis Testing
+
+Form hypotheses from evidence and test each one. Enforce the 3-strike escalation rule.
+
+## Objective
+
+- Form a maximum of 3 hypotheses from Phase 1-2 evidence
+- Test each hypothesis with minimal, read-only probes
+- Confirm or reject each hypothesis with concrete evidence
+- Enforce 3-strike rule: STOP and escalate after 3 consecutive test failures
+
+## Execution Steps
+
+### Step 1: Form Hypotheses
+
+Using evidence from Phase 1 (investigation report) and Phase 2 (pattern analysis), form up to 3 ranked hypotheses:
+
+```json
+{
+  "hypotheses": [
+    {
+      "id": "H1",
+      "description": "The root cause is X because evidence Y",
+      "evidence_supporting": ["evidence item 1", "evidence item 2"],
+      "predicted_behavior": "If H1 is correct, then we should observe Z",
+      "test_method": "How to verify: read file X line Y, check value Z",
+      "confidence": "high|medium|low"
+    }
+  ]
+}
+```
+
+**Hypothesis Formation Rules**:
+- Each hypothesis must cite at least one piece of evidence from Phase 1-2
+- Each hypothesis must have a testable prediction
+- Rank by confidence (high first)
+- Maximum 3 hypotheses per investigation
+
+### Step 2: Test Hypotheses Sequentially
+
+Test each hypothesis starting from highest confidence. Use read-only probes:
+
+**Allowed test methods**:
+- `Read` a specific file and check a specific value or condition
+- `Grep` for a pattern that would confirm or deny the hypothesis
+- `Bash` to run a specific test or command that reveals the condition
+- Temporarily add a log statement to observe runtime behavior (revert after)
+
+**Prohibited during testing**:
+- Modifying production code (save that for Phase 4)
+- Changing multiple things at once
+- Running the full test suite (targeted checks only)
+
+```javascript
+// Example hypothesis test
+// H1: "Function X receives null because caller Y doesn't check return value"
+const evidence = Read({ file_path: "src/caller.ts" })
+// Check: Does caller Y use the return value without null check?
+// Result: Confirmed / Rejected with specific evidence
+```
+
+### Step 3: Record Test Results
+
+For each hypothesis test:
+
+```json
+{
+  "hypothesis_tests": [
+    {
+      "id": "H1",
+      "test_performed": "Read src/caller.ts:42 - checked null handling",
+      "result": "confirmed|rejected|inconclusive",
+      "evidence": "specific observation that confirms or rejects",
+      "files_checked": ["src/caller.ts:42-55"]
+    }
+  ]
+}
+```
+
+### Step 4: 3-Strike Escalation Rule
+
+Track consecutive test failures. A "failure" means the test was inconclusive or the hypothesis was rejected AND no actionable insight was gained.
+
+```
+Strike Counter:
+  [H1 rejected, no insight] → Strike 1
+  [H2 rejected, no insight] → Strike 2
+  [H3 rejected, no insight] → Strike 3 → STOP
+```
+
+**Important**: A rejected hypothesis that provides useful insight (narrows the search) does NOT count as a strike. Only truly unproductive tests count.
+
+**On 3rd Strike — STOP and Escalate**:
+
+```
+## ESCALATION: 3-Strike Limit Reached
+
+### Failed Step
+- Phase: 3 — Hypothesis Testing
+- Step: Hypothesis test #{N}
+
+### Error History
+1. Attempt 1: H1 — {description}
+   Test: {what was checked}
+   Result: {rejected/inconclusive} — {why}
+2. Attempt 2: H2 — {description}
+   Test: {what was checked}
+   Result: {rejected/inconclusive} — {why}
+3. Attempt 3: H3 — {description}
+   Test: {what was checked}
+   Result: {rejected/inconclusive} — {why}
+
+### Current State
+- Evidence collected: {summary from Phase 1-2}
+- Hypotheses tested: {list}
+- Files examined: {list}
+
+### Diagnosis
+- Likely root cause area: {best guess based on all evidence}
+- Suggested human action: {specific recommendation — e.g., "Add logging to X", "Check runtime config Y", "Reproduce in debugger at Z"}
+
+### Diagnostic Dump
+{Full investigation-report.json content}
+```
+
+After escalation, set status to **BLOCKED** per Completion Status Protocol.
+
+### Step 5: Confirm Root Cause
+
+If a hypothesis is confirmed, document the confirmed root cause:
+
+```json
+{
+  "phase": 3,
+  "confirmed_root_cause": {
+    "hypothesis_id": "H1",
+    "description": "Root cause description with full evidence chain",
+    "evidence_chain": [
+      "Phase 1: Error message X observed in Y",
+      "Phase 2: Same pattern found in 3 other files",
+      "Phase 3: H1 confirmed — null check missing at file.ts:42"
+    ],
+    "affected_code": {
+      "file": "path/to/file.ts",
+      "line_range": "42-55",
+      "function": "functionName"
+    }
+  }
+}
+```
+
+## Output
+
+- **Data**: `hypothesis-tests` and `confirmed_root_cause` added to investigation report (in-memory)
+- **Format**: JSON structure as defined above
+
+## Gate for Phase 4
+
+**Phase 4 can ONLY proceed if `confirmed_root_cause` is present.** This is the Iron Law gate.
+
+| Outcome | Next Step |
+|---------|-----------|
+| Root cause confirmed | Proceed to [Phase 4: Implementation](04-implementation.md) |
+| 3-strike escalation | STOP, output diagnostic dump, status = BLOCKED |
+| Partial insight | Re-form hypotheses with new evidence (stays in Phase 3) |
+
+## Quality Checks
+
+- [ ] Maximum 3 hypotheses formed, each with cited evidence
+- [ ] Each hypothesis tested with a specific, documented probe
+- [ ] Test results recorded with concrete evidence
+- [ ] 3-strike counter maintained correctly
+- [ ] Root cause confirmed with full evidence chain OR escalation triggered
+
+## Next Phase
+
+Proceed to [Phase 4: Implementation](04-implementation.md) ONLY with confirmed root cause.

package/.claude/skills/investigate/phases/04-implementation.md

@@ -0,0 +1,139 @@
+# Phase 4: Implementation
+
+Implement the minimal fix and add a regression test. Iron Law gate enforced.
+
+## Objective
+
+- Verify Iron Law gate: confirmed root cause MUST exist from Phase 3
+- Implement the minimal fix that addresses the confirmed root cause
+- Add a regression test that fails without the fix and passes with it
+- Verify the fix resolves the original reproduction case
+
+## Iron Law Gate Check
+
+**MANDATORY**: Before any code modification, verify:
+
+```javascript
+if (!investigation_report.confirmed_root_cause) {
+  // VIOLATION: Cannot proceed without confirmed root cause
+  // Return to Phase 3 or escalate
+  throw new Error("Iron Law violation: No confirmed root cause. Return to Phase 3.")
+}
+
+console.log(`Root cause confirmed: ${investigation_report.confirmed_root_cause.description}`)
+console.log(`Evidence chain: ${investigation_report.confirmed_root_cause.evidence_chain.length} items`)
+console.log(`Affected code: ${investigation_report.confirmed_root_cause.affected_code.file}:${investigation_report.confirmed_root_cause.affected_code.line_range}`)
+```
+
+If the gate check fails, do NOT proceed. Return status **BLOCKED** with reason "Iron Law: no confirmed root cause".
+
+## Execution Steps
+
+### Step 1: Plan the Minimal Fix
+
+Define the fix scope BEFORE writing any code:
+
+```json
+{
+  "fix_plan": {
+    "description": "What the fix does and why",
+    "changes": [
+      {
+        "file": "path/to/file.ts",
+        "change_type": "modify|add|remove",
+        "description": "specific change description",
+        "lines_affected": "42-45"
+      }
+    ],
+    "total_files_changed": 1,
+    "total_lines_changed": "estimated"
+  }
+}
+```
+
+**Minimal Fix Rules** (from [specs/iron-law.md](../specs/iron-law.md)):
+- Change only what is necessary to fix the confirmed root cause
+- Do not refactor surrounding code
+- Do not add features
+- Do not change formatting or style of unrelated code
+- If the fix requires changes to more than 3 files, document justification
+
+### Step 2: Implement the Fix
+
+Apply the planned changes using `Edit` tool:
+
+```javascript
+Edit({
+  file_path: "path/to/affected/file.ts",
+  old_string: "buggy code",
+  new_string: "fixed code"
+})
+```
+
+### Step 3: Add Regression Test
+
+Create or modify a test that:
+1. **Fails** without the fix (tests the exact bug condition)
+2. **Passes** with the fix
+
+```javascript
+// Identify existing test file for the module
+Glob({ pattern: "**/*.test.{ts,js,py}" })
+// or
+Glob({ pattern: "**/test_*.py" })
+
+// Add regression test
+// Test name should reference the bug: "should handle null return from X"
+// Test should exercise the exact code path that caused the bug
+```
+
+**Regression test requirements**:
+- Test name clearly describes the bug scenario
+- Test exercises the specific code path identified in root cause
+- Test is deterministic (no flaky timing, external dependencies)
+- Test is placed in the appropriate test file for the module
+
+### Step 4: Verify Fix Against Reproduction
+
+Re-run the original reproduction case from Phase 1:
+
+```bash
+# Run the specific failing test/command from Phase 1
+# It should now pass
+```
+
+Record the verification result:
+
+```json
+{
+  "phase": 4,
+  "fix_applied": {
+    "description": "what was fixed",
+    "files_changed": ["path/to/file.ts"],
+    "lines_changed": 3,
+    "regression_test": {
+      "file": "path/to/test.ts",
+      "test_name": "should handle null return from X",
+      "status": "added|modified"
+    },
+    "reproduction_verified": true
+  }
+}
+```
+
+## Output
+
+- **Data**: `fix_applied` section added to investigation report (in-memory)
+- **Artifacts**: Modified source files and test files
+
+## Quality Checks
+
+- [ ] Iron Law gate passed: confirmed root cause exists
+- [ ] Fix is minimal: only necessary changes made
+- [ ] Regression test added that covers the specific bug
+- [ ] Original reproduction case passes with the fix
+- [ ] No unrelated code changes included
+
+## Next Phase
+
+Proceed to [Phase 5: Verification & Report](05-verification-report.md) to run full test suite and generate report.

package/.claude/skills/investigate/phases/05-verification-report.md

@@ -0,0 +1,153 @@
+# Phase 5: Verification & Report
+
+Run full test suite, check for regressions, and generate the structured debug report.
+
+## Objective
+
+- Run the full test suite to verify no regressions were introduced
+- Generate a structured debug report for future reference
+- Output the report to `.workflow/.debug/` directory
+
+## Execution Steps
+
+### Step 1: Run Full Test Suite
+
+```bash
+# Detect and run the project's test framework
+# npm test / pytest / go test / cargo test / etc.
+```
+
+Record results:
+
+```json
+{
+  "test_results": {
+    "total": 0,
+    "passed": 0,
+    "failed": 0,
+    "skipped": 0,
+    "regression_test_passed": true,
+    "new_failures": []
+  }
+}
+```
+
+**If new failures are found**:
+- Check if the failures are related to the fix
+- If related: the fix introduced a regression — return to Phase 4 to adjust
+- If unrelated: document as pre-existing failures, proceed with report
+
+### Step 2: Regression Check
+
+Verify specifically:
+1. The new regression test passes
+2. All tests that passed before the fix still pass
+3. No new warnings or errors in test output
+
+### Step 3: Generate Structured Debug Report
+
+Create the report following the schema in [specs/debug-report-format.md](../specs/debug-report-format.md):
+
+```bash
+mkdir -p .workflow/.debug
+```
+
+```json
+{
+  "bug_description": "concise description of the bug",
+  "reproduction_steps": [
+    "step 1",
+    "step 2",
+    "step 3: observe error"
+  ],
+  "root_cause": "confirmed root cause description with technical detail",
+  "evidence_chain": [
+    "Phase 1: error message X observed in module Y",
+    "Phase 2: pattern analysis found N similar occurrences",
+    "Phase 3: hypothesis H1 confirmed — specific condition at file:line"
+  ],
+  "fix_description": "what was changed and why",
+  "files_changed": [
+    {
+      "path": "src/module/file.ts",
+      "change_type": "modify",
+      "description": "added null check before property access"
+    }
+  ],
+  "tests_added": [
+    {
+      "file": "src/module/__tests__/file.test.ts",
+      "test_name": "should handle null return from X",
+      "type": "regression"
+    }
+  ],
+  "regression_check_result": {
+    "passed": true,
+    "total_tests": 0,
+    "new_failures": [],
+    "pre_existing_failures": []
+  },
+  "completion_status": "DONE|DONE_WITH_CONCERNS|BLOCKED",
+  "concerns": [],
+  "timestamp": "ISO-8601",
+  "investigation_duration_phases": 5
+}
+```
+
+### Step 4: Write Report File
+
+```javascript
+const slug = bugDescription.toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 40)
+const dateStr = new Date().toISOString().substring(0, 10)
+const reportPath = `.workflow/.debug/debug-report-${dateStr}-${slug}.json`
+
+Write({ file_path: reportPath, content: JSON.stringify(report, null, 2) })
+```
+
+### Step 5: Output Completion Status
+
+Follow the Completion Status Protocol from `_shared/SKILL-DESIGN-SPEC.md` section 13:
+
+**DONE**:
+```
+## STATUS: DONE
+
+**Summary**: Fixed {bug_description} — root cause was {root_cause_summary}
+
+### Details
+- Phases completed: 5/5
+- Root cause: {confirmed_root_cause}
+- Fix: {fix_description}
+- Regression test: {test_name} in {test_file}
+
+### Outputs
+- Debug report: {reportPath}
+- Files changed: {list}
+- Tests added: {list}
+```
+
+**DONE_WITH_CONCERNS**:
+```
+## STATUS: DONE_WITH_CONCERNS
+
+**Summary**: Fixed {bug_description} with concerns
+
+### Details
+- Phases completed: 5/5
+- Concerns:
+  1. {concern} — Impact: {low|medium} — Suggested fix: {action}
+```
+
+## Output
+
+- **File**: `debug-report-{YYYY-MM-DD}-{slug}.json`
+- **Location**: `.workflow/.debug/`
+- **Format**: JSON (see [specs/debug-report-format.md](../specs/debug-report-format.md))
+
+## Quality Checks
+
+- [ ] Full test suite executed
+- [ ] Regression test specifically verified
+- [ ] No new test failures introduced (or documented if pre-existing)
+- [ ] Debug report written to `.workflow/.debug/`
+- [ ] Completion status output follows protocol

package/.claude/skills/investigate/specs/debug-report-format.md

@@ -0,0 +1,226 @@
+# Debug Report Format
+
+Defines the structured JSON schema for debug reports generated by the investigate skill.
+
+## When to Use
+
+| Phase | Usage | Section |
+|-------|-------|---------|
+| Phase 5 | Generate final report | Full schema |
+| Phase 3 (escalation) | Diagnostic dump includes partial report | Partial schema |
+
+---
+
+## JSON Schema
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Debug Report",
+  "type": "object",
+  "required": [
+    "bug_description",
+    "reproduction_steps",
+    "root_cause",
+    "evidence_chain",
+    "fix_description",
+    "files_changed",
+    "tests_added",
+    "regression_check_result",
+    "completion_status"
+  ],
+  "properties": {
+    "bug_description": {
+      "type": "string",
+      "description": "Concise description of the bug symptom",
+      "minLength": 10
+    },
+    "reproduction_steps": {
+      "type": "array",
+      "description": "Ordered steps to reproduce the bug",
+      "items": { "type": "string" },
+      "minItems": 1
+    },
+    "root_cause": {
+      "type": "string",
+      "description": "Confirmed root cause with technical detail",
+      "minLength": 20
+    },
+    "evidence_chain": {
+      "type": "array",
+      "description": "Ordered evidence from Phase 1 through Phase 3, each prefixed with phase number",
+      "items": { "type": "string" },
+      "minItems": 1
+    },
+    "fix_description": {
+      "type": "string",
+      "description": "What was changed and why",
+      "minLength": 10
+    },
+    "files_changed": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["path", "change_type", "description"],
+        "properties": {
+          "path": {
+            "type": "string",
+            "description": "Relative file path"
+          },
+          "change_type": {
+            "type": "string",
+            "enum": ["add", "modify", "remove"]
+          },
+          "description": {
+            "type": "string",
+            "description": "Brief description of changes to this file"
+          }
+        }
+      }
+    },
+    "tests_added": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["file", "test_name", "type"],
+        "properties": {
+          "file": {
+            "type": "string",
+            "description": "Test file path"
+          },
+          "test_name": {
+            "type": "string",
+            "description": "Name of the test function or describe block"
+          },
+          "type": {
+            "type": "string",
+            "enum": ["regression", "unit", "integration"],
+            "description": "Type of test added"
+          }
+        }
+      }
+    },
+    "regression_check_result": {
+      "type": "object",
+      "required": ["passed", "total_tests"],
+      "properties": {
+        "passed": {
+          "type": "boolean",
+          "description": "Whether the full test suite passed"
+        },
+        "total_tests": {
+          "type": "integer",
+          "description": "Total number of tests executed"
+        },
+        "new_failures": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Tests that failed after the fix but passed before"
+        },
+        "pre_existing_failures": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Tests that were already failing before the investigation"
+        }
+      }
+    },
+    "completion_status": {
+      "type": "string",
+      "enum": ["DONE", "DONE_WITH_CONCERNS", "BLOCKED"],
+      "description": "Final status per Completion Status Protocol"
+    },
+    "concerns": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "description": { "type": "string" },
+          "impact": { "type": "string", "enum": ["low", "medium"] },
+          "suggested_action": { "type": "string" }
+        }
+      },
+      "description": "Non-blocking concerns (populated when status is DONE_WITH_CONCERNS)"
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO-8601 timestamp of report generation"
+    },
+    "investigation_duration_phases": {
+      "type": "integer",
+      "description": "Number of phases completed (1-5)",
+      "minimum": 1,
+      "maximum": 5
+    }
+  }
+}
+```
+
+## Field Descriptions
+
+| Field | Source Phase | Description |
+|-------|-------------|-------------|
+| `bug_description` | Phase 1 | User-reported symptom, one sentence |
+| `reproduction_steps` | Phase 1 | Ordered steps to trigger the bug |
+| `root_cause` | Phase 3 | Confirmed cause with file:line reference |
+| `evidence_chain` | Phase 1-3 | Each item prefixed with "Phase N:" |
+| `fix_description` | Phase 4 | What code was changed and why |
+| `files_changed` | Phase 4 | Each file with change type and description |
+| `tests_added` | Phase 4 | Regression tests covering the bug |
+| `regression_check_result` | Phase 5 | Full test suite results |
+| `completion_status` | Phase 5 | Final status per protocol |
+| `concerns` | Phase 5 | Non-blocking issues (if any) |
+| `timestamp` | Phase 5 | When report was generated |
+| `investigation_duration_phases` | Phase 5 | How many phases were completed |
+
+## Example Report
+
+```json
+{
+  "bug_description": "API returns 500 when user profile has null display_name",
+  "reproduction_steps": [
+    "Create user account without setting display_name",
+    "Call GET /api/users/:id/profile",
+    "Observe 500 Internal Server Error"
+  ],
+  "root_cause": "ProfileSerializer.format() calls displayName.trim() without null check at src/serializers/profile.ts:42",
+  "evidence_chain": [
+    "Phase 1: TypeError: Cannot read properties of null (reading 'trim') in server logs",
+    "Phase 2: Same pattern in 2 other serializers (address.ts:28, company.ts:35)",
+    "Phase 3: H1 confirmed — displayName field is nullable in DB but serializer assumes non-null"
+  ],
+  "fix_description": "Added null-safe access for displayName in ProfileSerializer.format()",
+  "files_changed": [
+    {
+      "path": "src/serializers/profile.ts",
+      "change_type": "modify",
+      "description": "Added optional chaining for displayName.trim() call"
+    }
+  ],
+  "tests_added": [
+    {
+      "file": "src/serializers/__tests__/profile.test.ts",
+      "test_name": "should handle null display_name without error",
+      "type": "regression"
+    }
+  ],
+  "regression_check_result": {
+    "passed": true,
+    "total_tests": 142,
+    "new_failures": [],
+    "pre_existing_failures": []
+  },
+  "completion_status": "DONE",
+  "concerns": [],
+  "timestamp": "2026-03-29T15:30:00+08:00",
+  "investigation_duration_phases": 5
+}
+```
+
+## Output Location
+
+Reports are written to: `.workflow/.debug/debug-report-{YYYY-MM-DD}-{slug}.json`
+
+Where:
+- `{YYYY-MM-DD}` is the investigation date
+- `{slug}` is derived from the bug description (lowercase, hyphens, max 40 chars)