Slicing

Breaks a shaped and modeled feature into vertical implementation slices. Explores the codebase per slice, generates acceptance criteria and validation requirements, and outputs self-contained plan files.

Trigger

• •Feature is shaped and modeled, ready for slicing
• •/modeling phase transition invokes this skill

Input

~/.claude/shaping/[feature]/shaping.md with selected shape + affordances.md

Output

• •~/.claude/shaping/[feature]/slices.md — slice definitions with acceptance criteria
• •~/.claude/shaping/[feature]/V*-plan.md — individual slice implementation plans
• •Symlinks into ~/.claude/plans/ for Claude Code plan mode

Process

1. Read the Model

• •Read shaping.md — extract: WHY, requirements (R), boundaries (X), selected shape parts, scope. If a frame.md exists, read it for the original problem statement
• •Read affordances.md — extract: UI/Code affordances, data stores, wiring
• •Read existing code referenced in the model — understand what exists before proposing changes
• •Identify which parts create new code vs modify existing code
• •If any ⚠️ flags remain on parts, work with the user to resolve them before proceeding

2. Break Into Vertical Slices

A vertical slice is a group of UI and Code affordances that does something demo-able. It cuts through all layers (UI, logic, data) to deliver a working increment. The opposite is a horizontal slice — doing work on one layer (e.g., "set up all the data models") that isn't clickable.

Every slice must have visible output that can be demoed:

• •Has an entry point (UI interaction or trigger)
• •Has an observable output (UI renders, effect occurs)
• •Shows meaningful progress toward the requirements

Procedure:

Step 1: Identify the minimal demo-able increment

Ask: "What's the smallest subset that demonstrates the core mechanism working?" Usually: core data fetch + basic rendering. No search, no pagination, no state persistence yet. This becomes V1.

Step 2: Layer additional capabilities

Each slice demonstrates a mechanism working. Max 9 slices — if you need more, combine related mechanisms.

Step 3: Assign affordances to slices

Go through every affordance and assign it to the slice where it's first needed:

Some affordances may have Wires Out to later slices — that's fine. They're implemented in their assigned slice; the wires are stubs until the later slice is built.

Step 4: Create per-slice affordance tables

For each slice, extract just the affordances being added into a focused table:

V2: Search Works

Step 5: Write demo statement per slice

Each slice needs a concrete demo: "Type 'dharma', results filter live." Something you can show that demonstrates progress.

Slice sizing:

• •Too small: 1-2 UI affordances, no meaningful demo → merge
• •Too big: 15+ affordances or multiple unrelated journeys → split
• •Right size: a coherent journey with a clear demo

For each slice, also:

• •List which shape parts the slice implements (using shaping notation — the shape's letter + number, e.g., F1, F2, E1)
• •List which requirements (R0, R1...) the slice satisfies

3. Explore the Codebase Per Slice

For each slice:

• •Read every file that will be modified
• •Identify existing patterns to reuse
• •Identify existing modules/components that do similar things
• •Identify what existing behavior could regress
• •Exact file paths for creates/modifies

4. Generate Acceptance Criteria

For each slice, generate as sane defaults. Present to user for confirmation.

4 mandatory categories:

Functional — demo statement works end-to-end, each mechanism produces correct output, edge cases handled (empty states, error states, boundary values)

Regression — "Existing [behavior] in [file] still works after changes." Name the behavior, the file, how to verify. If tests exist: "Existing test suite passes." If no tests: "Manual verification of [specific behavior]"

Dependency audit — "Verified [module] exists and exposes [method] before using." "No duplicate implementation — checked [locations] for existing [capability]"

Boundary — "Does not modify [out-of-scope area]." "Does not introduce [pattern/dependency] outside plan boundaries"

5. Generate Validation Requirements

For each slice, specify HOW validation happens. Use the /subagents skill to dispatch validation agents.

• •Dispatch independent testing agents — never self-validate (the implementing agent is biased)
• •Trace every code path touched to verify correctness
• •Validate code serves real user scenarios end-to-end
• •Browser testing via tester agent + /agent-browser when UI is involved
• •Exhaust every test category fitting scope (unit, integration, user flows, edge cases)
• •Autonomously fix all issues that don't significantly change the plan's architecture
• •Final step: present results to user for manual verification and feedback (no commits without approval)

Visualizing Slices in Mermaid

Optionally, show the complete model in slice diagrams with styling to distinguish scope:

Use classDef thisSlice fill:#90EE90, classDef built fill:#d3d3d3, classDef future fill:none,stroke-dasharray:3 3.

6. Write slices.md

Output file: ~/.claude/shaping/[feature]/slices.md

---
shaping: true
---

# [Feature Name] — Plan

> **Plan contract:** This plan is an immutable contract. Architectural deviations require explicit approval.

**WHY:** [One paragraph — business motivation from frame]

**Scope:** [Natural-language scope from shaping doc]

**Boundaries:**
- [From shaping doc + any discovered during planning]

## Slice Summary

| # | Slice | Parts | Requirements | Affordances | Demo |
|---|-------|-------|-------------|-------------|------|
| V1 | ... | F1, F4 | R0, R3 | U2-U5, N3-N8 | "..." |

## V1: [Slice Name]

**Parts:** F1, F4
**Requirements:** R0, R3
**Demo:** "[Concrete demo statement]"

**Files:**
- Create: `exact/path/to/file.ext`
- Modify: `exact/path/to/existing.ext`

**Reuses:**
- [Existing module/component] from [location]

**Regression scope:**
- [Existing behavior] in [file] — verify [how]

**Acceptance Criteria:**
- [ ] [Functional criterion]
- [ ] [Regression criterion]
- [ ] [Dependency audit criterion]
- [ ] [Boundary criterion]

**Validation:**
- [ ] [How each criterion gets validated — which agent, which test, which browser check]

7. Write V*-plan.md Files

For each slice, write an individual plan file: ~/.claude/shaping/[feature]/V*-plan.md

# [Feature] — V[N]: [Slice Name]

> **Plan contract:** This is an immutable contract. Architectural deviations require explicit approval. Tactical code-level adjustments are fine.

> **For Claude:** Use the /team skill to dispatch implementation.

**WHY:** [What user problem this slice solves]

## Requirements

| ID | Requirement | Status |
|----|-------------|--------|
| R0 | [only the R's this slice satisfies] | Must-have |

## Model Changes

[Database tables + columns, annotated NEW/REMOVED/RENAMED]

accounts
├── id: int
├── email: string
├── password: ?string                  <- NEW (nullable)
├── setup_token: ?string              <- NEW
└── tenant_id: int                     <- FK → tenants

## Affordances

[Per-slice affordance table — extracted from affordances.md]

| # | Component | Affordance | Control | Wires Out | Returns To |
|---|-----------|------------|---------|-----------|------------|
| U1 | ... | ... | ... | ... | ... |

---

### Task 1: [Component Name] (fulfills R0, R1)

**Files:**
- Create: `exact/path/to/file.ext`
- Modify: `exact/path/to/existing.ext`

**Step 1:** [Action — exact code or specific instruction]

**Step 2:** [Verification — concrete proof the step worked]
Verification can be: test command, API call, browser check via /agent-browser, CLI output, or any observable result.

...

### Task N: Validation (fulfills all R's)

Dispatch independent testing agents via /subagents — never self-validate:
- Trace every code path touched to verify correctness
- Validate code serves real user scenarios end-to-end
- Browser testing via tester agent + /agent-browser when UI is involved
- Exhaust every test category fitting scope (unit, integration, user flows, edge cases)
- Autonomously fix all issues that don't significantly change the plan's architecture
- Final step: present results to user for manual verification and feedback (no commits)

---

## Acceptance Criteria
- [ ] [Functional criterion]
- [ ] [Regression criterion]
- [ ] [Dependency audit criterion]
- [ ] [Boundary criterion]
- [ ] [Validation criterion — feature works end-to-end from a user's perspective]

## Changes

[Annotated file tree of all code files created/modified in this slice]

app/
├── Models/Account.php*              <- +password, +setup_token
├── Controllers/AuthController.php*  <- +setPassword(), +sendResetLink()
├── Services/EmailService.php*       <- NEW (extracted from tenant)
admin/
├── pages/SetPassword.tsx*           <- NEW
├── pages/Login.tsx*                 <- +forgot password toggle

Task structure:

• •Bite-sized steps (2-5 min each)
• •Exact file paths, complete code
• •Each step has concrete verification (not limited to unit tests)
• •Pattern: do → verify → commit

8. Symlink for Plan Mode

After writing V*-plan.md files, create symlinks so Claude Code plan mode can reference them:

ln -s ~/.claude/shaping/[feature]/V1-plan.md ~/.claude/plans/[descriptive-name].md

Claude Code reads/writes through symlinks transparently.

9. Validation Checklist

Before presenting the plan to the user, verify:

• • Every R has at least one slice that satisfies it
• • Every slice has all 4 acceptance criteria categories
• • Every modified file has regression criteria
• • Every slice has validation requirements
• • No ⚠️ flags remain on shape parts
• • slices.md and all V*-plan.md files written
• • Symlinks created
• • Every slice passes the demo test (can a user see this working?)

9b. Present Requirements & Decisions

Before announcing the contract, present to the user:

• •Full requirements table — which slice satisfies each R
• •Boundaries (X) — confirm all respected
• •Outstanding decisions — anything that emerged during slicing
• •Coverage gaps — any R without a satisfying slice

The user reviews the plan through conversation output, not by opening slices.md.

10. Announce the Contract

After all plan files are written, state:

"This plan is now an immutable contract. During execution:

• •Architectural changes require explicit approval
• •Tactical code-level adjustments are fine
• •Scope additions must be flagged as must-have or nice-to-have, never silently absorbed"

Plan Contract

The plan defines the architecture. The executing agent implements it. The agent does NOT redesign it.

What's Fixed (Requires Approval to Change)

• •File structure — which files are created, modified, deleted
• •Module boundaries — what belongs where, dependency direction
• •Patterns — which existing patterns to follow, which abstractions to use
• •Data ownership — which component owns which data
• •API contracts — function signatures, route shapes, response formats
• •Scope — what's included and what's explicitly excluded (boundaries)

What's Flexible (Agent Decides)

• •Variable and function names (within project naming conventions)
• •Error message wording
• •Internal implementation details (algorithm choice within the same complexity class)
• •Test structure (how tests are organized, not what's tested)
• •Code comments and documentation

Deviation Protocol

If an executing agent discovers the plan is wrong or incomplete:

1. •STOP — do not work around it
2. •State the issue — "The plan says X, but Y is actually the case because Z"
3. •Propose options — present alternatives with tradeoffs
4. •Wait for approval — do not proceed until the architect confirms
5. •Record the deviation — note in the slice's completion summary

Scope Additions

During execution, agents may discover work the plan didn't anticipate:

• •Must-have — blocks the current slice from being demo-able. Flag immediately, propose minimal addition
• •Nice-to-have — improves quality but slice works without it. Note for later, do not absorb silently
• •Out of scope — belongs to a different feature or future work. Note in completion summary, do not implement

Never silently absorb scope additions. Every addition is explicitly flagged.