learn-follow

<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 `<spec-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 wiki 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

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

<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 + spec-entry 块 PERSIST: knowhow files </states> <transitions>

S_RESOLVE: → S_CONTEXT WHEN: target resolved → S_RESOLVE WHEN: unresolvable DO: AskUserQuestion 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 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 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
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 + spec-entry blocks written </success_criteria>

<next_step_routing>

• Deep pattern dive → /learn-decompose <path>
• Add to specs → /spec-add coding <description>
• Second opinion → /learn-second-opinion <file> </next_step_routing>