Imported from David-Li0406/meta-skill-evloving (skill-flow/data/skills-refined-autoskill-36k/skillsmp/ralph-spec/SKILL.md). Install upstream with npx skills add David-Li0406/meta-skill-evloving --skill ralph-spec. Copyright stays with the author (MIT).

Writing Ralph Specs

Use this skill when creating or improving specification documents for Ralph, the autonomous task execution system. Ralph specs drive automated implementation through construct mode, which runs a staged loop: INVESTIGATE -> BUILD -> VERIFY (with DECOMPOSE for failures).

What Makes a Good Ralph Spec

A Ralph spec must be machine-actionable. An LLM agent will read this spec and autonomously implement it. Every requirement must be:

1. Unambiguous - No room for interpretation
2. Verifiable - Clear pass/fail criteria
3. Atomic - Decomposable into single-iteration tasks
4. Complete - All edge cases and constraints specified

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)

# Feature Name

Short, descriptive name. This becomes the spec identifier.

2. Overview

## Overview

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

3. Requirements

## Requirements

### Subsection Name

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

4. Acceptance Criteria

## Acceptance Criteria

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

CRITICAL: This section drives VERIFY stage. Each criterion becomes a verification check.

Optional Sections

Add these when relevant:

Architecture (for complex features)

## Architecture

Use ASCII diagrams for flows:

┌─────────┐ ┌─────────┐ ┌─────────┐ │ Input │────>│ Process │────>│ Output │ └─────────┘ └─────────┘ └─────────┘

Explain component relationships and data flow.

CLI Commands (for tools)

## CLI Commands

| Command | Output | Description |
|---------|--------|-------------|
| `tool cmd` | JSON | Does X |
| `tool cmd --flag` | String | Does Y |

Configuration (for configurable features)

## Configuration

```jsonl
{"field": "value", "description": "what it does"}

### Error Handling

```markdown
## Error Handling

| Error Condition | Response |
|-----------------|----------|
| Invalid input | Return error code X |
| Resource not found | Log warning, continue |

Writing Style Rules

DO

• Use imperative mood: "Add X", "Create Y", "Return Z"
• Be specific: "Return JSON with fields id, name, status"
• Include examples for complex formats
• Specify exact error messages and codes
• Define all acronyms on first use
• Use tables for structured information
• Include edge cases explicitly

DON'T

• Use vague language: "should be fast", "handle errors appropriately"
• Leave behavior undefined: "returns appropriate response"
• Assume context: always state dependencies explicitly
• Use pronouns without clear antecedents
• Mix requirements with implementation notes
• Include TODOs or "TBD" items - resolve before finalizing

Acceptance Criteria Best Practices

Each criterion should be:

- [ ] [Component] [Action] [Condition] [Expected Result]

Good Examples:

- [ ] `ralph query` returns JSON with `tasks` array containing all pending tasks
- [ ] `ralph task add "desc"` creates task with auto-generated ID matching `t-[a-z0-9]{4}`
- [ ] Build fails gracefully when spec file not found (exit code 1, error message to stderr)
- [ ] Timeout kills long-running task after `timeout_ms` milliseconds and sets `kill_reason: "timeout"`

Bad Examples:

- [ ] System works correctly  <!-- Too vague -->
- [ ] Performance is acceptable  <!-- Not measurable -->
- [ ] Errors are handled  <!-- No specific behavior -->
- [ ] Tests pass  <!-- Which tests? What constitutes passing? -->

Handling Complexity

Large Features

Break into multiple specs with clear boundaries:

ralph/specs/
  auth-core.md        # Core authentication logic
  auth-oauth.md       # OAuth provider integration
  auth-sessions.md    # Session management

Reference related specs: "See auth-core.md for base authentication flow."

Dependencies

State dependencies explicitly at the top of Requirements:

## Requirements

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

### Feature Requirements
...

Phased Implementation

Use acceptance criteria groupings:

## Acceptance Criteria

### Phase 1: Core
- [ ] Basic functionality works
- [ ] Happy path tested

### Phase 2: Edge Cases  
- [ ] Error handling complete
- [ ] All edge cases covered

### Phase 3: Polish
- [ ] Performance optimized
- [ ] Documentation complete

Example: Minimal Spec

# Widget Counter

## Overview

Track widget creation and deletion counts per user for billing purposes.

## Requirements

### Data Model

Store counts in `widget_counts` table:

| Column | Type | Description |
|--------|------|-------------|
| `user_id` | UUID | User identifier |
| `created` | INT | Widgets created |
| `deleted` | INT | Widgets deleted |

### API

`GET /api/users/{id}/widget-count`

Returns:
```json
{"user_id": "...", "created": 0, "deleted": 0, "net": 0}

net = created - deleted

Constraints

• Counts must never go negative
• Updates must be atomic (no lost increments under concurrency)

Acceptance Criteria

• widget_counts table created with correct schema
• GET /api/users/{id}/widget-count returns JSON with all fields
• Creating widget increments created count
• Deleting widget increments deleted count
• Concurrent updates don't lose increments (test with 100 parallel requests)
• Attempting to decrement below 0 returns 400 error

## Example: Complex Spec (Abbreviated)

```markdown
# Construct Mode

## Overview

Construct mode is Ralph's autonomous execution mode for implementing specs...

## Architecture

┌──────────────┐ │ CONSTRUCT │ │ MODE ENTRY │ └──────┬───────┘ v ┌──────────────────────────────────────┐ │ ITERATION N │ │ INVESTIGATE -> BUILD -> VERIFY │ │ │ │ │ │ │ v v v │ │ [FAILURE?]──> DECOMPOSE ──> NEXT │ └──────────────────────────────────────┘

## Requirements

### Stage: INVESTIGATE
...

### Stage: BUILD
...

### Stage: VERIFY
...

### Stage: DECOMPOSE
...

### Failure Conditions

| Condition | Trigger | Response |
|-----------|---------|----------|
| Timeout | Stage exceeds `timeout_ms` | Kill, decompose |
| Context | Usage > 95% | Kill, decompose |

## CLI Commands

| Command | Description |
|---------|-------------|
| `ralph construct [spec]` | Enter construct mode |
| `ralph query stage` | Get current stage |

## Configuration

| Field | Default | Description |
|-------|---------|-------------|
| `timeout_ms` | 300000 | Max time per stage |
| `max_iterations` | 10 | Iteration limit |

## Acceptance Criteria

### Core Flow
- [ ] Three-phase iteration: INVESTIGATE -> BUILD -> VERIFY
- [ ] BUILD processes tasks in priority order
- [ ] VERIFY accepts or rejects each done task
...

### Failure Handling
- [ ] Timeout triggers DECOMPOSE stage
- [ ] Context limit triggers DECOMPOSE stage
...

Verification Checklist

Before finalizing a spec, verify:

1. Completeness

   • All requirements have acceptance criteria
   • All edge cases are specified
   • All error conditions are defined

2. Clarity

   • No ambiguous language
   • All terms defined
   • Examples provided for complex formats

3. Testability

   • Each criterion is pass/fail verifiable
   • Test commands/methods are specified where relevant
   • Expected outputs are exact, not approximate

4. Structure

   • Required sections present
   • Logical organization
   • Consistent formatting

5. Scope

   • Single coherent feature
   • Dependencies explicitly stated
   • No circular dependencies with other specs
   • No task-level circular dependencies (code tasks don't require tests that depend on that code)

Common Mistakes

Avoiding Task-Level Circular Dependencies

CRITICAL: When Ralph generates tasks from a spec, acceptance criteria that reference tests can create unfulfillable dependencies.

The Anti-Pattern

If your spec implies this task structure:

Task A: "Extract foo.py"
  accept: "test_foo.py passes"
  
Task B: "Write test_foo.py"  
  deps: [Task A]  # Can't write tests until code exists

Task A can never pass verification because:

1. Task A's acceptance requires test_foo.py to pass
2. test_foo.py doesn't exist yet (it's Task B)
3. Task B depends on Task A completing first
4. Deadlock: Task A rejected forever

Solutions

Option 1: Import-only acceptance for code tasks

Acceptance criteria for extraction/implementation tasks should verify the code works, not that tests pass:

## Acceptance Criteria
- [ ] `from mymodule.foo import FooClass, foo_helper` works
- [ ] `FooClass().process()` returns expected result for basic input

Keep test requirements in separate test-focused criteria:

- [ ] `pytest tests/unit/test_foo.py` passes

Ralph will generate separate tasks, and the test task will naturally depend on the code task.

Option 2: Bundle code + test in one task

If you want tests written alongside code, make it explicit in the same criterion:

- [ ] `foo.py` implements FooClass with `process()` method AND `test_foo.py` covers basic functionality

This creates a single task that includes both.

Option 3: Test-first with stubs

Write tests first against a stub/interface:

- [ ] `test_foo.py` exists with tests against FooInterface
- [ ] `foo.py` implements FooInterface; all tests pass

Verification Patterns That Work

Verification Patterns That Fail

Integration with Ralph Workflow

Once the spec is written:

1. Plan: ralph plan <spec> generates tasks from the spec (stored in ralph/plan.jsonl)
2. Construct: ralph construct <spec> enters construct mode, running the staged loop:
   • INVESTIGATE: Converts issues into actionable tasks
   • BUILD: Executes tasks in priority/dependency order
   • VERIFY: Checks done tasks against acceptance criteria, creates new work for gaps
   • DECOMPOSE: Breaks down failed tasks that exceeded context/timeout limits
3. Iterate: The loop continues until all acceptance criteria are satisfied

Stage Flow

INVESTIGATE -> BUILD -> VERIFY
     ^                    |
     |     [gaps found]   |
     +--------------------+
            
     [failure: timeout/context]
              |
              v
         DECOMPOSE
              |
              v
      (next iteration)

The acceptance criteria section is parsed by VERIFY stage - each unchecked item (- [ ]) becomes a verification target.

Tips for Spec Authors

1. Start with acceptance criteria - Write what "done" looks like first, then fill in requirements
2. Use concrete examples - Show exact inputs and outputs
3. Think like a verifier - Can someone unfamiliar with the code check each criterion?
4. Be explicit about non-requirements - "This feature does NOT handle X" prevents scope creep
5. Version your specs - Major changes should create new spec files
6. Keep tasks atomic - Each task should be completable in ONE iteration (< context limit)
7. Consider context pressure - Break large features into smaller specs to avoid DECOMPOSE cycles

Log Files

Ralph logs are stored in /tmp/ralph-logs/<repo>/<branch>/<spec>/.

Example: /tmp/ralph-logs/neo-mittens/main/my-feature/ralph-20260120_162538-build.log

Logs are organized by:

• repo: Repository name (e.g., neo-mittens)
• branch: Git branch (e.g., main, feature-x)
• spec: Spec name without .md extension

Logs are auto-cleared on system restart.

Ralph CLI Commands Reference

Planning Commands

Plan mode behavior:

• Prompts to clear/keep existing tasks before starting
• Uses batch ralph task add '[...]' for efficiency
• Runs multiple iterations for complex specs
• Minimum 15 minute timeout per iteration

Task Commands

Batch add example:

ralph task add '[
  {"name": "Create config module", "notes": "Create app/ralph/config.py with GlobalConfig...", "accept": "import works"},
  {"name": "Create state module", "notes": "Create app/ralph/state.py...", "accept": "import works", "deps": ["t-xxx"]}
]'

Batch add is faster (single save) and supports intra-batch dependencies.

Issue Commands

Task Relationships

Tasks can have relationships for traceability:

Example with relationships:

ralph task add '{"name": "Fix race in Worker", "notes": "Add mutex", "accept": "TSAN clean", "created_from": "i-abc1", "priority": "high"}'

Context Management

Ralph uses tiered context management to preserve work:

When writing specs, keep in mind:

• Large specs cause DECOMPOSE cycles - Break into smaller focused specs
• Acceptance criteria should be independently testable - Each criterion should be verifiable without running the entire system
• Include test commands - Make verification concrete: "Run pytest tests/test_foo.py"