99 lines
4.4 KiB
Markdown
99 lines
4.4 KiB
Markdown
---
|
|
name: wiki-compile
|
|
description: >
|
|
Idempotent wiki source compilation — drain pending raw sources into the wiki.
|
|
Use when the cron drain goal fires or the user explicitly says "compile now" / "zkompiluj".
|
|
Handles duplicate detection, ambiguous sources, idempotent skip, and graph regeneration.
|
|
Do NOT trigger on a plain "add this to my wiki" request — that is capture-only (see llm-wiki skill).
|
|
---
|
|
|
|
# Wiki Compile
|
|
|
|
Idempotent compile of pending raw sources into the LLM wiki. Runs as a background drain (cron) or on explicit user request ("compile now" / "hned").
|
|
|
|
## When to use
|
|
|
|
- Cron drain goal fires (background batch compile)
|
|
- User explicitly requests synchronous compile ("compile now", "zkompiluj wiki", "do it now")
|
|
- **NOT** for plain "add this" / "save this" requests — those are capture-only (write to `cml/raw/`, stop)
|
|
|
|
## Prerequisites
|
|
|
|
- Wiki must be initialized (`cml/wiki/SCHEMA.md` exists)
|
|
- Read `SCHEMA.md` first — it defines page types, naming rules, and ingest customizations
|
|
- Read `index.md` to know what pages already exist
|
|
|
|
## Steps
|
|
|
|
### 1. List pending sources
|
|
|
|
Scan `cml/raw/` for regular `.md` files (ignore `_done/`, `_hard/`, `assets/` subdirectories).
|
|
|
|
If empty → nothing to do, stop.
|
|
|
|
### 2. Batch all pending sources
|
|
|
|
Process **all** pending sources in one batch — one index/graph update for many sources is more efficient than one-by-one.
|
|
|
|
### 3. For each source, check idempotency
|
|
|
|
Read the source slug from the filename (e.g., `cml/raw/my-source.md` → slug `my-source`).
|
|
|
|
Check if `cml/wiki/sources/<slug>.md` already exists:
|
|
- **Exists** → already compiled. Move `cml/raw/<slug>.md` to `cml/raw/_done/`, skip re-processing, log "skip (already compiled)".
|
|
- **Does not exist** → proceed to duplicate check.
|
|
|
|
### 4. Duplicate URL detection
|
|
|
|
If the source content is a URL (single-line URL or frontmatter `url:` field), check whether any existing source page in `cml/wiki/sources/` already references that same URL:
|
|
- **Duplicate found** → move the raw file to `cml/raw/_hard/`, append entry to `log.md` noting "duplicate URL — same as <existing-slug>", skip compilation.
|
|
- **No duplicate** → proceed to ambiguous/conflict check.
|
|
|
|
### 5. Ambiguous / conflicting source check
|
|
|
|
If the source content is unclear, contradictory, or cannot be reliably summarized (e.g., garbled text, empty content, conflicting metadata):
|
|
- Move to `cml/raw/_hard/`
|
|
- Append entry to `log.md` with reason (e.g., "ambiguous — garbled content", "conflicting — title mismatch")
|
|
- Skip compilation
|
|
|
|
### 6. Compile the source
|
|
|
|
Follow the standard ingest workflow (see `references/ingest-workflow.md` in the llm-wiki skill):
|
|
|
|
1. Read the source (chunked if large)
|
|
2. Write a source-summary page at `cml/wiki/sources/<slug>.md` with full frontmatter and citations
|
|
3. Identify existing entity/concept pages this source touches → surgically update relevant sections
|
|
4. Create new entity/concept pages for novel topics, linking from related pages
|
|
5. Update `index.md` (or relevant shard) with new pages
|
|
6. Append a single line to `log.md`: date, operation, source title
|
|
|
|
### 7. Move processed source
|
|
|
|
After successful compilation, move `cml/raw/<slug>.md` to `cml/raw/_done/`.
|
|
|
|
**Every source must leave `cml/raw/`** — either `_done/` (success/skip) or `_hard/` (held back). Never leave a source in the inbox after processing.
|
|
|
|
### 8. Regenerate graph (if applicable)
|
|
|
|
If the wiki has a graph layer (`cml/wiki/graph/ontology.yaml` exists) and this batch added any pages with `graph:` frontmatter metadata:
|
|
|
|
```bash
|
|
uv run skills/llm-wiki/scripts/wiki_graph_lint.py cml/wiki/
|
|
uv run skills/llm-wiki/scripts/wiki_graph_extract.py cml/wiki/
|
|
```
|
|
|
|
If no graph layer exists, skip this step entirely.
|
|
|
|
### 9. Summary
|
|
|
|
Report what happened in one concise line, e.g.:
|
|
- "Compiled 3 sources, skipped 1 (already done), held 1 (duplicate URL)."
|
|
- "Nothing to compile — inbox empty."
|
|
|
|
## Key rules
|
|
|
|
- **Idempotent**: re-running on the same source is a no-op (skip + move to `_done/`)
|
|
- **No force-compiling ambiguous sources**: move to `_hard/` and log why
|
|
- **Batch efficiency**: one index update + one graph regeneration per batch, not per source
|
|
- **Graph scripts require wrapper**: if workspace safety guard blocks direct execution, write a `tmp/` wrapper script using `uv run --script` with inline dependency metadata
|
|
- **Language**: wiki content is in Czech; compile output and log entries may be in English for consistency with existing logs |