maksutovic/joycraft-decompose

Decompose Feature into Atomic Specs

You have a Feature Brief (or the user has described a feature). Your job is to decompose it into atomic specs that can be executed independently — one spec per session.

Step 1: Verify the Brief Exists

Look for a Feature Brief in docs/briefs/. If one doesn't exist yet, tell the user:

No feature brief found. Run $joycraft-new-feature first to interview and create one, or describe the feature now and I'll work from your description.

If the user describes the feature inline, work from that description directly. You don't need a formal brief to decompose — but recommend creating one for complex features.

Step 2: Identify Natural Boundaries

Why: Good boundaries make specs independently testable and committable. Bad boundaries create specs that can't be verified without other specs also being done.

Read the brief (or description) and identify natural split points:

• Data layer changes (schemas, types, migrations) — always a separate spec
• Pure functions / business logic — separate from I/O
• UI components — separate from data fetching
• API endpoints / route handlers — separate from business logic
• Test infrastructure (mocks, fixtures, helpers) — can be its own spec if substantial
• Configuration / environment — separate from code changes

Ask yourself: "Can this piece be committed and tested without the other pieces existing?" If yes, it's a good boundary.

Step 3: Build the Decomposition Table

For each atomic spec, define:

| # | Spec Name | Description | Dependencies | Size | |---|-----------|-------------|--------------|------|

Rules:

• Each spec name is verb-object format (e.g., add-terminal-detection, extract-prompt-module)
• Each description is ONE sentence — if you need two, the spec is too big
• Dependencies reference other spec numbers — keep the dependency graph shallow
• More than 2 dependencies on a single spec = it's too big, split further
• Aim for 3-7 specs per feature. Fewer than 3 = probably not decomposed enough. More than 10 = the feature brief is too big

Step 4: Present and Iterate

Show the decomposition table to the user. Ask:

1. "Does this breakdown match how you think about this feature?"
2. "Are there any specs that feel too big or too small?"
3. "Should any of these run in parallel (separate branches)?"

Iterate until the user approves.

Step 5: Generate Atomic Specs

For each approved row, create docs/specs/<feature-name>/spec-name.md. Derive the feature-name from the brief filename (strip the date prefix and .md — e.g., 2026-04-06-token-discipline.md → token-discipline). If no brief exists, use a user-provided or inferred feature name (slugified to kebab-case). Create the docs/specs/<feature-name>/ directory if it doesn't exist.

Why: Each spec must be self-contained — a fresh session should be able to execute it without reading the Feature Brief. Copy relevant constraints and context into each spec.

Use this structure:

# [Verb + Object] — Atomic Spec

> **Parent Brief:** `docs/briefs/YYYY-MM-DD-feature-name.md` (or "standalone")
> **Status:** Ready
> **Date:** YYYY-MM-DD
> **Estimated scope:** [1 session / N files / ~N lines]

---

## What
One paragraph — what changes when this spec is done?

## Why
One sentence — what breaks or is missing without this?

## Acceptance Criteria
- [ ] [Observable behavior]
- [ ] Build passes
- [ ] Tests pass

## Test Plan

| Acceptance Criterion | Test | Type |
|---------------------|------|------|
| [Each AC above] | [What to call/assert] | [unit/integration/e2e] |

**Execution order:**
1. Write all tests above — they should fail against current/stubbed code
2. Run tests to confirm they fail (red)
3. Implement until all tests pass (green)

**Smoke test:** [Identify the fastest test for iteration feedback]

**Before implementing, verify your test harness:**
1. Run all tests — they must FAIL (if they pass, you're testing the wrong thing)
2. Each test calls your actual function/endpoint — not a reimplementation or the underlying library
3. Identify your smoke test — it must run in seconds, not minutes, so you get fast feedback on each change

## Constraints
- MUST: [hard requirement]
- MUST NOT: [hard prohibition]

## Affected Files
| Action | File | What Changes |
|--------|------|-------------|

## Approach
Strategy, data flow, key decisions. Name one rejected alternative.

## Edge Cases
| Scenario | Expected Behavior |
|----------|------------------|

If docs/templates/ATOMIC_SPEC_TEMPLATE.md exists, reference it for the full template with additional guidance.

Fill in all sections — each spec must be self-contained (no "see the brief for context"). Copy relevant constraints from the Feature Brief into each spec. Write acceptance criteria specific to THIS spec, not the whole feature. Every acceptance criterion must have at least one corresponding test in the Test Plan. If the user provided test strategy info from the interview, use it to choose test types and frameworks. Include the test harness verification rules in every Test Plan.

Step 6: Recommend Execution Strategy

Based on the dependency graph:

• Independent specs — "These can run in parallel branches"
• Sequential specs — "Execute these in order: 1 -> 2 -> 4"
• Mixed — "Start specs 1 and 3 in parallel. After 1 completes, start 2."

Update the Feature Brief's Execution Strategy section with the plan (if a brief exists).

Step 7: Hand Off

Tell the user:

Decomposition complete:
- [N] atomic specs created in docs/specs/
- [N] can run in parallel, [N] are sequential
- Estimated total: [N] sessions

To execute:
- Sequential: Open a session, point at each spec in order
- Parallel: One spec per branch, merge when done
- Each session should end with $joycraft-session-end to capture discoveries

Ready to start execution?

Tip: Run /new before starting the next step. Your artifacts are saved to files — this conversation context is disposable.