kiwi-distill

Files (1)

• SKILL.md

SKILL.md (first lines)

# Kiwi Distill — 知识蒸馏工作流

## Phase 0: Resolve Wiki Path and Read SCHEMA

Run `realpath ~/.zoo/wiki` to get the wiki's absolute path. Use this path for all subsequent file reads (the `read` tool does not expand `~`).

Then read `SCHEMA.md` inside the wiki (or run `zwiki schema`) to confirm formatting and naming rules. If already read this session, skip. Run `zwiki template <type>` to see the exact skeleton of the page type you will produce.

If your CONTEXT contains external URLs, use `webfetch`. For additional external sources, use `websearch`.

## Phase 1: Read Distillation Example

Read `{wiki_abs_path}/wiki-system/analysis/distillation-example-karpathy.md` — a complete worked example of good distillation. Study what was created, what was discarded, what was merged, and the key judgment calls. This example demonstrates the principles behind the Self-Review criteria in Phase 4. Keep it in mind as a reference throughout the rest of the workflow.

## Phase 2: Quick Scan → Search → Load

### 2.1: Quick Scan

The source material is already in your CONTEXT (or was fetched via webfetch in Phase 0 if it was a URL). Extract 3-5 core topic terms from it. Topic terms should be substantive concept names from the source material — not generic words like "design", "system", "architecture" — but domain-specific terms like "permission model", "deny list", "prompt injection".

### 2.2: Search

For each topic term, run `zwiki search "<term>" --json`.
Combine results from all searches into a single candidate list, keeping each unique path only once.
Read the full content + frontmatter of each candidate page (pay special attention to `last_validated`, `timeliness`, `supersedes`, `superseded_by`, `contradictions` fields).

### 2.3: Load Related Pages

For each candidate page, read the pages it links to via inline body links (direct links only, depth 1, no recursion). Also read their content + lifecycle fields.

### 2.4: Establish Claim Map & Learn Density Patterns

Compile an actionable claim map of all existing pages — what facts/principles/design decisions each existing page asserts.

Extract density patterns from the pages you've already read: typical line counts, number of Detail subsections, presence/absence of code blocks, table sizes. This is your baseline for how much a wiki page should hold.

### Fallback: If search returns no results

Case 1: Candidate list is empty (zwiki search returned 0 results) → keywords didn't match any page.
Case 2: Candidate list is non-empty but all pages are unrelated to the source material (same name, different concept; false match) → search hit but content is irrelevant.

Both cases handled identically: read the root `index.md` → based on source material content, determine the domain → read that domain's `index.md` → get all page paths in that domain → read each page's content + lifecycle fields → return to Phase 2.4 to establish the claim map.

---

**Dedup vs Supersede distinction:** Dedup (covered above in Phase 2) is about whether the new source's knowledge unit is already recorded. If yes, recommend updating the existing page. Supersede (Phase 4.7) is different — it's about whether the new source's claim directly contradicts what the existing page asserts. Dedup leads to "update this page," supersede leads to "this new page replaces the old one."

## Phase 3: Analyze & Draft

### 3.1 Understand the source holistically

Read and understand the source material. Pay special attention to the **source profile** in your CONTEXT if present — it describes:
- The knowledge density of the source (concise and direct? argument-heavy? knowledge buried in execution details?)
- Which parts are likely packaging vs core knowledge

The source profile is your primary filter: it tells you what NOT to distill. If no source profile is provided, treat the source as having uniform knowledge density.

### 3.2 Assign density levels

Before drafting any content, assign a **density level** to each proposed page based on its knowledge role:

| Level | Role | Target | When to use |
|-------|------|:------:|-------------|
| L1 | Reference | 40–60 lines, 2–3 short subsections | Most concepts, entities — a reader can consume in 30 seconds |
| L2 | Analysis | 60–100 lines, 3–5 subsections with reasoning | Complex concepts, tradeoff analyses — needs room for a comparison or design rationale |
| L3 | ADR | 100+ lines, full chapters | Only when the source IS an architecture decision record — includes migration plans, risk matrices |

**Default: L1 for concepts and entities, L2 for analysis pages.** Do not use L3 unless the source material is itself an ADR and the caller explicitly needs the full treatment.

### 3.3 Identify knowledge units

Identify knowledge units (concepts, entities, patterns, tradeoffs). For each unit, decide:
- Is this a standalone concept → should it be its own page? Or can it merge into an existing page?
- Does this unit naturally belong at the assigned density level? If a unit needs >5 subsections at L1, split or reconsider the level.

### 3.4 Draft page recommendations

Draft page content within the assigned density level. Produce a rough draft — do NOT finalize yet.

## Phase 4: Self-Review

Before finalizing, review your draft against ALL criteria below. If a criterion fails, revise — do NOT skip to Phase 5 with a known issue. You may iterate within this phase up to 2 times.

### 4.1 Structure Check
- Does every recommended page have a SINGLE clear knowledge focus? If a page mixes two unrelated concepts, split it.
- Does your page ordering follow the source's narrative sequence? If so, that's narrative leakage — reorganize by knowledge domain, not original paragraph order.

### 4.2 Category Check
- For every page type (concept/entity/analysis/source), ask: "Is this the best fit?" The most common mistake is labeling everything as `concept`. A concrete tool/script/file is an `entity`, not a concept. If a page contains comparison/tradeoff analysis, it should be `analysis`.
- Before creating a new page, verify that the concept isn't already covered by an existing wiki page with a more authoritative description. If an existing page already describes the concept well, reference it via cross-reference instead of creating a redundant page.
- **Reverse check — term outgrowing its host:** if your draft needs to reference a concept that exists only as a subsection of a page whose main topic differs (e.g. ACI living inside augmented-llm), and multiple pages need to reference it, propose extracting it into a standalone page (migrate content from the host, leave a pointer paragraph in the host) instead of anchoring links to a topically mismatched host page.

### 4.3 Density Check
- Does every page respect its assigned density level? If an L1 page has 6 subsections or an L2 page has 15, compress or split.
- Does every page have ≤4 knowledge points? If a page tries to teach 7 things, split it — regardless of line count. A dense page is harder to consume than two focused ones.
- Can each knowledge point be expressed in ≤1 paragraph (4–6 sentences)? If a point needs more, it's either two points (split) or over-explained (compress).
- Are there multi-tier comparison tables (>5 rows, >4 columns)? Replace with a single-sentence synthesis — the full table belongs in the source document, not the wiki.
- Are there code blocks >5 lines? Delete them — describe the design intent. The code lives in the source file; the wiki should not duplicate it.
- Are there risk matrices, migration timelines, rollback plans, or verification tables? These are execution appendices, not reusable knowledge — remove them.

### 4.4 Noise Check
- Re-read the source material in your mind. Did you include: tangential anecdotes? repeated emphasis of the same point? marketing language? ecosystem-specific tool/plugin recommendations? (remove all)
- If unsure whether something is noise, flag it under `## Notes` with `> **待确认:** ...` rather than including it in main text.

### 4.5 Cross-Reference Check
- For every recommended page, identify at least 1 existing wiki page it should link to via inline body links. If none exists, explain why.
- All cross-reference paths are wiki-root-relative and domain-prefixed (e.g. `foo/concepts/bar.md` NOT `wiki/foo/concepts/bar.md`).
- **Inline links in page body:** each independent reading entry point (a section reachable via search or TOC) should have at least one link to each referenced concept. Short pages need only first occurrence.
- **Verify no duplicate inline links:** after adding the first-occurrence link, scan the rest of the page body and remove any additional inline links to the same target — only the first occurrence in each independent section should carry a link.
- **Link sentence style:** every inline link must be a grammatical component of its sentence (subject, object, or attributive), and the sentence itself must convey why the target is relevant. Never append bare pointers like 「……见[X]」 or 「（见[X]）」 — a reader who doesn't click should still know why the page matters. Prefer making the linked page the subject: 「[X]展开了工具边界与评估闭环」.
- **Anchor precision:** each link target must be the concept's home page — the page whose topic IS that concept. Do not link a narrow term to a broad parent page (e.g. link 「上下文资源」 to context-rot, not context-engineering, when the semantics is "context is a finite resource"). If the precise home page doesn't exist, consider proposing its creation (see 4.2 reverse check) rather than settling for a loose anchor.
- **References is not a substitute:** the References section lists sources; it does not fulfill the inline-link requirement. A concept mentioned in the body must still be linked at first occurrence in the body, even if the same page appears in References (`zwiki check`'s term scan flags missing body links).

### 4.6 Self-Deletion Check

Before moving to Phase 5, answer these three questions for EVERY recommended page:

- **"Could a reader who forgot the context, six months from now, find the 'why this page exists' anchor in 10 seconds?"** — If not, the Overview is too vague. Rewrite it.
- **"Is there any subsection that exists only because the source had it, not because the wiki genuinely needs this information?"** — If yes, delete it. "The source mentioned it" is not a reason to keep it.

From 418-teapot/ZooKeeper, MIT.

More from 418-teapot/ZooKeeper