vintlin/zettelkasten/wiki-generation

Wiki Generation

This skill reads one analysis handoff document and completes the note-compilation pass.

Read First

• references/generation-rules.md

Input And Output

• Input: one .cache/<source-id>-analysis.md
• Output:
• created or updated notes under wiki/
• processing report at outputs/processing/<source-id>-report.md
• archived source under archive/
• archived analysis under archive/.cache/

Workflow

1. Load one handoff artifact.

Treat .cache/<source-id>-analysis.md as the direct input. Reopen the raw source only if the handoff is clearly insufficient.

1. Decide the edit scope.

Separate the work into:

• permanent notes
• reference notes
• argument notes
• structure notes

1. Write or update permanent notes.

• One reusable claim, distinction, method, step, or question per note
• Check whether each candidate repeats, extends, corrects, narrows, or challenges an existing permanent note before creating a new file
• Update an existing permanent note when the source adds clearer wording, stronger evidence, a caveat, an example, a correction, or a source link for the same reusable claim
• Create a new permanent note only when the candidate carries a distinct claim, method, distinction, question, or role in an argument chain
• Keep ## Summary and ## Note
• Preserve important links and needed images
• Use Markdown emphasis when it materially improves readability
• Turn raw candidate note units from the analysis file into formal permanent notes

1. Write or update reference notes.

Create or update wiki/reference-notes/ only for stable named items such as books, frameworks, methods, models, acronyms, or long-lived coined terms. Treat each reference note as a source-context anchor for a named object, not as an entrance note, argument container, or摘抄堆. Use it to preserve:

• what the named object is
• where it comes from
• its core definition, components, and boundaries
• which permanent notes are distilled from it

1. Place notes into argument notes.

• Judge from argument fit first
• Insert notes into existing chains when possible
• Create a new argument note when needed
• Use broad parent-question or meta-claim titles
• Prefer short, natural parent-question titles; keep the title simpler than the summary
• Keep titles natural but still conceptually precise; do not overcorrect into chatty or overly colloquial wording
• Allow branches or --- segmentation when the reasoning should not be forced
• argument-notes only connect upward to structure-notes and downward to permanent-notes
• Do not create argument -> argument links as a substitute for merging or insertion
• In each evidence item, explain the note's role in the chain directly
• Do not use filler transitions such as “上一条已经…”, “接着”, or “然后”
• Write argument-note summaries as direct conclusions, not as self-referential introductions about what the note is doing
• Do not begin summaries with low-information scaffolding such as “这条论点笔记回答的问题是：”, “回答：”, “这条链处理……”, or similar template phrasing
• This step owns the final decision about insertion order, branch shape, and supports / next structure
• Treat analysis-file argument matches as candidates, not as final placement
• If no existing argument fits, create or revise an argument note in the same pass
• Treat each argument note as one stable parent question or parent claim with a readable reasoning chain, not as a topic bucket or note container
• Put scope qualifiers, edge cases, and narrowed conclusions into ## Summary and ### 论据, not into the title unless they are the irreducible core of the parent question
• Title the note as a question a real person would naturally ask, not as an internal analysis label or compressed explanation
• Prefer direct, human wording such as 如何提升编程能力？, 如何沉淀经验？, 创作如何发生？, 如何提升作品的传播度？
• Avoid double-question titles such as 为什么要学X，以及X能力如何长出来？; prefer the shorter parent question and move the other half into ## Summary
• Avoid definition-plus-comparison titles such as 什么是X，X与Y有何不同？; prefer the core definition question and let the comparison become supporting evidence
• Avoid explanatory endings such as 如何…真正长出来, 如何…稳定沉淀, 如何…并被约束, 如何…并形成…, 如何…并提高… when the simpler question is still the same question
• Avoid abstract mechanism names such as 飞轮, 闭环, 框架, 模型, 可操作性层级, 系统设计与维护边界 as titles unless that mechanism name is itself the exact object under discussion
• If the title sounds like a sentence written by the analyst rather than a question asked by the reader, rewrite it

1. Attach argument notes to structure notes.

Every new or updated argument note must be linked from at least one relevant wiki/structure-notes/. structure-notes only collect argument-notes; do not link them to other structure-notes or permanent-notes. Decide structure placement only after the final argument shape is stable. Treat each structure note as a theme note: define the theme boundary, state what it covers and excludes, and list the few argument notes that are the correct entry paths.

1. Write the processing report.

Write outputs/processing/<source-id>-report.md. Include review blocks only for issues that cannot be resolved stably.

1. Finalize archival state.

• move the processed source into archive/
• move .cache/<source-id>-analysis.md into archive/.cache/
• create archive/.cache/ when needed

Hard Rules

• Do not create orphan permanent notes.
• Do not create a new permanent note when an existing note can be updated without losing a distinct claim or argument role.
• Do not leave new argument notes unattached to the structure layer.
• Do not attach structure-notes to other structure-notes.
• Do not attach structure-notes directly to permanent-notes.
• Do not leave any permanent-note without at least one argument-note target; if no fit exists, create or revise an argument note in the same pass.
• Do not treat source-analysis candidate links as final chain instructions.
• Do not use narrow process-description titles for argument notes.
• Do not use unnatural, over-explained, or analysis-jargon argument titles.
• Do not treat argument notes as topic buckets or unordered note piles.
• Do not treat structure notes as portal pages, cross-link hubs, maintenance scratchpads, or raw note indexes.
• Do not silently drop source links, citations, or useful images.
• Do not use wiki/reference-notes/ as an entrance layer.
• Do not use natural-language reference labels such as 来源文件：, 来源链接：, or 主题来源：; normalize to from / references / url.
• Do not use related_pattern or other pseudo-structural link labels inside reference-notes.

Completion Test

The pass is complete only when:

• wiki notes are updated as needed across permanent / reference / argument / structure layers
• new notes are placed into argument chains
• affected argument notes are attached to structure notes
• source provenance remains visible
• outputs/processing/<source-id>-report.md exists
• the processed source has moved to archive/
• the completed analysis file has moved to archive/.cache/