@tw93/waza 3.25.0

package/skills/hunt/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: hunt
+description: "Finds root cause before applying fixes for errors, crashes, regressions, failing tests, broken behavior, and screenshot-reported defects. Use when users ask 排查/报错/崩溃/不工作/回归/判断为什么报错, or say something used to work and now fails. Not for code review or new features."
+when_to_use: "排查, 查查, 报错, 崩溃, 不工作, 不对, 跑不通, 以前是好的, 回归, 截图回归, 判断错误原因, 判断为什么报错, 反复修不好, debug, regression, used to work, broke after update, why broken, not working, what's wrong, fix error, stack trace"
+dispatch_intent: "Error, crash, regression, screenshot-reported defect, test failure, stale cache, runtime boundary, why broken"
+---
+
+# Hunt: Diagnose Before You Fix
+
+Prefix your first line with 🥷 inline, not as its own paragraph.
+
+A patch applied to a symptom creates a new bug somewhere else.
+
+**Do not touch code until you can state the root cause in one sentence:**
+> "I believe the root cause is [X] because [evidence]."
+
+Name a specific file, function, line, or condition. "A state management issue" is not testable. "Stale cache in `useUser` at `src/hooks/user.ts:42` because the dependency array is missing `userId`" is testable. If you cannot be that specific, you do not have a hypothesis yet.
+
+## Diagnosis Signals
+
+Good progress: a log line matches the hypothesis, you can predict the next error before running it, you understand the propagation path from root cause to symptom, you can write a test that fails on the old code. At each of these signals, find one more independent piece of evidence before committing.
+
+Hypothesis quality gate: before acting on a hypothesis, list all observable symptoms (not just the one the user reported first). The hypothesis must explain every symptom; if it only covers some, it is a symptom-level guess, not a root cause. For timing-dependent issues (flicker, intermittent failure, race condition), reproduce reliably before diagnosing.
+
+Rationalization warning: "I'll just try this" means no hypothesis, write it first. "I'm confident" means run an instrument that proves it. "Probably the same issue" means re-read the execution path from scratch. "It works on my machine" means enumerate every env difference before dismissing. "One more restart" means read the last error verbatim; never restart more than twice without new evidence.
+
+## Durable Context Preflight
+
+See [rules/durable-context.md](../../rules/durable-context.md) for when to read durable context, the read-order budget, and the memory-type mapping.
+
+For `/hunt`, diagnostic constraints are `decision`, `preference`, and `principle` entries; `pattern` and `learning` can seed hypotheses. Current code, logs, repro steps, tests, environment versions, and remote state override memory. Durable context is hypothesis fuel only. It never replaces a fresh root-cause sentence, a reproducible symptom list, or evidence from the current state.
+
+## Hard Rules
+
+- **Same symptom after a fix is a hard stop; so is "let me just try this."** Both mean the hypothesis is unfinished. Re-read the execution path from scratch before touching code again.
+- **After three failed hypotheses, stop.** Use the Handoff format below to surface what was checked, what was ruled out, and what is unknown. Ask how to proceed.
+- **Verify before claiming.** Never state versions, function names, or file locations from memory. Run `sw_vers` / `node --version` / grep first. No results = re-examine the path.
+- **External tool failure: diagnose before switching.** When an MCP tool or API fails, determine why first (server running? API key valid? Config correct?) before trying an alternative.
+- **Pay attention to deflection.** When someone says "that part doesn't matter," treat it as a signal. The area someone avoids examining is often where the problem lives.
+- **Visual/rendering bugs: static analysis first.** Trace paint layers, stacking contexts, and layer order in DevTools before adding console.log or visual debug overlays. Logs cannot capture what the compositor does. Only add instrumentation after static analysis fails.
+- **Fix the cause, not the symptom.** If the fix touches more than 5 files, pause and confirm scope with the user.
+
+## Fix Scope Discipline
+
+If the bug genuinely needs a refactor first (e.g. the cause cannot be addressed without changing a shared interface), pause, name the refactor explicitly, and ask. Do not silently bundle it. A bug fix that grew into a refactor is a separate PR.
+
+## Bisect Mode
+
+Activate when: "以前是好的", "之前是好的", "used to work", "上一次提交还是对的", "broke after update", or the user remembers a specific good commit or version.
+
+1. Find candidate good tag: `git tag --sort=-version:refname | head -10` or ask the user for the last known-good commit.
+2. Define a non-interactive pass/fail test command before starting bisect. Bisect is worthless without a reproducible check.
+3. Run: `git bisect start && git bisect bad HEAD && git bisect good <tag-or-hash>`
+4. At each step bisect checks out a commit. Run the test command. Mark: `git bisect good` or `git bisect bad`.
+5. Let bisect drive. Do not jump ahead or skip commits unless explicitly asked.
+6. When bisect names the culprit commit, read only that diff. Identify the specific line that introduced the regression.
+7. Run `git bisect reset` when done.
+
+Read large files once and reference from notes rather than re-reading at each bisect step.
+
+## Repeated Regression / Screenshot Reference Mode
+
+Activate when the user says the same issue is still wrong after a fix, provides a "good" screenshot/version/file, or describes a visual result as previously correct.
+
+Treat the reference as evidence, not decoration:
+
+1. List every reported and visible symptom, preserving the user's concrete words where useful ("still slow", "not clear", "尖刺", "先显示上一个内容").
+2. Identify the reference oracle: last-good commit/tag, old build, fixture, screenshot, downloaded artifact, or expected state from the user's description.
+3. Define the pass/fail check before editing. For visual bugs, this may be a narrow screenshot checklist plus the command that renders the view; for behavioral bugs, prefer an automated regression test or deterministic repro.
+4. Compare current vs. reference and name the exact delta. Do not generalize a visual defect into "style polish" when the evidence points to a broken render, race, font pipeline, or state path.
+5. If the same symptom remains after one attempted fix, stop and rebuild the hypothesis from the evidence. Do not stack more patches onto a disproven explanation.
+
+If the issue is purely subjective UI taste, route to `/design`. If it is rendering, state, timing, build output, font generation, or a regression from a known-good version, stay in `/hunt`.
+
+## Scope Blast Mode
+
+Activate after fixing a root-cause pattern, before declaring the bug done; also when the user says "举一反三", "举一反三深入看看", or "其他地方有没有同样问题". The same shape often hides in N other places; one local fix that ignores the blast leaves N - 1 bugs in the tree.
+
+1. Extract the pattern signature: the specific function name, regex, API call, CSS selector, lock acquisition, validation skip, or input boundary that produced the bug.
+2. `grep -rn <pattern>` across the repo (exclude generated dirs, build output, vendored deps). For class-of-bug patterns (e.g. "any handler missing the lock"), grep for the surrounding shape, not just the literal text.
+3. List every match. For each one, answer in writing: same bug here? Pick fix / leave (explain why it is safe) / unsure (ask the user). Do not silently skip a match.
+4. Do not claim "fixed" until the blast report is in the Outcome block.
+
+Common triggers:
+- Visual bug fixed on one page: check every other page using the same component, layout, or media-query breakpoint.
+- One race fixed in one handler: check every handler acquiring the same lock or touching the same shared state.
+- One validation skip patched at one entry point: check every entry point that reaches the same downstream sink.
+- One regex / parser fix for one input shape: check every caller of the same regex / parser.
+
+If the blast surfaces unrelated bugs, list them but do not fix in this PR unless the user agrees; scope creep is its own anti-pattern.
+
+## Confirm or Discard
+
+Add one targeted instrument: a log line, a failing assertion, or the smallest test that would fail if the hypothesis is correct. Run it. If the evidence contradicts the hypothesis, discard it completely and re-orient with what was just learned. Do not preserve a hypothesis the evidence disproves.
+
+## Runtime Evidence Ladder
+
+Use this ladder before claiming a bug is fixed:
+
+1. Source trace: name the exact function, state transition, file, line, or condition that can produce the symptom.
+2. Deterministic repro: run or write the smallest command, fixture, UI path, or scenario that produces it.
+3. Logs/state/cache: inspect the runtime state that proves the path was reached, including queues, DB rows, caches, temp files, generated outputs, or external tool logs.
+4. Build/test: run the narrow test or build that exercises the fix.
+5. Real runtime check: for UI, native app, browser, rendering, or visual bugs, open the app/page/artifact and verify the visible result with a screenshot or concrete checklist.
+
+Compile-only is not enough for UI, native-app, visual, rendering, or generated-artifact bugs. If the runtime check is impossible in the environment, say why and hand off the exact screen, command, or artifact to verify.
+
+For recurring classes of failures, load `references/failure-patterns.md` before adding a second fix.
+
+## Targeted Logging
+
+Use logs as a scalpel, not as noise. Before adding a log, write the question it answers:
+
+> "If this log prints X before Y, hypothesis A is still possible; if it does not, hypothesis A is wrong."
+
+Load `references/logging-techniques.md` for the full logging playbook: binary-search instrumentation, discriminating log content, boundary-first placement, timing bug logging, and removal discipline.
+
+Quick rules:
+1. Place the first log at the midpoint of the execution path, not at the symptom. Binary search from there.
+2. Log discriminating facts only: sequence number, input key, branch taken, old/new state, error code.
+3. Remove temporary logs before finishing. Gate persistent diagnostics behind the project's debug flag.
+
+If adding logs changes the behavior, treat that as evidence of a timing, lifecycle, or concurrency problem.
+
+## Gotchas
+
+| What happened | Rule |
+|---------------|------|
+| Patched client pane instead of local pane | Trace the execution path backward before touching any file |
+| MCP not loading, switched tools instead of diagnosing | Check server status, API key, config before switching methods |
+| Orchestrator said RUNNING but TTS vendor was misconfigured | In multi-stage pipelines, test each stage in isolation |
+| Race condition diagnosed as a stale-state bug | For timing-sensitive issues, inspect event timestamps and ordering before state |
+| Added logs everywhere and still could not explain the bug | Rewrite each log as a yes/no question. Delete logs that do not rule a hypothesis in or out |
+| Reproduced locally but failed in CI | Align the environment first (runtime version, env vars, timezone), then chase the code |
+| Stack trace points deep into a library | Walk back 3 frames into your own code; the bug is almost always there, not in the dependency |
+| Worked when launched from app, broke when opened via file association / drag-drop / deep link / external proxy | Reproduce using the exact entry point the user described. App-internal init differs from cold-launch-with-file init; state may not be ready when the document arrives. |
+| Build passed but UI still looked wrong | Move up the Runtime Evidence Ladder and verify the real rendered surface or artifact. |
+
+## Outcome
+
+### Success Format
+
+```
+Root cause:        [what was wrong, file:line]
+Fix:               [what changed, file:line]
+Confirmed:         [evidence or test that proves the fix]
+Tests:             [pass/fail count, regression test location]
+Regression guard:  [test file:line] or [none, reason]
+```
+
+Status: **resolved**, **resolved with caveats** (state them), or **blocked** (state what is unknown).
+
+**Regression guard rule**: for any bug that recurred or was previously "fixed", the fix is not done until:
+1. A regression test exists that fails on the unfixed code and passes on the fixed code.
+2. The test lives in the project's test suite, not a temporary file.
+3. The commit message states why the bug recurred and why this fix prevents it.
+
+### Handoff Format (after 3 failed hypotheses)
+
+```
+Symptom:
+[Original error description, one sentence]
+
+Hypotheses Tested:
+1. [Hypothesis 1] → [Test method] → [Result: ruled out because...]
+2. [Hypothesis 2] → [Test method] → [Result: ruled out because...]
+3. [Hypothesis 3] → [Test method] → [Result: ruled out because...]
+
+Evidence Collected:
+- [Log snippets / stack traces / file content]
+- [Reproduction steps]
+- [Environment info: versions, config, runtime]
+
+Ruled Out:
+- [Root causes that have been eliminated]
+
+Unknowns:
+- [What is still unclear]
+- [What information is missing]
+
+Suggested Next Steps:
+1. [Next investigation direction]
+2. [External tools or permissions that may be needed]
+3. [Additional context the user should provide]
+```
+
+Status: **blocked**
+
+## Rendering Bug Mode
+
+Activate when: "PDF looks wrong", "page break issue", "font not rendering", broken PDF output, or print layout wrong.
+
+Load `references/rendering-debug.md` for the full diagnosis checklist (WeasyPrint quirks, font loading, page overflow, browser print CSS). Static analysis first, then reproduce if needed.
+
+## IME / Unicode Issues
+
+For input method, character rendering, or text encoding bugs (IME state, cursor drift, emoji splitting, composition events), check `references/ime-unicode.md` first before forming a hypothesis.

package/skills/hunt/references/failure-patterns.md

@@ -0,0 +1,75 @@
+# Failure Pattern Reference
+
+Use this when a bug has repeated, a first fix did not hold, or the symptom smells like runtime state rather than local code syntax.
+
+## Stale Verifier Or Tool Cache
+
+Signals: verifier output points at deleted temp worktrees, old generated files, or paths outside the current repo; rerunning after a clean checkout changes the file path but not the current code.
+
+Checks:
+- Confirm the reported path exists.
+- Clear the tool cache only after proving the path is stale.
+- Re-run the same verifier from the current repo root.
+
+## Worker Queue Or DB Boundary
+
+Signals: UI says work is running but no worker processes it; logs show scheduler activity but no queued row; retry fixes one item but not the pipeline.
+
+Checks:
+- Trace request -> enqueue -> worker pickup -> persistence -> UI refresh.
+- Inspect queue rows or job state directly.
+- Add a regression test around the enqueue boundary, not only the worker body.
+
+## Generated Rebuild Boundary
+
+Signals: source changed but generated output, app bundle, CLI artifact, archive, checksum, or release package still contains old behavior.
+
+Checks:
+- Identify the source-to-artifact rule.
+- Verify the build system watches the source path.
+- Inspect the generated artifact contents, not just the source diff.
+
+## Guard Lifetime Race
+
+Signals: permission, auth, or state guard looks correct locally but a delayed callback, app relaunch, or alternate entry point bypasses it.
+
+Checks:
+- Trace guard creation, retention, invalidation, and every alternate entry point.
+- Verify cold launch, warm launch, deep link/file open, and retry paths when applicable.
+- Prefer explicit durable state over transient flags when the guard must survive relaunch.
+
+## Atomic Temp Filename
+
+Signals: concurrent runs collide, cleanup removes the wrong file, or a partially written output is observed.
+
+Checks:
+- Use unique temp directories or atomic rename.
+- Keep cleanup scoped to files created by the current run.
+- Test two concurrent or back-to-back runs when the tool supports it.
+
+## Path, Cwd, Or Symlink Escape
+
+Signals: an operation intended for one root touches a sibling directory, follows a symlink unexpectedly, or behaves differently from another working directory.
+
+Checks:
+- Resolve and compare canonical roots before writing or deleting.
+- Reject paths outside the allowed root after symlink resolution.
+- Reproduce from a non-default cwd and through any UI entry point that supplies paths.
+
+## Snapshot Rebuild Drops Carried Field
+
+Signals: live data shows up at the data source and on the wire but a downstream view sees it empty; the field has a default value (`var x: [T] = []`, `var y: Int? = nil`) that lets memberwise init compile without it; the symptom appears only on the path where the snapshot is rebuilt (icon resolution, decoration, redaction), not on a fresh fetch.
+
+Checks:
+- Trace whether every code path that constructs the snapshot type passes the field. The Swift compiler does not warn on default-value omission in memberwise init.
+- Add a unit test that fetches the snapshot, runs the rebuild path, and asserts the carried field equals the input.
+- Prefer `with(...)` mutating helpers or `inout` mutation over fresh memberwise init when only one field is changing.
+
+## Multi-Sample Command Cold Start
+
+Signals: a CLI tool that takes `-l N` / `--samples N` / `--repeat N` returns one block of zeros and one block of real data; aggregating all blocks yields zeros; only the second sample carries real measurements.
+
+Checks:
+- Read the tool's man page for cold-start semantics. `top -l 2`, `iostat -d 2`, `vm_stat 1 2`, etc. all share this shape.
+- Slice the output to the latest sample (`.suffix(perSampleSize)` on parsed lines, or look for the second instance of the header row).
+- When in doubt, raise `-l` to 3 and confirm sample 2 and 3 agree; sample 1 stays zero.

package/skills/hunt/references/ime-unicode.md

@@ -0,0 +1,58 @@
+# IME / Unicode Debugging Reference
+
+Recurring patterns in Tauri and native macOS apps. Check these before forming a hypothesis.
+
+## IME State Desync
+
+**Symptom**: Latin characters appear correctly but CJK input is dropped, doubled, or committed at the wrong time.
+
+**Cause candidates**:
+- Input method switch mid-composition: the IME commits the preedit with a stale target, then the new mode processes the same keystrokes again.
+- `keydown` handler consuming events during active composition: check `event.isComposing` before acting on `keydown`/`keyup`. If `isComposing` is true, defer the action until `compositionend`.
+- Webview + native frame split focus: in Tauri, the webview and the native window title bar can hold focus simultaneously. A click on a native control during IME composition triggers a focus-out, committing incomplete preedit text.
+
+**Instruments**:
+- Log `compositionstart`, `compositionupdate`, `compositionend` sequence; confirm they fire in order without gaps.
+- Log the `data` field of each `compositionupdate`; a sudden empty string signals a forced commit.
+
+## Cursor Position Drift After IME Commit
+
+**Symptom**: After confirming a CJK word, the cursor jumps to the wrong position or the selection collapses.
+
+**Cause candidates**:
+- DOM mutation during composition: React/Svelte/Vue re-rendering while `isComposing` is true will reset the selection. Batch state updates and flush only on `compositionend`.
+- Counting bytes instead of code points in position math: CJK characters are multi-byte in UTF-8. Use `Array.from(str).length` or `[...str].length`, not `str.length`, for character-level offsets in positions.
+
+## Emoji ZWJ Sequence Splitting
+
+**Symptom**: Multi-person or profession emoji (e.g. `👩‍🚒`) renders as two or three separate emoji, or the ZWJ (`U+200D`) appears as a visible character.
+
+**Cause candidates**:
+- String sliced at byte offset: `str.slice(0, n)` splits a ZWJ sequence if `n` falls inside the sequence. Use `Intl.Segmenter` with `granularity: 'grapheme'` to split at grapheme cluster boundaries.
+- Font does not support the sequence: the font renders each code point individually. Verify with `canvas.measureText` or by checking which font is actually used via `document.fonts`.
+- Serialization strips ZWJ: some JSON encoders normalize or escape `U+200D`. Verify the raw bytes of the stored string.
+
+**Test**: `[...'👩‍🚒'].length` should be 1 (one grapheme cluster). If it returns 3, the runtime is iterating code points, not grapheme clusters.
+
+## `compositionend` / `keydown` Event Ordering
+
+**Symptom**: The action bound to Enter or Tab fires during IME confirmation, submitting incomplete input.
+
+**Cause**: On macOS + some IMEs, the sequence is `compositionend` → `keydown(Enter)`. On Windows + other IMEs it can be `keydown(Enter)` → `compositionend`. Code that blocks Enter only when `isComposing` is true will break on the macOS ordering because `isComposing` is already false when `keydown` fires.
+
+**Fix**: Track composition state with a boolean flag set on `compositionstart`, cleared on `compositionend`. Guard the Enter handler with that flag rather than `event.isComposing`.
+
+## macOS Text System vs Webview Conflict
+
+**Symptom**: Undo (`Cmd+Z`) reverts individual IME preedit characters instead of committed words, or system text shortcuts (Cmd+Shift+Left for word selection) behave differently inside vs outside the webview.
+
+**Cause**: WKWebView has its own text system that partially overlaps with NSTextView conventions. Tauri's `preventDefaultFor` config can suppress system shortcuts; check `tauri.conf.json` (v1) or `app.json` (v2) for any `preventDefault` rules that may be too broad.
+
+## Quick Checklist
+
+- [ ] `isComposing` checked before acting on keyboard events?
+- [ ] No DOM mutation while `isComposing` is true?
+- [ ] String position math uses grapheme clusters, not bytes or code points?
+- [ ] ZWJ sequences verified with `Intl.Segmenter`?
+- [ ] Enter/Tab guard uses a flag set by `compositionstart`, not `event.isComposing`?
+- [ ] `tauri.conf.json` `preventDefaultFor` not too broad?

package/skills/hunt/references/logging-techniques.md

@@ -0,0 +1,72 @@
+# Logging Techniques for Debugging
+
+Use logs as a scalpel, not as noise. The goal is to answer a yes/no question about a hypothesis, not to dump state.
+
+## Binary Search Instrumentation
+
+Place the first log at the midpoint of the execution path, not at the symptom. If it fires correctly, move downstream. If it does not fire, move upstream. This is binary search over the call graph.
+
+```
+Entry → [midpoint log] → ... → symptom
+         ^
+         First log here, not at the symptom
+```
+
+Repeat: each log cuts the remaining unknown path in half.
+
+## Log What Discriminates, Not What Is Convenient
+
+Before adding a log, write the question it must answer:
+
+> "If this prints X before Y, hypothesis A holds. If it prints Y first, A is wrong."
+
+Discriminating log content:
+- Sequence number or timestamp (ordering)
+- Input identity key (which request/item)
+- Branch taken (which `if` arm)
+- Old vs. new state transition (not just new value)
+- Error code plus context string (not just the exception message)
+
+Never log: full request/response bodies, credentials, PII, or huge JSON blobs.
+
+## Log the Boundary, Not the Interior
+
+Log at system boundaries where behavior should be predictable:
+
+- Request handler entry/exit
+- Cache read (hit or miss) with key
+- State setter (old value, new value, caller)
+- Async callback entry
+- External API call result
+- Build step start/end
+
+Interior logs (inside tight loops or low-level helpers) are noise unless the hypothesis is specifically about that interior.
+
+## Prefix Discipline
+
+Use a consistent log prefix to filter by context:
+
+```
+[hunt:auth] token validate: user=42 result=expired
+[hunt:cache] miss: key=user:42 latency=12ms
+[hunt:render] phase=layout height=842px overflow=yes
+```
+
+Gate verbose logging behind a debug flag when the project already has one. Remove temporary logs before finishing.
+
+## Timing Bug Logging
+
+For race conditions, flicker, or intermittent failures, log:
+- Event identity (which event source)
+- Timestamp (or monotonic counter)
+- Start and end (not just "it ran")
+- Thread/task/queue identity when concurrency is involved
+
+If adding a log changes the behavior, treat that as evidence of a timing, lifecycle, or concurrency problem. Do not dismiss it as "just logging side effects."
+
+## Removing Logs
+
+After the root cause is confirmed:
+1. Remove all temporary logs.
+2. If a log is genuinely useful in production, move it behind the project's debug flag or logger level.
+3. Do not leave `console.log`, `print`, or `fmt.Println` in shipped code paths unless the project keeps debug instrumentation there.

package/skills/hunt/references/rendering-debug.md

@@ -0,0 +1,34 @@
+# Rendering Bug Debug Reference
+
+## Rendering Bug Mode
+
+Activate when: "PDF looks wrong", "page break issue", "font not rendering", broken PDF output, print layout wrong.
+
+Static analysis first (CSS review), then reproduce if needed.
+
+### WeasyPrint
+
+- `rgba()` causes double-rectangle bug: use solid hex colors instead
+- `page-break-inside: avoid` is often ignored: use explicit breaks
+- Float-based layouts often break at page boundaries: prefer flexbox or block
+- External font URLs blocked at render time: embed fonts as base64 or host locally
+
+### Font Loading
+
+- Check `@font-face` src paths (relative vs. absolute)
+- CORS headers must allow the render origin for external fonts
+- Format support: WeasyPrint prefers WOFF/TTF; WOFF2 support depends on version
+- Missing font fallback = invisible text or system fallback glyph
+
+### Page Overflow
+
+- Calculate content height vs. page height before debugging line-by-line
+- Reduce `line-height`, `padding`, or `margin` to reclaim space
+- Orphan/widow control: `orphans: 3; widows: 3` in `@page` body rule
+
+### Browser Print CSS
+
+- Confirm `@media print` rules are present and not overridden
+- `@page` margin must account for printer unprintable area (~6mm minimum)
+- `break-before: page` / `break-after: page` on section dividers
+- Test with `window.print()` in browser DevTools, not just visual preview

package/skills/learn/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: learn
+description: "Runs a six-phase research workflow that turns unfamiliar domains, source bundles, or collected material into publish-ready output. Use when users ask 学习一下/深入研究/研究一下/整理成文章/deep dive/compile sources or need one coherent reference from many inputs. Not for quick lookups or single-file reads."
+when_to_use: "学习一下, 深入研究, 研究一下, 整理成文章, 把这批材料整理, 一站式参考, 一篇就够, 整理成长文, research, deep dive, help me understand, compile sources, unfamiliar domain"
+dispatch_intent: "Deep research, unfamiliar domain, compile sources into output"
+---
+
+# Learn: From Raw Materials to Published Output
+
+Prefix your first line with 🥷 inline, not as its own paragraph.
+
+Collect, organize, translate, explain, structure. Support the user's thinking; do not replace it.
+
+**Boundary**: single URL that only needs fetching belongs in `/read`. A single URL that needs summary or analysis can use `/read` as the fetch step, but the final answer should satisfy the user's requested summary or analysis. `/learn` is for multi-source research that produces a new structured output.
+
+## Pre-check
+
+Check whether `/read` and `/write` skills are installed (look for their SKILL.md in the skills directories). Warn if missing, do not block:
+- `/read` missing -- Phase 1 fetch falls back to native `WebFetch` / `curl`; coverage on paywalled, JS-heavy, and Chinese-platform pages degrades.
+- `/write` missing -- Phase 5 AI-pattern stripping falls back to manual scan. Phases 1-4 are unaffected.
+
+## Choose Mode
+
+Ask the user to confirm the mode, using the environment's native question or approval mechanism if it has one:
+
+| Mode | Goal | Entry | Exit |
+|------|------|-------|------|
+| **Deep Research** | Understand a domain well enough to write about it | Phase 1 | Phase 6: publish-ready draft |
+| **Quick Reference** | Build a working mental model fast, no article planned | Phase 2 | Phase 2: notes only |
+| **Write to Learn** | Already have materials, force understanding through writing | Phase 3 | Phase 6: publish-ready draft |
+| **Canonical Article** | One article that covers a topic so thoroughly readers need nothing else | Phase 1 | Phase 6: single authoritative reference |
+
+If unsure, suggest Quick Reference.
+
+## Canonical Article Mode
+
+Activate when: "一篇就够", "一站式参考", "整理成长文", "目的是大家只需要看这篇就好了", or the user wants a single authoritative reference on a topic.
+
+Goal: after reading the article, no one should need to search for anything else on this topic.
+
+Additional requirements on top of standard Deep Research:
+- Every major sub-topic must have its own section; nothing left as a footnote
+- Include worked examples, not just principles
+- Cover common mistakes and how to avoid them
+- Add a "Further Reading" section with the 3-5 sources that go deepest; flag which ones are the best starting points
+- Phase 6 self-review must confirm: "Could a reader implement/understand this from this article alone?"
+
+## Phase 1: Collect
+
+Gather primary sources only: papers that introduced key ideas, official lab/product blogs, posts from builders, canonical "build it from scratch" repositories. Not summaries. Not explainers.
+
+Three ordered steps per source -- no shortcuts, no merging:
+
+1. **Discover** -- use an installed search plugin (e.g., PipeLLM) to map the landscape, then deep-search the 2-3 most promising sub-topics. No plugin: use the environment's native web search. Output is a URL list; do not fetch content here.
+2. **Fetch** -- every URL goes through `/read`. `/read` already owns the proxy cascade, paywall detection, and platform routing (WeChat, Feishu, PDF, GitHub). `WebFetch` and raw `curl` silently fail on JS-heavy or paywalled sites and skip all of that. If `/read` is missing (Pre-check warned), fall back to native fetch and accept reduced coverage.
+3. **File** -- `/read` saves to `~/Downloads/{title}.md` when called from `/learn`. Move each file into a sub-topic directory under the research project after the fetch returns. Move, don't refetch.
+
+Target: 5-10 sources for a blog post, 15-20 for a deep technical survey.
+
+## Phase 2: Digest
+
+Work through the materials. For each piece: read it fully, keep what is good, cut what is not. At the end of this phase, cut roughly half of what was collected.
+
+For key claims, ask before including in the outline:
+- Does this idea appear in at least two different contexts from the same source?
+- Can this framework predict what the source would say about a new problem?
+- Is this specific to this source, or would any expert in the field say the same thing?
+
+Generic wisdom is not worth distilling. Passes two or three: belongs in the outline. Passes one: background material. Passes zero: cut it.
+
+When two sources contradict on a factual claim, note both positions and the evidence each gives. Do not silently pick one.
+
+### Conversation Or Review Distillation
+
+When the input is a recent conversation, project review, scorecard, or diagnostic report, treat it as raw material:
+
+- Extract repeated workflow failures, invariants, and verifier surfaces.
+- Drop dated line numbers, current-score framing, private paths, one-machine setup, and repo-specific commands unless the output is explicitly for that same repo.
+- Map each durable lesson to its target layer: project docs, shared rules, skill references, or deterministic scripts.
+- Keep evidence snippets only as notes for yourself; do not paste raw conversation history into the final artifact.
+
+## Phase 3: Outline
+
+Write the outline for the article. For each section: note the source materials it draws from. If a section has no sources, either it does not belong or a source needs to be found first.
+
+Do not start Phase 4 until the outline is solid.
+
+## Phase 4: Fill In
+
+Work through the outline section by section. If a section is hard to write, the mental model is still weak there: return to Phase 2 for that sub-topic. The outline may change, and that is fine.
+
+Stall signals (any one means the mental model is incomplete for this section):
+- You have rewritten the opening sentence three or more times without settling
+- The section relies on a single source and you cannot cross-check the claim
+- You need a new source that was not collected in Phase 1
+- The paragraph makes a claim you could not explain to someone out loud
+
+When stalled: return to Phase 2 for that sub-topic, not for the whole article.
+
+## Phase 5: Refine
+
+Pass the draft with a specific brief:
+- Remove redundant and verbose passages without changing meaning or voice
+- Flag places where the argument does not flow
+- Identify gaps: concepts used before they are explained, claims needing sources
+
+Do not summarize sections the user has not written. Do not draft new sections from scratch. Edits only.
+
+Then strip AI patterns from the draft. If `/write` is installed, invoke it. If not, do it manually: scan for filler phrases, binary contrasts, dramatic fragmentation, and overused adverbs. Cut them without changing meaning.
+
+## Phase 6: Self-review and Publish Readiness
+
+The user reads the entire article linearly before publishing. Not with AI. Mark everything that feels off, fix it, read again. Two passes minimum.
+
+When it reads clean from start to finish, the draft is ready for the user to publish.
+
+**After the user confirms the article is ready to publish, stop.** Do not upload, post, distribute, or perform any publish action unless explicitly asked.
+
+## Gotchas
+
+| What happened | Rule |
+|---------------|------|
+| Collected 30 secondary explainers instead of primary sources | Phase 1 targets papers, official blogs, and repos by builders. Summaries are not sources. |
+| Used `WebFetch` or `curl` on URLs while `/read` was installed | Phase 1 fetch is not optional. `/read` owns the proxy cascade, paywall detection, and platform routing. Bypassing it silently loses coverage on paywalled, JS-heavy, or Chinese-platform pages. |
+| Treated a convincing explainer as ground truth | Ask: does this appear in at least two different contexts from the same source? |
+| Phase 2 wrote summaries instead of teaching the concept | Digest means building the mental model. Summarizing is not digesting. |
+| AI offered to upload the article to a blog or social platform after the user said it was ready | Stop at confirmation. Publishing is the user's action, not yours. |
+| Turned a project review into a generic Waza rule without filtering | Promote only repeated workflow behavior. Leave project-specific commands, paths, and safety constraints in that project |