Skip to content

Best Practices

Jump to bottom
Chris Sweet edited this page Jul 14, 2026 · 3 revisions

type: synthesis up: "What-is-the-llm-wiki-Template" supports: "Template-Philosophy" related:

Best Practices

How to get real value out of the template rather than a decorative wiki. Grounded in the SCHEMA's "When to Update / When NOT to Update" rules, the agent-agnostic discipline and verification gates, and the vision wiki's authoring guidance on capturing expertise and experience.

What content belongs in the wiki?

Durable understanding that a future session or teammate would benefit from: experiment results (configuration, metrics, what changed, what surprised you), decisions with stated reasons, reusable syntheses, source summaries, and contradictions of prior claims. The rule from the generated CLAUDE.md: write whenever significant work produces something worth knowing later. Good query answers count too, file a reusable analysis back as a page so explorations compound.

What content should stay out of the wiki?

Per the SCHEMA's "When NOT to Update": routine debugging or code fixes (git history is enough), temporary analysis you will not reference again, and speculative plans that have not been executed. Also keep out anything that must not live in a shared, versioned artifact: secrets, credentials, and private personal data. If it belongs in git history, a ticket, or a scratch file, it does not belong in durable memory.

How often should I commit? Should I let the LLM commit for me?

Commit every wiki edit; the wiki is only durable memory if the commit closes the loop. The template's guidance is explicit that the agent commits without asking, because local commits in the wiki sub-repo are trivially reversible. The discipline: run the verification gate, then commit pages and index as one commit, and the log entry as its own separate commit (one commit per log entry). Letting the LLM commit is the intended default; you review the diff, not the mechanics.

Should I push the wiki, or keep it local until published?

Keep it local by default. The template convention is that pushes are explicit: the human asks, or the agent asks first. Commit freely (local and reversible); push only when you intend to publish. When you do push, use the write protocol rather than a plain git push (see Team-Workflow).

How do I organize pages when the wiki gets larger?

Lean on the index categories and up: hierarchy. As a category accumulates pages, it becomes a natural cluster; promote a repeatedly-mentioned concept to its own page rather than letting it live scattered across bodies. Let hubs emerge (heavily-linked pages) and use them as entry points. Keep the Home page's ## Categories section curated as top-level categories appear. See Wiki-Structure-and-Conventions.

When should I use extends: versus related:?

Use the most specific edge you can justify; treat related: as the fallback. extends: means intellectual lineage: this page builds on, refines, or continues the target's content, and traversing it licenses the agent to inherit the parent's claims as background. related: carries no operation contract; it just says "connected somehow." The vision wiki makes the honest counterpoint: when a note is written mid-work and the specific relation is genuinely uncertain, related: is the correct choice, forcing extends:/supports:/criticizes: manufactures crispness the material does not have. So: specific when you are sure, related: when you are not, and revisit during lint.

Is aggressive typed-edge discipline worth the effort for my project?

It depends on the wiki's content shape, per the vision wiki's experimental-vs-review distinction. Bibliographic/review wikis (each page a paper; papers cite, support, and contradict each other) are objectively typeable, so aggressive typing pays off: SPARQL over the graph answers real questions. Experimental/research wikis (speculative, provisional, in-progress) are where forcing crisp types backfires and downstream queries return over-confident results. Match the discipline to the material rather than typing everything maximally on principle.

How do I document a failed experiment honestly?

File it truthfully, not polished. The verification gate and discipline gates are built around exactly this: bad results, contradicted claims, and worsened metrics get filed plainly, with no "needs more investigation" hedge that hides a real negative result. Never report a number from a projection; only from a real script output, and tag every number with its corpus/configuration scope. A failed experiment that is honestly recorded saves a future session from repeating it, which is one of the highest-value things the wiki captures (the experience layer from Template-Philosophy).

How do I record decisions so my future self can find them?

Use a type: decision page. The SCHEMA requires: Question, Options considered (with pros/cons), Decision, Rejected alternatives (and why), Revisit triggers, plus a decided_at: date. Recording the rejected alternatives and the conditions that should re-open the choice is what makes the decision useful later, not just the choice itself.

How do I keep the wiki healthy over months of use?

Run lint periodically (see below), commit and cross-reference as you go rather than "later" (the discipline gates name "I'll add the cross-reference later" as a rationalization that is always wrong), and update or flag pages when new work contradicts them rather than letting contradictions sit. Health is a byproduct of not deferring the bookkeeping, which is exactly the work the LLM is good at doing immediately.

Should I let the LLM auto-write pages, or approve every one?

Either works; it is a workflow choice. llm-wiki.md describes the author's own preference (ingest one source at a time, stay involved, read the summaries) but also notes you can batch-ingest with less supervision. The proactive default in the template is that the agent writes and commits without asking. For high-stakes or shared bundles, review each page; for a fast personal deep-dive, let it run and review in batches. The commits are reversible, so the cost of over-delegating is low.

How do I review LLM-authored content critically?

Read for the failure modes the discipline gates name: projection presented as measured fact, numbers without a corpus tag, cross-corpus comparisons stated as direct gaps, missing back-references, and contradictions papered over. Check that typed edges reflect relationships that actually hold. Trust current code and results over any wiki claim; if a page conflicts with what you observe now, flag the stale page rather than repeating it. The verification gate is the checklist; you are the second reader.

How do I capture expertise and experience, not just facts?

Facts fall out of ingest by default; expertise and experience take deliberate prompting. The vision wiki's authoring checklist, per page: knowledge check (are the facts and citations right?), expertise check (is my judgment visible, did I record why I chose this framing, are the typed edges honest?), experience check (are the concrete cases attached, did I log what I tried and what surprised me?). The experience check is the one most often skipped and the biggest opportunity. Synthesis pages, decision records, "considered and rejected" notes, and dated log entries with reasoning are where these two layers live.

Do I need to run lint regularly, and when?

Yes, but incrementally. The lint skill's guidance: run it every several sessions, when the wiki has grown by roughly ten or more pages since the last pass, after a major ingest that touched many pages, or whenever you notice a broken link or contradiction. Lint is not all-or-nothing; fix the findings that matter this pass and file a log entry describing what was cleaned. See Everyday-Operations.

See also

Clone this wiki locally