deep-interview

<Purpose_And_Principles> **DIPP-1 — Purpose.** Deep Interview applies Socratic questioning with mathematical ambiguity scoring to replace vague ideas with crystal-clear specifications: it exposes hidden assumptions, measures clarity across weighted dimensions, and refuses to proceed until ambiguity drops below the resolved threshold for this run. The output feeds into a gated pipeline: **deep-interview → ralplan consensus refinement → pending approval → explicitly approved execution**, ensuring maximum clarity before any mutation starts. AI can build anything. The hard part is knowing what to build. GJC planning Phase 0 expands ideas into specs via analyst + architect, but this single-pass approach struggles with genuinely vague inputs: it asks "what do you want?" instead of "what are you assuming?" Deep Interview iteratively exposes assumptions and mathematically gates readiness, ensuring the AI has genuine clarity before spending execution cycles. Inspired by the [Ouroboros project](https://github.com/Q00/ouroboros), which demonstrated that specification quality is the primary bottleneck in AI-assisted development. **DIPP-2 — Use when.** > **Use when** the user wants requirements clarified before execution: a vague or exploratory idea ("I have a vague idea", "not sure exactly what I want"); an explicit request to interview ("deep interview", "interview me", "ask me everything", "don't assume", "make sure you understand", "socratic"); a wish to avoid "that's not what I meant" outcomes from autonomous execution or to reach mathematically-validated clarity before committing to execution; a task complex enough that jumping to code would waste cycles on scope discovery; an implementation ask whose target, scope, acceptance criteria, or safety boundary is ambiguous enough that mutation would require guessing; or an explicit deep-interview request even after being told the request is already clear. > - User requests a trace/research pre-step before the interview, e.g. `/skill:deep-interview --trace <idea>` **DIPP-3 — Question pacing.** - Ask ONE question at a time -- never batch multiple questions **DIPP-4 — Language.** - Default to English when no language preference is explicit or obvious. Preserve the user/session language for every user-facing announcement, topology confirmation, option label, and interview question when state includes `language.instruction`; do not add language-specific special cases **DIPP-5 — Self-proofread.** - Before emitting any user-facing natural-language prose governed by `language.instruction`, perform one silent, best-effort self-proofread in the preserved session language for obvious spelling, spacing, grammar, inflection/particle, and word-choice errors, using the same language-agnostic pass for whatever language is active rather than special-casing any single language. Apply it only to newly generated prose and never announce the proofreading, show before/after text, apologize for it, or re-emit a corrected copy. Do not alter code blocks or identifiers, file paths, CLI commands, JSON/configuration keys, `ask` metadata keys, table/round structure, fixed labels, numeric scores, component ids, status tokens, user quotes or source text, Phase 0 threshold markers such as `Deep Interview threshold: <resolvedThresholdPercent> (source: <resolvedThresholdSource>)`, or fixed paths such as `.gjc/_session-{sessionid}/specs/deep-interview-{slug}.md`; still apply the self-proofread to generated natural-language clauses or cells inside those structures, including Why now rationale, gap text, next-target phrasing, and coverage notes **DIPP-6 — Weakest dimension.** - Target the WEAKEST clarity dimension with each question. Make weakest-dimension targeting explicit every round: name the weakest dimension, state its score/gap, and explain why the next question is aimed there **DIPP-7 — Prompt budget.** > Keep prompt payloads budgeted: summarize or trim oversized initial context/history before composing question, scoring, spec, or handoff prompts. If the user's initial context is oversized or likely to crowd out downstream prompts, create a concise prompt-safe summary first — one that preserves user intent, decisions, constraints, unknowns, cited files/symbols, and any explicit non-goals — and wait until that summary exists before ambiguity scoring, weakest-dimension selection, question generation, brownfield exploration prompts, spec crystallization, or any downstream execution handoff (bridge to `ralplan` or `ultragoal`). **DIPP-8 — Artifact writes.** - Use the active GJC workflow/state CLI as the only sanctioned writer for `.gjc/` interview artifacts; do not edit `.gjc/` directly without an explicit force override. **DIPP-9 — Execution threshold.** - Do not proceed to execution until ambiguity ≤ the resolved threshold for this run and the user explicitly approves a scoped execution path </Purpose_And_Principles> <Do_Not_Use_When> - User has a detailed, specific request with file paths, function names, or acceptance criteria -- execute directly - User has an explicit concrete low-risk implementation request with enough target, scope, and acceptance criteria to execute safely -- execute directly - User wants to explore options or brainstorm -- use `ralplan` skill instead - User wants a quick fix or single change -- use direct execution, not deep-interview or role-agent delegation - User says "just do it" or "skip the questions" without an explicit execution path -- respect their intent by exiting deep-interview, not by writing a `pending approval` spec - User already has a PRD or plan file and explicitly asks to execute it -- use the requested execution skill with that plan </Do_Not_Use_When> <Execution_Policy> - Before Round 1 ambiguity scoring, run a one-time Round 0 topology enumeration gate that confirms the top-level component list and locks it into state - Gather codebase facts via focused read/search tools or a canonical read-only role agent (`planner`/`architect`) BEFORE asking the user about them - For brownfield confirmation questions, cite the repo evidence that triggered the question (file path, symbol, or pattern) instead of asking the user to rediscover it - Score ambiguity after every answer -- display the score transparently - When the locked topology has multiple active components, score and target each component explicitly so depth-first clarity on one component cannot hide ambiguity in siblings - Route ambiguous implementation asks to clarification, deep-interview, or downstream `ralplan` before mutation; do not infer missing target, scope, acceptance criteria, or safety boundary just to start coding. - Treat user wording such as `implementation`, "implementation plan", Korean `구현`, or "구현 계획" as describing the eventual target, not permission to implement now. - While still in deep-interview, do not implement, edit/write code, launch implementation workers, or start task/skill/ultragoal implementation; continue interviewing for scope, risks, acceptance criteria, and unknowns. - When the user wants interview output for eventual implementation, say: "I can interview for an implementation plan, but I won't implement during deep-interview." Then continue clarifying scope, risks, acceptance criteria, and unknowns. - Implementation requires an explicit phase transition/approval after the interview: deep-interview must first produce its spec/handoff, the workflow phase must explicitly transition out of deep-interview, and execution approval must be captured by a downstream execution path. - Allow early exit with a clear warning if ambiguity is still high - Persist interview state for resume across session interruptions - A multi-persona lateral-review panel convenes at ambiguity-milestone transitions (and before synthesizing any agent-supplied answer) to expose blind spots from independent perspectives - Refine free-text answers into a structured interpretation and confirm nothing is lost before scoring - After 3 consecutive agent-resolved answers (accepted auto-answers), route the next question to the user (dialectic rhythm guard) - Run an independent closure audit and a one-sentence goal restatement, each requiring explicit user confirmation, before crystallizing the spec - When `--trace` is active, use the bounded trace evidence summary as pre-question context; never dump raw logs, raw files, or unbounded search output into questions, scoring, specs, or handoffs **Native kickoff contract.** Seed the interviewing phase with `gjc deep-interview [--trace] [--json] [--quick|--standard|--deep] <idea or vague description>`. `--trace` enables the bounded evidence pre-step and `--json` selects machine-readable output; neither flag changes the approval gate. The generic workflow API retains `api --input <json-or-@file>` for bounded payloads and does not authorize execution. **Native spec-write contract.** Persist a final specification with `gjc deep-interview --write --stage final --slug <slug> --spec <markdown-or-path> [--force] [--json]`. The `--force` option is limited to overwriting corrupt deep-interview state and never grants execution approval; use the separate approval transition before any execution handoff. ### Crystallize sub-mode `--crystallize` is a bounded shortcut on this skill, not a new workflow or an execution path. It is the sanctioned `interviewing` → `handoff` transition for a ready Crystal and must remain non-authorizing. Use it only when the current conversation already contains material requirements and decisions. Before any state write, capture a deterministic conversation snapshot with an explicit message range, source revision, and digest. Extract each item into exactly one of `confirmed`, `inferred`, or `disputed`; every confirmed goal, constraint, decision, and acceptance criterion MUST retain a verbatim source anchor. Do not treat inferred or disputed text as confirmed. Submit the bounded snapshot and extraction through the native crystallize writer. The writer is the sole promoter into the existing deep-interview state/spec shape; exploration remains non-canonical. A sufficient snapshot creates a versioned Crystal/spec without replaying interview rounds. One or two blocking gaps may be asked through `ask`; unresolved consequential choices use the existing lateral/adversarial review hook. Broad ambiguity MUST fall back to the ordinary full interview flow. Never create a Crystal when the snapshot revision or digest is stale or mismatched. When a prior Crystal exists, compare only evidence after its bound revision. Preserve unchanged confirmed material and record a versioned delta: additive requirements create the next version, changed constraints or decisions reopen affected fields and invalidate execution approval, changed goals supersede the prior Crystal, and conflicting later evidence marks it stale rather than overwriting it. Every promoted Crystal records `spec_version`, source range/revision/digest, classifications, anchors, open gaps, and `execution_approval: not-approved` unless a separate existing approval gate later records approval. Crystallization MUST NOT invoke implementation, `run`, `ralplan`, or any automatic handoff. **Native CLI contract.** Invoke this sub-mode as `gjc deep-interview --crystallize --input <json-or-@file> --slug <slug> [--session-id <id>] [--json]`; both `--input` and `--slug` are required. The `--input` value is either inline JSON or an `@file` and is bounded to 1 MiB. It must have this required object shape (the listed arrays are optional when empty): ```json { "snapshot": { "revision": 1, "start": 0, "end": 0, "digest": "<64 lowercase hex SHA-256>", "messages": [ { "index": 0, "role": "user", "content": "Build audit reports" } ] }, "current_revision": 1, "items": [ { "id": "goal:reports", "kind": "goal", "classification": "confirmed", "statement": "Build audit reports", "anchor": { "message_index": 0, "quote": "Build audit reports" } } ], "open_gaps": [], "conflicts": [] } ``` `snapshot.messages` MUST be ordered, unique, contiguous, and cover every index from `start` through `end`; the range and message list are capped at 200 messages, `items` at 128 entries, and each text field at 10,000 characters. `snapshot.end` MUST be the live transcript tail, `current_revision` MUST equal `snapshot.revision`, and `digest` MUST be the SHA-256 digest of the normalized snapshot. For a prior Crystal, include every message after its stored boundary; never skip a range or reuse stale evidence. Items use exactly one of `goal`, `constraint`, `decision`, `acceptance_criterion`, or `non_goal` and exactly one of `confirmed`, `inferred`, or `disputed`; confirmed items require a verbatim user `anchor` and inferred/disputed items never count as confirmed requirements. For the first Crystal, `snapshot.start` MUST be 0 and the full authenticated transcript MUST fit within 200 messages (exactly 200 is valid). If it exceeds that bound, continue the ordinary interview flow; never submit only the last 200 messages or replace authenticated evidence with a summary. With a canonical stored prior Crystal preserving the prefix, a contiguous delta of at most 200 messages may start after its stored boundary even when the full transcript is longer than 200 messages. The ordinary state writer has a separate required shape: `gjc deep-interview write --input '{"state":{...}}'` and `stage --for <transition> --input '{"state":{...}}'`; stage transitions are incremental deltas, not whole-transcript replacements. A Crystal is ready only when ambiguity/readiness evidence has no unresolved gaps, conflicts, or disputed requirements; `needs-questions`, `stale`, and `superseded` results do not publish a spec and return to the ordinary interview/resolution path. A ready result persists the versioned artifact `.gjc/_session-{sessionid}/specs/deep-interview-{slug}-v{spec_version}.md`. Every Crystal starts with `execution_approval: not-approved`; only the separate `gjc deep-interview approve-execution --json` action records explicit user execution approval for a ready canonical Crystal, and handoff never grants that approval. </Execution_Policy> <Internal_Auto_Mode_Protocol> - `auto-answer-uncertain.md` and `lateral-review-panel.md` are internal prompt fragments loaded on demand with bundle metadata `kind: "skill-fragment"`; they are not public skills, are never slash-command/discoverable, and must not be registered through any `skill://` route. - Load fragments only for the specific hook that needs them, with forked inherited context kept read-only and prompt-budgeted; summarize active interview context before spawning the architect if the payload is large. - Auto-mode architects are read-only: no code edits, no `.gjc/` mutation, no workflow chaining, no formatters, and no execution delegation. - Validate every fragment response before using it: required sections must be present, candidates/answer must match the requested shape, rationale must cite available context, confidence must be explicit, and insufficient-context fallbacks must be honored. - If architect spawn, fragment loading, or response validation fails, continue the normal manual interview path silently and record an internal audit note in state by incrementing `architect_failures`; do not expose tool noise to the user unless it changes the next user-facing question. - Track `auto_answered_rounds`, `lateral_reviews`, `auto_answer_streak`, `refined_rounds`, `architect_failures`, and `lateral_panel_failures` in state and final spec metadata. </Internal_Auto_Mode_Protocol> <Steps> ## Native Plugin Invocation Guard (Issue #3030) If this raw bundled skill is loaded by GJC's native skill loader through `/skill:deep-interview`, do not treat that path as permission to skip rendered GJC setup. The user-facing invocation is `/skill:deep-interview`; do not recommend or advertise CLI bridge commands as the deep-interview entrypoint. Regardless of invocation path, Phase 0 below remains blocking and must resolve `gjc.deepInterview.ambiguityThreshold` from pre-resolved native state or settings before any announcement, state write, question, or ambiguity score. ## Corrupt current-session state recovery When deep-interview detects its own current-session state is corrupt, tampered, unreadable, or stale on resume, run `gjc deep-interview clear --force` before reseeding or restarting. Scope the clear to the current session via `--session-id` or `GJC_SESSION_ID`; it clears only deep-interview state for that session and never clears other skills or sessions. ## Phase 0: Resolve Ambiguity Threshold (blocking prerequisite) Complete this phase before Phase 1, before brownfield exploration, before GJC state persistence, before Round 0, and before any ambiguity scoring. Do not continue if the resolved threshold and source are unknown. 1. **Prefer pre-resolved native state**: - First inspect active deep-interview state with `gjc deep-interview read --json`. - If state contains a finite numeric `threshold` and a non-empty `threshold_source`, use those values, set `<resolvedThreshold>`, `<resolvedThresholdPercent>`, and `<resolvedThresholdSource>`, and skip optional settings-file reads. This is the normal `/skill:deep-interview` path because the native hook already resolved settings quietly before loading the skill. 2. **Only if native state lacks a resolved threshold, read threshold settings in the runtime precedence order** (one shared resolver; first valid value wins): 1. project `.gjc/config.yml` 2. user `<agentDir>/config.yml` (normally `~/.gjc/agent/config.yml`, honoring `GJC_CODING_AGENT_DIR`/`PI_CODING_AGENT_DIR`; XDG variables apply only to categorized data/state/cache subdirectories, never to the workflow config path) 3. built-in default (`0.05` before resolution-flag fallback) - `config.yml` uses the nested (schema) form - `gjc: { deepInterview: { ambiguityThreshold } }`. Project configuration beats user configuration. The reported `threshold_source` is the canonical path of the winning file, or the default. `config.yml` is the ONLY settings surface: the legacy `settings.json` files' workflow keys are retired: the config-root `~/.gjc/settings.json` is migrated once into the default global agent `config.yml` and its source removed, while the project `.gjc/settings.json` is retained for non-workflow settings (only its workflow keys are migrated into project `.gjc/config.yml` and no longer read unless a migration target is absent - a migration that could not publish (e.g. a read-only `.gjc`) leaves the retained legacy value effective as the previously configured override until it can publish). Invalid optional settings files continue to the next layer or the default (tolerant) — never a failed `Read`; do not probe arbitrary ancestor candidates. 3. **Resolve threshold and source**: - Use the first valid configured value in the precedence order above; otherwise use the mode default when a resolution flag was passed: `--quick` = `0.6`, `--standard` = `0.5`, `--deep` = `0.35`; with no resolution flag, use the base default `0.05`. - Set these run variables exactly: `<resolvedThreshold>`, `<resolvedThresholdPercent>`, and `<resolvedThresholdSource>` (for example `./.gjc/config.yml`, `<agentDir>/config.yml` such as `~/.gjc/agent/config.yml`, or the selected mode default). 4. **Emit the required first line to the user before any other interview announcement**: ``` Deep Interview threshold: <resolvedThresholdPercent> (source: <resolvedThresholdSource>) ``` 5. **Carry threshold source forward mechanically**: - Substitute `<resolvedThreshold>`, `<resolvedThresholdPercent>`, and `<resolvedThresholdSource>` throughout the remaining instructions before continuing. - Include `threshold_source` in the first `gjc deep-interview write` payload and preserve it on later state updates; do not edit `.gjc/_session-{sessionid}/state` files directly unless an explicit force override is active. - Include both threshold and source in the final spec metadata. - Read any `language` object from active deep-interview state and carry `language.instruction` forward mechanically. If absent, default to English unless the appended `User:` request makes another user/session language obvious or the user explicitly requests another language. Do not add language-specific special cases. ## Phase 0.5: Suitability Gate Run this gate after the Phase 0 threshold marker and before Phase 1, brownfield exploration, `gjc deep-interview write`, Round 0, ambiguity scoring, or spec writing. If the user request appended after this skill as the final `User:` line is already clear, bounded, low-risk, and asks for a quick fix, single change, known file/symbol edit, explicit command, or direct answer: 1. **Stop deep-interview immediately**: - First inspect current-session state with `gjc deep-interview read --json` (include `--session-id <current-session-id>` when available). - Clear through `gjc deep-interview clear --force --json` only when the state is a newly seeded empty interview: no recorded `rounds`, no `spec_path`, no `handoff_from`, no final/pending spec, and no user-confirmed topology. - If state already contains rounds, a spec path, handoff metadata, pending approval, or confirmed topology, do not clear it. Preserve the active interview and ask the user whether to continue, cancel, or explicitly clear the workflow. - Do not initialize deep-interview state. - Do not run Round 0. - Do not write a pending-approval spec. - Do not hand off to `ralplan`, `ultragoal`, or a role agent. 2. **Return the request to direct implementation**: - Say briefly that deep-interview is unnecessary because the request is already clear and small. - State the direct implementation path the normal coding agent should take. - If the user explicitly insists on deep-interview anyway, continue to Phase 1. This gate exists to prevent deep-interview from making easy problems harder. A small verification need does not make a request interview-worthy. ## Phase 0.75: Optional Trace Pre-Step Run this phase only when the active deep-interview state or invocation indicates `--trace` / `state.trace.enabled === true`. It is a pre-interview research step, not an implementation phase. 1. Read the native trace summary from active deep-interview state (`trace`, `state.trace`, or `state.trace_summary`). The native seed must have produced this summary before any interview question. 2. Treat the summary as compact evidence: project hints, relevant paths, and path-level findings only. Do not expand it by dumping raw files, raw logs, or unbounded command output. 3. Store or preserve it under `state.trace_summary` and fold it into `codebase_context` with citations to the summarized paths. 4. Use trace findings to influence Round 0 topology, Phase 2 question targeting, requirement wording, acceptance criteria, and final Technical Context. Normal no-trace interviews must behave exactly as before. 5. If `--trace` was requested but no valid bounded summary exists, increment `architect_failures` or record an internal audit note, then continue with the normal no-trace path without surfacing tool noise. ## Phase 1: Initialize 1. **Parse the user's idea** from the user request appended after this skill as the final `User:` line 2. **Detect brownfield vs greenfield**: - Use focused read/search tools or a canonical read-only role agent (`planner`/`architect`) to check if cwd has existing source code, package files, or git history - If source files exist AND the user's idea references modifying/extending something: **brownfield** - Otherwise: **greenfield** 3. **For brownfield**: Build the first-round context before designing Round 1 questions: - Use focused read/search tools or a canonical read-only role agent (`planner`/`architect`) to map relevant codebase areas, store as `codebase_context`.