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_ORDER — 确定阅读顺序 PERSIST: — S_READ — 逐节应用 forcing questions PERSIST: — S_EXTRACT — 提取 patterns、cross-ref conventions PERSIST: — S_PERSIST — 写 understanding map + learning-entry 块 PERSIST: knowhow files </states> <transitions> S_RESOLVE: → S_CONTEXT WHEN: target resolved → S_RESOLVE WHEN: unresolvable DO: request_user_input with suggestions S_CONTEXT: → S_ORDER DO: A_BUILD_CONTEXT_WEB S_ORDER: → S_READ DO: A_BUILD_READING_ORDER S_READ: → S_EXTRACT DO: A_GUIDED_READ (apply 4 forcing questions per section) S_EXTRACT: → S_PERSIST DO: A_EXTRACT_PATTERNS S_PERSIST: → END GATE: unless -y, request_user_input showing files to write and learning-entries to append — proceed only on confirm DO: write KNW-follow + append .workflow/specs/learnings.md [+ wiki note if --save-wiki] </transitions> <actions> ### A_BUILD_CONTEXT_WEB | Target type | Context | |-------------|---------| | Wiki entry | `maestro wiki forward <id>` + `maestro wiki backlinks <id>` → read top 3 related | | Code file | Parse imports → dependency files; grep exports → reverse deps; read top 3 dependents (50 lines) | | Directory | List files, identify entry points → build reading order: entry → core → utils → tests | ### A_BUILD_READING_ORDER - Single file: split by function/class/export boundaries - Wiki entry: split by markdown headings - Directory: order by dependency (entry points first, leaf last) - `--depth shallow`: top-level structure only; `--depth deep`: every body and branch ### A_GUIDED_READ For each section, apply 4 forcing questions: | # | Question | Extracts | |---|----------|----------| | 1 | "What pattern is being used here?" | Design patterns, idioms, conventions | | 2 | "Why this approach instead of alternatives?" | Trade-offs, rejected options | | 3 | "What assumption does this depend on?" | Implicit contracts, input shape, ordering | | 4 | "What would break if this changed?" | Fragility, downstream effects | ### A_EXTRACT_PATTERNS Extract: design patterns (with file:line anchors), naming conventions, error handling approach, data flow, assumptions. Cross-ref against `coding-conventions.md`: documented → "confirmed convention", undocumented → "candidate for maestro-spec add". Write understanding map: Key Concepts, Patterns (table: name/location/convention status), Assumptions, Open Questions, Connections. </actions> </state_machine> <error_codes> | Code | Condition | Recovery | |------|-----------|----------| | E001 | No target path/wiki-id/topic provided | Prompt user for target | | E002 | Target path not found and wiki/grep search returned no results | Check path or broaden search terms | | W001 | Wiki forward/backlinks unavailable | Proceed without context web; note reduced coverage | | W002 | coding-conventions.md not found | All patterns marked "unknown status" | | W003 | Target > 1000 lines | Auto-switch to shallow; use --depth deep to override | </error_codes> <success_criteria> - [ ] 4 forcing questions applied per section - [ ] Patterns extracted with file:line anchors and convention cross-ref - [ ] Understanding map + learning-entry blocks written </success_criteria> <next_step_routing> - Deep pattern dive → `/maestro-learn decompose <path>` - Add to specs → `/maestro-spec add coding <description>` - Second opinion → `/maestro-learn consult <file>` </next_step_routing> --- ## Subcommand: investigate **Usage**: `/maestro-learn investigate <question> [--scope <path>] [--max-hypotheses N] [-y]` <purpose> Systematic investigation for understanding questions (not bug-fixing). 4-phase scientific method with scope lock, 3-strike escalation, and evidence persistence. </purpose> <context> Arguments — question text and optional flags. **Flags**: - `--scope <path>`: Restrict to files under this dir (default: entire project) - `--max-hypotheses N`: Max hypotheses before escalation (default: 3) - `-y`: Skip confirmation prompts for report/spec writes **Storage write**: - `.workflow/knowhow/KNW-investigate-{slug}/evidence.ndjson` — structured evidence (one JSON line per item) - `.workflow/knowhow/KNW-investigate-{slug}/understanding.md` — evolving understanding - `.workflow/knowhow/KNW-investigate-{slug}/report.md` — final report - `.workflow/specs/learnings.md` — appended `<learning-entry>` blocks **Storage read**: source files in scope + `maestro search` + `.workflow/specs/learnings.md` + `debug-notes.md` + `codebase/architecture.md` **Output boundary**: ALL file writes MUST target `.workflow/knowhow/KNW-investigate-{slug}/` and `.workflow/specs/learnings.md` only. NEVER modify source code or files outside these paths. </context> <invariants> 1. **Read-only investigation** — NEVER modify source code files; all writes go to `.workflow/` only 2. **Evidence append-only** — `evidence.ndjson` MUST be appended line-by-line; NEVER overwrite or truncate existing evidence entries 3. **Scope lock** — once `--scope` is resolved in S_FRAME, NEVER expand search scope without explicit user confirmation via S_ESCALATE 4. **Hypothesis cap** — MUST NOT generate more than `--max-hypotheses` (default 3) before triggering escalation; NEVER silently exceed the cap 5. **Structured evidence format** — every evidence entry MUST include `{ts, type, source, relevance, content, note}`; incomplete entries SHALL NOT be appended 6. **3-strike escalation** — after all hypotheses fail, MUST escalate to user via request_user_input; NEVER silently conclude as INCONCLUSIVE without user interaction 7. **Confirmation gate** — unless `-y` is set, MUST present report.md path and learning-entries via request_user_input before final writes </invariants> <state_machine> <states> S_FRAME — 解析问题、确定 scope、搜索先验知识 PERSIST: understanding.md (initial) S_EVIDENCE — 系统收集证据 PERSIST: evidence.ndjson S_PATTERN — 比对已知模式 PERSIST: understanding.md (patterns) S_HYPOTHESIZE — 生成假设列表 PERSIST: understanding.md (hypotheses) S_CLI_EXPLORE — CLI 辅助探索（可选） PERSIST: evidence.ndjson (append) S_TEST — 逐假设测试 PERSIST: evidence.ndjson + understanding.md S_ESCALATE — 3-strike 升级 PERSIST: — S_REPORT — 综合报告 + persist PERSIST: report.md + .workflow/specs/learnings.md </states> <transitions> S_FRAME: → S_EVIDENCE DO: A_FRAME_QUESTION S_EVIDENCE: → S_PATTERN DO: A_COLLECT_EVIDENCE S_PATTERN: → S_HYPOTHESIZE DO: match evidence against debug-notes.md + .workflow/specs/learnings.md patterns S_HYPOTHESIZE: → S_CLI_EXPLORE WHEN: CLI tools enabled (at least one tool in cli-tools.json enabled) AND hypotheses non-trivial (require cross-file tracing or data-flow analysis) DO: A_FORM_HYPOTHESES → S_TEST WHEN: no CLI tools OR trivial hypotheses (answerable by local Grep/Read) DO: A_FORM_HYPOTHESES S_CLI_EXPLORE: → S_TEST DO: A_CLI_SUPPLEMENT (maestro delegate --to <first-enabled-tool> --mode analysis, run_in_background, STOP) S_TEST: → S_REPORT WHEN: hypothesis confirmed DO: A_TEST_HYPOTHESIS → S_REPORT WHEN: all hypotheses tested (some confirmed) DO: A_TEST_HYPOTHESIS → S_ESCALATE WHEN: max_hypotheses all failed DO: A_TEST_HYPOTHESIS S_ESCALATE: → S_HYPOTHESIZE WHEN: user broadens scope or provides new hypothesis DO: request_user_input → S_REPORT WHEN: user selects "Escalate" or still stuck DO: mark INCONCLUSIVE S_REPORT: → END GATE: unless -y, request_user_input showing report.md path and learning-entries to append — proceed only on confirm DO: A_SYNTHESIZE_REPORT </transitions> <actions> ### A_FRAME_QUESTION 1. Parse question, generate slug, create KNW-investigate-{slug}/ 2. Search prior knowledge: `maestro search "<question>"` + search .workflow/specs/learnings.md + read debug-notes.md 3. Write initial understanding.md (question, prior knowledge summary, scope, timestamp) ### A_COLLECT_EVIDENCE Parallel evidence gathering: 1. Code search: Grep keywords from question 2. File inspection: Read most relevant files 3. Import tracing: follow dependency chain 4. Git history: `git log --oneline -10 -- <relevant-files>` Each item → append evidence.ndjson: `{ts, type (code|git|search|doc), source (file:line), relevance (high|medium|low), content, note}` ### A_FORM_HYPOTHESES Generate ranked hypotheses: each is specific, testable claim about "how/why". Rank by plausibility (evidence strength). Write to understanding.md: