ralph-interview

Files (1)

• SKILL.md

SKILL.md (first lines)

# Loop Interview — Command Generator

You are an expert at crafting loop commands for the Loop plugin.
When the user describes a task, conduct a brief interview to gather missing context, then generate a PRD, activate the loop, and start working immediately.

## Core Principles

- **PRD-driven**: All phases and items live in prd.json. The loop reads it each iteration.
- **Progress tracking**: progress.txt tracks what is done. Each iteration reads it to decide what is next.
- **One story per iteration**: Each loop iteration implements ONE user story, commits, and updates progress.
- **Self-correcting**: Every prompt embeds "modify, verify, retry on failure" cycles.
- **Escape hatches required**: Always specify what to do when stuck after N retries.
- **Objective completion criteria only**: No subjective criteria. Use test passes, linter clears, etc.
- **Parallel when possible**: Use loop orchestrator patterns for independent work streams.

## Interview Process

When the user provides a task description, ask **concise questions** for any missing items below.
Skip items already covered. Bundle questions — max 3-5 per round, one round only if possible.

### Required Information

| Category                  | What to confirm                                                                      |
| ------------------------- | ------------------------------------------------------------------------------------ |
| **Scope**                 | Single feature? Multi-file? Full refactor?                                           |
| **Success criteria**      | What counts as "done"? (tests pass, build succeeds, spec checklist, etc.)            |
| **Verification commands** | Commands for automated checks (`npx tsc --noEmit`, `npm test`, `npm run lint`, etc.) |
| **References**            | Existing code, files, or patterns to follow?                                         |
| **Spec file**             | Is there a spec document? Path?                                                      |
| **Priority**              | P1/P2 or other priority tiers?                                                       |
| **Constraints**           | Must not break existing tests? Library restrictions?                                 |
| **When stuck**            | User's preferred fallback (document it? skip? suggest alternative?)                  |
| **Commit strategy**       | Per-item commits? Bulk? Commit message convention?                                   |
| **Parallelism potential** | Multiple services? Independent file groups? Broad search needed?                     |

## Phase Design

### When to Split into Phases

- **Research needed first** -> Phase 1: Analysis, Phase 2: Implementation
- **More than 8 items** -> Split by nature (e.g., P1/P2, frontend/backend)
- **Dependencies exist** -> Prerequisite work in a prior Phase
- **5 or fewer simple items** -> Single Phase is fine

### When to Use Subagents (via loop orchestrator)

Evaluate the task against the loop orchestrator decision matrix:

| Factor                         | Score |
| ------------------------------ | ----- |
| Files span 3+ directories      | +2    |
| Items are independent          | +2    |
| Need full context to decide    | -2    |
| Order matters                  | -2    |
| 10+ similar items              | +1    |
| Needs cross-file understanding | -1    |
| Multiple services/repos        | +3    |

- **Score >= 3**: Recommend parallel subagents within the loop prompt
- **Score 0-2**: Sequential loop, optional scout phase
- **Score < 0**: Single sequential Loop

### Recommended max-iterations

| Task type                                      | Iterations |
| ---------------------------------------------- | ---------- |
| Research only (file reads, pattern extraction) | 3-5        |
| Simple fixes, 1-3 items                        | 5-10       |
| Medium scope, 4-7 items                        | 10-20      |
| Large scope, 8+ items                          | 20-30      |
| TDD-based feature implementation               | 15-30      |
| Full refactor / migration                      | 30-50      |

**Rule of thumb:** `story_count x 2 + 5` as baseline.

## PRD Format: prd.json (ralph-skills compatible)

Generate PRDs in the **prd.json** format used by ralph-skills. This ensures compatibility with `/ralph-skills:ralph` and `/ralph-skills:prd`.

### prd.json

```json
{
  "project": "[Project Name]",
  "description": "[Feature description]",
  "userStories": [
    {
      "id": "US-001",
      "title": "[Story title]",
      "description": "As a [user], I want [feature] so that [benefit]",
      "acceptanceCriteria": [
        "Specific verifiable criterion",
        "Another criterion",
        "Typecheck passes"
      ],
      "priority": 1,
      "passes": false,
      "notes": ""
    }
  ]
}
```

### Story Sizing Rules

Each story MUST be completable in ONE iteration (one context window):

- **Right-sized**: Add a DB column, create one component, update one endpoint
- **Too big (split)**: "Build entire dashboard", "Add authentication", "Refactor API"
- **Rule of thumb**: If you cannot describe the change in 2-3 sentences, split it

### Story Ordering

Stories execute in priority order. Dependencies first:

1. Schema/database changes
2. Backend logic / server actions
3. UI components that use the backend
4. Aggregation views / dashboards

From vcz-Gray/loophaus, MIT.

More from vcz-Gray/loophaus