| name | wiki-init |
| description | Bootstrap a hallouminate wiki from scratch by interviewing the user with Socratic questioning, then writing the first entries. Use when a repo has no wiki yet or the corpus is near-empty — "start a wiki", "bootstrap the knowledge base", "interview me about this project", "set up the wiki", "/wiki-init". Do NOT use to answer questions (use wiki-query) or to fold new source docs into an existing wiki (use wiki-ingest). |
wiki-init — Socratic bootstrap of a hallouminate wiki
Turn what's in the user's head into a structured, searchable wiki. The hard part is
elicitation — experts can't introspect tacit knowledge on demand, so you ask
about behavior in concrete situations and extract the model from their answers.
Agent topology (required):
- Root = opus-tier (the strongest model the harness offers). Runs the interview,
holds the dialogue history, decides the page
taxonomy, and extracts answers into structured slots. All reasoning lives here.
- Fan-out = haiku-tier (the cheapest model). Once topics are captured, one
sub-agent per planned page drafts
the entry and calls
add_markdown. Drafting is mechanical formatting of slots the
root already gathered — cheap, parallel, isolated.
The root interviews; it does not draft pages itself. Haiku drafts; it does not
interview. Never invert.
Phase 1 — Interview (root / opus)
Semi-structured beats both a rigid script and open rambling. Move
unstructured → semi-structured → structured: open wide to learn the domain's
vocabulary, then tighten to fill gaps.
Rules of the interview:
- One question per turn. Multiple questions → the user answers the easiest and
drops the rest.
- Behavior-first, not knowledge-first. "What do you know about X?" fails. Ask
"walk me through what you do when X happens" and extract the model from the story.
- Internal slots, open phrasing. Track slots (
purpose, components,
constraints, gotchas, decisions/why, edge-cases) silently. Never say the
slot name — ask "what would break this?" not "what are the constraints?".
- Don't repeat. Keep dialogue history; suppress questions overlapping an
already-filled slot.
- No leading questions. Don't smuggle the answer into the question.
ACTA sequence (the practical spine):
-
Task diagram — first, scope it: "Break this project into more than three but
fewer than six major areas — what are they?" This sets the page list without
premature detail.
-
Knowledge audit — per area, probe with the high-yield question types:
| Probe | Asks for | Example |
|---|
| Tour | the mental model | "Walk me through how X works here." |
| Taxonomic | categories | "What kinds of Y are there?" |
| Reason-seeking | rationale | "Why this way and not the obvious alternative?" |
| Constraint | non-obvious limits | "What can go wrong? What breaks it?" |
| Counterfactual | edge cases | "What if [current condition] weren't true?" |
| Consistency | contradictions | "Earlier you said X — does that fit with Y?" |
| Elaboration | depth | "Tell me more about that." |
-
Simulation — for tricky areas: "Imagine situation Z lands — what do you do,
and why?" Surfaces decision logic direct questions miss.
Chain the questions. Derive each next question from the prior answer — pick one
thread to deepen, park the others, come back. Stop an area when probes stop
yielding new slots; stop the session when the user signals done or the task diagram's
areas are all covered.
After each exchange, extract what was said into a structured slot record (keep it in
your working notes), separating what was said from how it'll be written.
Phase 2 — Plan the taxonomy (root / opus)
- One topic per file, kebab-case slug, first line
# Title (the chunker uses the
H1 as the breadcrumb root and the index gloss).
- Top-level files for foundational topics (
architecture.md, mcp-surface.md);
subdirectories for clusters (adapters/lance.md). The daemon creates dirs and
maintains each index.md link list for you.
- Shape every page on the pack's formal entry template
(
../../templates/wiki-entry.md from this skill's directory): lifecycle
frontmatter, H1 first, footnote citations, provenance footer.
- Write a
wiki-conventions.md first (the wiki's constitution): slug rules, the
H1 rule, one-topic-per-file, the voice, and a provenance-footer convention
(_Source: <how we know this> · Updated: <date> · Supersedes: <if any>_). Declare
the Supersedes: field here so wiki-ingest writes and reads one key. Also declare
the two ingest-ledger conventions so wiki-ingest reads and writes one shape:
log.md — an append-only ingest journal at the corpus root under a stable
## Log heading. wiki-ingest appends one row per decision via
an add_markdown append (corpus, path: "log.md", under_heading: "Log", position: "append", content: <row>); it is never
rewritten and never a routing/merge target.sha256sum source-hash ledger — wiki-ingest's Layer-1 dedup hashes each
normalized source (sha256sum, first 16 hex chars) and records the id in log.md;
a ledger hit skips the whole source. Note the hash convention here so the id format
is stable across ingests.
Also declare the local-link rule: links must resolve inside the corpus. A
link target that is a local file outside the corpus root gets copied into the
corpus first (add_markdown, e.g. sources/<slug>.md) — or into another
corpus declared in config if it belongs elsewhere — and the link rewritten
corpus-relative. Web URLs pass through; code is cited as path:line text,
never linked or copied.
Later skills (wiki-ingest) read all of this to stay consistent.
- Pick the corpus:
repo:{name}:wiki for the repo, or ask if ambiguous
(list_corpora). Confirm the page list with the user before fanning out.
Phase 3 — Fan out drafts (haiku, parallel)
Spawn one haiku sub-agent per planned page, in a single message, each with:
- the slug + path, the H1 title, and the slot record for that topic,
- the
wiki-conventions.md rules,
- this contract:
Draft a one-topic markdown entry from these slots. First non-blank line is
# <Title>. Lead with the conclusion, ~50–150 lines, concrete over abstract,
cite code as path:line where the slots name files. Link only corpus-relative
targets — if a slot names a local doc that should be linked, do not link it;
flag it in your return for the root to copy into the corpus. Add the provenance footer.
Then call add_markdown { corpus, path, content, overwrite: false } — the target
corpus must be single-root (add_markdown rejects multi-root corpora);
repo:{name}:wiki is single-root. Return the path written and any lint warnings
from the response. Do NOT interview the user.
Do NOT invent facts beyond the slots — if a slot is thin, write only what's there
and note the gap.
The daemon reindexes each file and refreshes ancestor index.md link lists
automatically on write.
Phase 4 — Stitch (root / opus)
- Collect the written paths and lint warnings; fix any flagged entry (heading jumps,
empty links) with an
overwrite: true redraft.
- Copy any local docs the drafts flagged into the corpus (
add_markdown, e.g.
sources/<slug>.md) and add the corpus-relative links — no page ships a link
that resolves outside the corpus.
list_tree to confirm the shape; write or refine the top-level index.md prose
(outside the <!-- HALLOUMINATE:INDEX-START --> / <!-- HALLOUMINATE:INDEX-END -->
markers — the daemon owns the link list between them).- Scaffold an empty
log.md at the corpus root so wiki-ingest has a ledger to
append to from its first run: add_markdown { corpus, path: "log.md", content: "# Ingest Log\n\n## Log\n", overwrite: false }. It stays append-only thereafter.
- Report the page list to the user and name the gaps the interview didn't reach
(hand-off candidates for a later
wiki-init continuation or wiki-ingest).
Rules
- Root interviews and reasons; haiku drafts. One question per turn.
- Ask about behavior in concrete situations, not abstract knowledge.
- Track slots internally; phrase every question open-ended.
- One topic per file, H1 first line, kebab slug — non-negotiable for retrieval.
- Confirm the page taxonomy with the user before writing anything.
- Fan out page drafts in one message so they run in parallel.
- Never write a fact the interview didn't establish; note thin spots as gaps.
- Never ship a link to a local file outside the corpus — copy the file in, then
link the copy.
