Skip to content

tzachbon/smart-ralph / plugins/ralph-specum/skills/interview-framework

interview-framework

Verified

This 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.

FileKindSize
SKILL.mdskill md8.7 KB
references/algorithm.mdmarkdown6.1 KB
references/domain-modeling.mdmarkdown2.1 KB
references/examples.mdmarkdown2.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.
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: 467kUpdated Claude CodeCodexVerifiedInstall
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: 319kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 319kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 319kUpdated Claude CodeCodexVerifiedInstall