Mode Detection — pick fix (default), refactor, or review (rule file)
Context Gathering — 11-point checklist before reasoning
Call-Graph Map (optional accelerator) — mechanically seed the execution map when a call-graph CLI is available
Phase 1: Full Execution Path Walkthrough — entry-to-exit map, per-block analysis, contract boundaries, summary
Phase 2: Step Back — Identify the Principle
Phase 3: Scene Set — Explain the Situation to the Duck
Phase 4: Structured Hypothesis Generation — fix-mode root causes / refactor-mode approaches
Phase 5: Meta-Cognitive Check — Challenge Your Own Reasoning
Phase 6: Confidence Gate — Analysis Validation — /confidence analysis or /confidence plan
Phase 7: Plan the Change — Words Before Code
Phase 8: Implement and Verify — /confidence code gate
Output Format
Contribute verified facts to codebase-knowledge — writer-primary, best-effort, gated on real verification
Anti-Patterns — What NOT to Do

Mode Detection

Check $ARGUMENTS for mode:

Mode	Default	Use case
`fix`	yes	Bug, broken behavior, failing test — something is wrong and needs root cause analysis
`refactor`		Restructuring, cleanup, improvement — the code works but needs to be better
`review`		PR validation — does this diff implement what its description claims, and does the change make sense given how the changed code is used in the wider system? Returns structured findings for the `pr-reviewer` agent to consume — not root-cause analysis. Streamlined three-phase flow that skips Phases 2–8; full procedure lives in `rules/review-mode.md`.

The mode determines how certain phases are framed (noted inline below). fix and refactor walk the full eight-phase protocol in this file. review is a structurally different flow — see the rule file linked above.

Context Gathering

Before analyzing, gather all relevant context:

The full function/component — not just the lines around the bug
All callers — grep for every call site; understand how the function is used
All dependencies — read every function, type, and module this code imports or calls
Tests — read existing tests to understand intended behavior and edge cases
Recent changes — run git log -10 --oneline -- <file> and git diff HEAD~5 -- <file> to see what changed recently
Related files — if this is a component, read the parent; if a utility, read its consumers
Find the entry point — Where does this execution path begin? For an API endpoint, this is the route handler or middleware entry. For a UI flow, this is the user action or event trigger. For a background job, this is the scheduler or queue consumer. Walk upstream from the user's focus point until you reach the boundary of the system.
Find the exit point — Where does this execution path end? The HTTP response, the database commit, the rendered output, the emitted event. Walk downstream from the user's focus point until you reach the boundary.
Map the full chain — Read every file, function, and middleware between entry and exit. Build an ordered list of every step in the execution path. Use Explore agents in parallel to trace imports and call sites if the chain spans many files. Fast path (optional): if a call-graph CLI is available, seed this map mechanically first via rules/call-graph-map.md, then read each step's body; fall back to the manual Explore + grep trace when it is not.
Read every step in full — Do not skim. Read each function body completely. Bugs hide in the parts you'd normally skip.
Identify all side effects — Database writes, cache mutations, event emissions, external API calls, logging, metrics — anything that modifies state outside the current function scope.

Do NOT skip any of these. The point is to build a complete mental model before reasoning.

Phase 1: Full Execution Path Walkthrough

After gathering context, walk through the execution path sequentially from entry to exit.

Step 1a: Draw the Execution Map

Create a numbered list of every step in the execution path. If you seeded a call map via rules/call-graph-map.md, use it as the skeleton here — it already resolves the cross-file callers and callees, so your job is to order the steps and read each body.

## Execution Path: [name of the flow, e.g., "POST /api/v1/ingest"]

1. [file:line] Route registration / middleware entry
2. [file:line] Authentication middleware
3. [file:line] Request validation
4. [file:line] Business logic - step A
5. [file:line] Business logic - step B
6. [file:line] Database interaction
7. [file:line] Response construction
8. [file:line] Error handler / response send

Step 1b: Analyze Each Block

For each step in the execution map, answer:

Question	Answer
What does this block expect?	Input shape, preconditions, assumptions about prior state
What does this block guarantee?	Output shape, postconditions, side effects
Does the previous block's guarantee match this block's expectation?	YES / NO / PARTIALLY — explain any gaps
Are there implicit assumptions?	Types that aren't validated, null checks that are missing, ordering that isn't enforced
What happens on the unhappy path?	Error handling, edge cases, timeouts, empty inputs
Is there a "hole in the cheese" here?	A subtle issue that only matters in combination with other blocks

Step 1c: Contract Boundary Analysis

After analyzing each block individually, check every boundary between blocks:

Type contracts — Does block N's return type match block N+1's parameter type? Not just structurally — semantically. (e.g., a string that's supposed to be a UUID but nothing validates that)
Null/undefined propagation — Can block N return null/undefined where block N+1 doesn't handle it?
Error contract mismatches — Does block N throw/reject in ways block N+1 doesn't catch? Are error types preserved or lost?
State assumptions — Does block N+1 assume block N modified some shared state (DB, cache, context) that block N might skip under certain conditions?
Concurrency gaps — Between block N and N+1, can another process/request modify the state they share?
Timing and ordering — async operations, event ordering, lifecycle methods — is the sequence guaranteed?

Step 1d: Synthesize Findings

Produce a Walkthrough Summary before continuing:

## Execution Path Summary

### Health
- Total blocks analyzed: X
- Blocks with no issues: X
- Blocks with potential issues: X
- Contract boundary mismatches found: X

### Issues Found (ordered by severity)

#### Critical
- [block N → block N+1]: Description of the issue

#### Warning
- [block N]: Description of the concern

#### Info
- [block N]: Observation worth noting

### The Full Picture
[2-3 paragraphs explaining what the end-to-end analysis reveals that isolated
analysis would miss. Connect the dots across the entire chain.]

Phase 2: Step Back — Identify the Principle

Based on step-back prompting research (Zheng et al., 2023 — up to 36% improvement over chain-of-thought).

Answer these questions explicitly in your thinking:

What general principle or domain concept governs this code? (e.g., "this is a state machine", "this follows the observer pattern", "this implements eventual consistency")
What are the fundamental rules and invariants that must hold?
What is the business intent? Not what the code does — what should it accomplish for the user/system?

Phase 3: Scene Set — Explain the Situation to the Duck

Based on rubber duck debugging protocol — forces externalization of hidden assumptions.

Before any analysis, state clearly:

Fix mode:

Expected behavior: What should happen, with specific inputs/scenarios?
Actual behavior: What is happening instead? Include error messages, wrong outputs, or symptoms.
The gap: Where exactly does expected diverge from actual?
Prior attempts: What fixes were already tried and why did they fail?

Refactor mode:

Current state: What does the code look like now? What's wrong with the structure?
Desired state: What should it look like after? What quality attributes are we optimizing for? (readability, performance, extensibility, testability, etc.)
The gap: What specifically makes the current structure inadequate?
Prior attempts: What refactor approaches were already tried and why didn't they work?

Write this out explicitly. Do not skip to hypotheses.

Phase 4: Structured Hypothesis Generation

Based on structured RCA frameworks and the 5 Whys technique.

Fix mode — Root Cause Hunt

Generate at least 3 distinct hypotheses for the root cause:

#	Hypothesis	Supporting Evidence	Contradicting Evidence	Confidence
1	...	...	...	low/med/high
2	...	...	...	low/med/high
3	...	...	...	low/med/high

Then ask:

What changed? Check git history — did a recent commit introduce this?
What's the simplest explanation? Prefer Occam's razor.
Am I treating a symptom or the disease? Trace the causal chain deeper.

Refactor mode — Approach Exploration

Generate at least 3 distinct refactoring approaches:

#	Approach	Pros	Cons	Risk level
1	...	...	...	low/med/high
2	...	...	...	low/med/high
3	...	...	...	low/med/high

Then ask:

Who are the consumers? Will this refactor require changes in callers?
What's the migration path? Can this be done incrementally or is it all-or-nothing?
Am I restructuring for a real problem or aesthetics? What concrete benefit does each approach deliver?

Phase 5: Meta-Cognitive Check — Challenge Your Own Reasoning

Based on metacognitive prompting research (Wang & Zhao, 2023 — up to 26.9% improvement).

Answer honestly:

What assumptions am I making? List every assumption, especially ones that feel "obvious."
If my leading hypothesis turned out to be wrong, why might that be? Force yourself to argue against it.
What contradictory evidence have I dismissed or not looked for?
What alternative explanations have I not considered?
Am I anchored on my first idea? If the first hypothesis still leads, deliberately spend time on hypothesis #2 and #3.

Phase 6: Confidence Gate — Analysis Validation

Run the appropriate /confidence mode based on the analysis type:

Fix mode → `/confidence analysis`

Scores:

Evidence strength (40%) — Is the analysis backed by concrete evidence?
Root cause certainty (30%) — Is this the root cause or just a symptom?
Fix confidence (30%) — Will the proposed fix resolve the issue?

Refactor mode → `/confidence plan`

Scores:

Completeness (40%) — Are all affected areas identified? Is the scope fully understood?
Feasibility (30%) — Is the approach sound and consistent with the codebase?
No ambiguity (30%) — Are the refactoring steps specific enough to execute without interpretation?

Thresholds (both modes):

90%+: Proceed to Phase 7 (planning).
70-89%: Address the specific concerns the confidence assessment raises before proceeding. Re-run the confidence check after.
Below 70%: Do NOT proceed. Return to Phase 4 with new hypotheses/approaches informed by what the assessment flagged. Up to 2 iterations to raise the score before escalating to the user.

Phase 7: Plan the Change — Words Before Code

No code until this phase is complete.

Describe the change in plain language. What will change and why?
Impact analysis: What other code paths, components, or tests will this affect?
What could go wrong? Pre-mortem: if this change introduced a new bug or regression, what would it be?
Is this the minimal change? Or am I over-engineering? (Fix mode: address the root cause and nothing else. Refactor mode: address the structural problem without scope creep.)
How will I verify it works? What test, command, or check confirms success?
Refactor mode only — Migration steps: If the change affects callers or consumers, list the ordered steps to migrate without breaking anything.

Phase 8: Implement and Verify

Only now write code. After implementing:

Run the relevant tests
Manually trace through the fix to confirm it addresses the root cause from Phase 4
Check that no new issues were introduced (run the broader test suite if available)
Run /confidence code to validate the implementation:
- 90%+: The fix is ready. Present the summary.
- 70-89%: Address the flagged concerns. If in doubt, run /confidence code fix to auto-fix mechanical issues and re-assess.
- Below 70%: The fix is insufficient. Do NOT patch further — return to Phase 4 with the new information from the confidence assessment.

Output Format

Present the analysis using this structure:

## Holistic Analysis

### Context Gathered
[List files read and key findings from each]

### Execution Path Walkthrough
[Full execution map from Phase 1]
[Per-block analysis table]
[Contract boundary findings]
[Walkthrough Summary with severity-ordered issues]

### Step Back: The Principle
[What general concept governs this code and what invariants must hold]

### The Situation (Scene Set)
[Fix mode: Expected / Actual / Gap / Prior attempts]
[Refactor mode: Current state / Desired state / Gap / Prior attempts]

### Hypotheses / Approaches
[Fix mode: Root cause hypothesis table from Phase 4]
[Refactor mode: Approach comparison table from Phase 4]

### Meta-Cognitive Check
[Key assumptions challenged, strongest counter-argument]

### Root Cause / Chosen Approach
[Fix mode: The identified root cause]
[Refactor mode: The selected approach and rationale]

### Analysis Confidence
[Fix mode: /confidence analysis score and breakdown]
[Refactor mode: /confidence plan score and breakdown]

### Change Plan
[Plain-language description, impact analysis, verification plan]

### Implementation Confidence (/confidence code)
[Score and dimension breakdown from Phase 8]

Contribute verified facts to codebase-knowledge

This skill is the engine that confirms the why — an invariant a symbol upholds (Step 1c), a consumer count swept in Context Gathering, a root-cause defect pinned at a SHA (Phase 4 → Phase 6). Those confirmed facts are the scarcest, most reusable entries in the shared codebase-knowledge bucket. When a run has genuinely verified such a fact against the code, contribute it back so the next code-changer (aw, fix-bug, implement-suggestion, ci-auto-fix, and optimize-approach) plans with it in hand.

This is a writer-primary, best-effort step: it never blocks or reshapes the analysis above, writes only what THIS run verified, and follows the multi-writer contract. Full procedure and the gate on real verification: rules/codebase-knowledge-write.md.

Anti-Patterns — What NOT to Do

Do NOT skip context gathering and jump to hypotheses
Do NOT generate only one hypothesis
Do NOT write code before completing Phase 7
Do NOT ignore contradicting evidence for a favored hypothesis
Do NOT treat this as a formality — if the analysis reveals a different root cause than expected, follow the evidence
Do NOT apply this skill to trivial one-line fixes — it is for when isolated fixes have failed
Do NOT analyze only the isolated failure point — always trace the full execution path from entry to exit

holistic-analysis

Holistic Analysis

Contents