intake-interview

name	intake-interview
description	The first conversation with the owner of this Knowledge System of Record — seven questions that define what it is authoritative for, who may read it and who may approve it, then write instance.md together. Use when the owner asks to set up, configure, or "get started with" this project, when instance.md still contains its scaffold placeholder text, or when the scope of the corpus is unclear.
metadata	{"version":"1.5.0"}

Intake interview

instance.md is the identity of this Knowledge System of Record, and its prose IS the agent surface's system prompt (ksor serve wires it into the MCP server's instructions). Do not draft it from guesses — interview the owner, one question at a time, and write down what they actually say.

Ask THREE questions, one at a time

Ask them in the OWNER's words, not this project's. The vocabulary on this page — record, corpus, abstention, governance act — is precise and it is ours; an owner meeting it for the first time in a question cannot answer, and says so (reported 2026-08-26, against the wording these replaced: "the corpus wins about ___" asked them to complete a sentence that is not English unless you already know the ledger analogy).

Ask exactly this much. Do not explain what the answer will be used for inside the question — that is what made the last version unanswerable.

---

1 of 3 — What is this knowledge base about?

Be specific enough that I would know what does NOT belong in it.

Too vague: "our engineering docs" — I still could not tell what to leave out. Specific enough: "our leave, expense and conduct policies, current versions only."

---

2 of 3 — What is close to that, but not part of it?

Things people will ask this and it should NOT answer. A confident wrong answer is worse than "I do not cover that."

For the policies example: "not salaries, not individual HR cases, not last year's versions."

---

3 of 3 — Who signs off on a document, and who can take one down?

Names or handles, not job titles. If it is just you, say so.

Ask for BOTH: the handle the record will store (human:bashiraziz) and the natural name to print ("Bashir Aziz"). They are not derivable from each other — human:ciso and human:mjs are not anybody's squashed full name — so the handle goes into the frontmatter and the policy, and the pair goes into .ksor/people.yaml for the site to print.

---

Follow up until each is concrete, but follow up in their words too: "what would someone actually ask this?" gets further than "name the boundary".

Why these three and no others. The first two give the record an EDGE, and the abstention gate is meaningless without one: a knowledge base that is authoritative for everything has no outside, so an agent asked something the owner never wrote about reaches for its training instead of declining. The third cannot be guessed at all — the scaffold ships human:you in both authority lists, and a placeholder that survives this conversation is a person who was never there. Everything else has a sane default, and defaults are stated rather than asked.

Then STATE the defaults; do not ask them

Show these as a block, say they are defaults, and invite a correction. Do not walk them one at a time — they are near-constant, and asking makes the interview feel like a form.

	default
read by	people and agents both
declines	firmly — "not in this corpus" is a correct answer
audiences	one, public — every reader sees every document
sources	none yet — the corpus is still the samples

Each is written only if the owner does not object, and the write-back names which were answered and which were defaulted. Never report a default as an answer. Two answered and four defaulted is an honest sentence; "all seven answered" is not, and it is what happened the first time this skill ran.

If the owner says NOT every reader sees every document, then and only then: register each audience in .ksor/governance.yaml under audiences: with a one-line description: of who is in it — public is reserved and never registered. There is no ranking and no default: a document lists the audiences that may read it, a reader holds a list that always includes public, and the document is visible when the two lists OVERLAP. Tell them what this does and does not do: builds are made per audience, but anyone who can clone the repository reads everything in it — if someone must not read a document and can clone, that document belongs in a different repository.

What the answers become

Scope and Boundary become the BODY of instance.md, which ksor serve wires into the MCP server's instructions — so it is read by every agent that connects, and vague prose there is vague instructions everywhere.

Authority becomes approval_authorities and takedown_authorities in .ksor/governance.yaml. Names, not roles-in-the-abstract: the checker refuses an approval or a takedown by anyone the policy does not name. An actor is human:<handle>, process:<name> or <producer>/<version>; handles are published with the record, so use the handle the owner would put in a commit, never an email address.

Then write

• Rewrite instance.md from the answers. title: is the record's display title, the human name every page leads with ("Acme Operations Handbook", not the slug); description: is one sentence, and it seeds llms.txt and the MCP discovery document; the BODY is the authority sentence, boundary, audience and strictness — plain prose, handed in full to every connecting agent as the MCP server's instructions, so write it for a reader who must act on it. There is no # H1: the title is a key. Leave name: and toolchain: alone. One block is added here only when the owner stands up the served MCP rung — database:/embedding:/ retrieval: (see AGENTS.md → "Serving to agents"; that is a later climb, not part of this interview). The strictness answer from question 5 is the intent behind the retrieval.vector_floor on that climb, measured by ksor calibrate — capture it in the prose now so it is ready.
• Write .ksor/governance.yaml from question 3: version: "0.1", the audiences: registry if there is one, and the two authority sets with real actors. That file is the root of authority — every approval, every deprecation and every ledger entry is checked against it. Keep ksor-starter/KSOR-STAMP-VERSION in approval_authorities while any starter document is still in knowledge/. Those five are approved by it, so a policy rewritten without it refuses the next build by name (ksor-approver-unauthorised). It leaves when the last sample does.
• Write .ksor/people.yaml from question 3: version: "0.1" and a people: MAP from each actor to its natural name — "human:bashiraziz": Bashir Aziz. Keyed by the actor exactly as the record stores it, quoted because it contains a colon. Nothing else — the site looks the actor up at render time, so pages read "Owner · Bashir Aziz" instead of "Owner · human:bashiraziz". Every skill that records a governance act (this one, add-sources for verified: entries, ksor takedown for withdrawals) asks the owner for a natural name whenever it is about to write an actor that isn't in people.yaml yet — the owner is the only source of a display name, never a convention-based guess.
• Offer to start replacing the starter documents — they are already published. All five ship , approved by , so the site and carry them from the first build. They describe KSoR itself rather than the owner's organisation. Say it plainly: "Five sample documents about KSoR are published on your record right now. The tool that wrote them approved them — nobody has reviewed them, which is what the tier on each page says. Shall we start replacing them with yours?" Replacing means deleting the sample and writing a real document at ; the owner approves it afterwards, and that act is theirs. When the last sample is gone, delete from in the same change — nothing of theirs should be approved by a tool. Never record an approval nobody gave, and never write a entry: the approval is not a review, and inventing one would retire the tier that exists to say nobody has checked this.