claude-code-workflow 7.2.26 → 7.2.28

package/.codex/skills/investigate/phases/02-pattern-analysis.md

@@ -0,0 +1,181 @@
+# Phase 2: Pattern Analysis
+
+> **COMPACT PROTECTION**: This is a core execution phase. If context compression has occurred and this file is only a summary, **MUST `Read` this file again before executing any Step**. Do not execute from memory.
+
+Search for similar patterns in the codebase to determine if the bug is isolated or systemic.
+
+## Objective
+
+- Search for similar error patterns, antipatterns, or code smells across the codebase
+- Determine if the bug is an isolated incident or part of a systemic issue
+- Identify related code that may be affected by the same root cause
+- Refine the scope of the investigation
+
+## Input
+
+| Source | Required | Description |
+|--------|----------|-------------|
+| investigation-report (phase 1) | Yes | Evidence, affected files, affected modules, initial diagnosis suspects |
+| assign_task message | Yes | Phase 2 instruction |
+
+## Execution Steps
+
+### Step 1: Search for Similar Error Patterns
+
+Search for the same error type or message elsewhere in the codebase:
+
+1. Grep for identical or similar error message fragments in `src/` with 3 lines of context.
+2. Grep for the same exception class or error code — output mode: files with matches.
+3. Grep for similar error handling patterns in the same module.
+
+**Decision table**:
+
+| Result | Action |
+|--------|--------|
+| Similar patterns found in same module | Note as module-wide indicator, continue |
+| Similar patterns found across multiple modules | Note as systemic indicator, continue |
+| No similar patterns found | Note as isolated indicator, continue |
+
+---
+
+### Step 2: Search for the Same Antipattern
+
+If the Phase 1 initial diagnosis identified a coding antipattern, search for it globally:
+
+**Common antipattern examples to search for**:
+
+| Antipattern | Grep pattern style |
+|-------------|-------------------|
+| Missing null/undefined check | `variable\.property` without guard |
+| Unchecked async operation | unhandled promise, missing await |
+| Direct mutation of shared state | shared state write without lock |
+| Type assumption violation | forced cast without validation |
+
+Execute at least one targeted Grep for the identified antipattern across relevant source directories.
+
+**Decision table**:
+
+| Result | Action |
+|--------|--------|
+| Antipattern found in multiple files | Classify as module-wide or systemic candidate |
+| Antipattern isolated to one location | Classify as isolated candidate |
+| No antipattern identifiable | Proceed without antipattern classification |
+
+---
+
+### Step 3: Module-Level Analysis
+
+Examine the affected module for structural issues:
+
+1. Use Glob to list all files in the affected module directory.
+2. Grep for imports from the affected module to understand its consumers.
+3. Check for circular dependencies or unusual import patterns.
+
+---
+
+### Step 4: CLI Cross-File Pattern Analysis (Optional)
+
+For complex patterns that span many files, use inline-cli-analysis subagent:
+
+```
+spawn_agent({
+  task_name: "inline-cli-analysis",
+  fork_context: false,
+  model: "haiku",
+  reasoning_effort: "medium",
+  message: `### MANDATORY FIRST STEPS
+1. Read: ~/.codex/agents/cli-explore-agent.md
+
+PURPOSE: Identify all instances of antipattern across codebase; success = complete scope map
+TASK: Search for pattern '<antipattern_description>' | Map all occurrences | Assess systemic risk
+MODE: analysis
+CONTEXT: @src/**/*.<ext> | Bug in <module>, pattern: <pattern_description>
+EXPECTED: List of all files with same pattern, risk assessment per occurrence (same_bug|potential_bug|safe)
+CONSTRAINTS: Focus on <antipattern> pattern only | Ignore test files for scope`
+})
+const patternResult = wait_agent({ targets: ["inline-cli-analysis"], timeout_ms: 180000 })
+close_agent({ target: "inline-cli-analysis" })
+```
+
+**Decision table**:
+
+| Condition | Action |
+|-----------|--------|
+| Pattern spans >3 files in >1 module | Use subagent for full scope map |
+| Pattern confined to 1 module | Skip subagent, proceed with manual search results |
+| Subagent timeout | Continue with manual search results |
+
+---
+
+### Step 5: Classify Scope and Assemble Pattern Analysis
+
+Classify the bug scope based on all search findings:
+
+**Scope Definitions**:
+
+| Scope | Definition |
+|-------|-----------|
+| `isolated` | Bug exists in a single location; no similar patterns found elsewhere |
+| `module-wide` | Same pattern exists in multiple files within the same module |
+| `systemic` | Pattern spans multiple modules; may require broader fix |
+
+Assemble `pattern_analysis` section and add to investigation-report:
+
+```
+pattern_analysis = {
+  scope: "isolated|module-wide|systemic",
+  similar_occurrences: [
+    {
+      file: "<path/to/file.ts>",
+      line: <line number>,
+      pattern: "<description of similar pattern>",
+      risk: "same_bug|potential_bug|safe"
+    }
+  ],
+  total_occurrences: <count>,
+  affected_modules: ["<module-name>"],
+  antipattern_identified: "<description or null>",
+  scope_justification: "<evidence-based reasoning for this scope classification>"
+}
+```
+
+**Scope decision table**:
+
+| Scope | Phase 3 Focus |
+|-------|--------------|
+| isolated | Narrow hypothesis scope to single location |
+| module-wide | Note all occurrences for Phase 4 fix planning |
+| systemic | Note for potential multi-location fix; flag for separate tracking |
+
+Output Phase 2 summary and await assign_task for Phase 3.
+
+---
+
+## Output
+
+| Artifact | Format | Description |
+|----------|--------|-------------|
+| investigation-report (phase 2) | In-memory JSON | Phase 1 fields + pattern_analysis section added |
+| Phase 2 summary | Structured text output | Scope classification with justification, await Phase 3 |
+
+## Success Criteria
+
+| Criterion | Validation Method |
+|-----------|-------------------|
+| At least 3 search queries executed | Count of Grep/Glob operations performed |
+| Scope classified | pattern_analysis.scope is one of: isolated, module-wide, systemic |
+| Similar occurrences documented | pattern_analysis.similar_occurrences populated (empty array acceptable for isolated) |
+| Scope justification provided | pattern_analysis.scope_justification non-empty with evidence |
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| No source directory found | Search from project root, document uncertainty |
+| Grep returns too many results | Narrow pattern, add path filter, take top 10 most relevant |
+| inline-cli-analysis timeout | Continue with manual search results, log warning |
+| Antipattern not identifiable from Phase 1 | Skip Step 2 antipattern search, proceed with error pattern search only |
+
+## Next Phase
+
+-> [Phase 3: Hypothesis Testing](03-hypothesis-testing.md)

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

@@ -0,0 +1,214 @@
+# Phase 3: Hypothesis Testing
+
+> **COMPACT PROTECTION**: This is a core execution phase. If context compression has occurred and this file is only a summary, **MUST `Read` this file again before executing any Step**. Do not execute from memory.
+
+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 unproductive test failures
+
+## Input
+
+| Source | Required | Description |
+|--------|----------|-------------|
+| investigation-report (phases 1-2) | Yes | Evidence, affected files, pattern analysis, initial suspects |
+| assign_task message | Yes | Phase 3 instruction |
+
+## Execution Steps
+
+### Step 1: Form Hypotheses
+
+Using evidence from Phase 1 (investigation report) and Phase 2 (pattern analysis), form up to 3 ranked hypotheses:
+
+**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
+
+Assemble hypotheses in memory:
+
+```
+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"
+  }
+]
+```
+
+Initialize strike counter: 0
+
+---
+
+### Step 2: Test Hypotheses Sequentially
+
+Test each hypothesis starting from highest confidence (H1 first). Use read-only probes only during testing.
+
+**Allowed test methods**:
+
+| Method | Usage |
+|--------|-------|
+| Read a specific file | Check a specific value, condition, or code pattern |
+| Grep for a pattern | Confirm or deny the presence of a condition |
+| Bash targeted test | Run a specific test that reveals the condition |
+| Temporary log statement | Add a log to observe runtime behavior; MUST revert after |
+
+**Prohibited during hypothesis testing**:
+- Modifying production code (save for Phase 4)
+- Changing multiple things at once
+- Running the full test suite (targeted checks only)
+
+---
+
+### Step 3: Record Test Results
+
+For each hypothesis test, record:
+
+```
+hypothesis_test = {
+  id: "H1",
+  test_performed: "<what was checked, e.g.: 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 unproductive test failures. After each hypothesis test, evaluate:
+
+**Strike evaluation**:
+
+| Test result | New insight gained | Strike action |
+|-------------|-------------------|---------------|
+| confirmed | — | CONFIRM root cause, end testing |
+| rejected | Yes — narrows search or reveals new cause | No strike (productive rejection) |
+| rejected | No — no actionable insight | +1 strike |
+| inconclusive | Yes — identifies new area | No strike (productive) |
+| inconclusive | No — no narrowing | +1 strike |
+
+**Strike counter tracking**:
+
+| Strike count | Action |
+|--------------|--------|
+| 1 | Continue to next hypothesis |
+| 2 | Continue to next hypothesis |
+| 3 | STOP — output escalation block immediately |
+
+**On 3rd Strike — output this escalation block verbatim and halt**:
+
+```
+## 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 content from all phases>
+
+STATUS: BLOCKED
+```
+
+After outputting escalation: set status BLOCKED. Do not proceed to Phase 4.
+
+---
+
+### Step 5: Confirm Root Cause
+
+If a hypothesis is confirmed, document the confirmed root cause:
+
+```
+confirmed_root_cause = {
+  hypothesis_id: "H1",
+  description: "<Root cause description with full technical detail>",
+  evidence_chain: [
+    "Phase 1: <Error message X observed in Y>",
+    "Phase 2: <Same pattern found in N other files>",
+    "Phase 3: H1 confirmed — <specific condition at file.ts:42>"
+  ],
+  affected_code: {
+    file: "<path/to/file.ts>",
+    line_range: "<42-55>",
+    function: "<functionName>"
+  }
+}
+```
+
+Add `hypothesis_tests` and `confirmed_root_cause` to investigation-report in memory.
+
+Output Phase 3 results and await assign_task for Phase 4.
+
+---
+
+## Output
+
+| Artifact | Format | Description |
+|----------|--------|-------------|
+| investigation-report (phase 3) | In-memory JSON | Phases 1-2 fields + hypothesis_tests + confirmed_root_cause |
+| Phase 3 summary or escalation block | Structured text output | Either confirmed root cause or BLOCKED escalation |
+
+## Success Criteria
+
+| Criterion | Validation Method |
+|-----------|-------------------|
+| Maximum 3 hypotheses formed | Count of hypotheses array |
+| Each hypothesis cites evidence | evidence_supporting non-empty for each |
+| Each hypothesis tested with documented probe | test_performed field populated for each |
+| Strike counter maintained correctly | Count of unproductive consecutive failures |
+| Root cause confirmed with evidence chain OR escalation triggered | confirmed_root_cause present OR BLOCKED output |
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Evidence insufficient to form 3 hypotheses | Form as many as evidence supports (minimum 1), proceed |
+| Partial insight from rejected hypothesis | Do not count as strike; re-form or refine remaining hypotheses with new insight |
+| All 3 hypotheses confirmed simultaneously | Use highest-confidence confirmed one as root cause |
+| Hypothesis test requires production change | Prohibited — use static analysis or targeted read-only probe instead |
+
+## 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 | -> [Phase 4: Implementation](04-implementation.md) |
+| 3-strike escalation triggered | STOP — output diagnostic dump — STATUS: BLOCKED |
+| Partial insight, re-forming hypotheses | Stay in Phase 3, re-test with refined hypotheses |
+
+## Next Phase
+
+-> [Phase 4: Implementation](04-implementation.md) ONLY with confirmed root cause.

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

@@ -0,0 +1,195 @@
+# Phase 4: Implementation
+
+> **COMPACT PROTECTION**: This is a core execution phase. If context compression has occurred and this file is only a summary, **MUST `Read` this file again before executing any Step**. Do not execute from memory.
+
+Implement the minimal fix and add a regression test. Iron Law gate enforced at entry.
+
+## 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
+
+## Input
+
+| Source | Required | Description |
+|--------|----------|-------------|
+| investigation-report (phase 3) | Yes | Must contain confirmed_root_cause with evidence chain |
+| assign_task message | Yes | Phase 4 instruction |
+
+## Iron Law Gate Check
+
+**MANDATORY FIRST ACTION before any code modification**:
+
+| Condition | Action |
+|-----------|--------|
+| investigation-report contains `confirmed_root_cause` with non-empty description | Proceed to Step 1 |
+| `confirmed_root_cause` absent or empty | Output "BLOCKED: Iron Law violation — no confirmed root cause. Return to Phase 3." Halt. Do NOT modify any files. |
+
+Log the confirmed state before proceeding:
+- Root cause: `<confirmed_root_cause.description>`
+- Evidence chain: `<confirmed_root_cause.evidence_chain.length>` items
+- Affected code: `<confirmed_root_cause.affected_code.file>:<confirmed_root_cause.affected_code.line_range>`
+
+## Execution Steps
+
+### Step 1: Plan the Minimal Fix
+
+Define the fix scope BEFORE writing any code:
+
+```
+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: <count>,
+  total_lines_changed: "<estimated>"
+}
+```
+
+**Minimal Fix Rules** (from Iron Law):
+
+| Rule | Requirement |
+|------|-------------|
+| Change only necessary code | Only the confirmed root cause location |
+| No refactoring | Do not restructure surrounding code |
+| No feature additions | Fix only; no new capabilities |
+| No style/format changes | Do not touch unrelated code formatting |
+| >3 files changed | Requires written justification in fix_plan |
+
+**Fix scope decision**:
+
+| Files to change | Action |
+|----------------|--------|
+| 1-3 files | Proceed without justification |
+| More than 3 files | Document justification in fix_plan.description before proceeding |
+
+---
+
+### Step 2: Implement the Fix
+
+Apply the planned changes using Edit:
+
+- Target only the file(s) and line(s) identified in `confirmed_root_cause.affected_code`
+- Make exactly the change described in fix_plan
+- Verify the edit was applied correctly by reading the modified section
+
+**Decision table**:
+
+| Edit outcome | Action |
+|-------------|--------|
+| Edit applied correctly | Proceed to Step 3 |
+| Edit failed or incorrect | Re-apply with corrected old_string/new_string; if Edit fails 2+ times, use Bash sed as fallback |
+| Fix requires more than planned | Document the additional change in fix_plan with justification |
+
+---
+
+### Step 3: Add Regression Test
+
+Create or modify a test that proves the fix:
+
+1. Find the appropriate test file for the affected module:
+   - Use Glob for `**/*.test.{ts,js,py}`, `**/__tests__/**/*.{ts,js}`, or `**/test_*.py`
+   - Match the test file to the affected source module
+2. Add a regression test with these requirements:
+
+**Regression test requirements**:
+
+| Requirement | Details |
+|-------------|---------|
+| Test name references the bug | Name clearly describes the bug scenario (e.g., "should handle null display_name without error") |
+| Tests exact code path | Exercises the specific path identified in root cause |
+| Deterministic | No timing dependencies, no external services |
+| Correct placement | In the appropriate test file for the affected module |
+| Proves the fix | Must fail when fix is reverted, pass when fix is applied |
+
+**Decision table**:
+
+| Condition | Action |
+|-----------|--------|
+| Existing test file found for module | Add test to that file |
+| No existing test file found | Create new test file following project conventions |
+| Multiple candidate test files | Choose the one most directly testing the affected module |
+
+---
+
+### Step 4: Verify Fix Against Reproduction
+
+Re-run the original reproduction case from Phase 1:
+
+- If Phase 1 used a failing test: run that same test now
+- If Phase 1 used a failing command: run that same command now
+- If Phase 1 used static analysis: run the regression test as verification
+
+Record verification result:
+
+```
+fix_applied = {
+  description: "<what was fixed>",
+  files_changed: ["<path/to/file.ts>"],
+  lines_changed: <count>,
+  regression_test: {
+    file: "<path/to/test.ts>",
+    test_name: "<test name>",
+    status: "added|modified"
+  },
+  reproduction_verified: true|false
+}
+```
+
+**Decision table**:
+
+| Verification result | Action |
+|--------------------|--------|
+| Reproduction case now passes | Set reproduction_verified: true, proceed to Step 5 |
+| Reproduction case still fails | Analyze why fix is insufficient, adjust fix, re-run |
+| Cannot verify (setup required) | Document as concern, set reproduction_verified: false, proceed |
+
+---
+
+### Step 5: Assemble Phase 4 Output
+
+Add `fix_applied` to investigation-report in memory. Output Phase 4 summary and await assign_task for Phase 5.
+
+---
+
+## Output
+
+| Artifact | Format | Description |
+|----------|--------|-------------|
+| Modified source files | File edits | Minimal fix applied to affected code |
+| Regression test | File add/edit | Test covering the exact bug scenario |
+| investigation-report (phase 4) | In-memory JSON | Phases 1-3 fields + fix_applied section |
+| Phase 4 summary | Structured text output | Fix description, test added, verification result |
+
+## Success Criteria
+
+| Criterion | Validation Method |
+|-----------|-------------------|
+| Iron Law gate passed | confirmed_root_cause present before any code change |
+| Fix is minimal | fix_plan.total_files_changed <= 3 OR justification documented |
+| Regression test added | fix_applied.regression_test populated |
+| Original reproduction passes | fix_applied.reproduction_verified: true |
+| No unrelated code changes | Only confirmed_root_cause.affected_code locations modified |
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Iron Law gate fails | Output BLOCKED, halt, do not modify any files |
+| Edit tool fails twice | Try Bash sed/awk as fallback; if still failing, use Write to recreate file |
+| Fix does not resolve reproduction | Analyze remaining failure, adjust fix within Phase 4 |
+| Fix requires changing >3 files | Document justification, proceed after explicit justification |
+| No test file found for module | Create new test file following nearest similar test file pattern |
+| Regression test is non-deterministic | Refactor test to remove timing/external dependencies |
+
+## Next Phase
+
+-> [Phase 5: Verification & Report](05-verification-report.md)