learn-decompose

<purpose>
Systematic pattern extraction: analyze module across 4 dimensions using parallel agents, catalog findings with code anchors, persist to specs/wiki. Produces reusable pattern catalog.
</purpose>

<context>
$ARGUMENTS — target path/module and optional flags.

**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`: `Skill("spec-add")` for each new pattern
- `--save-wiki`: create wiki note per dimension group

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

<state_machine>

<states>
S_RESOLVE    — 解析 target 为具体文件列表                PERSIST: —
S_DEDUP      — 加载已有 patterns 用于去重                PERSIST: —
S_ANALYZE    — 4 维度并行 Agent 分析                     PERSIST: —
S_CROSSREF   — 交叉引用、去重、标记状态                   PERSIST: —
S_CATALOG    — 生成 pattern catalog 报告                  PERSIST: outputs
S_PERSIST    — 写文件 + 可选 spec-add/wiki create         PERSIST: knowhow files
</states>

<transitions>

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

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           DO: append .workflow/specs/learnings.md [+ spec-add if --save-spec] [+ wiki note if --save-wiki]

</transitions>

<actions>

### 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 |
| new | Not seen before |

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

</actions>

</state_machine>

<error_codes>
| Code | Condition | Recovery |
|------|-----------|----------|
| E002 | No source files in target | Check target has .ts/.js files |
| W001 | One+ dimension agent failed | Proceed with available dimensions |
| 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 → `/learn-follow <anchor-file>`
- Second opinion → `/learn-second-opinion <target>`
- Add to specs → `/spec-add coding ...`
</next_step_routing>