wiki-generation

name	wiki-generation
description	Generate or update formal wiki notes from one `.cache/source-id-analysis.md` handoff document.

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.

2. Decide the edit scope. Separate the work into:

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

3. 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

4. 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

5. 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

6. 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.

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

8. 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/