/maestro-learn

name: maestro-learn
disable-model-invocation: true
description: User-invoked learning toolkit — guided reading, investigation, pattern extraction, or second opinions. Manual `/maestro-learn` only; NEVER auto-invoke for code exploration or analysis — route those intents to the analyze step via /maestro-next
argument-hint: "follow|investigate|decompose|consult [args...]"
allowed-tools:
  - Read
  - Write
  - Bash
  - Glob
  - Grep
  - Agent
  - AskUserQuestion
session-mode: none

<purpose> Learning toolkit for building understanding of code, decisions, and plans. Four subcommands:

• `follow` — guided section-by-section reading with forcing questions → understanding map
• `investigate` — hypothesis-driven scientific investigation of a question → evidence-backed report
• `decompose` — parallel multi-dimension pattern extraction → reusable pattern catalog
• `consult` — alternative perspectives via review / challenge / interactive Q&A

All findings persist to `.workflow/knowhow/` and append `<learning-entry>` blocks to `.workflow/specs/learnings.md`. </purpose>

<routing> $ARGUMENTS — parse first token as `<subcommand>`, remainder as that subcommand's args.

| Subcommand | Section | |------------|---------| | `follow` | [Subcommand: follow](#subcommand-follow) | | `investigate` | [Subcommand: investigate](#subcommand-investigate) | | `decompose` | [Subcommand: decompose](#subcommand-decompose) | | `consult` | [Subcommand: consult](#subcommand-consult) |

**Routing errors:** | Code | Condition | Recovery | |------|-----------|----------| | E_NO_SUBCOMMAND | No subcommand provided in $ARGUMENTS | Display valid subcommands (follow, investigate, decompose, consult), prompt user to select | | E_INVALID_SUBCOMMAND | Unrecognized first token | Display valid subcommands with usage hints |

**Subcommand selection guide:**

• `follow` — understand code logic flow (why/how). Input: code path. Method: sequential reading + forcing questions. Output: understanding map.
• `decompose` — extract reusable pattern catalog (what patterns). Input: module/directory. Method: 4 parallel dimension agents. Output: pattern catalog.
• `follow --depth deep` covers every branch but focuses on comprehension; `decompose` focuses on pattern classification and reusability. They are complementary, not alternatives.
• `investigate` — answer a specific question via hypothesis-driven search. Input: question. Method: scientific method (evidence → hypothesis → test). Output: evidence-backed report.
• Key distinction: `follow` input is a **code path** (top-down reading); `investigate` input is a **question** (hypothesis-driven search).

</routing>

---

Subcommand: follow

**Usage**: `/maestro-learn follow <path|wiki-id|topic> [--depth shallow|deep] [--save-wiki] [-y]`

<purpose> Guided reading: walk through content section-by-section using forcing questions to extract patterns, identify assumptions, and build an understanding map. Findings persist to `.workflow/specs/learnings.md` as `<learning-entry>` blocks. </purpose>

<context> Arguments — target and optional flags.

**Target resolution** (auto-detected): | Input | Resolution | |-------|-----------| | File path (contains `/` or `\`) | Read source file | | Wiki ID (`<type>-<slug>`) | `maestro wiki get <id>` | | Topic string | `maestro search "<topic>"` → top result; fallback: Grep src/ |

**Flags**:

• `--depth shallow` (default): key patterns and structure only
• `--depth deep`: every function, every branch, every assumption
• `--save-wiki`: create wiki note entry with reading notes
• `-y`: Skip confirmation prompts for knowhow/spec writes

**Storage read**: target file + wiki forward/backlinks + `coding-conventions.md` + `.workflow/specs/learnings.md` (dedup) **Storage write**: `.workflow/knowhow/KNW-follow-{slug}-{date}.md` + append `.workflow/specs/learnings.md`

**Output boundary**: ALL file writes MUST target `.workflow/knowhow/KNW-follow-{slug}-{date}.md` and `.workflow/specs/learnings.md` only. NEVER modify source code or files outside these paths. </context>

<invariants> 1. **Read-only traversal** — NEVER modify source code or wiki entries under analysis; all writes go to `.workflow/` only 2. **Forcing questions mandatory** — each section MUST have all 4 forcing questions applied; NEVER skip questions even for trivial sections 3. **Anchor requirement** — every extracted pattern MUST include a `file:line` anchor; unanchored patterns SHALL NOT be persisted to learnings.md 4. **Convention cross-ref** — MUST check every finding against `coding-conventions.md` and mark status (documented/candidate); NEVER persist without status tag 5. **Append-only learnings** — `.workflow/specs/learnings.md` MUST be appended, NEVER overwritten or truncated 6. **Confirmation gate** — unless `-y` is set, MUST present findings and target files via [@ask] AskUserQuestion before any writes 7. **Depth contract** — `--depth shallow` MUST NOT descend into function bodies; `--depth deep` MUST cover every branch and sub-expression </invariants>

<execution>

Phase Gates (MANDATORY, BLOCKING)

**GATE 1: Resolve → Context Building** (S_RESOLVE → S_CONTEXT)

• REQUIRED: Target resolved to a readable source (file path, wiki entry, or search result).
• BLOCKED if: target unresolvable after user prompt (E001/E002).

**GATE 2: Reading → Extraction** (S_READ → S_EXTRACT)

• REQUIRED: All sections traversed with 4 forcing questions applied per section.
• REQUIRED: Depth contract honored — shallow stays at top-level, deep covers every branch.
• BLOCKED if: any section skipped without forcing questions.

**GATE 3: Extraction → Persistence** (S_EXTRACT → S_PERSIST)

• REQUIRED: All extracted patterns have file:line anchors.
• REQUIRED: Convention cross-ref completed against coding-conventions.md (or marked "unknown status" if W002).
• BLOCKED if: unanchored patterns remain in extraction results.

**GATE 4: Persistence → Completion** (S_PERSIST → END)

• REQUIRED: Unless `-y`, [@ask] AskUserQues