# Spec Delta

> Write a specification for a delta

- Skill: `asermax/spec-delta` (Agent Skill)
- Install (CLI): `npx skillmds@latest add asermax/spec-delta`
- Raw SKILL.md: https://api.skillmd.com/api/skills/asermax/spec-delta/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: asermax (https://skillmd.com/u/asermax)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/asermax/spec-delta

---


# Delta Specification Workflow

Write a spec for a specific delta.

## Input

Delta ID: $ARGUMENTS (e.g., "DLT-001")

## Context

**You must load the following skills and read the following files before proceeding.**

### Skills
- `katachi:framework-core` - Workflow principles
- `katachi:working-on-delta` - Per-feature workflow

### Delta inventory
- `docs/planning/DELTAS.md` - Delta definitions

### Existing spec (if present)
- `docs/delta-specs/$ARGUMENTS.md` - Current spec to update or create

### Feature documentation (for context and impact discovery)
- `docs/feature-specs/README.md` - Feature capability index
- `docs/feature-specs/` - Existing feature specifications (read specific docs as needed)
- `docs/feature-designs/README.md` - Feature design index (optional, for design context)
- Use existing feature specs to understand current behavior that delta extends/modifies

### Templates and Guides
- `${CLAUDE_PLUGIN_ROOT}/skills/working-on-delta/references/delta-spec.md` - Spec structure to follow
- `${CLAUDE_PLUGIN_ROOT}/skills/working-on-delta/references/delta-design.md` - Design structure (for seeding design doc)
- `${CLAUDE_PLUGIN_ROOT}/skills/working-on-delta/references/breadboarding.md` - UI flow guide (if needed)
- `${CLAUDE_PLUGIN_ROOT}/skills/working-on-delta/references/spike-template.md` - Spike investigation template (if needed)

## Process

### 1. Check Existing State

If `docs/delta-specs/$ARGUMENTS.md` exists:
- Read current spec
- Check for drift: Has DELTAS.md description changed?
- Summarize to user: user story, key acceptance criteria, known edge cases
- Ask: "What aspects need refinement? Or should we review the whole spec?"
- Enter iteration mode as appropriate

If no spec exists: proceed with initial creation

Update status:
```bash
python ${CLAUDE_PLUGIN_ROOT}/scripts/deltas.py status set $ARGUMENTS "⧗ Spec"
```

### 2. Research Phase (Silent)

- Read delta description from `docs/planning/DELTAS.md`
- Explore related codebase areas if needed
- For deltas involving libraries/frameworks/APIs:
  - Research typical usage patterns
  - Understand standard behaviors and edge cases
- **Identify if this is a UI delta:**
  - Does it introduce new screens or views?
  - Does it modify user navigation or workflow?
  - Does it add interactive components (forms, dialogs, buttons)?
  - If YES to any: note key interaction flows that will need breadboarding
  - If NO to all (technical delta, bug fix, API-only): will skip UI Flow section
- Build complete understanding without asking questions

### 3. User Interview

Now that I've researched the delta, I'll present my understanding and collaborate on requirements.

**Present your understanding:**

Briefly summarize:
- What the delta is trying to achieve (the core change)
- The main user story or use case
- Any assumptions about scope, constraints, or priorities
- Key areas where you see multiple valid approaches

**Identify and ask about important decisions:**

Based on your research, propose an initial Requirements table (R table) and use it as the backbone for the interview. R0 should be the core goal; include requirements from the delta description, dependencies, and research with initial status values (Core goal, Must-have, Nice-to-have). Present it as a starting point for collaborative refinement.

Use AskUserQuestion to ask focused questions about:

- **Requirements refinement:**
  - Confirm, adjust, or remove proposed requirements
  - Surface missing requirements you didn't identify
  - Negotiate priority status (Must-have vs Nice-to-have vs Out)

- **Assumptions that need confirmation:**
  - "I'm assuming [X] - is this correct?"
  - "Should this handle [edge case Y] or is that out of scope?"

- **Approach choices where multiple options exist:**
  - "For [problem area], should we [approach A] or [approach B]?"
  - Each option should have a clear description of what it means

- **Scope and priority decisions:**
  - "Should we include [feature X] in this delta or defer it?"
  - "What's more important: [quality A] or [quality B]?"

- **Behavior clarifications:**
  - "When [situation], should the system [option A] or [option B]?"
  - Present options with clear behavioral descriptions

**Guidelines for effective questions:**
- Keep questions high-level and targeted toward important decisions
- Base questions on your research findings and assumptions
- Ask only about decisions that meaningfully affect the spec
- Each question should have 2-4 specific, actionable options
- Include "Other" option automatically for user-provided alternatives
- Avoid asking about obvious details or things already clear from DELTAS.md
- Don't overwhelm - focus on the decisions that truly need user input

**After the interview:**
- Finalize the R table incorporating user's input
- Incorporate user's answers into your understanding
- Note any areas where user deferred decisions or said "it's up to you"
- Proceed to impact discovery with clarified understanding

### 4. Impact Discovery (Silent)

**Auto-discover affected features by:**

1. **Analyze delta description** - identify capability areas mentioned
2. **Search feature-specs/** - find related feature documentation:
   - Glob for all feature docs: `docs/feature-specs/**/*.md`
   - Grep for keywords from delta description
   - Identify overlapping or related capabilities

3. **Determine impact type** for each affected feature:
   - **Adds**: Creates new sub-capability within domain
   - **Modifies**: Changes existing behavior documented in feature
   - **Removes**: Deprecates or removes documented capability

4. **Note impacts** for later inclusion in "Detected Impacts" section

### 5. Draft Complete Spec (with Decision Points)

Create full spec document following template:
- User story (who/what/why - specific and clear)
- Behavior description (inputs, outputs, what can go wrong)
- **Requirements table** (finalized R table from interview)
- **Acceptance criteria** (Given/When/Then format, grouped by requirement area — each R should map to one or more AC groups)
- Dependencies (deltas that must exist first)

**Add User Flow section (conditionally):**

If this is a UI delta (identified in research phase):
1. **Read breadboarding guide**: `${CLAUDE_PLUGIN_ROOT}/skills/working-on-delta/references/breadboarding.md`
2. **Create breadboard diagram(s)** showing places, affordances, and navigation connections
3. **Write flow description** with entry point, happy path, decision points, exit points
4. **Ensure alignment with acceptance criteria** - each flow path should match criteria

If NOT a UI delta (technical, bug fix, API-only):
- **Delete the entire User Flow section from the template**
- Do not include empty breadboards

**Draft initial shape (not included in spec):**

After drafting the spec, draft an initial shape parts table:
- Identify the high-level mechanisms needed to satisfy the requirements
- Each part should describe what to build or change — a mechanism, not a constraint
- Flag parts with unknowns using ⚠️ in the Flag column, and include a description below the table for each flagged part explaining what needs investigation — the specific question or uncertainty about HOW
- This is a proposal — the user will refine it in the next step

**Run requirements coverage check (internal, not saved):**

Verify coverage between R table and initial shape:
- Every requirement (R) should have at least one shape part addressing it — missing parts indicate gaps in the solution
- Every shape part should trace back to at least one requirement — orphan parts indicate scope creep
- Note any gaps for presentation in the next step

**Decision Points:** If you encounter choices requiring user input, use AskUserQuestion:
- Ambiguous requirements with multiple interpretations
- Multiple valid technical approaches
- Missing context that affects design choices
- Trade-offs between competing concerns

**Add Detected Impacts section:**
```markdown
## Detected Impacts

### Affected Features
- **[path/to/feature.md]** - [Adds/Modifies/Removes]: [description]

### Notes for Reconciliation
- [What needs to change in feature docs]
- [New feature docs that need to be created]
```

Note any uncertainties or assumptions clearly.

### 6. Shape Collaboration

Present the initial shape parts table to the user for collaborative refinement. The shape bridges spec to design — the user must validate it before it gets seeded.

**Present:**
- The shape parts table with mechanism descriptions and unknowns
- A brief R→Shape mapping showing which parts address which requirements
- Any coverage gaps identified in the internal check

**Collaborate:**

Use AskUserQuestion or open discussion to refine the shape with the user:
- Confirm or adjust mechanism descriptions
- Add missing parts or remove unnecessary ones
- Discuss unknowns — does the user have insight that resolves them, or should they remain for design-phase spikes?
- Refine unknown descriptions: are they specific enough to guide investigation?
- Negotiate scope: are any shape parts over-engineering the solution?

Iterate until the user approves the shape. The approved shape is what gets passed to the reviewer and eventually seeded into the design doc.

### 7. External Validation (Silent)

Dispatch the spec-reviewer agent:

```python
Task(
    subagent_type="katachi:spec-reviewer",
    prompt=f"""
Review this delta specification.

## Delta Description (from DELTAS.md)
{delta_description}

## Completed Spec
{spec_content}

## Shape Parts (validated with user)
{shape_parts_table}

## Review Criteria (if spec includes User Flow section)
- Does breadboard accurately represent the described flows?
- Do affordances match acceptance criteria?
- Are all paths from breadboard covered by acceptance criteria?
- Are decision points in the flow documented?
- Is the flow description complete (entry, happy path, decisions, exit)?
"""
)
```

### 8. Apply Validation Feedback (Silent)

Apply ALL recommendations from spec-reviewer automatically:
- Fix coverage gaps
- Add missing edge cases
- Clarify ambiguous criteria
- Improve testability

**Decision Points:** If applying a recommendation requires a choice (multiple valid ways to fix, conflicts with earlier decisions), use AskUserQuestion.

Track changes made for presentation in next step.

**Auto-apply (no user input):**
- Clear fixes (typos, formatting, obvious gaps)
- Adding missing sections with clear content
- Reordering for clarity
- Standard compliance fixes

### 9. Present Validated Spec

Present the complete validated spec to the user in its entirety.

**Also present the final shape table** alongside the spec — show the shape parts table with any adjustments from reviewer feedback in step 8. Highlight changes from the version the user approved in step 6 if any were made. The user should see the complete output of the spec phase before finalizing.

Highlight any unresolved issues requiring input.
Invite feedback: "What needs adjustment in this spec or the shape?"

### 10. Iterate Based on User Feedback

Apply user corrections, additions, or changes to the spec and/or shape.
Re-run validation (steps 5-7) if significant changes.
Repeat until user approves both the spec and the shape.

### 11. Finalize

Finalize document to `docs/delta-specs/$ARGUMENTS.md`

Update status:
```bash
python ${CLAUDE_PLUGIN_ROOT}/scripts/deltas.py status set $ARGUMENTS "✓ Spec"
```

### 12. Seed Design Document

If `docs/delta-designs/$ARGUMENTS.md` does not already exist:

1. Read the delta-design template: `${CLAUDE_PLUGIN_ROOT}/skills/working-on-delta/references/delta-design.md`
2. Create `docs/delta-designs/$ARGUMENTS.md` following the template structure:
   - Header linking to the spec, Status: Draft
   - `## Shape` section populated with the user-approved shape parts table from steps 5-10
   - All remaining template sections included but left empty for the design phase to fill

This bridges spec and design — the design phase starts with the shape already drafted.

Present summary:

```
"Delta spec complete for $ARGUMENTS.

[Requirements table]

[Shape parts table]

Detected impacts: [list of affected feature docs]
Design doc seeded with initial shape: docs/delta-designs/$ARGUMENTS.md"
```

## Workflow

**This is a validate-first process:**
- Research silently, then interview user on key decisions — build R table collaboratively
- Draft spec with R table and grouped AC, draft initial shape (not in spec)
- Run requirements coverage check internally, then **present shape to user for collaborative refinement**
- Auto-discover affected features
- Validate spec and user-approved shape with spec-reviewer agent (silent)
- Apply all validation fixes automatically (ask decisions when needed)
- Present validated spec **and final shape** with applied changes summary
- User provides feedback on both spec and shape
- Iterate until approved
- Finalize spec, then seed design doc with user-approved shape