# Critical-Frontier Interview Algorithm

Use this state machine for every normal-mode phase interview.

## 1. Establish the interview

```text
context = goal + applicable prior artifact bytes or research relevance context
phase = start | triage | research | requirements | design | tasks
interviewId = stable ID for this phase attempt
discoveryRevision = current skill discovery revision
contextDigest = SHA-256 for the ordered current phase context

complete discovery and preload
record-skill-load(state, manifest)
begin-interview(state, phase, interviewId, round, discoveryRevision, contextDigest)
```

Compute the digest from the length-framed phase, exact goal snapshot, and current artifact-source bytes defined in `normal-mode-gates.md`. The helper re-reads those sources and recomputes the digest at every gate. Exclude answers, state, receipts, discovery history, and skill bytes. Reuse the existing interview ID, immutable digest, discovery revision, and round when resuming. `begin-interview` preserves the active record. Advance one layer with `open-frontier --round N+1`; do not overwrite partial answers.

## 2. Build the design tree

First resolve facts from the goal, state, `.progress.md`, prior artifacts, configured specs index, applicable `CONTEXT.md`, code, configuration, and tests. Classify each unknown as a discoverable fact or a consequential user decision. Use read-only exploration for facts. Ask no repository fact as a user question.

For each candidate topic from the phase territory:

1. Assign a stable decision ID.
2. Mark dependencies on other decisions.
3. Inspect the codebase and prior artifacts for discoverable facts.
4. Drop the topic when it fails the critical decision test.
5. Resolve it from evidence when the answer is factual.
6. Keep it open only when user judgment can materially change the artifact.

Represent each open node as:

```text
{
  id,
  dependencies,
  evidence,
  options[2..4],
  recommendation,
  rationale,
  tradeoffs,
  consequences
}
```

Track each node as `OPEN`, `INVESTIGATING`, `RESOLVED`, or `OUT_OF_SCOPE`. Apply the domain-language checks in `domain-modeling.md` throughout the tree. Update the applicable glossary when a domain term is resolved; do not create an ADR.

Apply clear instruction precedence automatically. If loaded skill contracts still conflict materially after system, developer, user, project, plugin, and skill precedence is applied, create an unblocked conflict decision in the first layer. Describe both unresolved contracts and the consequence of choosing each.

## 3. Traverse by frontier

```text
while critical open nodes remain:
  frontier = every open node whose dependencies are resolved
  inspect any newly discoverable facts
  remove nodes resolved by evidence or inference
  frontier = recompute frontier

  if frontier is empty:
    report the blocking dependency or conflict
    stop without delegating

  call open-frontier with the current round for every frontier decision ID
  ask every node in frontier using AskUserQuestion
  chunk only at the tool's four-question maximum

  call classify-reply on the whole response

  if bare skip after an active question:
    call skip with decision ID skip-confirmation, reason, defaults, and assumptions
    leave state awaiting_confirmation
    break

  if control-only:
    keep every frontier node open
    ask the same frontier again
    continue

  for each substantively answered node:
    record-answer immediately
    mark that node resolved

  keep omitted or ambiguous nodes open
  turn an Other response into a specific dependent node
  add branches exposed by the answers
  infer dependent answers only when the inference is deterministic
```

Ask all independent decisions together. Never reduce the batch below four merely to simulate a one-question-at-a-time conversation.
If `AskUserQuestion` is available, use it for the numbered frontier round; otherwise render the same numbered round in the response. Ask every currently unblocked user decision in the same round, splitting only at the tool limit. Advance no phase with an open frontier.

## 4. Handle partial and free-text answers

- Map each clear answer to its stable decision ID.
- Persist the mapped answers before asking again.
- Keep unanswered questions active.
- Turn ambiguous free text into a focused follow-up only when the ambiguity changes a material outcome.
- Inspect any factual claim that can be verified locally before asking the user to confirm it.
- Treat `Other` as input to a concrete next-layer decision, never as a generic invitation to elaborate.
- Bound follow-ups by decision resolution, not an arbitrary question count.

## 5. Prepare the decision brief

When no critical node remains open, synthesize one recommended approach. Include viable rejected alternatives only when their tradeoffs help the approval decision.

```text
brief = {
  resolved decisions,
  recommended approach,
  material tradeoffs,
  defaults,
  assumptions,
  unresolved non-material items,
  skill conflicts and resolutions
}
```

Call `await-confirmation` with a stable confirmation decision ID and the recommended approach. Then ask the explicit final approval question.

## 6. Process final approval

```text
if explicit "Approve and delegate" selection:
  confirm(state, confirmationDecisionId or skip-confirmation, source)
  check-delegation(state, phase, interviewId, discoveryRevision, contextDigest)
  delegate immediately

if "Revise decisions":
  call revise once with every affected decision ID
  reopen affected nodes
  invalidate dependent answers when necessary
  return to frontier traversal

if "Cancel":
  leave the interview nonterminal
  stop without delegation

if control-only text:
  keep awaiting_confirmation
  repeat the approval question
```

Approval of an earlier phase does not approve the current phase. Artifact approval after writing does not substitute for this pre-delegation approval.

## 7. Quick mode

Only exact `--quick` authorization may bypass the interview. Record mode first, begin the phase interview so the helper writes `bypassed_quick`, then run the delegation check. Natural-language requests, `-q`, stale booleans, and legacy malformed quick state do not bypass the gate.

# Domain Modeling During Grilling

Use domain modeling to sharpen project language while the design tree is active.

## Locate the Applicable Context

1. Resolve the repository root.
2. If `CONTEXT-MAP.md` exists, read it and select the context that owns the current capability. If the mapped `CONTEXT.md` does not exist, create it at that mapped path only when the first term for that context is resolved.
3. Otherwise read the root `CONTEXT.md` when present.
4. If neither file exists, create a root `CONTEXT.md` only when the first project-specific domain term becomes resolved. Never fall back to the root when `CONTEXT-MAP.md` names the owning context. Do not create an empty placeholder during preflight.
5. If multiple contexts could own the term and repository evidence cannot decide, add context ownership to the user-decision frontier.

## Work the Language

- Challenge a term that conflicts with the glossary in the same round.
- Replace vague or overloaded words with a proposed canonical term.
- Invent a concrete scenario when a relationship, boundary, lifecycle, or ownership rule remains fuzzy.
- Read the relevant code when the user describes current behavior. Surface any contradiction as evidence for the next frontier.
- Keep general programming terms out of the domain glossary.

## Update CONTEXT.md Inline

Write a resolved term during the round that resolves it. Do not wait until the interview ends.

Use this format:

```markdown
# <Context Name>

<One or two sentences describing the context.>

## Language

**<Canonical Term>**:
<One or two sentences defining what the concept is.>
_Avoid_: <conflicting or discouraged alternatives>
```

Apply these rules:

- Pick one canonical term.
- Define what the concept is, not how code implements it.
- Keep definitions to one or two sentences.
- List competing names under `_Avoid_` when doing so prevents future ambiguity.
- Preserve unrelated glossary entries and existing context structure.

Do not store requirements, implementation details, task notes, or technical decisions in `CONTEXT.md`. Do not create ADRs from the interview framework; keep technical decisions in the spec's `design.md`.

# Grilling Examples

## Whole critical frontier

Suppose requirements has three independent critical decisions: primary user, compatibility promise, and data retention. Ask all three in one `AskUserQuestion` call. Put `[Recommended]` on the grounded first option for each and name its tradeoff. Do not ask repository framework, output path, or ticket number when those facts are discoverable.

If five independent critical decisions are open, ask four in the first call and one in the second. The tool maximum is the only batching reason.

Resolve repository facts and domain language before asking. For example, inspect the active authentication boundary and its `CONTEXT.md` definition instead of asking which module owns it. Ask only when the remaining boundary choice materially changes the artifact.

## Partial answer

The user answers the primary-user and retention questions but omits compatibility.

1. Record both answered decision IDs immediately.
2. Leave compatibility open.
3. Recompute dependencies.
4. Ask compatibility plus any decisions it unblocked.

Do not discard the two saved answers or restart the round.

If the user selects `Other`, create a specific dependent decision from the supplied alternative. Do not ask a generic "what did you have in mind?" question.

## Control-only reply

Active frontier: architecture boundary and rollout safety.

User: `proceed`

Result: persist no answer, keep both decisions open, and ask the same frontier again. `continue`, `go ahead`, and `apply the changes` behave the same way.

## Bare skip

Active frontier: test depth and rollback policy.

User: `skip`

Result: record the phase interview as skipped with the recommended test depth and rollback policy listed as defaults and assumptions. Present those choices in the final decision brief and require explicit approval before delegation.

User: `Skip browser tests; keep the rollback task.`

Result: treat the reply as substantive. Persist both decisions. It is not a bare skip.

## Final approval

Present:

```text
Decision brief
- Scope: existing API only
- Compatibility: preserve the current client contract
- Approach: extend the current module
- Tradeoff: smallest change, but keeps the current coupling
- Assumptions: current deployment pipeline remains available
```

Ask `Approve and delegate`, `Revise decisions`, or `Cancel`. Only the explicit approval selection completes the gate. After approval, call the helper check and launch the artifact agent in the same response.

## Artifact revision

After the agent writes `design.md`, the user says `apply the changes` and supplies reviewer findings.

Result: delegate the revision with those findings, show the updated walkthrough, and ask for artifact approval again. Keep the phase in artifact approval until the user explicitly approves.