crystallize

name: crystallize description: > Distil a session into durable wiki pages — extract decisions, findings, and open questions into concept or query-result pages. type: skill status: active last_updated: "2026-04-27" when_to_use: > Preserving session knowledge — decisions reached, patterns discovered, questions resolved, or design rationale established. Propose crystallization when a session produces durable knowledge; always confirm with the user before writing. tags: [crystallize, session, knowledge-capture] owner: jguibert@gmail.com metadata: version: "0.3.0"

Crystallize

Distil a session into durable wiki pages. Valuable knowledge emerges from conversations — decisions reached, patterns discovered, questions resolved. Without crystallization, this knowledge disappears when the session ends.

What to capture

Keep: decisions made, patterns established, lessons learned, open questions, current understanding, key findings, agreed frameworks, design rationale.

Discard: exploratory back-and-forth, dead ends, process chat, superseded drafts, corrections already incorporated.

The output is always significantly shorter and more structured than the input. Crystallize distils — it does not transcribe.

When to crystallize

• A decision was reached → crystallize the decision and rationale
• New knowledge was absorbed → crystallize into a concept page
• A question was resolved → update the page that had the open question
• A design was settled → crystallize into a query-result or concept
• The chat is getting heavy → crystallize before context degrades
• Closing a long thread → crystallize everything worth keeping

Search for an existing home

Before creating anything new, orient with the full wiki map:

wiki_list(format: "llms")

This produces all pages grouped by type with summaries — a complete map in a single call. Use it to identify existing pages that may cover the same ground, then search for candidates:

wiki_search(query: "<topic>")

If a concept page, section index, or prior query-result already covers this ground, prefer updating it over creating a new page.

Read candidates to check scope:

wiki_content_read(uri: "<candidate-slug>")

Analyse before writing

Before creating or updating any page, produce a concise extraction plan.

For each item of durable knowledge in the session, note:

• What — one sentence describing the knowledge
• Type — decision, finding, pattern, open-question
• Action — create <type> <slug>, update <slug>, or discard
• Confidence — estimated score (see calibration table below)

Example plan output:

1. tantivy fast fields require f64 not f32 (finding) → create concept tantivy-fast-field-types [0.85]
2. tweak_score replaces post-retrieval sort (decision) → create query-result search-ranking-tweak-score [0.9]
3. design-03 needs to depend on design-04 (decision) → update query-result improvements-ordering [0.8]
4. explored renaming ops module (dead end) → discard

Present the plan to the user and confirm before writing. This keeps the user in control and prevents the session from producing redundant or misclassified pages.

Confidence calibration for session knowledge

These ranges are starting points. Adjust up when the session provided strong evidence (code confirmed to work, multiple independent sources); adjust down when the conclusion was tentative or context-specific.

The default when no calibration applies is 0.5 (neutral — present but unreviewed). Never leave confidence absent on session-derived pages: the lint rule will flag them as stale if they stay at default for long.

Create a new page

When no existing page fits, use type: query-result for session conclusions or type: concept for synthesized knowledge.

Get the frontmatter scaffold:

wiki_schema(action: "show", type: "query-result", template: true)

Create and write:

wiki_content_new(uri: "<slug>", type: "query-result")
wiki_content_write(uri: "<slug>", content: "<full markdown>")

Set sources to the source pages that contributed claims, concepts to the concept pages discussed. These create typed graph edges (fed-by and depends-on).

Update an existing page

Respect the accumulation contract:

1. Read the current page: wiki_content_read(uri: "<slug>")
2. Preserve existing list values (tags, read_when, sources, concepts, claims) — add, do not replace
3. Update scalar fields (summary, tldr, confidence) only with clear reason
4. Write the complete file:

wiki_content_write(uri: "<slug>", content: "<updated markdown>")

Validate and index

Dry-run to catch errors (including edge target type mismatches):

wiki_ingest(path: "<path>", dry_run: true)

Then ingest for real:

wiki_ingest(path: "<path>")

Check structural quality

After ingest, run the engine lint for the pages just written:

wiki_lint(rules: "broken-link,orphan")

This catches:

• Dead references in sources, concepts, or body wikilinks introduced by the new pages
• Orphan pages if the new page was not linked from anywhere

Fix any Error findings before closing the session. Warning findings (orphan on a newly created standalone page) can be deferred.

Note: wiki_lint ships with engine v0.2.0. If the command is not recognized, skip this step and follow the lint skill manually for broken-link and orphan checks.

Verify

Confirm the knowledge was captured correctly:

wiki_content_read(uri: "<slug>")

Check graph edges are connected as expected:

wiki_graph(root: "<slug>", depth: 1)

Suggest links for the new page:

wiki_suggest(slug: "<slug>")

Suggested body structure

Adapt to the content — not every section is needed: