maestro-learn

<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 request_user_input 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`, request_user_input showing files to write and learning-entries to append — user must confirm.
- REQUIRED: KNW-follow-{slug}-{date}.md written with understanding map.
- REQUIRED: learnings.md appended (not overwritten) with new learning-entry blocks.
- BLOCKED if: user declines confirmation — offer to adjust findings before retry.

</execution>

<state_machine>

<states>
S_RESOLVE      — 解析 target (file/wiki/topic)              PERSIST: —
S_CONTEXT      — 构建 1-hop 上下文邻域                       PERSIST: —
S_OR