Ralph Research

---
description: Generate JTBD-aligned specifications through interactive discovery
model: opus
---

# Generate Specifications

You are tasked with creating a set of JTBD-aligned specification files through an interactive, iterative process. Your goal is to deeply understand what we're building, break it into well-scoped topics of concern, and produce one `specs/*.md` file per topic.

You should be skeptical, thorough, and work collaboratively with the user to clarify the jobs-to-be-done before writing any specs.

## Initial Response

When this command is invoked:

1. **Check if parameters were provided**:

   - If a file path, URL, or description was provided as a parameter, skip the default message
   - Immediately read any provided files FULLY
   - Begin the discovery process

2. **If no parameters provided**, respond with:

I'll help you define specifications for what we're building. Let me start by understanding the jobs-to-be-done.

Please provide any of the following:

1. A description of what you want to build (or a PRD/brief file path)
2. URLs to reference materials, APIs, or inspiration
3. Any constraints, target audience, or specific requirements

I'll research everything you provide, then work with you to break this into well-scoped specifications.

Then wait for the user's input.

## Process Steps

### Step 1: Context Gathering

1. **Read all mentioned files immediately and FULLY**:

   - PRDs, briefs, requirement docs
   - Existing specs or design documents
   - Any referenced data files or configs
   - **IMPORTANT**: Use the Read tool WITHOUT limit/offset parameters to read entire files
   - **CRITICAL**: DO NOT spawn sub-tasks before reading these files yourself in the main context
   - **NEVER** read files partially - if a file is mentioned, read it completely

2. **Spawn parallel research tasks to gather external context**:

   Before asking the user any questions, use specialized agents to research in parallel:

   - For each URL the user provides, spawn a Task with `subagent_type="url-reader"` (1 task per URL, max ~10 concurrent). Do NOT use `general-purpose` for URL fetching.
   - If an existing codebase is referenced, use the **codebase-analyzer** agent to understand current state (scope by relevant directories, not the whole repo)
   - If existing `specs/*` files exist, read them ALL to understand what's already defined

   Prefer few, focused agents over many scattered ones. Each agent should have a clear, singular research objective and return a structured summary.

3. **Read all results from research tasks fully into main context**

4. **Synthesize your understanding**:

   - What is the high-level goal?
   - Who is the target user/audience?
   - What outcomes do they want (Jobs to Be Done)?
   - What constraints or requirements exist?
   - What did the external research reveal?

### Step 2: JTBD Discovery & Clarification

1. **Present your understanding and ask focused questions**:

Based on what you've shared and my research, here's my understanding:

What we're building: [concise summary] For whom: [target audience/user] Key JTBDs I see:

1. [Job to be done - outcome-oriented, not feature-oriented]
2. [Job to be done]
3. [Job to be done]

From my research:

• [Key insight from URL/doc research]
• [Constraint or pattern discovered]
• [Relevant prior art or API detail]

Questions I need answered:

• [Specific question that research couldn't answer]
• [Ambiguity that requires human judgment]
• [Scope decision that affects breakdown]

Only ask questions you genuinely cannot answer through research. Prefer presenting your best understanding and letting the user correct you.

2. **If the user corrects any misunderstanding**:

- DO NOT just accept the correction
- Spawn new research tasks to verify if needed
- Read any newly mentioned files or URLs
- Only proceed once you've verified the facts yourself

3. **Iterate until JTBDs are clear and agreed upon**

### Step 3: Topic Decomposition

Once JTBDs are understood:

1. **Break each JTBD into topics of concern**:

A topic of concern is a distinct aspect or component within a JTBD. Each topic will become one spec file.

**Apply the Scope Test** — Can you describe the topic in one sentence without "and" conjoining unrelated capabilities?

- ✓ "The color extraction system analyzes images to identify dominant colors"
- ✗ "The user system handles authentication, profiles, and billing" → 3 topics

2. **Present the decomposition for review**:

Here's how I'd break this down into specs:

JTBD: [Job to be done] Topics:

• [topic-a] — [one-sentence description]
• [topic-b] — [one-sentence description]

JTBD: [Job to be done] Topics:

• [topic-c] — [one-sentence description]
• [topic-d] — [one-sentence description]

Each topic becomes one spec file in specs/. Does this decomposition feel right? Too granular? Too broad? Any missing topics?

3. **Iterate on decomposition** until the user is satisfied:

- Merge topics if they're too granular
- Split topics that fail the scope test
- Add missing topics the user identifies
- Reorder or re-parent topics across JTBDs if needed

### Step 4: Spec Writing

After decomposition is approved:

1. **For each topic, spawn a parallel subagent** to draft the spec file:

- Provide the subagent with: full context from Steps 1-3, the specific topic scope, and all relevant research findings
- Each subagent writes one `specs/[topic-name].md` file
- One subagent per topic, running in parallel

2. **Spec file structure** (required sections only, keep concise):

```markdown
# [Topic Name]

## Overview

[What this topic covers and why it matters. Keep brief — a short paragraph, not an essay.]

## Requirements

[What must be true when this is fully implemented. Behavioral, observable outcomes — no