Maestro Learn

• background: false is the default. Use foreground dispatch whenever the result determines the current answer or next action.
• Use background: true only for independent work. If this turn must consume a background result, call observe exactly once with action: "wait" and a bounded timeout before continuing; never continue independently while the result is pending.
• Otherwise end the turn and wait for the automatic teammate-complete notification. Do not rely on SendMessage, team_msg, or hook callbacks as completion signals.
• Never silently ignore an unfinished dispatch.

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

Routing errors:

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).

Subcommand: follow

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

Target resolution (auto-detected):

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.

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] user prompt 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.

S_RESOLVE: → S_CONTEXT WHEN: target resolved → S_RESOLVE WHEN: unresolvable DO: [@ask] user prompt 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, [@ask] user prompt 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]

A_BUILD_CONTEXT_WEB

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:

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.

Subcommand: investigate

Usage: /maestro-learn investigate <question> [--scope <path>] [--max-hypotheses N] [-y]

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.

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 (teammate({ agent: "general", taskType: "analysis", /* --to */ }), 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: [@ask] user prompt → S_REPORT WHEN: user selects "Escalate" or still stuck DO: mark INCONCLUSIVE

S_REPORT: → END GATE: unless -y, [@ask] user prompt showing report.md path and learning-entries to append — proceed only on confirm DO: A_SYNTHESIZE_REPORT

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:

• [HIGH] hypothesis — Evidence: {refs}
• [MEDIUM] hypothesis — Evidence: {refs}

A_CLI_SUPPLEMENT

teammate({ agent: "general", taskType: "analysis", tasks: [{ prompt: "PURPOSE: Gather evidence for hypotheses\nTASK: Trace call chains and data flows per hypothesis | Find corroborating/contradicting patterns\nEXPECTED: JSON [{hypothesis_rank, evidence: [{file, line, supports: bool, explanation}]}]" }], /* --to <first-enabled-tool>: set model via model-availability */ })

Run_in_background, STOP, wait. On teammate-complete notification: append to evidence.ndjson.

A_TEST_HYPOTHESIS

For each hypothesis (rank order):

1. Design test: what evidence would confirm/disprove?
2. Execute: code trace, targeted search, data inspection
3. Record: append evidence.ndjson with type: "test"
4. Update: mark hypothesis confirmed / disproved / inconclusive

A_SYNTHESIZE_REPORT

Write report.md: Answer (or INCONCLUSIVE), Evidence Trail table, Hypotheses Tested table, Key Learnings, Open Questions. Append to .workflow/specs/learnings.md: confirmed → roles="implement", disproved → roles="analyze" (gotcha).

Subcommand: decompose

Usage: /maestro-learn decompose <path|module> [--patterns <list>] [--save-spec] [--save-wiki] [-y]

Target resolution: file path → that file; directory → all source files; module name → Glob src/**/{module}*.

Flags:

• --patterns <list>: Comma-separated pattern names to look for (default: detect all)
• --save-spec: execute /maestro-spec add ... for each new pattern (not just recommend)
• --save-wiki: create wiki note per dimension group
• -y: Skip confirmation prompts for knowhow/spec writes

Storage read: target files + coding-conventions.md + .workflow/specs/learnings.md (dedup) Storage write: .workflow/knowhow/KNW-decompose-{slug}-{date}.md + append .workflow/specs/learnings.md

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

S_RESOLVE: → S_DEDUP WHEN: file list resolved → S_RESOLVE WHEN: unresolvable DO: [@ask] user prompt

S_DEDUP: → S_ANALYZE DO: read coding-conventions.md + .workflow/specs/learnings.md → build known pattern set

S_ANALYZE: → S_CROSSREF DO: A_PARALLEL_DIMENSION_ANALYSIS

S_CROSSREF: → S_CATALOG DO: A_CROSSREF_DEDUP

S_CATALOG: → S_PERSIST DO: write KNW-decompose report (grouped by dimension: pattern table + details)

S_PERSIST: → END GATE: unless -y, [@ask] user prompt showing files to write and patterns to persist — proceed only on confirm DO: append .workflow/specs/learnings.md [+ execute maestro-spec add if --save-spec] [+ wiki note if --save-wiki]

A_PARALLEL_DIMENSION_ANALYSIS

[@subagent] Spawn 4 Agents in single message:

If --patterns specified: agents focus only on named patterns.

Each agent returns: [{ name, dimension, confidence (high/medium/low), anchors [file:line], description, rationale, tradeoffs }]

A_CROSSREF_DEDUP

For each finding, match against known pattern set:

Flag contradictions (finding conflicts with documented convention). Merge duplicates across agents (same pattern found by multiple dimensions).

Subcommand: consult

Usage: /maestro-learn consult <target> [--mode review|challenge|consult] [-y]

Target resolution (auto-detected):

Flags:

• --mode review|challenge|consult (default: review)
• -y: Skip confirmation prompts for knowhow/spec writes

-y in consult mode: skips the final write confirmation only. The interactive Q&A loop is NOT affected by -y (it is the core interaction, not a confirmation). Use --mode review for non-interactive alternative.

Pre-load (optional): recommend maestro load --type spec for conventions + maestro search "<target topic>" for related entries.

Output: .workflow/knowhow/KNW-opinion-{slug}-{YYYY-MM-DD}.md

Output boundary: ALL file writes MUST target .workflow/knowhow/KNW-opinion-{slug}-{YYYY-MM-DD}.md and .workflow/specs/learnings.md only. NEVER modify source code or files outside these paths.

S_RESOLVE: → S_CONTEXT WHEN: target resolved DO: read target content → S_RESOLVE WHEN: unresolvable DO: [@ask] user prompt for clarification

S_CONTEXT: → S_EXECUTE DO: load specs + wiki search (optional, proceed without)

S_EXECUTE: → S_SYNTHESIZE WHEN: mode == review DO: A_REVIEW → S_SYNTHESIZE WHEN: mode == challenge DO: A_CHALLENGE → S_SYNTHESIZE WHEN: mode == consult DO: A_CONSULT

S_SYNTHESIZE: → S_PERSIST DO: merge perspectives → agreements, disagreements, verdict, top 3 recommendations

S_PERSIST: → END GATE: unless -y, [@ask] user prompt showing files to write and learning-entries to append — proceed only on confirm DO: write KNW-opinion + append blocks to .workflow/specs/learnings.md

A_REVIEW

[@subagent] Spawn 3 Agents in single message:

Each returns: persona, verdict (approve/concern/reject), confidence, findings[{severity, description, location, suggestion}], summary.

A_CHALLENGE

[@subagent] Spawn 1 adversarial Agent:

• Find weakest assumption
• Propose concrete breaking scenario
• Identify single biggest risk
• Suggest alternative approach
• Apply forcing questions: "What invalidates this?", "Simplest thing that breaks this?", "What would you regret in 6 months?", "What implicit contract isn't enforced?"

A_CONSULT

Interactive loop:

1. Agent studies target
2. Display "Target loaded. What would you like to know?"
3. [@ask] user prompt → Agent answers with code refs → repeat until "done"
4. Compile Q&A into report