Create Ralph Topics

---
description: Decompose JTBD into Topics of Concern and write behavioral spec files
model: opus
---

# Create Ralph Topics

You are tasked with taking a Jobs to Be Done document and decomposing it into **Topics of Concern** — the distinct, scoped aspects of each job that each become a standalone behavioral specification file. This is the bridge between strategic JTBD thinking and actionable specs that a planning/building loop can consume.

## Core Concept

A **Topic of Concern** is a single, cohesive capability area within a JTBD. The scoping test:

> "Can you describe this topic in one sentence without conjoining unrelated capabilities?"

- **Pass**: "The discovery engine analyzes CLI help output to extract a structured command tree"
- **Fail**: "The provider system handles discovery, policy enforcement, and config persistence" → that's 3 topics

Each topic produces exactly one spec file. The relationship:
- 1 JTBD → N topics of concern
- 1 topic → 1 spec file (`thoughts/shared/specs/NN-topic-name.md`)
- 1 spec → N tasks (consumed by planning/building loops later)

## Initial Response

When this command is invoked:

1. **Check if a JTBD document path was provided**:
   - If yes, read it fully before proceeding
   - If a JTBD path and a focus area were provided, scope to that area

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

I'll decompose your JTBD into Topics of Concern and write spec files.

I need:

1. The path to a JTBD document (e.g., thoughts/shared/jtbd/YYYY-MM-DD-description.md)
2. Optionally, a specific job story to focus on (e.g., "JS-001" or "registration")

If no JTBD document exists yet, run /create_jtbd first.

Tip: /create_ralph_topics thoughts/shared/jtbd/YYYY-MM-DD-description.md

Then wait for the user's input.

## Process Steps

### Step 1: Load Context

1. **Read the JTBD document completely** — this is your primary input
2. **Read SPEC.md completely** — this grounds topics in what the product actually specifies
3. **Read any other files the user mentions** fully
4. **Do NOT spawn sub-tasks yet** — understand the JTBD and spec yourself first

### Step 2: Codebase Research

You need to understand what exists so topics align with real code boundaries.

1. **Spawn parallel research agents**:

   - A **codebase-locator** agent: "Find all source directories, entry points, exported modules, and config files across the entire project. Return a map of what capability lives where."
   - A **codebase-analyzer** agent: "Analyze the domain model — types, entities, interfaces, data structures. What concepts does the system model? How are they related?"
   - A **codebase-pattern-finder** agent: "Find the natural boundaries in the codebase — which files/modules are tightly coupled? Which are independent? Where are the seams between concerns?"
   - If `thoughts/shared/specs/` directory exists, a **codebase-analyzer** agent: "Read all existing spec files and summarize what topics are already covered"
   - If `thoughts/` directory exists, a **thoughts-locator** agent: "Find any existing topic decompositions, research, or architectural decisions"

2. **Wait for ALL agents to complete**

3. **Synthesize**: You now understand:
   - The jobs (from JTBD document)
   - The spec (from SPEC.md)
   - The code boundaries (from research)
   - Any existing specs (from `thoughts/shared/specs/` if present)

### Step 3: Identify Topics of Concern

For each Job Story in the JTBD document:

1. **List the distinct capabilities** the job requires
2. **Group tightly-coupled capabilities** — things that must change together are one topic
3. **Split loosely-coupled capabilities** — things that can be built/tested independently are separate topics
4. **Apply the one-sentence test** to each candidate topic
5. **Frame as activities** (verbs, not nouns) when possible:
   - Prefer: "Discover CLI command trees" over "Discovery Engine"
   - Prefer: "Enforce per-command access policy" over "Policy System"
   - This makes the user journey through topics more natural

6. **Align with code boundaries** where they exist — topics that cross major module boundaries are likely too broad

7. **Check for completeness** — every job story should be fully served by the union of topics. No gaps.

### Step 4: Build the Story Map

Arrange topics into a user journey:

[Activity 1] → [Activity 2] → [Activity 3] → [Activity 4] basic basic basic basic enhanced enhanced enhanced enhanced advanced advanced advanced advanced

- **Columns** = activities in chronological order (the journey backbone)
- **Rows** = capability depth (basic → enhanced → advanced)
- This reveals natural SLC (Simple/Lovable/Complete) release slices as horizontal cuts

### Step 5: Present Topics for Refinement

Present your decomposition to the user BEFORE writing any spec files:

Based on the JTBD document and codebase research, here are the topics I've identified:

Topics of Concern

#	Topic (Activity)	One-Sentence Description	Job Stories Served	Code Area
01	[Activity name]	[One sentence — passes the test]	JS-001, JS-003	src/...
02	[Activity name]	[One sentence]	JS-002	src/...
...	...	...	...	...

Story Map

[The journey map from Step 4]

Proposed SLC Slices

• Slice 1 (MVP): Topics 01, 03, 05 — [what this delivers]
• Slice 2: + Topics 02, 04 — [what this adds]
• Slice 3: + Topics 06, 07 — [full vision]

Validation

• Every job story is covered: [yes/no — list any gaps]
• Each topic passes one-sentence test: [yes/no]
• Topics align with code boundaries: [yes/notes]

Questions:

• [Any topics you're uncertain about]
• [Any boundaries that could go either way]

Should I adjust any topics before I write the spec files?

**Iterate** until the user approves the topic decomposition. This is the most important checkpoint — wrong topics produc