tzachbon/smart-ralph / plugins/ralph-specum/skills/interview-framework
interview-framework
VerifiedThis skill should be used when a Ralph phase must identify critical user decisions, run a layered grill, persist partial answers, obtain explicit approval, or resume an interrupted phase interview before delegating artifact work.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.7 KB |
| references/algorithm.md | markdown | 6.1 KB |
| references/domain-modeling.md | markdown | 2.1 KB |
| references/examples.md | markdown | 2.8 KB |
references/algorithm.md
View on GitHub# 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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |