maestro-learn

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

Subcommand	Section
follow	Subcommand: follow
investigate	Subcommand: investigate
decompose	Subcommand: decompose
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).

---

Subcommand: follow

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

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.

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.

<state_machine>

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]

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.

</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]

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.

<state_machine>

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

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

maestro delegate "PURPOSE: Gather evidence for hypotheses
TASK: Trace call chains and data flows per hypothesis | Find corroborating/contradicting patterns
EXPECTED: JSON [{hypothesis_rank, evidence: [{file, line, supports: bool, explanation}]}]
" --to <first-enabled-tool> --mode analysis

Run_in_background, STOP, wait. On callback: 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).

</state_machine>

<error_codes>

Code	Condition	Recovery
E001	No question text provided	Prompt user for investigation question
E002	--scope path not found	Check path
W001	Prior knowledge search returned no results	Proceed without prior context; note cold-start
W002	Very few evidence matches (<3)	Broaden search terms or expand scope
W003	All hypotheses inconclusive	Investigation marked INCONCLUSIVE
</error_codes>

<success_criteria>

• Evidence collected and logged to evidence.ndjson (structured NDJSON)
• At least 1 hypothesis formed and tested
• 3-strike escalation triggered if all fail
• Report + learning-entry blocks written </success_criteria>

<next_step_routing>

• Save to specs → /maestro-spec add debug <finding>
• Follow code → /maestro-learn follow <path>
• Decompose patterns → /maestro-learn decompose <module> </next_step_routing>

---

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.

<state_machine>

S_RESOLVE: → S_DEDUP WHEN: file list resolved → S_RESOLVE WHEN: unresolvable DO: request_user_input

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, request_user_input 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

Spawn 4 Agents in single message:

Agent	Dimension	Looks for
1	Structural	Class hierarchy, composition, DI/IoC, Factory/Builder/Singleton, barrel exports
2	Behavioral	Event flow, middleware chains, observer/pub-sub, command/strategy, state machines
3	Data	Repository/DAO, DTO pipelines, caching (memo/LRU/TTL), serialization, schema validation
4	Error	Error boundaries, retry/backoff/circuit-breaker, fallback chains, guard clauses, logging

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:

Status	Condition
documented	Already in coding-conventions.md
known	In .workflow/specs/learnings.md (if file exists)
new	Not seen before (or learnings.md absent — treat all as new)

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

</state_machine>

<error_codes>

Code	Condition	Recovery
E001	No target path/module provided	Prompt user for target
E002	No source files in target	Check target has .ts/.js files
W001	One+ dimension agent failed	Proceed with available dimensions
W002	.workflow/specs/learnings.md missing or malformed	Treat all patterns as new; create file on persist
W003	Large target (>50 files)	Consider --patterns filter
</error_codes>

<success_criteria>

• 4 dimension agents spawned in parallel, findings with anchors
• Cross-reference: documented/known/new status assigned
• Pattern catalog written + .workflow/specs/learnings.md appended </success_criteria>

<next_step_routing>

• Follow-along → /maestro-learn follow <anchor-file>
• Second opinion → /maestro-learn consult <target>
• Add to specs → /maestro-spec add coding ... </next_step_routing>

---

Subcommand: consult

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

Target resolution (auto-detected):

Input	Resolution
File path	Read file content
Wiki ID (<type>-<slug>)	maestro wiki get <id>
HEAD / staged	git diff HEAD / git diff --staged
Phase number	Resolve the sealed plan artifact through the selected Session's ArtifactRegistry

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.