ralph-spec

Files (1)

• SKILL.md

SKILL.md (first lines)

# Writing Ralph Specs

Use this skill when creating or improving specification documents for Ralph, the autonomous task execution system.

## How Specs Become Work

Understanding the pipeline is essential to writing good specs:

```
SPEC (you write)
  |
  v
PLAN stage (LLM reads spec, does gap analysis against codebase)
  |
  v
TASKS (LLM generates: name, notes, accept, deps, priority)
  |
  v
BUILD stage (separate LLM implements one task per iteration)
  |
  v
VERIFY stage (checks task's acceptance criteria)
```

**The spec is a requirements document.** It defines WHAT must be true when done and HOW to verify it. The planner decides task boundaries, implementation order, and per-task acceptance criteria. The builder writes the code.

A spec's job is to give the planner enough structure and clarity that it naturally produces well-scoped tasks. You do NOT need to prescribe task boundaries in the spec — but you DO need to write requirements at a granularity that makes good decomposition obvious.

## Hard Limits

| Constraint | Limit | Why |
|-----------|-------|-----|
| Spec length | **≤ 300 lines** | The planner must read the spec AND explore the codebase in one context window. Long specs crowd out codebase research. |
| Files touched | **≤ 10 files** per spec | More than this means the spec covers multiple concerns. Split it. |
| New concepts | **≤ 3** per spec | Each new type, API, protocol, or abstraction adds cognitive load. |
| Requirements subsections | **≤ 8** H3 sections | Each subsection is a natural task boundary for the planner. More than 8 and the planner starts merging them. |

If your spec exceeds any of these, **split it into multiple specs**.

## Spec File Location

Place specs in: `ralph/specs/<spec-name>.md`

Use kebab-case for filenames (e.g., `user-authentication.md`, `api-rate-limiting.md`).

## Required Sections

Every Ralph spec MUST have these sections in order:

### 1. Title (H1)

```markdown
# Feature Name
```

Short, descriptive name. This becomes the spec identifier.

### 2. Overview

```markdown
## Overview

One paragraph explaining WHAT this feature does and WHY it exists.
Focus on the problem being solved, not implementation details.
```

### 3. Requirements

```markdown
## Requirements

### Subsection Name

Detailed requirements organized by topic. Use:
- Bullet points for lists of requirements
- Code blocks for interfaces, signatures, schemas
- Tables for structured data (field definitions, command references)
```

**Granularity rule**: Each H3 subsection under Requirements should describe ONE cohesive deliverable. The planner will naturally create one task (or a small cluster) per subsection. If a subsection requires changes to more than 3 files, it's too big — split it.

### 4. Acceptance Criteria

```markdown
## Acceptance Criteria

- [ ] Criterion 1: Specific, testable requirement
- [ ] Criterion 2: Another testable requirement
- [ ] Criterion 3: Edge case handling
```

**CRITICAL**: The VERIFY stage checks these. Each criterion must be independently verifiable — completing it should not require other criteria to be done first (unless there's an explicit dependency chain).

## Optional Sections

Add these when relevant:

### Architecture (for features with component interactions)

```markdown
## Architecture

Use ASCII diagrams for flows. Keep brief — architecture communicates
relationships, not implementation.
```

### Dependencies

```markdown
## Dependencies

- Requires `auth-core.md` to be implemented first
- Assumes `libfoo >= 2.0` is available
```

### Non-Requirements

```markdown
## Non-Requirements

From djmittens/neo-mittens, MIT.

More from djmittens/neo-mittens