Wizard

What is the Wizard

The wizard turns the linear discovery → /dr-prd chain into a guided, one-question-at-a-time interview the operator can branch, pause, and re-scope. It exists to eliminate «the agent misread the task intent» by co-authoring the PRD WITH the operator.

It is a thin orchestrator: it composes the existing discovery skill (the one-question-at-a-time engine) and consilium (the on-demand panel) — it never re-implements their prompting — and persists every step through a deterministic state engine.

Four Capabilities

1. Nested drill with auto-context-capture. The operator can drill into a hard sub-question in a side-thread and pull the conclusion back into the head thread without carrying a manual session identifier. State is anchored to the task ID; the captured context is a persisted drill frame holding references to prior answers, not a copy — it resolves at pop, and the conclusion is written back as the parent question's answer.
2. On-demand consilium. For a hard decision, convene a panel via the consilium skill and record the verdict as a decision graph node plus a «resolves» edge.
3. Mid-flow re-scope. Adding or revising a requirement, or changing a goal, sets a research-dirty or plan-dirty flag. In v1 the actual re-research and re-plan stay operator-confirmed — dirty-flag tracking only, no auto-fire loop.
4. Knowledge / dependency graph emission. Concepts, requirements, and decisions surfaced during the interview are emitted as graph nodes and edges to a side artefact for the graph sink.

State Model

State is an append-only JSONL event log; the current state is a projection (fold) over events. This is what makes the interview resumable and branchable:

• Resume — replay the log; re-running /dr-wizard continues, never restarts.
• Branch — a derived drill-stack (push / pop) plus parent links.
• Idempotency — the latest event per question id wins on projection.
• Every event carries a schema version and a monotonic sequence number.
• A terminal «finalized» event closes the interview; open drill frames are popped as abandoned. /dr-prd consumes only a finalized artefact — a half-finished interview is never authoritative.

Files live under the gitignored runtime tree: datarim/wizard/{TASK-ID}.wizard.jsonl holds the interview event log (kinds: meta, question, answer, drill push, drill pop, flag, finalized).

Engine API

Consumers source the state library and call its public functions — init, add question, answer, get answer, drill push, drill pop, re-scope, flags, finalize, status, validate, graph node, graph edge. The engine is the single point of correctness: run validation before any consumer trusts the log. It checks balanced push and pop, monotonic sequence, known event kinds and schema version, and that every graph edge references an existing node. Validation rejects — it never best-effort-repairs.

Graph Artefact

datarim/wizard/{TASK-ID}.graph.jsonl is the documented ingestion contract for the graph sink — one JSON object per line: a meta header, then nodes (typed concept, requirement, or decision) and edges (relation: dependency, refines, or resolves).

The graph flows OUTBOUND, so node labels are redacted at the sink boundary (token shapes, bearer credentials, private-key blocks, user-password-host forms, home paths, private-range addresses) before write. The local interview log keeps raw text. Enrichment, merge, and query semantics belong to the graph sink — this skill only emits against the contract; it builds no sink.

Composition with /dr-prd

/dr-prd gains a single, non-invasive hook: if a finalized wizard artefact exists for the task, it consumes that artefact's Requirements Summary and graph instead of running the plain discovery interview. The hook is idempotent — a re-run re-reads the same artefact and never double-consumes. When no wizard artefact exists, the plain discovery path is unchanged. This keeps one interview engine with two entry ergonomics, avoiding a second, drifting discovery pass.

Security Posture

Enforced by the engine, not by prose: an injection gate escaping backslash, quote, and tab while rejecting line feeds, carriage returns, other C0 controls, and DEL; allowlists for question ids, node ids, category slugs, and closed type / relation enums; path containment with a strict task-ID pattern, refusal of symlink targets, and append under a lock; and redaction on the outbound graph sink.

When to Stop

Same contract as discovery: all branches resolved (no open drill frame), done criteria defined, no question left whose answer would change the approach. Then finalize, validate, and emit the Requirements Summary. Do not over-interview — one-word confirmations mean the scope is clear; wrap up.