maestro-flow 0.3.38 → 0.3.40

package/.claude/commands/manage-learn.md

@@ -1,67 +1,67 @@
----
-name: manage-learn
-description: Capture, search, and review atomic learning insights and tips into .workflow/learning/lessons.jsonl
-argument-hint: "[<text>|tip <text>|list|search|show <id>] [--category ...] [--tag t1,t2] [--phase N] [--confidence ...]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - AskUserQuestion
----
-<purpose>
-Unified atomic knowledge capture for the workflow learning library. Captures two types of knowledge:
-- **Insights**: Timeless "eureka moment" entries (patterns, gotchas, techniques) — the default mode
-- **Tips**: Quick contextual notes for cross-session recovery (formerly in `manage-knowhow-capture tip`)
-
-Both types are stored in `.workflow/learning/lessons.jsonl` with auto-detected phase linkage and keyword-based category inference. Tips are distinguished by `source: "tip"` and implicitly tagged `tip`. Same store as retrospective output, so search and list see the entire knowledge corpus.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/learn.md
-</required_reading>
-
-<context>
-Arguments: $ARGUMENTS
-
-**Modes (auto-detected from first token):**
-- `"<insight text>"` (or any non-keyword text) → insight capture mode
-- `tip <text>` → tip capture mode (quick contextual note, auto-tagged `tip`)
-- `list` → list recent entries (default 20)
-- `search <query>` → text search across lessons.jsonl
-- `show <INS-id>` → full detail with phase context
-- empty → AskUserQuestion to prompt for text
-
-Flags, storage paths, and shared store rationale defined in workflow learn.md.
-</context>
-
-<execution>
-Follow `~/.maestro/workflows/learn.md` Stages 1–5 in order.
-</execution>
-
-<error_codes>
-| Code | Severity | Description | Stage |
-|------|----------|-------------|-------|
-| E001 | error | `.workflow/` not initialized — run `/maestro-init` first | parse_input |
-| E002 | error | Unknown `--category` value (allowed: pattern, antipattern, decision, tool, gotcha, technique, tip) | parse_input |
-| E003 | error | `show` mode requires an INS-id argument | show |
-| E004 | error | Insight id not found in lessons.jsonl | show |
-| W001 | warning | Auto-phase detection found a current_phase but no matching artifact in registry; phase set to null | capture |
-| W002 | warning | learning-index.json out of sync with lessons.jsonl (different row count); offer to rebuild | list/search |
-</error_codes>
-
-<success_criteria>
-- [ ] Mode correctly routed (capture / list / search / show)
-- [ ] Capture: `lessons.jsonl` row appended with valid JSON and all required fields
-- [ ] Capture: `learning-index.json` updated with matching entry
-- [ ] Capture: phase auto-link resolves correctly via artifact registry when `state.json` has `current_phase`
-- [ ] Capture: category inference produces a sensible default when `--category` absent
-- [ ] List: filters apply, output sorted newest-first, default limit 20
-- [ ] Search: results ranked by title (3) > tags (2) > summary (1) match
-- [ ] Show: full insight displayed with phase context and routed-artifact link if any
-- [ ] No file modifications outside `.workflow/learning/`
-- [ ] Confirmation banner displayed with INS-id and next-step hints
-- [ ] Next step: `/manage-learn list` to browse, or `/manage-learn search <query>` to find related insights
-</success_criteria>
+---
+name: manage-learn
+description: Capture and search learning insights and tips
+argument-hint: "[<text>|tip <text>|list|search|show <id>] [--category ...] [--tag t1,t2] [--phase N] [--confidence ...]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+<purpose>
+Unified atomic knowledge capture for the workflow learning library. Captures two types of knowledge:
+- **Insights**: Timeless "eureka moment" entries (patterns, gotchas, techniques) — the default mode
+- **Tips**: Quick contextual notes for cross-session recovery (formerly in `manage-knowhow-capture tip`)
+
+Both types are stored in `.workflow/learning/lessons.jsonl` with auto-detected phase linkage and keyword-based category inference. Tips are distinguished by `source: "tip"` and implicitly tagged `tip`. Same store as retrospective output, so search and list see the entire knowledge corpus.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/learn.md
+</required_reading>
+
+<context>
+Arguments: $ARGUMENTS
+
+**Modes (auto-detected from first token):**
+- `"<insight text>"` (or any non-keyword text) → insight capture mode
+- `tip <text>` → tip capture mode (quick contextual note, auto-tagged `tip`)
+- `list` → list recent entries (default 20)
+- `search <query>` → text search across lessons.jsonl
+- `show <INS-id>` → full detail with phase context
+- empty → AskUserQuestion to prompt for text
+
+Flags, storage paths, and shared store rationale defined in workflow learn.md.
+</context>
+
+<execution>
+Follow `~/.maestro/workflows/learn.md` Stages 1–5 in order.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | error | `.workflow/` not initialized — run `/maestro-init` first | parse_input |
+| E002 | error | Unknown `--category` value (allowed: pattern, antipattern, decision, tool, gotcha, technique, tip) | parse_input |
+| E003 | error | `show` mode requires an INS-id argument | show |
+| E004 | error | Insight id not found in lessons.jsonl | show |
+| W001 | warning | Auto-phase detection found a current_phase but no matching artifact in registry; phase set to null | capture |
+| W002 | warning | learning-index.json out of sync with lessons.jsonl (different row count); offer to rebuild | list/search |
+</error_codes>
+
+<success_criteria>
+- [ ] Mode correctly routed (capture / list / search / show)
+- [ ] Capture: `lessons.jsonl` row appended with valid JSON and all required fields
+- [ ] Capture: `learning-index.json` updated with matching entry
+- [ ] Capture: phase auto-link resolves correctly via artifact registry when `state.json` has `current_phase`
+- [ ] Capture: category inference produces a sensible default when `--category` absent
+- [ ] List: filters apply, output sorted newest-first, default limit 20
+- [ ] Search: results ranked by title (3) > tags (2) > summary (1) match
+- [ ] Show: full insight displayed with phase context and routed-artifact link if any
+- [ ] No file modifications outside `.workflow/learning/`
+- [ ] Confirmation banner displayed with INS-id and next-step hints
+- [ ] Next step: `/manage-learn list` to browse, or `/manage-learn search <query>` to find related insights
+</success_criteria>

package/.claude/commands/manage-status.md

@@ -1,51 +1,51 @@
----
-name: manage-status
-description: Display project dashboard with phase progress, active tasks, and next steps
-allowed-tools:
-  - Read
-  - Bash
-  - Glob
-  - Grep
----
-<purpose>
-Display a unified project dashboard showing artifact progress, task counts, active work, and intelligent next-step suggestions.
-Reads state.json artifact registry and roadmap to render a formatted overview with progress and status tables.
-Provides situational awareness before continuing work. Uses virtual phase view derived from artifact registry.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/status.md
-</required_reading>
-
-<context>
-$ARGUMENTS (no arguments required)
-
-**State files read:**
-- `.workflow/state.json` -- project-level state machine + artifact registry
-- `.workflow/roadmap.md` -- milestone and phase structure
-- `.workflow/scratch/*/plan.json` -- plan metadata (via artifact registry paths)
-- `.workflow/scratch/*/.task/TASK-*.json` -- individual task statuses
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/status.md' completely.
-
-Next-step decision table defined in workflow status.md Step 5.
-</execution>
-
-<error_codes>
-| Code | Severity | Description | Stage |
-|------|----------|-------------|-------|
-| E001 | fatal | `.workflow/` not initialized -- run `/maestro-init` first | parse_input |
-| E002 | fatal | `state.json` missing or corrupt -- project state unrecoverable | parse_input |
-</error_codes>
-
-<success_criteria>
-- [ ] Project state loaded from `state.json`
-- [ ] Roadmap parsed with milestone/phase structure
-- [ ] Per-phase progress calculated (task counts, completion %)
-- [ ] Dashboard rendered with progress bars and status table
-- [ ] Active work section shows current phase details
-- [ ] Next steps suggested based on current state analysis
-- [ ] Wiki health score displayed (or graceful unavailable message)
-</success_criteria>
+---
+name: manage-status
+description: Show project dashboard with progress and next steps
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+---
+<purpose>
+Display a unified project dashboard showing artifact progress, task counts, active work, and intelligent next-step suggestions.
+Reads state.json artifact registry and roadmap to render a formatted overview with progress and status tables.
+Provides situational awareness before continuing work. Uses virtual phase view derived from artifact registry.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/status.md
+</required_reading>
+
+<context>
+$ARGUMENTS (no arguments required)
+
+**State files read:**
+- `.workflow/state.json` -- project-level state machine + artifact registry
+- `.workflow/roadmap.md` -- milestone and phase structure
+- `.workflow/scratch/*/plan.json` -- plan metadata (via artifact registry paths)
+- `.workflow/scratch/*/.task/TASK-*.json` -- individual task statuses
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/status.md' completely.
+
+Next-step decision table defined in workflow status.md Step 5.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | fatal | `.workflow/` not initialized -- run `/maestro-init` first | parse_input |
+| E002 | fatal | `state.json` missing or corrupt -- project state unrecoverable | parse_input |
+</error_codes>
+
+<success_criteria>
+- [ ] Project state loaded from `state.json`
+- [ ] Roadmap parsed with milestone/phase structure
+- [ ] Per-phase progress calculated (task counts, completion %)
+- [ ] Dashboard rendered with progress bars and status table
+- [ ] Active work section shows current phase details
+- [ ] Next steps suggested based on current state analysis
+- [ ] Wiki health score displayed (or graceful unavailable message)
+</success_criteria>

package/.claude/commands/manage-wiki.md

@@ -1,62 +1,62 @@
----
-name: manage-wiki
-description: Wiki knowledge graph management — health dashboard, orphan cleanup, entry search, and graph statistics
-argument-hint: "[health|search|cleanup|stats] [options]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - AskUserQuestion
----
-<purpose>
-Unified wiki graph management command. Provides interactive access to wiki health monitoring, entry search, orphan cleanup, and graph statistics — the day-to-day operations that keep the knowledge graph healthy.
-
-Complements `/wiki-connect` (link discovery) and `/wiki-digest` (synthesis) with operational tooling.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/wiki-manage.md
-</required_reading>
-
-<context>
-$ARGUMENTS — subcommand and optional flags.
-
-**Subcommands:**
-| Subcommand | Description |
-|-----------|-------------|
-| `health` | Health dashboard — score, broken links, orphans, hubs (default) |
-| `search <query>` | Interactive BM25 search with follow-up actions |
-| `cleanup` | Find and resolve orphans, broken links, stale entries |
-| `stats` | Graph statistics — type distribution, tag frequency, growth trends |
-| No args | Same as `health` |
-
-**Flags:**
-- `--type <type>` — Filter by wiki type: spec, knowhow, note, lesson, issue
-- `--fix` — Auto-fix issues found during cleanup (remove broken links, suggest connections)
-- `--json` — Output in JSON format
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/wiki-manage.md' completely.
-</execution>
-
-<error_codes>
-| Code | Severity | Description | Stage |
-|------|----------|-------------|-------|
-| E001 | fatal | `.workflow/` not initialized — run `/maestro-init` first | validate |
-| E002 | fatal | No wiki entries found — create content first | load |
-| E003 | error | Invalid subcommand | parse_input |
-| W001 | warning | Health score below 50 — graph needs attention | health |
-| W002 | warning | Orphan cleanup had partial failures | cleanup |
-</error_codes>
-
-<success_criteria>
-- [ ] Subcommand parsed (health/search/cleanup/stats)
-- [ ] Wiki data loaded via `maestro wiki` CLI
-- [ ] Results displayed in formatted output
-- [ ] If cleanup --fix: issues resolved and delta reported
-- [ ] Next-step suggestions provided
-</success_criteria>
+---
+name: manage-wiki
+description: Manage wiki graph — health, cleanup, search, stats
+argument-hint: "[health|search|cleanup|stats] [options]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+<purpose>
+Unified wiki graph management command. Provides interactive access to wiki health monitoring, entry search, orphan cleanup, and graph statistics — the day-to-day operations that keep the knowledge graph healthy.
+
+Complements `/wiki-connect` (link discovery) and `/wiki-digest` (synthesis) with operational tooling.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/wiki-manage.md
+</required_reading>
+
+<context>
+$ARGUMENTS — subcommand and optional flags.
+
+**Subcommands:**
+| Subcommand | Description |
+|-----------|-------------|
+| `health` | Health dashboard — score, broken links, orphans, hubs (default) |
+| `search <query>` | Interactive BM25 search with follow-up actions |
+| `cleanup` | Find and resolve orphans, broken links, stale entries |
+| `stats` | Graph statistics — type distribution, tag frequency, growth trends |
+| No args | Same as `health` |
+
+**Flags:**
+- `--type <type>` — Filter by wiki type: spec, knowhow, note, lesson, issue
+- `--fix` — Auto-fix issues found during cleanup (remove broken links, suggest connections)
+- `--json` — Output in JSON format
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/wiki-manage.md' completely.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | fatal | `.workflow/` not initialized — run `/maestro-init` first | validate |
+| E002 | fatal | No wiki entries found — create content first | load |
+| E003 | error | Invalid subcommand | parse_input |
+| W001 | warning | Health score below 50 — graph needs attention | health |
+| W002 | warning | Orphan cleanup had partial failures | cleanup |
+</error_codes>
+
+<success_criteria>
+- [ ] Subcommand parsed (health/search/cleanup/stats)
+- [ ] Wiki data loaded via `maestro wiki` CLI
+- [ ] Results displayed in formatted output
+- [ ] If cleanup --fix: issues resolved and delta reported
+- [ ] Next-step suggestions provided
+</success_criteria>

package/.claude/commands/quality-auto-test.md

@@ -1,6 +1,6 @@
 ---
 name: quality-auto-test
-description: Unified automated testing via CSV layer pipeline — generates, executes, and iterates tests from PRD specs, coverage gaps, or code exploration
+description: Auto-generate and run tests from specs or coverage gaps
 argument-hint: "<phase> [-y] [-c N] [--max-iter <N>] [--layer <L0-L3>] [--strategy <name>] [--dry-run] [--re-run]"
 allowed-tools:
   - spawn_agents_on_csv
@@ -116,6 +116,10 @@ Append to state.json.artifacts[]:
 - [ ] Tests executed progressively (L0→L3) with fail-fast on critical
 - [ ] Iteration engine ran (inner: test_defect fix, outer: strategy adjust)
 - [ ] state.json, report.json, reflection-log.md written
+- [ ] Test confidence scored per iteration (Step 7.5) with 5-dimension factor model
+- [ ] Convergence check includes confidence >= 60% alongside pass_rate threshold
+- [ ] Pressure pass completed on highest-pass-rate layer before completion
+- [ ] report.json includes confidence section
 - [ ] index.json updated with auto_test section
 - [ ] If spec source: traceability matrix built, traceability.md written
 - [ ] If failures: issues auto-created in issues.jsonl

package/.claude/commands/quality-debug.md

@@ -1,115 +1,125 @@
----
-name: quality-debug
-description: Parallel hypothesis-driven debugging with UAT integration and structured root cause collection
-argument-hint: "[issue description] [--from-uat <phase>] [--parallel]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Debug issues using scientific method with subagent isolation and persistent debug state. Three entry modes (standalone, from-UAT, parallel) and structured root cause collection with UAT feedback loop. Full algorithm defined in workflow debug.md.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/debug.md
-</required_reading>
-
-<context>
-User's issue: $ARGUMENTS
-
-**Flags:**
-- `--from-uat <phase>` -- Read gaps from phase's uat.md as pre-filled symptoms
-- `--parallel` -- Spawn parallel debug agents (one per gap cluster)
-
-**All context via state.json.artifacts[]:**
-
-```
-related = artifacts.filter(a =>
-  a.phase === target_phase && a.milestone === current_milestone
-).sort_by(completed_at asc)
-```
-
-Each artifact's type determines its outputs at `.workflow/{a.path}/`:
-- **execute** → .summaries/, .task/ (source of code changes)
-- **review** → review.json (findings guide hypothesis formation)
-- **debug** → understanding.md, evidence.ndjson (prior investigations, avoid re-investigation)
-- **test** → uat.md (--from-uat gap source), .tests/
-
-Extract conclusions from related artifacts that may affect this debug session — review findings guide investigation direction, prior debug avoids redundant work.
-
-**Output**: `DEBUG_DIR = .workflow/scratch/{YYYYMMDD}-debug-P{N}-{slug}/` (P{N} = phase number when phase-scoped; omit for standalone). Output directory rules defined in workflow debug.md Step 4.
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/debug.md' completely.
-
-**Register artifact on completion (phase-scoped only):**
-```
-Append to state.json.artifacts[]:
-{
-  id: nextArtifactId(artifacts, "debug"),  // DBG-001
-  type: "debug",
-  milestone: current_milestone,
-  phase: target_phase,
-  scope: "phase",
-  path: "scratch/{YYYYMMDD}-debug-P{N}-{slug}",
-  status: all_diagnosed ? "completed" : "failed",
-  depends_on: triggering_review_id || exec_art.id,
-  harvested: false,
-  created_at: start_time,
-  completed_at: now()
-}
-```
-
-### Post-debug Knowledge Inquiry
-
-After root cause is confirmed, evaluate inquiry triggers:
-
-1. **Recurring pattern**: If root cause matches a recurring pattern (similar to prior debug sessions):
-   → Ask: "This root cause pattern has appeared before. Should it be documented in `debug-notes.md` to prevent recurrence? (`/spec-add debug`)"
-
-2. **Non-obvious fix**: If fix involved a non-obvious approach or workaround:
-   → Ask: "This fix used a non-obvious strategy. Should it be recorded as a learning? (`/spec-add learning`)"
-
-3. **Architectural gap**: If root cause traces to architectural boundary violation or missing constraint:
-   → Ask: "Root cause points to an architectural gap. Should `architecture-constraints.md` be updated? (`/spec-add arch`)"
-
-If user confirms, invoke `Skill({ skill: "spec-add", args: "<category> <content>" })`.
-
-**Next-step routing on completion:**
-- Root cause found, fix needed → `/maestro-plan {phase} --gaps`
-- Root cause found (from UAT), auto-fix → `/quality-test {phase} --auto-fix`
-- Inconclusive, need more info → `/quality-debug {issue} -c` (resume session)
-- Standalone fix already applied → `/maestro-verify {phase}`
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Issue description required (no arguments, no active sessions) | Check arguments format, re-run with correct input |
-| E002 | error | UAT file not found for --from-uat phase | Verify UAT file exists for specified phase |
-| W001 | warning | Existing debug session found, offer resume | Review existing sessions, choose resume or new |
-| W002 | warning | Checkpoint reached, user input needed | Provide requested input to continue |
-| W003 | warning | Some gaps inconclusive, partial diagnosis | Review partial results, retry inconclusive gaps |
-</error_codes>
-
-<success_criteria>
-- [ ] Input parsed: standalone, --from-uat, or --parallel mode determined
-- [ ] Active sessions checked and resume offered if applicable
-- [ ] Symptoms gathered (interactive) or loaded from UAT (pre-filled)
-- [ ] Debug output directory created (phase .debug/ or scratch/)
-- [ ] Debug agent(s) spawned with full symptom context
-- [ ] If --parallel: one agent per gap cluster, all concurrent
-- [ ] evidence.ndjson written with structured NDJSON entries
-- [ ] understanding.md tracks evolving understanding per cluster
-- [ ] Root causes collected with fix_direction and affected_files
-- [ ] If --from-uat: uat.md gaps updated with diagnosis artifacts
-- [ ] Results unified into diagnosis summary
-- [ ] Next step routed (plan --gaps + execute if fix needed, verify if fix applied, resume if inconclusive)
-</success_criteria>
+---
+name: quality-debug
+description: Debug with parallel hypotheses and root cause analysis
+argument-hint: "[issue description] [--from-uat <phase>] [--parallel]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Debug issues using scientific method with subagent isolation and persistent debug state. Three entry modes (standalone, from-UAT, parallel) and structured root cause collection with UAT feedback loop. Full algorithm defined in workflow debug.md.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/debug.md
+</required_reading>
+
+<context>
+User's issue: $ARGUMENTS
+
+**Flags:**
+- `--from-uat <phase>` -- Read gaps from phase's uat.md as pre-filled symptoms
+- `--parallel` -- Spawn parallel debug agents (one per gap cluster)
+
+**All context via state.json.artifacts[]:**
+
+```
+related = artifacts.filter(a =>
+  a.phase === target_phase && a.milestone === current_milestone
+).sort_by(completed_at asc)
+```
+
+Each artifact's type determines its outputs at `.workflow/{a.path}/`:
+- **execute** → .summaries/, .task/ (source of code changes)
+- **review** → review.json (findings guide hypothesis formation)
+- **debug** → understanding.md, evidence.ndjson (prior investigations, avoid re-investigation)
+- **test** → uat.md (--from-uat gap source), .tests/
+
+Extract conclusions from related artifacts that may affect this debug session — review findings guide investigation direction, prior debug avoids redundant work.
+
+### Pre-load context (before hypothesis formation)
+
+1. **Codebase docs**: If `.workflow/codebase/ARCHITECTURE.md` exists, load module boundaries to scope impact analysis and inform hypothesis formation.
+2. **Wiki prior knowledge**: Run `maestro wiki search "<symptom keywords>" --json 2>/dev/null`. If results found, check for prior investigations on similar issues to avoid re-investigation.
+3. Both are optional — proceed without if unavailable.
+
+**Output**: `DEBUG_DIR = .workflow/scratch/{YYYYMMDD}-debug-P{N}-{slug}/` (P{N} = phase number when phase-scoped; omit for standalone). Output directory rules defined in workflow debug.md Step 4.
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/debug.md' completely.
+
+**Register artifact on completion (phase-scoped only):**
+```
+Append to state.json.artifacts[]:
+{
+  id: nextArtifactId(artifacts, "debug"),  // DBG-001
+  type: "debug",
+  milestone: current_milestone,
+  phase: target_phase,
+  scope: "phase",
+  path: "scratch/{YYYYMMDD}-debug-P{N}-{slug}",
+  status: all_diagnosed ? "completed" : "failed",
+  depends_on: triggering_review_id || exec_art.id,
+  harvested: false,
+  created_at: start_time,
+  completed_at: now()
+}
+```
+
+### Post-debug Knowledge Inquiry
+
+After root cause is confirmed, evaluate inquiry triggers:
+
+1. **Recurring pattern**: If root cause matches a recurring pattern (similar to prior debug sessions):
+   → Ask: "This root cause pattern has appeared before. Should it be documented in `debug-notes.md` to prevent recurrence? (`/spec-add debug`)"
+
+2. **Non-obvious fix**: If fix involved a non-obvious approach or workaround:
+   → Ask: "This fix used a non-obvious strategy. Should it be recorded as a learning? (`/spec-add learning`)"
+
+3. **Architectural gap**: If root cause traces to architectural boundary violation or missing constraint:
+   → Ask: "Root cause points to an architectural gap. Should `architecture-constraints.md` be updated? (`/spec-add arch`)"
+
+If user confirms, invoke `Skill({ skill: "spec-add", args: "<category> <content>" })`.
+
+**Next-step routing on completion:**
+- Root cause found, fix needed → `/maestro-plan {phase} --gaps`
+- Root cause found (from UAT), auto-fix → `/quality-test {phase} --auto-fix`
+- Inconclusive, need more info → `/quality-debug {issue} -c` (resume session)
+- Standalone fix already applied → `/maestro-verify {phase}`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Issue description required (no arguments, no active sessions) | Check arguments format, re-run with correct input |
+| E002 | error | UAT file not found for --from-uat phase | Verify UAT file exists for specified phase |
+| W001 | warning | Existing debug session found, offer resume | Review existing sessions, choose resume or new |
+| W002 | warning | Checkpoint reached, user input needed | Provide requested input to continue |
+| W003 | warning | Some gaps inconclusive, partial diagnosis | Review partial results, retry inconclusive gaps |
+</error_codes>
+
+<success_criteria>
+- [ ] Input parsed: standalone, --from-uat, or --parallel mode determined
+- [ ] Active sessions checked and resume offered if applicable
+- [ ] Symptoms gathered (interactive) or loaded from UAT (pre-filled)
+- [ ] Debug output directory created (phase .debug/ or scratch/)
+- [ ] Debug agent(s) spawned with full symptom context
+- [ ] If --parallel: one agent per gap cluster, all concurrent
+- [ ] evidence.ndjson written with structured NDJSON entries
+- [ ] understanding.md tracks evolving understanding per cluster
+- [ ] Root causes collected with fix_direction and affected_files
+- [ ] Multi-factor confidence scored per gap (Step 7.0) replacing simple high/medium/low
+- [ ] Readiness gate checked before ROOT CAUSE declaration
+- [ ] Pressure pass completed on confirmed hypothesis
+- [ ] Confidence table appended to understanding.md
+- [ ] If --from-uat: uat.md gaps updated with diagnosis artifacts
+- [ ] Results unified into diagnosis summary with confidence section
+- [ ] Next step routed (plan --gaps + execute if fix needed, verify if fix applied, resume if inconclusive)
+</success_criteria>