vitya
93a37f9aa5
Extends Karpathy LLM Wiki canon with two new artifact types alongside existing entities/concepts/packages/sources. Inspired by community discussion that highlighted explicit tracking of surfaced tensions and unanswered questions as missing aggregation points in the canonical layout — they currently get scattered into concepts/ or lost in log.md. Scope is schema-level only — no new ingest behaviour prescribed. Policy on when to escalate an inline `> **Противоречие:**` flag into a contradictions/<slug>.md page (and the analogous flow for open-questions) stays the user's call. setup-wiki [v1.0.0 → v1.1.0, MINOR — additive page types]: - Discovery (Phase 1) now requires 6 content dirs for `noop` mode - Phase 2 plan blocks list new dirs in greenfield + migrate - CLAUDE.md schema template gains two page-type entries with status enums (contradictions: open|resolved|accepted-divergence; open-questions: open|answered|obsolete) - index.md template gains two empty sections - Phase 4a .gitkeep list, Phase 4b mkdir + touch, Phase 5 verify count (four → six dirs), Phase 6 report count all updated - README.md layout tree + content-dirs sentence using-wiki [v1.0.0 → v1.1.0, MINOR — additive type values]: - Prerequisites: four → six content directories - Page frontmatter type enum: + contradiction | open-question - Per-type frontmatter extensions documented (status + affects/touches) - File naming patterns: + contradictions/<slug>.md, open-questions/<slug>.md - index.md sections-by-type list updated - README.md mirrors SKILL.md changes dist/: setup-wiki.skill + using-wiki.skill rebuilt. project-bootstrap inline reference block intentionally untouched — it's labelled "Reference (for context only — setup-wiki is the source of truth)" and drift-tolerant by design. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
183 lines
6.3 KiB
Markdown
183 lines
6.3 KiB
Markdown
# using-wiki
|
||
|
||
Runtime policy for an LLM Wiki built on the
|
||
[Karpathy LLM Wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f).
|
||
Knowledge is **compiled once and kept current** across three layers, via
|
||
three named operations, with strict file formats that keep the wiki
|
||
parseable and grep-friendly.
|
||
|
||
`using-wiki` governs *usage* of an existing `.wiki/`. Initial creation and
|
||
migration to canon are owned by [`setup-wiki`](../setup-wiki/).
|
||
|
||
> Renamed from `wiki-maintainer` at v1.0.0.
|
||
|
||
## When it triggers
|
||
|
||
- User says: "use project wiki", "query the wiki", "ingest this", or the
|
||
Russian equivalents ("обнови вики", "проверь вики", "запроси вики",
|
||
"заингесть").
|
||
- Any time the agent modifies a file under `.wiki/` — the workflow and
|
||
formats below are mandatory.
|
||
- If `.wiki/` is missing or non-canonical, this skill delegates to
|
||
[`setup-wiki`](../setup-wiki/) before doing anything else.
|
||
|
||
## Three layers (do not blur)
|
||
|
||
1. **Raw sources** — `.wiki/raw/` (or external paths registered in
|
||
`raw/README.md`). **Immutable.** Read, never edit. The only exception is
|
||
appending a `> Status` blockquote when the user explicitly asks for a
|
||
status audit.
|
||
2. **Wiki** — everything else under `.wiki/`. Agent-owned. Entity / concept /
|
||
package / source summary pages.
|
||
3. **Schema** — `.wiki/CLAUDE.md`. Project-specific conventions (what
|
||
entities, what packages, naming). Always read it first; it overrides this
|
||
skill on conflict.
|
||
|
||
## Three operations
|
||
|
||
### Ingest
|
||
|
||
«заингесть X» — pull a raw source into the wiki.
|
||
|
||
1. Read the raw source fully.
|
||
2. Extract: entities, concepts, packages, cross-cutting patterns.
|
||
3. Create `sources/<slug>.md` (one summary page per source, ~50–150 lines).
|
||
4. For each affected entity / concept / package page: update if exists,
|
||
create if not. Flag contradictions explicitly with
|
||
`> **Противоречие:** источник A говорит X, источник B — Y`.
|
||
**Never silently overwrite.**
|
||
5. Update `index.md`.
|
||
6. Append one line to `log.md`.
|
||
7. Report: what was created, updated, contradicted.
|
||
|
||
One ingest may touch 10–15 pages. That's normal — that's why an LLM does it.
|
||
|
||
### Query
|
||
|
||
A question answered from the wiki.
|
||
|
||
1. Read `index.md` first, drill into relevant pages.
|
||
2. Answer with citations as markdown links.
|
||
3. **Compound the wiki.** If the answer is a real synthesis, ask the user:
|
||
"Сохранить как страницу wiki?" Good queries become durable pages under
|
||
`concepts/` or `analyses/`.
|
||
4. Append one line to `log.md`.
|
||
|
||
### Lint
|
||
|
||
«проверь wiki» — health check.
|
||
|
||
Scan for:
|
||
|
||
- Contradictions between pages.
|
||
- Orphans (pages with no inbound links).
|
||
- Stale claims (raw source updated after the summary's `ingested:` date —
|
||
check via `git log -p`).
|
||
- Concepts mentioned in prose but missing their own page.
|
||
- Empty / TODO sections.
|
||
|
||
Report as a punch list. Don't delete anything automatically. Append one
|
||
line to `log.md` with the findings.
|
||
|
||
## File formats (mandatory)
|
||
|
||
### Page frontmatter
|
||
|
||
```yaml
|
||
---
|
||
title: Человекочитаемое имя
|
||
type: entity | concept | package | source | contradiction | open-question | overview
|
||
tags: [short, tokens]
|
||
sources: [../sources/foo.md, ../sources/bar.md]
|
||
updated: 2026-04-21
|
||
---
|
||
```
|
||
|
||
Source pages also carry `ingested: YYYY-MM-DD` and `raw_path: ../raw/...`.
|
||
Contradiction pages also carry `status: open | resolved | accepted-divergence` and `affects: [../entities/x.md, ../concepts/y.md]`.
|
||
Open-question pages also carry `status: open | answered | obsolete` and `touches: [../entities/x.md, ../sources/z.md]`.
|
||
|
||
### File naming
|
||
|
||
- `kebab-case.md`, **Latin only**. Transliterate Cyrillic / non-Latin in
|
||
filenames; keep the original title in H1 + frontmatter.
|
||
- `entities/<name>.md`, `concepts/<name>.md`, `packages/<name>.md`
|
||
(no `@org/` prefix), `sources/<slug>.md`, `contradictions/<slug>.md`,
|
||
`open-questions/<slug>.md`.
|
||
|
||
### `log.md` — append-only, grep-parseable
|
||
|
||
Every entry must start with:
|
||
|
||
```
|
||
## [YYYY-MM-DD] <operation> | <short description>
|
||
```
|
||
|
||
Operations: `ingest`, `query`, `lint`, `refactor`, `decision`, `init`.
|
||
|
||
Parse with: `grep "^## \[" .wiki/log.md | tail -20`.
|
||
|
||
### `index.md`
|
||
|
||
Catalog, not narrative. One line per page: `- [Title](path) — hook.`
|
||
Sections by type. Update on every ingest.
|
||
|
||
### Cross-references
|
||
|
||
- Wiki → wiki: relative markdown links — `[Name](../entities/x.md)`.
|
||
- Wiki → code: relative path from repo root — `[foo.js](../../packages/api/foo.js)`.
|
||
- Wiki → raw: `../raw/<file>`.
|
||
- URL-encode spaces (`%20`) and Cyrillic when needed.
|
||
|
||
## Quick reference
|
||
|
||
| Situation | Files touched |
|
||
|---|---|
|
||
| Ingest one doc | `sources/<slug>.md` (new) + 3–15 entity/concept/package pages + `index.md` + `log.md` |
|
||
| Query | (read only) + optionally a new wiki page + `log.md` |
|
||
| Lint | (read only) + `log.md` |
|
||
| Bootstrap / migrate | (delegated to [`setup-wiki`](../setup-wiki/)) |
|
||
|
||
## Common mistakes
|
||
|
||
- **Editing `raw/`.** Don't. Only allowed change: status blockquote on
|
||
explicit request.
|
||
- **Dumping raw content into `sources/`.** Summaries are summaries. Link to
|
||
raw, don't copy.
|
||
- **Silent overwrites on contradictions.** Flag them with a `> **Противоречие:**`
|
||
block.
|
||
- **Narrative `log.md`.** "Today I added…" is wrong. Use
|
||
`## [YYYY-MM-DD] ingest | <what>`.
|
||
- **Non-ASCII filenames.** Breaks greppability and cross-platform. Transliterate.
|
||
- **Forgetting `index.md`.** Pages not listed there are invisible to future
|
||
queries.
|
||
- **Improvising layout when canon files are missing.** Hand off to
|
||
[`setup-wiki`](../setup-wiki/) instead of patching ad-hoc.
|
||
|
||
## When NOT to use
|
||
|
||
- The project has CLAUDE.md / AGENTS.md docs but no `.wiki/` — that's regular
|
||
documentation, not an LLM Wiki.
|
||
- The user wants a single-file README or ADR — this skill is for persistent,
|
||
interlinked knowledge bases.
|
||
- One-off questions about code — read files directly, no wiki workflow needed.
|
||
|
||
## Install
|
||
|
||
From the repo root:
|
||
|
||
```bash
|
||
bash scripts/install.sh using-wiki
|
||
```
|
||
|
||
Works on Windows under git-bash, Linux, macOS.
|
||
|
||
## See also
|
||
|
||
- [`setup-wiki`](../setup-wiki/) — companion, owns `.wiki/` creation and
|
||
canon migration.
|
||
- [`project-bootstrap`](../project-bootstrap/) — invokes `setup-wiki` for
|
||
new projects.
|
||
- Karpathy's LLM Wiki gist:
|
||
<https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f>
|