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.

<state_machine>

S_RESOLVE: → S_CONTEXT WHEN: target resolved DO: read target content → S_RESOLVE WHEN: unresolvable DO: request_user_input 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, request_user_input 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

Spawn 3 Agents in single message:

Agent	Focus	Question
Pragmatist	simplicity, YAGNI, maintenance	"Simplest thing that works? Maintenance burden?"
Purist	correctness, edge cases, type safety	"What assumptions can be violated?"
Strategist	scalability, architecture alignment	"Supports future growth? Fits architecture?"

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

A_CHALLENGE

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. request_user_input → Agent answers with code refs → repeat until "done"
4. Compile Q&A into report

</state_machine>

<error_codes>

Code	Condition	Recovery
E001	No target provided	Prompt user for target (path, wiki ID, HEAD, staged, or phase)
E002	Unknown --mode value	Use: review, challenge, or consult
E003	Target resolution failed — path not found, wiki ID invalid, or no staged changes	Check target exists
W001	One review agent failed	Proceed with available perspectives
W002	Specs/wiki pre-load unavailable	Proceed without convention context; note reduced coverage
</error_codes>

<success_criteria>

• Mode executed: review (3 parallel agents) / challenge (adversarial) / consult (interactive Q&A)
• Synthesis with agreements, disagreements, verdict
• Report written + findings appended to .workflow/specs/learnings.md </success_criteria>

<next_step_routing>

• Create issue → /maestro-issue create <description>
• Decompose patterns → /maestro-learn decompose <path>
• Follow code → /maestro-learn follow <path> </next_step_routing>