devflow-kit 1.8.3 → 2.0.1

package/dist/commands/code-review.md

@@ -0,0 +1,403 @@
+---
+description: Comprehensive branch review using specialized sub-agents for PR readiness
+---
+# Code Review Command
+
+Run a comprehensive code review of the current branch by spawning parallel review agents, then synthesizing results into PR comments. Supports incremental reviews, timestamped report directories, and multi-worktree auto-discovery.
+
+## Usage
+
+```
+/code-review           (review current branch — or all worktrees if multiple found)
+/code-review #42       (review specific PR)
+/code-review --full    (force full-branch review, ignore previous review state)
+/code-review --path /path/to/worktree  (review a specific worktree only)
+```
+
+## Phases
+
+### Phase 0: Worktree Discovery & Pre-Flight
+
+#### Step 0a: Discover Worktrees
+
+**Produces:** WORKTREES
+
+1. **Discover reviewable worktrees** using the `devflow:worktree-support` skill discovery algorithm:
+   - Run `git worktree list --porcelain` → parse, filter (skip protected/detached/mid-rebase), dedup by branch, sort by recent commit
+   - See `~/.claude/skills/devflow:worktree-support/SKILL.md` for the full 7-step algorithm and canonical protected branch list
+2. **If `--path` flag provided:** use only that worktree, skip discovery
+   **`--path` validation**: Before proceeding, verify the path exists as a directory and appears in `git worktree list` output. If not: report error and stop.
+3. **If only 1 reviewable worktree** (the common case): proceed as single-worktree flow — zero behavior change
+4. **If multiple reviewable worktrees:** report "Found N worktrees with reviewable branches: {list with paths and branches}" and proceed with multi-worktree flow
+
+#### Step 0b: Resolve COMPLIANCE_SKILL_INSTALLED
+
+**Produces:** COMPLIANCE_SKILL_INSTALLED
+
+**Resolve `COMPLIANCE_SKILL_INSTALLED` once per run:** Check whether `~/.claude/skills/devflow:compliance/SKILL.md` exists (one file-existence check, read-only, silent). Set `COMPLIANCE_SKILL_INSTALLED = true` if the file exists, `false` otherwise.
+Reuse this result for every worktree and every downstream phase.
+
+#### Step 0c: Per-Worktree Pre-Flight (Git Agent)
+
+**Produces:** BRANCH_INFO, PR_INFO, PR_DESCRIPTION, PR_DESCRIPTION_GUIDANCE
+**Requires:** WORKTREES
+
+Discover PR description guidance from plan artifact (per worktree):
+1. List `{worktree}/.devflow/docs/design/*.md` files
+2. Sort by timestamp in filename (descending -- timestamps are YYYY-MM-DD_HHMM, naturally sortable)
+3. Read the most recent file, extract `## PR Description Guidance` section
+4. If no plan files exist or section not found, set `PR_DESCRIPTION_GUIDANCE` to `(none)`
+
+For each reviewable worktree, spawn Git agent:
+
+```
+Agent(subagent_type="Git", run_in_background=false):
+"OPERATION: ensure-pr-ready
+WORKTREE_PATH: {worktree_path}  (omit if cwd)
+PR_DESCRIPTION_GUIDANCE: {pr_description_guidance}
+COMPLIANCE: {COMPLIANCE_SKILL_INSTALLED ? "enabled" : "(none)"}
+Validate branch, commit if needed, push, create PR if needed.
+Return: branch, base_branch, branch-slug, PR#"
+```
+
+In multi-worktree mode, spawn all pre-flight agents **in a single message** (parallel).
+
+**If BLOCKED:** In single-worktree mode, stop and report. In multi-worktree mode, report the failure but continue with other worktrees.
+
+**Extract from response:** `branch`, `base_branch`, `branch_slug`, `pr_number` per worktree.
+
+**Fetch PR body** (after extracting `pr_number`):
+```bash
+PR_DESCRIPTION=$(gh pr view {pr_number} --json body --jq '.body' 2>/dev/null || echo "(none)")
+```
+If `pr_number` is absent or the command fails, set `PR_DESCRIPTION` to `(none)`.
+
+#### Step 0d: Incremental Detection & Timestamp Setup
+
+**Produces:** DIFF_RANGE, REVIEW_DIR, TIMESTAMP
+**Requires:** BRANCH_INFO
+
+For each worktree:
+
+1. Generate timestamp: `YYYY-MM-DD_HHMM`. If directory already exists (same-minute collision), append seconds (`YYYY-MM-DD_HHMMSS`).
+2. Create timestamped review directory: `mkdir -p {worktree}/.devflow/docs/reviews/{branch-slug}/{timestamp}/`
+3. Check if `{worktree}/.devflow/docs/reviews/{branch-slug}/.last-review-head` exists:
+   - **If yes AND `--full` NOT set:**
+     - Read the SHA from the file
+     - Verify reachable: `git -C {worktree} cat-file -t {sha}` (handles rebases — if unreachable, fallback to full)
+     - Check if SHA == current HEAD → if so, skip review: "No new commits since last review. Use --full for a full re-review."
+     - Set `DIFF_RANGE` to `{last-review-sha}...HEAD`
+   - **If no (first review), or `--full`:**
+     - Set `DIFF_RANGE` to `{base_branch}...HEAD`
+
+#### Step 0e-i: Load Prior Resolution and Count Cycles
+
+**Produces:** PRIOR_RESOLUTIONS, CYCLE_NUMBER
+**Requires:** BRANCH_INFO
+
+For each worktree, perform a single pass over timestamped directories:
+1. List timestamped directories in `{worktree}/.devflow/docs/reviews/{branch-slug}/` sorted descending: `ls -1d {worktree}/.devflow/docs/reviews/{branch-slug}/20* 2>/dev/null | sort -r`
+2. Iterate once: accumulate CYCLE_NUMBER count for each directory containing `resolution-summary.md`; capture the first (most-recent) such directory as PRIOR_DIR.
+3. If CYCLE_NUMBER = 0: set PRIOR_RESOLUTIONS=(none), CYCLE_NUMBER=1, proceed.
+4. Otherwise: set CYCLE_NUMBER = count + 1. Read `{PRIOR_DIR}/resolution-summary.md` as PRIOR_RESOLUTIONS.
+5. If `--full`: still load PRIOR_RESOLUTIONS (valuable for Review agent cross-cycle awareness).
+
+#### Step 0e-ii: Convergence Assessment
+
+**Produces:** (refines CYCLE_NUMBER)
+**Requires:** PRIOR_RESOLUTIONS, BRANCH_INFO
+
+MAX_REVIEW_CYCLES = 10
+
+1. If CYCLE_NUMBER > MAX_REVIEW_CYCLES:
+   Warn in output: "⚠️ Review pipeline has run {CYCLE_NUMBER-1} cycles (exceeds MAX_REVIEW_CYCLES=10). Consider merging or manual inspection."
+   Continue with review.
+2. Parse Statistics table from PRIOR_RESOLUTIONS:
+   - Extract False Positive, Fixed, Deferred counts
+   - `deferred_count` = the Deferred row value (= FIX_SEPARATE + TECH_DEBT); By Design and Escalated are excluded from the fp_ratio denominator
+   - fp_ratio = fp_count / (fp_count + fixed_count + deferred_count)
+   - If denominator = 0: fp_ratio = 0, skip warning
+   - If parsing fails: fp_ratio = 0, skip warning; note in output: "Warning: Could not parse Statistics table from prior resolution. FP ratio unavailable — convergence tracking degraded."
+3. If fp_ratio > 0.7 AND CYCLE_NUMBER >= 3:
+   Warn in output: "⚠️ Convergence: {ratio}% false positives in cycle {N-1}. Consider merging or manual inspection."
+   Continue with review.
+
+**Decision table — Step 0e-ii paths:**
+
+| Condition | Outcome |
+|-----------|---------|
+| CYCLE_NUMBER > MAX_REVIEW_CYCLES | Warn in output, continue |
+| denominator = 0 OR parsing failed | fp_ratio = 0, skip warning (degraded note on parse failure) |
+| fp_ratio > 0.7 AND CYCLE_NUMBER >= 3 | Warn in output, continue |
+
+#### Step 0f: Resolve Publication Mode (Per Worktree)
+
+**Produces:** REVIEW_PUBLICATION
+**Requires:** WORKTREES
+
+For each reviewable worktree, call:
+
+**Resolve `REVIEW_PUBLICATION` per worktree:** Read the current worktree's `.devflow/config.json` (a single, direct file read — multi-worktree repos may have different publication settings per worktree root). If the file exists and `reviewPublication` is one of `auto`, `full`, or `off`, set `REVIEW_PUBLICATION` to that value; otherwise set `REVIEW_PUBLICATION = "auto"`.
+
+Note: `auto` is NOT fail-open — under `auto`, the Git agent probes the repository visibility and treats any error or unrecognised value as PUBLIC (mode STUB).
+
+### Phase 1: Analyze Changed Files
+
+**Produces:** REVIEW_FOCUS_LIST
+**Requires:** DIFF_RANGE, COMPLIANCE_SKILL_INSTALLED (from Step 0b)
+
+Per worktree, detect file types in diff using `DIFF_RANGE` to determine conditional reviews.
+
+| Condition | Adds Review |
+|-----------|-------------|
+| Any .ts or .tsx files | typescript |
+| .tsx or .jsx files (React components) | react |
+| .tsx or .jsx files (React components) | accessibility |
+| .tsx/.jsx/.css/.scss files | ui-design |
+| .go files | go |
+| .java files | java |
+| .py files | python |
+| .rs files | rust |
+| DB/migration files | database |
+| Dependency files changed | dependencies |
+| Docs or significant code | documentation |
+| COMPLIANCE_SKILL_INSTALLED AND diff touches regulated surface | compliance |
+
+If `COMPLIANCE_SKILL_INSTALLED` AND the diff touches regulated surface (data models, auth flows, logging/observability, payments, IaC, retention): add `compliance` to REVIEW_FOCUS_LIST for this worktree.
+
+### Phase 1b: Load Decisions Index
+
+**Produces:** DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, COMPLIANCE_SKILL_INSTALLED (carried from Step 0b)
+
+**Load Companion Skills** — Load via Skill tool: `devflow:quality-gates`, `devflow:software-design`. If a skill fails to load, continue without it.
+
+### Load DECISIONS_CONTEXT
+
+Resolve the worktree root using the `devflow:worktree-support` algorithm (use WORKTREE_PATH if provided, otherwise cwd). All paths below are relative to `{worktree}`.
+
+**Step 1 — Read the pre-rendered index:**
+
+Attempt to read `{worktree}/.devflow/learning/index.md`.
+
+- If the file exists and contains non-empty content: use that content as `DECISIONS_CONTEXT`.
+- If the file is absent or empty: set `DECISIONS_CONTEXT` to `(none)`.
+
+**No subprocess, no `.cjs` script.** This is a single direct file read — the index is written at render time by `render-decisions.cjs` alongside `decisions.md`/`pitfalls.md`.
+
+**Step 2 — Apply decisions using `devflow:apply-decisions`:**
+
+When `DECISIONS_CONTEXT` is not `(none)`, follow `devflow:apply-decisions` to scan the index, identify plausibly-relevant entries, Read full entry bodies on demand, and cite verbatim IDs in downstream agent prompts and reasoning.
+
+This produces a compact index of active ADR/PF entries. Pass `DECISIONS_CONTEXT` to all Review agents. Review agents use `devflow:apply-decisions` to Read full entry bodies on demand.
+
+### Load Feature Knowledge
+
+Resolve the worktree root using the `devflow:worktree-support` algorithm (use WORKTREE_PATH if provided, otherwise cwd). All paths below are relative to `{worktree}`.
+
+**Step 1 — Read the index cache:**
+
+Attempt to read `{worktree}/.devflow/features/index.md`. Each line follows the format:
+
+```
+- **{slug}** — {areas} — {Use-when description}
+```
+
+If `index.md` exists and contains at least one entry line, use it for relevance matching.
+
+**Step 2 — Fallback: glob frontmatter (if `index.md` is absent or empty):**
+
+Glob `{worktree}/.devflow/features/*/KNOWLEDGE.md`. For each file found, read only its YAML frontmatter block (between the opening and closing `---` delimiters). The frontmatter fields `name`, `description`, and `directories` are the authoritative relevance surface — `index.md` is only a cache.
+
+**Step 3 — Pick relevant KBs:**
+
+Match the current task area and description against each index line (or frontmatter `description` + `directories` on fallback). Select entries whose documented area overlaps the current task. This is a relevance judgment — prefer specificity over breadth.
+
+**Step 4 — Read selected KBs:**
+
+For each selected entry, read `{worktree}/.devflow/features/{slug}/KNOWLEDGE.md` in full. When the KB content contradicts the current code you observe, **trust the code** — the code is the freshness mechanism; the KB may lag behind.
+
+**Step 5 — Set FEATURE_KNOWLEDGE:**
+
+Concatenate the selected KNOWLEDGE.md files under slug headers:
+
+```
+--- Feature knowledge: {slug} ---
+{full KNOWLEDGE.md content}
+```
+
+If no KBs exist, no KBs are relevant, or `.devflow/features/` is absent, set `FEATURE_KNOWLEDGE` to `(none)`.
+
+**No subprocess, no git calls, no `.cjs` script.** This entire step is direct file reads — 1 index read (or N frontmatter reads on fallback), bounded by KB count.
+
+Pass `FEATURE_KNOWLEDGE` to all Review agents alongside `DECISIONS_CONTEXT`.
+
+### Phase 2: Run Reviews (Parallel)
+
+**Produces:** REVIEW_FOCUS_OUTPUTS
+**Requires:** DIFF_RANGE, REVIEW_DIR, TIMESTAMP, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, PR_DESCRIPTION, PRIOR_RESOLUTIONS, REVIEW_FOCUS_LIST
+
+Spawn Review agents **in a single message**. Always run 8 core reviews; conditionally add more based on changed file types (max 20 per worktree):
+
+| Focus | Always | Pattern Skill |
+|-------|--------|---------------|
+| security | ✓ | devflow:security |
+| architecture | ✓ | devflow:architecture |
+| performance | ✓ | devflow:performance |
+| complexity | ✓ | devflow:complexity |
+| consistency | ✓ | devflow:consistency |
+| regression | ✓ | devflow:regression |
+| testing | ✓ | devflow:testing |
+| reliability | ✓ | devflow:reliability |
+| typescript | conditional | devflow:typescript |
+| react | conditional | devflow:react |
+| accessibility | conditional | devflow:accessibility |
+| ui-design | conditional | devflow:ui-design |
+| go | conditional | devflow:go |
+| java | conditional | devflow:java |
+| python | conditional | devflow:python |
+| rust | conditional | devflow:rust |
+| database | conditional | devflow:database |
+| dependencies | conditional | devflow:dependencies |
+| documentation | conditional | devflow:documentation |
+| compliance | diff-driven | devflow:compliance |
+
+Review agent count: 8 always-active, +1-12 diff-driven conditional (max 20 total per worktree).
+
+Each Review agent invocation (all in one message, **NOT background**):
+```
+Agent(subagent_type="Review", run_in_background=false):
+"Review focusing on {focus}. Load the pattern skill via the Skill tool: Skill(skill="devflow:{focus}").
+Follow 6-step process from devflow:review-methodology.
+PR: #{pr_number}, Base: {base_branch}
+WORKTREE_PATH: {worktree_path}  (omit if cwd)
+DIFF_COMMAND: git -C {WORKTREE_PATH} diff {DIFF_RANGE}  (omit -C flag if no WORKTREE_PATH)
+DECISIONS_CONTEXT: {decisions_context}
+FEATURE_KNOWLEDGE: {feature_knowledge}
+PR_DESCRIPTION: <pr-description>{pr_description}</pr-description>
+PRIOR_RESOLUTIONS: <prior-resolution-summary>{prior_resolutions}</prior-resolution-summary>
+If PRIOR_RESOLUTIONS is not (none), follow Cross-Cycle Awareness in review.md.
+Follow devflow:apply-decisions to scan the index and Read full ADR/PF bodies on demand.
+Follow devflow:apply-feature-knowledge for FEATURE_KNOWLEDGE — feature-specific patterns and anti-patterns inform findings.
+IMPORTANT: Write report to {worktree_path}/.devflow/docs/reviews/{branch-slug}/{timestamp}/{focus}.md using Write tool"
+```
+
+In multi-worktree mode, process worktrees **sequentially** (one worktree at a time). Complete Phases 1-4 for each worktree before starting the next. This prevents agent overload — spawning 8-20 Review agents per worktree across multiple worktrees simultaneously overwhelms the system.
+
+### Phase 3: Synthesis → Review Comment (Sequential)
+
+**Produces:** REVIEW_SUMMARY, PR_COMMENT
+**Requires:** REVIEW_FOCUS_OUTPUTS, REVIEW_DIR, PR_INFO
+
+**WAIT** for Phase 2. For each worktree, run steps 3a and 3b in sequence:
+
+**Step 3a — Synthesize agent** per worktree (wait for completion before 3b):
+```
+Agent(subagent_type="Synthesize", run_in_background=false):
+"Mode: review
+WORKTREE_PATH: {worktree_path}  (omit if cwd)
+REVIEW_BASE_DIR: {worktree_path}/.devflow/docs/reviews/{branch-slug}/{timestamp}
+TIMESTAMP: {timestamp}
+CYCLE_NUMBER: {cycle_number}
+PRIOR_RESOLUTIONS: <prior-resolution-summary>{prior_resolutions}</prior-resolution-summary>
+Include Convergence Status section in review-summary.md.
+Aggregate findings, determine merge recommendation.
+Output: {worktree_path}/.devflow/docs/reviews/{branch-slug}/{timestamp}/review-summary.md"
+```
+
+**Step 3b — Git agent (post-review-summary)** per worktree (after Step 3a writes review-summary.md):
+```
+Agent(subagent_type="Git", run_in_background=false):
+"OPERATION: post-review-summary
+PR_NUMBER: {pr_number}
+REVIEW_SUMMARY_PATH: {worktree_path}/.devflow/docs/reviews/{branch-slug}/{timestamp}/review-summary.md
+CYCLE_NUMBER: {cycle_number}
+REVIEW_TIMESTAMP: {timestamp}
+REVIEW_PUBLICATION: {REVIEW_PUBLICATION}
+WORKTREE_PATH: {worktree_path}  (omit if cwd)
+Posts the consolidated review-summary comment (marker-deduped by the operation on the cycle+timestamp pair)."
+```
+
+### Phase 4: Write Review Head Marker & Report
+
+**Requires:** BRANCH_INFO, REVIEW_DIR
+
+Per worktree, after successful completion:
+1. Write current HEAD SHA to `{worktree_path}/.devflow/docs/reviews/{branch-slug}/.last-review-head`
+2. Display results from all agents:
+   - Merge recommendation (from Synthesize agent)
+   - Issue counts by category (🔴 blocking / ⚠️ should-fix / ℹ️ pre-existing)
+   - Review comment status: POSTED / POSTED+TRUNCATED (body exceeded 60k after redaction) / SKIPPED (D7 dedup) / DEGRADED (from Git)
+   - Publication status: FULL (private repo) | FULL (config override) | STUB (public repository) | OFF (publication disabled by config) (from Git agent)
+   - Artifact paths
+
+In multi-worktree mode, report results per worktree.
+
+## Architecture
+
+```
+/code-review (orchestrator - spawns agents only)
+│
+├─ Phase 0: Worktree Discovery & Pre-flight
+│  ├─ Step 0a: git worktree list → filter reviewable
+│  ├─ Step 0b: Resolve COMPLIANCE_SKILL_INSTALLED
+│  ├─ Step 0c: Git agent (ensure-pr-ready) per worktree [parallel]
+│  ├─ Step 0d: Incremental detection + timestamp setup per worktree
+│  ├─ Step 0e-i: Load prior resolution-summary.md
+│  ├─ Step 0e-ii: Convergence assessment (warn if FP ratio > 70%)
+│  └─ Step 0f: Resolve REVIEW_PUBLICATION per worktree (publication gate)
+│
+├─ Per worktree (SEQUENTIAL — one worktree at a time):
+│  │
+│  ├─ Phase 1: Analyze changed files
+│  │  └─ Detect file types for conditional reviews
+│  │
+│  ├─ Phase 2: Reviews (PARALLEL within worktree)
+│  │  ├─ Review agent: security
+│  │  ├─ Review agent: architecture, performance, complexity
+│  │  ├─ Review agent: consistency, regression, testing
+│  │  └─ Review agent: [conditional]
+│  │
+│  ├─ Phase 3: Synthesis → Review Comment (SEQUENTIAL within worktree)
+│  │  ├─ Step 3a: Synthesize agent (mode: review, writes review-summary.md)
+│  │  └─ Step 3b: Git agent (post-review-summary, D7 marker-dedup, REVIEW_PUBLICATION)
+│  │
+│  └─ Phase 4: Write .last-review-head + display results
+```
+
+## Edge Cases
+
+| Case | Handling |
+|------|----------|
+| No new commits since last review | Skip review, report: "No new commits since last review. Use --full for a full re-review." |
+| Rebase invalidates `.last-review-head` SHA | `git cat-file -t` check fails → fallback to full diff |
+| Same-minute review collision | `mkdir` fails → retry with seconds appended (`YYYY-MM-DD_HHMMSS`) |
+| Worktree in detached HEAD | Filtered out (no branch name → not reviewable) |
+| Worktree mid-rebase or mid-merge | Filtered out by status check |
+| Two worktrees on same branch | Deduplicate by branch — review once, use first worktree's path |
+| Worktree on protected branch | Filtered out (not reviewable) |
+| Worktree pre-flight fails | Report failure, continue with other worktrees |
+| `--full` in multi-worktree mode | Applies to all worktrees (global modifier) |
+| Many worktrees (5+) | Report count and proceed — user manages their worktree count |
+| Review comment already posted | Git agent matches `<!-- devflow:review-summary cycle:{N} ts:{REVIEW_TIMESTAMP}` pair → skip silently (D7); a re-review in the same cycle (different timestamp) posts its own comment |
+| First review (no prior resolution) | PRIOR_RESOLUTIONS=(none), no convergence check |
+| fp_ratio denominator = 0 | fp_ratio = 0, no warning |
+| `--full` flag | Bypass incremental detection (Step 0d), still load PRIOR_RESOLUTIONS for cross-cycle awareness |
+| Parsing failure on resolution-summary.md | fp_ratio = 0, convergence tracking degraded (see Step 0e-ii) |
+| Concurrent sessions | Advisory only, each session computes independently |
+| Public repo (`auto` mode) | Git agent probes visibility, posts counts-only STUB comment; full report stays local |
+| `reviewPublication: off` | Git agent skips posting the review comment (OFF) |
+
+## Backwards Compatibility
+
+- **Single worktree**: Auto-discovery finds only one worktree → proceeds exactly as before. Zero behavior change.
+- **Legacy flat layout**: If `.devflow/docs/reviews/{branch-slug}/` contains flat `*.md` files (no timestamped subdirectories), new runs create timestamped subdirectories. Old flat files remain untouched.
+
+## Principles
+
+1. **Orchestration only** - Command spawns agents, doesn't do git/review work itself
+2. **Parallel, not background** - Multiple agents in one message, but `run_in_background=false` so phases complete before proceeding
+3. **Git agent for git work** - All git operations go through Git agent
+4. **Clear ownership** - Each agent owns its output completely
+5. **Honest reporting** - Display agent outputs directly
+6. **Incremental by default** - Only review new changes unless `--full` specified
+7. **Auto-discover worktrees** - One command handles all reviewable branches

package/dist/commands/debug.md

@@ -0,0 +1,282 @@
+---
+description: Debug issues using competing hypothesis investigation with parallel agents
+---
+# Debug Command
+
+Investigate bugs by spawning parallel agents, each pursuing a different hypothesis. Evidence is aggregated and synthesized to identify the root cause.
+
+## Usage
+
+```
+/debug "description of bug or issue"
+/debug "function returns undefined when called with empty array"
+/debug #42   (investigate bug from GitHub issue)
+```
+
+## Input
+
+`$ARGUMENTS` contains whatever follows `/debug`:
+- Bug description: "login fails after session timeout"
+- GitHub issue: "#42"
+- Empty: use conversation context
+
+## Phases
+
+### Phase 1: Load Decisions Index (Orchestrator-Local)
+
+**Produces:** DECISIONS_CONTEXT
+
+**Load Companion Skills** — Load via Skill tool: `devflow:test-driven-development`, `devflow:software-design`, `devflow:testing`. If a skill fails to load, continue without it.
+
+### Load DECISIONS_CONTEXT
+
+Resolve the worktree root using the `devflow:worktree-support` algorithm (use WORKTREE_PATH if provided, otherwise cwd). All paths below are relative to `{worktree}`.
+
+**Step 1 — Read the pre-rendered index:**
+
+Attempt to read `{worktree}/.devflow/learning/index.md`.
+
+- If the file exists and contains non-empty content: use that content as `DECISIONS_CONTEXT`.
+- If the file is absent or empty: set `DECISIONS_CONTEXT` to `(none)`.
+
+**No subprocess, no `.cjs` script.** This is a single direct file read — the index is written at render time by `render-decisions.cjs` alongside `decisions.md`/`pitfalls.md`.
+
+**Step 2 — Apply decisions using `devflow:apply-decisions`:**
+
+When `DECISIONS_CONTEXT` is not `(none)`, follow `devflow:apply-decisions` to scan the index, identify plausibly-relevant entries, Read full entry bodies on demand, and cite verbatim IDs in downstream agent prompts and reasoning.
+
+The orchestrator uses `DECISIONS_CONTEXT` locally when generating hypotheses (Phase 2) — prior pitfalls and decisions can suggest specific root causes to investigate. Follow `devflow:apply-decisions` to Read full entry bodies on demand. **Do NOT pass `DECISIONS_CONTEXT` to Explore investigators** — decisions context stays in the orchestrator; investigators examine code directly.
+
+**No up-front feature knowledge load** — debug investigation workers read code directly to avoid confirmation bias. Feature knowledge is only written back at the end if the investigation surfaced durable, cross-cutting knowledge.
+
+### Phase 2: Context Gathering
+
+**Produces:** HYPOTHESES, BUG_CONTEXT
+**Requires:** DECISIONS_CONTEXT
+
+If `$ARGUMENTS` starts with `#`, fetch the GitHub issue:
+
+```
+Agent(subagent_type="Git"):
+"OPERATION: fetch-issue
+ISSUE: {issue number}
+Return issue title, body, labels, and any linked error logs."
+```
+
+Analyze the bug description (from arguments or issue) and identify 3-5 plausible hypotheses. Each hypothesis must be:
+- **Specific**: Points to a concrete mechanism (not "something is wrong")
+- **Testable**: Can be confirmed or disproved by reading code/logs
+- **Distinct**: Does not overlap significantly with other hypotheses
+
+### Phase 3: Investigate (Parallel)
+
+**Produces:** INVESTIGATION_RESULTS
+**Requires:** HYPOTHESES
+
+Spawn one Explore agent per hypothesis in a **single message** (parallel execution):
+
+```
+Agent(subagent_type="Explore"):
+"Investigate this bug: {bug_description}
+
+Hypothesis: {hypothesis A description}
+Focus area: {specific code area, mechanism, or condition}
+
+Steps:
+1. Read relevant code files in your focus area
+2. Trace data flow related to this hypothesis
+3. Collect evidence FOR this hypothesis (with file:line references)
+4. Collect evidence AGAINST this hypothesis (with file:line references)
+
+Return a structured report:
+- Hypothesis: {restate}
+- Status: CONFIRMED / DISPROVED / PARTIAL
+- Evidence FOR: [list with file:line refs]
+- Evidence AGAINST: [list with file:line refs]
+- Key finding: {one-sentence summary}"
+
+Agent(subagent_type="Explore"):
+"Investigate this bug: {bug_description}
+
+Hypothesis: {hypothesis B description}
+Focus area: {specific code area, mechanism, or condition}
+
+[same steps and return format]"
+
+Agent(subagent_type="Explore"):
+"Investigate this bug: {bug_description}
+
+Hypothesis: {hypothesis C description}
+Focus area: {specific code area, mechanism, or condition}
+
+[same steps and return format]"
+
+(Add more investigators if bug complexity warrants 4-5 hypotheses)
+```
+
+### Phase 4: Converge
+
+**Produces:** CONVERGENCE_DECISION
+**Requires:** INVESTIGATION_RESULTS
+
+Evaluate investigation verdicts before synthesis:
+
+- **One CONFIRMED**: Spawn 1-2 additional `Agent(subagent_type="Explore")` agents to validate from different angles (prevent confirmation bias)
+- **Multiple PARTIAL**: Look for a unifying root cause that explains all partial evidence
+- **All DISPROVED**: Report honestly — "No root cause identified from initial hypotheses." Generate 2-3 second-round hypotheses if conversation context suggests avenues not yet explored. Loop back to Phase 3.
+
+### Phase 5: Synthesize
+
+**Produces:** ROOT_CAUSE_SYNTHESIS
+**Requires:** INVESTIGATION_RESULTS, CONVERGENCE_DECISION
+
+Once all investigators return, spawn a Synthesize agent to aggregate findings:
+
+```
+Agent(subagent_type="Synthesize"):
+"You are a root cause analyst. Synthesize these investigation reports:
+
+{paste all investigator reports}
+
+Instructions:
+1. Compare evidence across all hypotheses
+2. Identify which hypothesis has the strongest evidence
+3. Note contradictions between investigators
+4. Determine overall root cause (may combine partial findings)
+5. Assess confidence level based on evidence strength"
+```
+
+### Phase 6: Report
+
+**Requires:** ROOT_CAUSE_SYNTHESIS
+
+Produce the final report:
+
+```markdown
+## Root Cause Analysis: {bug description}
+
+### Root Cause
+{Description of the root cause supported by evidence}
+{Key evidence with file:line references}
+
+### Investigation Summary
+
+| Hypothesis | Status | Key Evidence |
+|-----------|--------|-------------|
+| A: {description} | CONFIRMED/DISPROVED/PARTIAL | {file:line + summary} |
+| B: {description} | CONFIRMED/DISPROVED/PARTIAL | {file:line + summary} |
+| C: {description} | CONFIRMED/DISPROVED/PARTIAL | {file:line + summary} |
+
+### Key Findings
+{2-3 most important discoveries across all investigators}
+
+### Recommended Fix
+{Concrete action items with file references}
+
+### Confidence Level
+{HIGH/MEDIUM/LOW based on evidence strength and investigator agreement}
+```
+
+### Phase 7: Offer Fix
+
+**Requires:** ROOT_CAUSE_SYNTHESIS
+
+Ask user via AskUserQuestion: "Want me to implement this fix?"
+
+- **YES** → Load `devflow:patterns` and `devflow:test-driven-development` skills, implement the fix, then spawn `Agent(subagent_type="Simplify")` on changed files.
+- **NO** → Done. Report stands as documentation.
+
+### Feature Knowledge Write-Back (Conditional)
+
+Resolve the worktree root using the `devflow:worktree-support` algorithm (use WORKTREE_PATH if provided, otherwise cwd). All paths below are relative to `{worktree}`.
+
+**Step 1 — Check the opt-out gate:**
+
+Read `{worktree}/.devflow/config.json`. If the `knowledge` field is `false`, skip write-back entirely — the user has disabled it.
+
+If `.devflow/config.json` does not exist, proceed (default is enabled).
+
+**Step 2 — Evaluate whether write-back is warranted:**
+
+Only proceed if **at least one** of these is true:
+- This workflow changed files in a directory that is documented by an existing feature knowledge base (a documented area changed).
+- This workflow surfaced durable, cross-cutting knowledge about a codebase area that would help future agents working in the same area — patterns, anti-patterns, integration points, gotchas not visible from a single file read.
+
+**Never spawn unconditionally.** If neither condition is met, skip write-back silently.
+
+**Step 3 — Spawn the Knowledge agent:**
+
+Spawn `Agent(subagent_type="Knowledge")` with the following context:
+
+```
+"WORKTREE_PATH: {worktree root}
+FEATURE_SLUG: {slug derived from primary changed directory, kebab-case}
+FEATURE_NAME: {human-readable name}
+DIRECTORIES: {list of primary directories touched by this workflow}
+FILES_CHANGED: {list of files changed}
+DECISIONS_CONTEXT: {DECISIONS_CONTEXT if available, else (none)}
+
+Load the devflow:feature-knowledge skill and follow its authoring process.
+
+Write the knowledge base to:
+  {worktree}/.devflow/features/{slug}/KNOWLEDGE.md
+
+Then update the index cache by performing a read-modify-write on:
+  {worktree}/.devflow/features/index.md
+
+Index line format: `- **{slug}** — {areas} — {Use-when description}`
+
+If the line for this slug already exists in index.md, replace it. If it does not exist, append it. If index.md does not exist, create it with just this line.
+
+The frontmatter in KNOWLEDGE.md is the source of truth — index.md is only a cache. Write the two files directly — no intermediate result JSON files, no external scripts.
+
+After writing, commit the two files to the current worktree branch yourself by running git via your Bash tool (do not use a script). Stage ONLY .devflow/features/index.md and .devflow/features/{slug}/KNOWLEDGE.md, then commit just those paths with a docs(knowledge): message. Do NOT push, do NOT force, do NOT stage anything else. Follow your Commit Protocol — it is non-blocking, so if any git step fails, report KB_COMMIT and finish normally."
+```
+
+**Failure handling**: Non-blocking. If the Knowledge agent fails, log the failure and continue — the workflow outcome is not affected by write-back success.
+
+## Architecture
+
+```
+/debug (orchestrator)
+│
+├─ Phase 1: Load Decisions Index (Orchestrator-Local)
+│  └─ No up-front feature knowledge load (avoids confirmation bias in investigators)
+│
+├─ Phase 2: Context gathering
+│  └─ Git agent (fetch issue, if #N provided)
+│
+├─ Phase 3: Parallel investigation
+│  └─ 3-5 Explore agents, one per hypothesis (single message)
+│
+├─ Phase 4: Converge
+│  └─ Validate confirmed hypotheses, unify partials, or generate second-round
+│
+├─ Phase 5: Synthesize
+│  └─ Synthesize agent aggregates and compares findings
+│
+├─ Phase 6: Root cause report with confidence level
+│
+├─ Phase 7: Offer Fix
+│  └─ AskUserQuestion → implement fix + Simplify agent, or done
+│
+└─ Feature Knowledge Write-Back (Conditional)
+   └─ Knowledge agent (if investigation surfaced durable cross-cutting knowledge)
+```
+
+## Principles
+
+1. **Competing hypotheses** - Never investigate a single theory; always have alternatives
+2. **Parallel execution** - All investigators run simultaneously for speed
+3. **Evidence-based** - Every claim requires file:line references
+4. **Honest uncertainty** - If no hypothesis survives, report that clearly
+5. **Convergence validation** - Confirmed hypotheses get additional validation to prevent confirmation bias
+6. **No pre-loaded knowledge in sub-agents** - Investigators read code fresh to avoid confirmation bias; feature knowledge write-back happens only after investigation completes
+
+## Error Handling
+
+- If fewer than 3 hypotheses can be generated: proceed with 2, note limited scope
+- If all hypotheses are disproved: report "No root cause identified" with investigation summary
+- If an investigator errors: continue with remaining results, note the gap
+- If convergence validation contradicts the original confirmation: downgrade confidence and report contradicting evidence
+- If user declines fix: done — report stands as documentation