NickMoignard/okf-domain-elicit

OKF Domain Elicitation

Conduct a domain interview that survives across sessions and emits an OKF bundle as it runs. Three leading words govern every run:

• saturation — a line of questioning is done only when it goes saturated: an answer that is concrete, bounded, exemplified, and exception-tested, spawning no new thread.
• branch queue — every unexplored case is pushed to an on-disk queue and worked until empty. Depth-first, breadth-tracked; nothing is dropped.
• tri-temporal — every time-bearing fact records when it happened, when the organisation received it, and when it was entered. See TRI-TEMPORAL.md.

This skill supplies the structure and the artefacts; pair it with a relentless interviewing stance (e.g. /grilling) for the persistence.

Session workspace — resume before asking anything

All state lives on disk so the interview survives context-window and session boundaries. On invocation:

1. Determine the topic slug (ask the user for the subject if unset).
2. Look for .interview/<slug>/. If it exists, READ state.json and queue.jsonl, resume from the recorded state and active thread, and announce where you are resuming.
3. If it does not exist, create it:

.interview/<slug>/
  state.json      # {state, active_thread, topic, temporal_relevance}
  queue.jsonl     # one branch per line: {id, prompt, status, parent}
  index.md        # OKF bundle root        — see BUNDLE-FORMAT.md
  glossary.md     # ubiquitous language    — see GLOSSARY-FORMAT.md
  events.md       # domain-event timeline  — see EVENTS-FORMAT.md
  rules.md        # business rules         — see RULES-FORMAT.md
  context-map.md  # bounded contexts       — see CONTEXT-MAP-FORMAT.md

Persist after every captured fact and every state transition. Never hold the queue or captured facts only in context — the disk is the source of truth.

State machine

Walk these states. The engine is the loop NARRATE → DRILL → BRANCH, popping the branch queue back into NARRATE until termination holds. Full prompts: QUESTION-BANKS.md.

• S0 Frame — scope, goal, actors at the edges. Set temporal_relevance (calendar day? clock second?) in state.json.
• S1 Narrate — elicit one concrete story as an event timeline; append events to events.md.
• S2 Drill — per event extract trigger · actor · data-in · rule · outcome · timing · identity, plus its tri-temporal states (see TRI-TEMPORAL.md).
• S3 Branch — "what else could happen here?" Push each exception / alternate / failure to queue.jsonl as pending.
• S4 Define — pin terms (each with a non-example), cardinalities, and boundaries; write to glossary.md and context-map.md.
• S5 Reflect — replay the model back in the stakeholder's words; capture corrections.

Probing reflex

Apply to EVERY answer, in every state — this is the relentless core:

vague quantifier ("usually","a few","normally") → ask for the boundary
abstraction with no example                      → demand a concrete instance
asserted rule ("we always X")                    → hunt the exception
new term                                          → write to glossary.md WITH a non-example
new actor or event                                → push to queue.jsonl
time-bearing fact                                 → capture all three tri-temporal states
else (concrete, bounded, exemplified, exception-tested)
                                                  → mark thread saturated; pop next pending branch

Branch queue protocol

• A branch is {id, prompt, status: pending|active|saturated, parent} — one JSON object per line, append-only.
• To work a branch: set it active in state.json, run S1→S3 on it, then append a line marking it saturated.
• Pop the next pending branch only once the active thread is saturated.
• On resume, the queue is the source of truth for what is left — read it, never reconstruct from memory.

Completion criteria

Stop only when ALL hold. These are checkable — do not declare done early:

• queue.jsonl has no pending branch.
• Every term in glossary.md has both a definition and a non-example.
• Every event in events.md carries all three tri-temporal states, or an explicit n/a — {reason}.
• The S5 replay produced no material correction.
• New questions yield only restatements of known facts.

Emit

Write OKF as you go — never batch at the end. Each artefact follows its *-FORMAT.md; together they form an OKF bundle rooted at index.md. Keep index.md current as artefacts gain content. The bundle is the deliverable — hand it off (e.g. to /to-prd or /to-issues) once the completion criteria hold.