home / skills / matthew-plusprogramming / monorepo / atomize

atomize skill

safe

This skill decomposes a high-level spec into atomic, independently testable, deployable, and reviewable units to improve clarity and traceability.

npx playbooks add skill matthew-plusprogramming/monorepo --skill atomize

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

3.6 KB

---
name: atomize
description: Decompose high-level specs into atomic specs
allowed-tools: Read, Glob, Task
user-invocable: true
---

# /atomize Skill

## Purpose

Decompose a high-level spec (`spec.md`) into atomic specs—units that are independently testable, deployable, reviewable, and reversible.

## Usage

```
/atomize                      # Decompose current spec group
/atomize <spec-group-id>      # Decompose specific spec group
/atomize --refine             # Re-run with enforcer feedback
/atomize --auto-enforce       # Decompose + iterate until /enforce passes
```

## Prerequisites

Before running `/atomize`:
1. Spec group must exist with `manifest.json`
2. `requirements.md` must exist (from `/prd sync` or `/pm`)
3. `spec.md` must exist (from `/spec`)

## Process

### Standard Mode

1. **Locate spec group**
   - If no ID provided, look for active spec group in `.claude/specs/groups/`
   - Validate `manifest.json`, `requirements.md`, `spec.md` exist

2. **Dispatch atomizer agent**
   ```
   Task: atomizer
   Prompt: Decompose spec.md into atomic specs
   Input: <spec-group-path>
   ```

3. **Review output**
   - Atomizer creates `atomic/as-XXX-*.md` files
   - Updates `manifest.json` with counts and coverage

4. **Report to user**
   - Number of atomic specs created
   - Requirements coverage percentage
   - Suggest running `/enforce` to validate

### Refine Mode (`--refine`)

1. **Read enforcement report**
   - Look for `enforcement-report.md` in spec group
   - Extract TOO_COARSE, TOO_GRANULAR, MISSING_COVERAGE items

2. **Dispatch atomizer with feedback**
   ```
   Task: atomizer
   Prompt: Refine atomic specs based on enforcement feedback
   Input: <spec-group-path>, <enforcement-report>
   ```

3. **Report changes**
   - Which specs were split
   - Which specs were merged
   - New coverage percentage

### Auto-Enforce Mode (`--auto-enforce`)

1. Run standard decomposition
2. Automatically run `/enforce`
3. If FAILING:
   - Run `--refine` with feedback
   - Re-run `/enforce`
   - Repeat until PASSING or max iterations (3)
4. Report final status

## Output

### On Success

```
Atomization complete for sg-logout-feature

Created 5 atomic specs:
  - as-001-logout-button-ui
  - as-002-auth-token-clear
  - as-003-session-invalidation
  - as-004-redirect-to-login
  - as-005-error-handling

Requirements coverage: 100% (4/4 requirements)

Next step: Run /enforce to validate atomicity criteria
```

### On Failure

```
Atomization failed for sg-logout-feature

Error: requirements.md not found
Run /pm or /prd sync first to generate requirements
```

## Integration with Workflow

```
/pm or /prd sync
    ↓
requirements.md created
    ↓
/spec
    ↓
spec.md created
    ↓
/atomize          ← YOU ARE HERE
    ↓
atomic/ specs created
    ↓
/enforce
    ↓
(if failing) /atomize --refine
    ↓
User reviews summary → APPROVED
    ↓
/implement + /test
```

## Edge Cases

### No Active Spec Group
```
Error: No active spec group found
Create one with /prd sync <doc-id> or /pm
```

### Already Has Atomic Specs
```
Warning: Spec group already has 3 atomic specs
Options:
  1. /atomize --refine (preserve and refine)
  2. /atomize --fresh (delete and recreate)
```

### Requirements Changed After Atomization
```
Warning: requirements.md modified after last atomization
Re-run /atomize to ensure coverage
```

## State Transitions

After successful `/atomize`:
- `manifest.json` updated:
  - `atomic_specs.count`: N
  - `atomic_specs.coverage`: "X%"
  - `atomic_specs.enforcement_status`: "not_run"
- Decision log entry added
- Spec group remains in current `review_state` (still needs `/enforce` + user approval)

Overview

This skill decomposes a high-level spec into atomic specs—small, independently testable and reviewable units that map directly to requirements. It produces markdown atomic spec files, updates the spec group's manifest with counts and coverage, and reports next steps. The tool supports refinement based on enforcement feedback and an auto-enforce loop to iterate until atomicity checks pass or a limit is reached.

How this skill works

The atomizer locates an active spec group, validates that manifest, requirements, and spec documents exist, then generates atomic/as-XXX-*.md files representing discrete deliverables. In refine mode it ingests an enforcement report to split, merge, or add specs to address TOO_COARSE, TOO_GRANULAR, and MISSING_COVERAGE items. Auto-enforce runs atomization, triggers enforcement, and repeats refinement up to a maximum iteration count if checks fail.

When to use it

After requirements.md and spec.md are present and you need testable units
When preparing a feature for implementation and review
To convert high-level product intent into deployable, reversible tasks
When enforcement reports indicate poor granularity or missing coverage
As part of a CI step before /implement and /test

Best practices

Run /pm or /prd sync first so requirements.md is current
Start with standard mode, then run /enforce and use --refine only if needed
Keep atomic specs focused: one behavior or observable outcome per spec
Re-run atomize after requirements change to maintain coverage
Limit auto-enforce iterations to a small number (default 3) to avoid churn

Example use cases

Decomposing a logout feature into UI, token clear, session invalidation, redirect, and error handling specs
Refining atomic specs after enforcement flags coverage gaps or overly coarse items
Automating decomposition + validation in a pre-implementation CI pipeline
Recovering from a changed requirement by re-running atomize to update atomic spec set

FAQ

What happens if requirements.md is missing?

Atomization fails and reports the missing requirements; run /pm or /prd sync to create them, then retry.

How does --auto-enforce stop infinite loops?

Auto-enforce repeats atomize + enforce up to a configured max iterations (typically 3) and then stops with the last status.