Ralphie Spec Generation (V2 Format) Skill

Ralphie Spec Generation (V2 Format)

Generate comprehensive specs using the V2 format with task IDs, status tracking, and size-based budgeting through structured interviews with the user.

When to Use

User is present and can answer questions
Complex projects needing clarification
When requirements need discussion

80/20 Integration

This skill works with Ralphie's compound engineering features:

Research Phase (optional): If Ralphie ran ralphie spec with research, findings are in .ralphie/research-context.md
Analysis Phase (optional): After spec generation, Ralphie may analyze for gaps (saved to .ralphie/analysis.md)
Interactive Review: Since user is present, gaps are discussed and resolved in real-time

The skill checks for these files and incorporates findings, but doesn't trigger research/analysis itself (that's the CLI's job).

Output Location

Write specs to .ralphie/specs/active/{name}.md:

Generate a kebab-case filename from the description
Example: "user authentication" → .ralphie/specs/active/user-authentication.md
Only one spec allowed in .ralphie/specs/active/ at a time

Workflow

Check Research → Interview User → Explore Codebase → Draft Tasks → Size Review → Write V2 Spec → Check Analysis → Review Gaps → Present for Approval

80/20 Philosophy: Research and analysis are part of the 80% (planning). Incorporate their findings to make specs thorough.

Step 0: Check for Research Context (Optional)

Before interviewing, check if Ralphie ran research:

cat .ralphie/research-context.md 2>/dev/null

If the file exists:

Read it to understand codebase patterns, conventions, and framework best practices
Use findings to inform your interview questions
Reference research in Context section of final spec

If it doesn't exist, skip this step—interview will gather requirements directly from user.

Step 1: Interview User

Use AskUserQuestion to gather requirements in batches of 2-4 questions.

Batch 1: Project Foundation

AskUserQuestion({
  questions: [
    {
      question: "What type of project is this?",
      header: "Type",
      multiSelect: false,
      options: [
        { label: "CLI tool", description: "Command-line application" },
        { label: "Web API", description: "REST/GraphQL backend" },
        { label: "Library", description: "Reusable package" },
        { label: "Full-stack", description: "Frontend + backend" }
      ]
    },
    {
      question: "What language/framework?",
      header: "Stack",
      multiSelect: false,
      options: [
        { label: "TypeScript/Node.js (Recommended)", description: "Modern JS with types" },
        { label: "Python", description: "Great for data, ML, scripting" },
        { label: "Go", description: "Fast, good for systems" },
        { label: "Rust", description: "Memory-safe systems" }
      ]
    }
  ]
})

Batch 2: Requirements

AskUserQuestion({
  questions: [
    {
      question: "What is the primary use case?",
      header: "Use Case",
      multiSelect: false,
      options: [
        { label: "Internal tool", description: "Used by your team" },
        { label: "Public product", description: "External users" },
        { label: "Library/SDK", description: "For other developers" },
        { label: "Learning/experiment", description: "Personal project" }
      ]
    },
    {
      question: "What's the testing expectation?",
      header: "Testing",
      multiSelect: false,
      options: [
        { label: "Unit tests only (Recommended)", description: "Test individual functions" },
        { label: "Unit + Integration", description: "Test components together" },
        { label: "Full coverage", description: "Unit + Integration + E2E" },
        { label: "Minimal/none", description: "Prototype or spike" }
      ]
    }
  ]
})

Batch 3: Scope

Follow up based on previous answers:

"What external services or APIs does this integrate with?"
"Are there auth requirements? (none / basic / OAuth)"
"What's the priority: MVP or full feature set?"

Interview Tips

If answers are vague, ask for specific examples
Clarify: "Is X a must-have or nice-to-have?"
Don't proceed until core requirements are clear

Step 2: Explore Codebase

If this is a brownfield project (existing code), explore it:

2.1 Check for Existing Code

ls package.json pyproject.toml go.mod Cargo.toml 2>/dev/null

2.2 Understand Structure

Glob("src/**/*")
Glob("lib/**/*")

2.3 Read Context

README.md - Project description
CLAUDE.md - AI instructions
specs/lessons.md - Past learnings to apply
Main entry points

2.4 Detect Patterns

Grep("export function", path="src/")
Grep("(describe|test)\\(", path="tests/")

Step 3: Draft Tasks with Sizes

Before writing the spec, draft tasks and estimate sizes.

Size Guidelines

| Size | Points | Criteria | Examples | |------|--------|----------|----------| | S | 1 | Single file, simple logic, < 50 lines | Config setup, type definition, simple util | | M | 2 | Multiple files, moderate logic, 50-200 lines | CRUD endpoint, feature module | | L | 4 | Complex feature, architectural changes, 200+ lines | Auth system, major refactor |

Draft Format

Create a mental or written draft:

T001: Setup project structure [S]
T002: Implement core data model [M]
T003: Add authentication [L]
T004: Create API endpoints [M]
T005: Add tests [M]

Step 4: Size Review with User

Present the task breakdown and ask for size confirmation:

AskUserQuestion({
  questions: [
    {
      question: "Here's my task breakdown with size estimates. Do these sizes seem accurate?",
      header: "Sizes",
      multiSelect: false,
      options: [
        { label: "Looks good", description: "Proceed with these estimates" },
        { label: "Some too small", description: "I'll bump up specific tasks" },
        { label: "Some too large", description: "Let's split into smaller tasks" },
        { label: "Discuss changes", description: "I have specific feedback" }
      ]
    }
  ]
})

Show the summary:

## Proposed Tasks

| ID | Task | Size | Points |
|----|------|------|--------|
| T001 | Setup project structure | S | 1 |
| T002 | Implement core data model | M | 2 |
| T003 | Add authentication | L | 4 |
| T004 | Create API endpoints | M | 2 |
| T005 | Add tests | M | 2 |

**Total: 11 points** (~3 iterations at 4 pts/iteration)

Adjust based on feedback before writing the spec.

Step 5: Write V2 Spec

Format

# Feature Name

Goal: One-sentence description of what this achieves when complete.

## Context

Background information for the agent implementing this spec:
- What problem does this solve?
- What existing code/patterns should it follow?
- Any constraints or requirements?
- (If research was conducted) Key findings from codebase research

## Tasks

### T001: First task title
- Status: pending
- Size: S

**Deliverables:**
- What to build (WHAT, not HOW)
- Another deliverable

**Verify:** `npm test -- something`

---

### T002: Second task title
- Status: pending
- Size: M

**Deliverables:**
- Deliverable description
- Another deliverable

**Verify:** `curl localhost:3000/api` returns 200

---

### T003: Third task title
- Status: pending
- Size: S

**Deliverables:**
- Deliverable description

**Verify:** `npm run type-check` passes

---

## Acceptance Criteria

- WHEN user does X, THEN Y happens
- WHEN condition Z, THEN expected outcome

## Notes

<!-- AI updates this section during implementation -->

### Interview Summary
- Project type: [from interview]
- Stack: [from interview]
- Key decisions: [from interview]

V2 Format Rules

| Element | Format | Example | |---------|--------|---------| | Task ID | ### T###: | ### T001: Setup database | | Status | - Status: pending | Always pending for new specs | | Size | - Size: S\|M\|L | - Size: M | | Deliverables | **Deliverables:** + bullets | See template | | Verify | **Verify:** + command | **Verify:** \npm test`| | Separator |---` between tasks | Required |

Content Rules

| Rule | Do | Don't | |------|-----|-------| | Task count | 3-10 total | 20+ micro-tasks | | IDs | Sequential T001, T002... | T1, Task-1, random | | Status | Always pending for new specs | Leave blank | | Size | User-confirmed estimates | Skip or guess | | Sub-bullets | Deliverables (WHAT) | Instructions (HOW) | | Code | Only in Verify: | In task descriptions | | File paths | Never in tasks | src/auth.ts:42 | | Batching | Related work = 1 task | Split into tiny pieces |

Step 6: Check for Analysis (Optional)

After writing the spec, check if Ralphie ran analysis:

cat .ralphie/analysis.md 2>/dev/null

If the file exists:

Read it to identify any gaps, edge cases, or missing elements
Analysis may include:
- Missing error handling scenarios
- Unclear user flows
- Missing verify commands or test coverage
- Tasks that should be split
- Integration points not addressed

If gaps found:

Review each concern
Decide with user whether to:
- Revise spec to address gaps
- Accept as-is (document why in spec Notes)
- Add follow-up tasks

If analysis doesn't exist, skip to Step 7.

Step 7: Present for Approval

Write spec to .ralphie/specs/active/{name}.md and present summary:

## Spec Created

`.ralphie/specs/active/{name}.md` created with X tasks (Y size points total).

### Task Summary
| ID | Task | Size |
|----|------|------|
| T001 | First task | S |
| T002 | Second task | M |
...

### Estimated Effort
- Total points: Y
- Iterations needed: ~Z (at 4 pts/iteration)

### Research Findings (if available)
- [Key pattern 1 from research-context.md]
- [Key pattern 2 from research-context.md]

### Analysis Results (if available)
- ✅ All critical flows covered
- ⚠️ [Gap 1] - [How we addressed it or why it's acceptable]
- ⚠️ [Gap 2] - [How we addressed it or why it's acceptable]

### Key Decisions from Interview
- [Decision 1]
- [Decision 2]

Please review the spec. Ready to start with `ralphie run`?

The user reviews and approves. Since user is present, analysis gaps are discussed and resolved during the interview—no additional automated review needed.

Quick Reference

| Check | Pass | Fail | |-------|------|------| | Location | specs/active/*.md | Missing or wrong directory | | Task IDs | ### T001: | - [ ], ### Task 1: | | Status | - Status: pending | Missing or blank | | Size | - Size: S\|M\|L (user confirmed) | Missing or unconfirmed | | Deliverables | **Deliverables:** + bullets | Missing section | | Verify | **Verify:** \cmd`| Missing section | | Separators |---between tasks | None | | Code | Only in Verify | In task descriptions | | Files | No paths |src/file.ts:42` |

Agent Skills: Ralphie Spec Generation (V2 Format)

Install this agent skill to your local

Skill Files