maestro-flow 0.5.1 → 0.5.3

package/.codex/skills/learn-decompose/SKILL.md

@@ -1,144 +1,144 @@
----
-name: learn-decompose
-description: Extract design patterns from code into specs and wiki
-argument-hint: "[-y|--yes] [-c|--concurrency 4] [--continue] \"<path|module> [--patterns <list>] [--save-spec] [--save-wiki]\""
-allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
----
-
-<purpose>
-Systematic pattern extraction from code via CSV wave pipeline. 4 parallel dimension agents
-scan a module, then a cross-reference agent deduplicates against existing patterns and
-produces a catalog. Discovered patterns persist to `.workflow/specs/learnings.md` and optionally to
-specs (via `spec-add`) and wiki.
-
-```
-Resolve Target → Load Existing Patterns → Wave 1 (4 parallel dimension scans) → Wave 2 (cross-ref + catalog) → Persist
-```
-</purpose>
-
-<context>
-$ARGUMENTS — target path/module and optional flags.
-
-**Target resolution:**
-- File path → analyze that file
-- Directory path → all source files in it
-- Module name → Glob `src/**/{module}*`
-
-**Flags:**
-- `-y, --yes`: Skip confirmations
-- `-c, --concurrency N`: Max concurrent agents (default: 4)
-- `--continue`: Resume existing session
-- `--patterns <list>`: Comma-separated pattern names to focus on
-- `--save-spec`: Invoke `spec-add` for each new pattern
-- `--save-wiki`: Create wiki note entries per dimension group
-
-**Output**: `.workflow/.csv-wave/{session-id}/` + `.workflow/knowhow/KNW-decompose-{slug}-{date}.md`
-</context>
-
-<invariants>
-1. **4 dimensions always**: structural, behavioral, data, error — each a wave 1 task
-2. **Evidence required**: Every finding must have file:line anchors
-3. **Dedup before persist**: Cross-reference against existing specs + lessons
-4. **Stable IDs**: INS-id from `hash("decompose" + target + pattern_name)`
-5. **No files modified outside** `.workflow/knowhow/` (and optionally specs/wiki)
-</invariants>
-
-<execution>
-
-### Phase 1: Session Init + Target Resolution
-
-Parse flags from `$ARGUMENTS`: `-y`/`--yes`, `--patterns <list>`, `--save-spec`, `--save-wiki`, `--continue`, `-c N`.
-Extract remaining text as target path/module.
-
-Resolve target to file list. Load coding specs: `maestro spec load --category coding` for documented patterns and conventions. Load existing patterns from `coding-conventions.md` + `.workflow/specs/learnings.md` for dedup set. Browse wiki: `maestro search --category coding`, load relevant entries.
-
-### Phase 2: Wave 1 — Parallel Dimension Scans
-
-Generate `tasks.csv` with 4 dimension rows (wave 1) + 1 cross-ref row (wave 2). Initialize every row with `status="pending"`. Filter `wave==N AND status=="pending"` when writing each wave CSV.
-
-| id | dimension | focus |
-|----|-----------|-------|
-| 1 | structural | Class hierarchy, composition, DI, factories, exports |
-| 2 | behavioral | Events, middleware, observer, command, state machines |
-| 3 | data | Repository, DTO, caching, serialization, validation |
-| 4 | error | Boundaries, retry/backoff, fallbacks, guards, logging |
-| 5 | cross-ref | Dedup + catalog from wave 1 findings |
-
-**output_schema** (both waves):
-
-```json
-{
-  "type": "object",
-  "properties": {
-    "id":            { "type": "string" },
-    "result_status": { "type": "string", "enum": ["completed", "failed"] },
-    "dimension":     { "type": "string", "enum": ["structural", "behavioral", "data", "error", "cross-ref"] },
-    "patterns":      { "type": "string", "description": "JSON array string: [{name, dimension, confidence, anchors, description, rationale, tradeoffs}]" },
-    "findings":      { "type": "string", "maxLength": 500 },
-    "error":         { "type": "string" }
-  },
-  "required": ["id", "result_status", "findings"]
-}
-```
-
-Merge: `result_status` → master `status`; copy `dimension`, `patterns`, `findings`, `error`.
-
-**Shared termination contract** (embed in every instruction):
-```
-You MUST call report_agent_job_result EXACTLY ONCE before exiting.
-- Success → result_status=completed (patterns may be empty array if nothing found)
-- Failure → result_status=failed with error message
-- Timeout → near max_runtime_seconds → result_status=completed with partial patterns
-- NEVER continue indefinitely. NEVER exit silently. NEVER omit the call.
-- Every finding MUST include file:line anchors. No speculation.
-- Read-only analysis. Do NOT modify source.
-Do NOT write to tasks.csv, wave-*.csv, results.csv. Do NOT call spawn_agents_on_csv (no recursion).
-```
-
-Each dimension agent populates `patterns` as a JSON array string of:
-```json
-[{
-  "name": "pattern name",
-  "dimension": "structural|behavioral|data|error",
-  "confidence": "high|medium|low",
-  "anchors": ["file:line"],
-  "description": "what it does",
-  "rationale": "why this approach",
-  "tradeoffs": "what was given up"
-}]
-```
-
-### Phase 3: Wave 2 — Cross-Reference + Catalog
-
-Single agent receives all wave 1 findings via `prev_context`. Uses same `output_schema` + termination contract above. Tasks:
-- Match against dedup set → mark as `documented`, `known`, or `new`
-- Merge duplicates across dimensions (same pattern found by multiple agents)
-- Flag contradictions with documented conventions
-- Build pattern catalog grouped by dimension
-
-### Phase 4: Persist
-
-1. Write `KNW-decompose-{slug}-{date}.md` with full catalog
-2. Append each **new** pattern to `.workflow/specs/learnings.md` (source: "decompose", category: "pattern")
-3. If `--save-spec`: invoke `spec-add` per new pattern
-4. If `--save-wiki`: create wiki note per dimension group
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Target path not found | Check path or use module name |
-| E002 | error | No source files in target | Check target has .ts/.js files |
-| W001 | warning | Dimension agent failed — partial results | Proceed with available dimensions |
-| W002 | warning | coding-conventions.md not found | All patterns marked "new" |
-</error_codes>
-
-<success_criteria>
-- [ ] Target resolved to concrete file list
-- [ ] 4 dimension agents spawned in parallel via spawn_agents_on_csv
-- [ ] Each finding has: name, dimension, confidence, anchors, description
-- [ ] Cross-reference performed (documented / known / new)
-- [ ] Pattern catalog written to `KNW-decompose-{slug}-{date}.md`
-- [ ] New patterns appended to `.workflow/specs/learnings.md` with stable INS-ids
-- [ ] If --save-spec / --save-wiki: entries created
-</success_criteria>
+---
+name: learn-decompose
+description: Extract design patterns from code into specs and wiki
+argument-hint: "[-y|--yes] [-c|--concurrency 4] [--continue] \"<path|module> [--patterns <list>] [--save-spec] [--save-wiki]\""
+allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request_user_input
+---
+
+<purpose>
+Systematic pattern extraction from code via CSV wave pipeline. 4 parallel dimension agents
+scan a module, then a cross-reference agent deduplicates against existing patterns and
+produces a catalog. Discovered patterns persist to `.workflow/specs/learnings.md` and optionally to
+specs (via `spec-add`) and wiki.
+
+```
+Resolve Target → Load Existing Patterns → Wave 1 (4 parallel dimension scans) → Wave 2 (cross-ref + catalog) → Persist
+```
+</purpose>
+
+<context>
+$ARGUMENTS — target path/module and optional flags.
+
+**Target resolution:**
+- File path → analyze that file
+- Directory path → all source files in it
+- Module name → Glob `src/**/{module}*`
+
+**Flags:**
+- `-y, --yes`: Skip confirmations
+- `-c, --concurrency N`: Max concurrent agents (default: 4)
+- `--continue`: Resume existing session
+- `--patterns <list>`: Comma-separated pattern names to focus on
+- `--save-spec`: Invoke `spec-add` for each new pattern
+- `--save-wiki`: Create wiki note entries per dimension group
+
+**Output**: `.workflow/.csv-wave/{session-id}/` + `.workflow/knowhow/KNW-decompose-{slug}-{date}.md`
+</context>
+
+<invariants>
+1. **4 dimensions always**: structural, behavioral, data, error — each a wave 1 task
+2. **Evidence required**: Every finding must have file:line anchors
+3. **Dedup before persist**: Cross-reference against existing specs + lessons
+4. **Stable IDs**: INS-id from `hash("decompose" + target + pattern_name)`
+5. **No files modified outside** `.workflow/knowhow/` (and optionally specs/wiki)
+</invariants>
+
+<execution>
+
+### Phase 1: Session Init + Target Resolution
+
+Parse flags from `$ARGUMENTS`: `-y`/`--yes`, `--patterns <list>`, `--save-spec`, `--save-wiki`, `--continue`, `-c N`.
+Extract remaining text as target path/module.
+
+Resolve target to file list. Load coding specs: `maestro spec load --category coding` for documented patterns and conventions. Load existing patterns from `coding-conventions.md` + `.workflow/specs/learnings.md` for dedup set. Browse wiki: `maestro search --category coding`, load relevant entries.
+
+### Phase 2: Wave 1 — Parallel Dimension Scans
+
+Generate `tasks.csv` with 4 dimension rows (wave 1) + 1 cross-ref row (wave 2). Initialize every row with `status="pending"`. Filter `wave==N AND status=="pending"` when writing each wave CSV.
+
+| id | dimension | focus |
+|----|-----------|-------|
+| 1 | structural | Class hierarchy, composition, DI, factories, exports |
+| 2 | behavioral | Events, middleware, observer, command, state machines |
+| 3 | data | Repository, DTO, caching, serialization, validation |
+| 4 | error | Boundaries, retry/backoff, fallbacks, guards, logging |
+| 5 | cross-ref | Dedup + catalog from wave 1 findings |
+
+**output_schema** (both waves):
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "id":            { "type": "string" },
+    "result_status": { "type": "string", "enum": ["completed", "failed"] },
+    "dimension":     { "type": "string", "enum": ["structural", "behavioral", "data", "error", "cross-ref"] },
+    "patterns":      { "type": "string", "description": "JSON array string: [{name, dimension, confidence, anchors, description, rationale, tradeoffs}]" },
+    "findings":      { "type": "string", "maxLength": 500 },
+    "error":         { "type": "string" }
+  },
+  "required": ["id", "result_status", "findings"]
+}
+```
+
+Merge: `result_status` → master `status`; copy `dimension`, `patterns`, `findings`, `error`.
+
+**Shared termination contract** (embed in every instruction):
+```
+You MUST call report_agent_job_result EXACTLY ONCE before exiting.
+- Success → result_status=completed (patterns may be empty array if nothing found)
+- Failure → result_status=failed with error message
+- Timeout → near max_runtime_seconds → result_status=completed with partial patterns
+- NEVER continue indefinitely. NEVER exit silently. NEVER omit the call.
+- Every finding MUST include file:line anchors. No speculation.
+- Read-only analysis. Do NOT modify source.
+Do NOT write to tasks.csv, wave-*.csv, results.csv. Do NOT call spawn_agents_on_csv (no recursion).
+```
+
+Each dimension agent populates `patterns` as a JSON array string of:
+```json
+[{
+  "name": "pattern name",
+  "dimension": "structural|behavioral|data|error",
+  "confidence": "high|medium|low",
+  "anchors": ["file:line"],
+  "description": "what it does",
+  "rationale": "why this approach",
+  "tradeoffs": "what was given up"
+}]
+```
+
+### Phase 3: Wave 2 — Cross-Reference + Catalog
+
+Single agent receives all wave 1 findings via `prev_context`. Uses same `output_schema` + termination contract above. Tasks:
+- Match against dedup set → mark as `documented`, `known`, or `new`
+- Merge duplicates across dimensions (same pattern found by multiple agents)
+- Flag contradictions with documented conventions
+- Build pattern catalog grouped by dimension
+
+### Phase 4: Persist
+
+1. Write `KNW-decompose-{slug}-{date}.md` with full catalog
+2. Append each **new** pattern to `.workflow/specs/learnings.md` (source: "decompose", category: "pattern")
+3. If `--save-spec`: invoke `spec-add` per new pattern
+4. If `--save-wiki`: create wiki note per dimension group
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Target path not found | Check path or use module name |
+| E002 | error | No source files in target | Check target has .ts/.js files |
+| W001 | warning | Dimension agent failed — partial results | Proceed with available dimensions |
+| W002 | warning | coding-conventions.md not found | All patterns marked "new" |
+</error_codes>
+
+<success_criteria>
+- [ ] Target resolved to concrete file list
+- [ ] 4 dimension agents spawned in parallel via spawn_agents_on_csv
+- [ ] Each finding has: name, dimension, confidence, anchors, description
+- [ ] Cross-reference performed (documented / known / new)
+- [ ] Pattern catalog written to `KNW-decompose-{slug}-{date}.md`
+- [ ] New patterns appended to `.workflow/specs/learnings.md` with stable INS-ids
+- [ ] If --save-spec / --save-wiki: entries created
+</success_criteria>

package/.codex/skills/learn-follow/SKILL.md

@@ -1,83 +1,83 @@
----
-name: learn-follow
-description: Guided reading of code or wiki to extract patterns
-argument-hint: "<path|wiki-id|topic> [--depth shallow|deep] [--save-wiki]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
----
-
-<purpose>
-Guided reading experience for code files, wiki entries, or topics. Walks through content
-section by section using 4 forcing questions to extract patterns, identify assumptions,
-and build a structured understanding map. Insights persist to `.workflow/specs/learnings.md`.
-
-Unlike `learn-decompose` which is parallel pattern extraction, this is sequential
-deep reading that builds understanding incrementally.
-</purpose>
-
-<context>
-$ARGUMENTS — target and optional flags.
-
-**Target resolution (auto-detected):**
-- File path → Read source file
-- Wiki ID (`type-slug`) → Fetch via `maestro wiki get`
-- Topic string → Search via `maestro search`, use top result
-
-**Flags:**
-- `--depth shallow` — Key patterns and structure only (default)
-- `--depth deep` — Every function, branch, assumption
-- `--save-wiki` — Create wiki note with reading notes
-
-**Output**: `.workflow/knowhow/KNW-follow-{slug}-{date}.md`
-</context>
-
-<execution>
-
-### Stage 1: Resolve Target + Load Context Web
-- File: verify exists, parse imports for dependency files
-- Wiki ID: fetch + load forward/backlinks
-- Topic: search wiki, take top result
-- Build 1-hop context neighborhood (imports/exports or wiki links)
-
-### Stage 2: Build Reading Order
-- Single file: split into logical sections (function/class boundaries)
-- Directory: entry point → core modules → utilities → tests
-- `--depth shallow`: top-level structure only
-- `--depth deep`: every function body, every branch
-
-### Stage 3: Guided Reading (4 Forcing Questions per Section)
-1. **"What pattern is being used here?"** — design patterns, idioms, conventions
-2. **"Why this approach instead of alternatives?"** — trade-offs made
-3. **"What assumption does this depend on?"** — external state, input shape, ordering
-4. **"What would break if this changed?"** — fragility, downstream effects
-
-### Stage 4: Extract Patterns + Produce Understanding Map
-From forcing question answers, extract: design patterns (with file:line anchors), naming conventions, error handling approach, data flow, assumptions.
-
-Cross-reference against `coding-conventions.md`: documented vs undocumented patterns.
-
-### Stage 5: Persist
-1. Write `KNW-follow-{slug}-{date}.md` with understanding map
-2. Append new patterns to `.workflow/specs/learnings.md` (source: "follow", stable INS-ids)
-3. If `--save-wiki`: create wiki note entry
-
-**Next steps:** `/learn-decompose <path>`, `/spec-add coding ...`, `/learn-second-opinion <file>`
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Target not resolvable | Check path/ID or rephrase topic |
-| W001 | warning | Wiki graph unavailable | Proceed with code-only context |
-| W002 | warning | coding-conventions.md not found | Patterns flagged "unknown status" |
-| W003 | warning | Large target (>1000 lines) | Auto-switch to shallow depth |
-</error_codes>
-
-<success_criteria>
-- [ ] Target resolved to concrete content
-- [ ] Context web loaded (imports/exports or wiki links)
-- [ ] All 4 forcing questions applied per section
-- [ ] Patterns extracted with file:line anchors
-- [ ] Understanding map produced with concepts, patterns, assumptions, questions
-- [ ] `KNW-follow-{slug}-{date}.md` written
-- [ ] `.workflow/specs/learnings.md` appended with stable INS-ids
-</success_criteria>
+---
+name: learn-follow
+description: Guided reading of code or wiki to extract patterns
+argument-hint: "<path|wiki-id|topic> [--depth shallow|deep] [--save-wiki]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
+---
+
+<purpose>
+Guided reading experience for code files, wiki entries, or topics. Walks through content
+section by section using 4 forcing questions to extract patterns, identify assumptions,
+and build a structured understanding map. Insights persist to `.workflow/specs/learnings.md`.
+
+Unlike `learn-decompose` which is parallel pattern extraction, this is sequential
+deep reading that builds understanding incrementally.
+</purpose>
+
+<context>
+$ARGUMENTS — target and optional flags.
+
+**Target resolution (auto-detected):**
+- File path → Read source file
+- Wiki ID (`type-slug`) → Fetch via `maestro wiki get`
+- Topic string → Search via `maestro search`, use top result
+
+**Flags:**
+- `--depth shallow` — Key patterns and structure only (default)
+- `--depth deep` — Every function, branch, assumption
+- `--save-wiki` — Create wiki note with reading notes
+
+**Output**: `.workflow/knowhow/KNW-follow-{slug}-{date}.md`
+</context>
+
+<execution>
+
+### Stage 1: Resolve Target + Load Context Web
+- File: verify exists, parse imports for dependency files
+- Wiki ID: fetch + load forward/backlinks
+- Topic: search wiki, take top result
+- Build 1-hop context neighborhood (imports/exports or wiki links)
+
+### Stage 2: Build Reading Order
+- Single file: split into logical sections (function/class boundaries)
+- Directory: entry point → core modules → utilities → tests
+- `--depth shallow`: top-level structure only
+- `--depth deep`: every function body, every branch
+
+### Stage 3: Guided Reading (4 Forcing Questions per Section)
+1. **"What pattern is being used here?"** — design patterns, idioms, conventions
+2. **"Why this approach instead of alternatives?"** — trade-offs made
+3. **"What assumption does this depend on?"** — external state, input shape, ordering
+4. **"What would break if this changed?"** — fragility, downstream effects
+
+### Stage 4: Extract Patterns + Produce Understanding Map
+From forcing question answers, extract: design patterns (with file:line anchors), naming conventions, error handling approach, data flow, assumptions.
+
+Cross-reference against `coding-conventions.md`: documented vs undocumented patterns.
+
+### Stage 5: Persist
+1. Write `KNW-follow-{slug}-{date}.md` with understanding map
+2. Append new patterns to `.workflow/specs/learnings.md` (source: "follow", stable INS-ids)
+3. If `--save-wiki`: create wiki note entry
+
+**Next steps:** `$learn-decompose <path>`, `$spec-add coding ...`, `$learn-second-opinion <file>`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Target not resolvable | Check path/ID or rephrase topic |
+| W001 | warning | Wiki graph unavailable | Proceed with code-only context |
+| W002 | warning | coding-conventions.md not found | Patterns flagged "unknown status" |
+| W003 | warning | Large target (>1000 lines) | Auto-switch to shallow depth |
+</error_codes>
+
+<success_criteria>
+- [ ] Target resolved to concrete content
+- [ ] Context web loaded (imports/exports or wiki links)
+- [ ] All 4 forcing questions applied per section
+- [ ] Patterns extracted with file:line anchors
+- [ ] Understanding map produced with concepts, patterns, assumptions, questions
+- [ ] `KNW-follow-{slug}-{date}.md` written
+- [ ] `.workflow/specs/learnings.md` appended with stable INS-ids
+</success_criteria>

package/.codex/skills/learn-investigate/SKILL.md

@@ -1,84 +1,84 @@
----
-name: learn-investigate
-description: Investigate questions with hypothesis testing and evidence logging
-argument-hint: "<question> [--scope <path>] [--max-hypotheses N]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
----
-
-<purpose>
-Systematic investigation for understanding questions (not bug-fixing). 4-phase approach
-with scope lock and 3-strike escalation. Produces structured evidence trails and
-understanding documents that persist to the learning system.
-
-Unlike `quality-debug` (fixing bugs during execution), this answers "how does X work?",
-"why does Y happen?", "what would happen if Z?" questions.
-</purpose>
-
-<context>
-$ARGUMENTS — question text and optional flags.
-
-**Flags:**
-- `--scope <path>` — Restrict to files under this directory (default: entire project)
-- `--max-hypotheses N` — Max hypotheses before escalating (default: 3)
-
-**Output**: `.workflow/knowhow/KNW-investigate-{slug}/` (evidence.ndjson, understanding.md, report.md)
-</context>
-
-<execution>
-
-### Stage 1: Frame the Question
-- Parse question, generate slug, create investigation directory
-- Load debug specs: `maestro spec load --category debug` for known issues and patterns
-- Search prior knowledge: `maestro search --category debug`, wiki search, grep .workflow/specs/learnings.md
-- Write initial `understanding.md`
-
-### Stage 2: Evidence Collection
-1. **Code search**: Grep keywords across scoped files
-2. **File inspection**: Read most relevant files
-3. **Import tracing**: Follow dependency chain
-4. **Git history**: `git log --oneline -10 -- <relevant-files>`
-
-Each evidence item → `evidence.ndjson`:
-```json
-{"ts":"ISO","type":"code|git|search|doc","source":"file:line","relevance":"high|medium|low","content":"...","note":"..."}
-```
-
-### Stage 3: Hypothesis Formation + Testing
-Generate ranked hypotheses from evidence. For each (in rank order):
-1. Design test: what evidence would confirm/disprove?
-2. Execute test: code trace, targeted search, experiment
-3. Record result in `evidence.ndjson` (type: "test")
-4. Update `understanding.md`: confirmed / disproved / inconclusive
-
-### Stage 4: 3-Strike Escalation
-If all hypotheses fail: broaden scope, search wiki with alt keywords, or mark INCONCLUSIVE.
-
-### Stage 5: Synthesize + Persist
-1. Write `report.md` with answer, evidence trail, hypothesis results
-2. Append to `.workflow/specs/learnings.md`:
-   - Confirmed → category: "technique" / "pattern"
-   - Disproved → category: "gotcha"
-3. Display summary with next-step routing
-
-**Next steps:** `/spec-add debug <finding>`, `/learn-follow <path>`, `/learn-decompose <module>`
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | No question provided | Provide question as first argument |
-| E002 | error | Scope path does not exist | Check --scope path |
-| W001 | warning | No prior knowledge found | Proceed with fresh investigation |
-| W002 | warning | Very few evidence matches (<3) | Broaden search terms |
-| W003 | warning | All hypotheses inconclusive | Marked INCONCLUSIVE |
-</error_codes>
-
-<success_criteria>
-- [ ] Question parsed and investigation directory created
-- [ ] Evidence collected and logged to evidence.ndjson
-- [ ] At least 1 hypothesis formed and tested
-- [ ] understanding.md tracks evolving understanding
-- [ ] report.md written with answer and evidence trail
-- [ ] Findings appended to .workflow/specs/learnings.md with stable INS-ids
-- [ ] 3-strike escalation triggered if all hypotheses fail
-</success_criteria>
+---
+name: learn-investigate
+description: Investigate questions with hypothesis testing and evidence logging
+argument-hint: "<question> [--scope <path>] [--max-hypotheses N]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
+---
+
+<purpose>
+Systematic investigation for understanding questions (not bug-fixing). 4-phase approach
+with scope lock and 3-strike escalation. Produces structured evidence trails and
+understanding documents that persist to the learning system.
+
+Unlike `quality-debug` (fixing bugs during execution), this answers "how does X work?",
+"why does Y happen?", "what would happen if Z?" questions.
+</purpose>
+
+<context>
+$ARGUMENTS — question text and optional flags.
+
+**Flags:**
+- `--scope <path>` — Restrict to files under this directory (default: entire project)
+- `--max-hypotheses N` — Max hypotheses before escalating (default: 3)
+
+**Output**: `.workflow/knowhow/KNW-investigate-{slug}/` (evidence.ndjson, understanding.md, report.md)
+</context>
+
+<execution>
+
+### Stage 1: Frame the Question
+- Parse question, generate slug, create investigation directory
+- Load debug specs: `maestro spec load --category debug` for known issues and patterns
+- Search prior knowledge: `maestro search --category debug`, wiki search, grep .workflow/specs/learnings.md
+- Write initial `understanding.md`
+
+### Stage 2: Evidence Collection
+1. **Code search**: Grep keywords across scoped files
+2. **File inspection**: Read most relevant files
+3. **Import tracing**: Follow dependency chain
+4. **Git history**: `git log --oneline -10 -- <relevant-files>`
+
+Each evidence item → `evidence.ndjson`:
+```json
+{"ts":"ISO","type":"code|git|search|doc","source":"file:line","relevance":"high|medium|low","content":"...","note":"..."}
+```
+
+### Stage 3: Hypothesis Formation + Testing
+Generate ranked hypotheses from evidence. For each (in rank order):
+1. Design test: what evidence would confirm/disprove?
+2. Execute test: code trace, targeted search, experiment
+3. Record result in `evidence.ndjson` (type: "test")
+4. Update `understanding.md`: confirmed / disproved / inconclusive
+
+### Stage 4: 3-Strike Escalation
+If all hypotheses fail: broaden scope, search wiki with alt keywords, or mark INCONCLUSIVE.
+
+### Stage 5: Synthesize + Persist
+1. Write `report.md` with answer, evidence trail, hypothesis results
+2. Append to `.workflow/specs/learnings.md`:
+   - Confirmed → category: "technique" / "pattern"
+   - Disproved → category: "gotcha"
+3. Display summary with next-step routing
+
+**Next steps:** `$spec-add debug <finding>`, `$learn-follow <path>`, `$learn-decompose <module>`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No question provided | Provide question as first argument |
+| E002 | error | Scope path does not exist | Check --scope path |
+| W001 | warning | No prior knowledge found | Proceed with fresh investigation |
+| W002 | warning | Very few evidence matches (<3) | Broaden search terms |
+| W003 | warning | All hypotheses inconclusive | Marked INCONCLUSIVE |
+</error_codes>
+
+<success_criteria>
+- [ ] Question parsed and investigation directory created
+- [ ] Evidence collected and logged to evidence.ndjson
+- [ ] At least 1 hypothesis formed and tested
+- [ ] understanding.md tracks evolving understanding
+- [ ] report.md written with answer and evidence trail
+- [ ] Findings appended to .workflow/specs/learnings.md with stable INS-ids
+- [ ] 3-strike escalation triggered if all hypotheses fail
+</success_criteria>