Frame

Frame

Structure implementation as vertical slices — each phase crosses all affected layers end-to-end, producing a testable integrated path. Phase 1 is the tracer bullet: the thinnest possible slice wired through every layer. Models default to horizontal plans (all DB, then all API, then all UI); this skill enforces vertical structure that cannot be prompted away.

Horizontal (wrong — layer by layer):

• Phase 1: All DB — notification tables, preferences, delivery log
• Phase 2: All service — email sender, in-app dispatcher, preference resolver
• Phase 3: All API — notification endpoints, preference endpoints
• Phase 4: All UI — notification center, preference panel, toast

By Phase 4, the agent has generated hundreds of lines across every layer. Integration reveals the notification table schema assumed a delivery model the service layer doesn't support. Fix cascades through all layers — most work is discarded.

Vertical (correct — slice by slice):

• Phase 1 (tracer bullet): Email notification, one path — table, service, endpoint, toast. Validates the full stack.
• Phase 2: In-app notifications — extends schema, adds dispatcher, wires notification center.
• Phase 3: User preferences — preference table, resolver, settings endpoint, preference panel.

Schema error surfaces in Phase 1, not Phase 4. Each phase is testable and deployable independently.

Prerequisites

Locate the inputs:

1. Alignment — check conversation context first; fall back to design-docs/NN-name.alignment.md; if absent, ask whether to run alignment.
2. Research — optional reference for codebase details. Check context or design-docs/NN-name.research.md.

Process

Phase 1 — Define the Tracer Bullet

1. Read the alignment document's desired end state and adopted patterns.
2. Identify the thinnest end-to-end slice that exercises the core path — from data layer through service logic to the outermost interface (API, UI, CLI, or whatever the system exposes).
3. This is Phase 1 of the frame. It must cross all relevant layers. A phase touching only one layer is a horizontal slice — restructure it.

Phase 2 — Define Subsequent Phases

4. Each subsequent phase adds depth as a vertical pass — new behavior, edge cases, integration points — always crossing layers, never completing one layer in isolation.
5. Target 3–5 phases total. More than 5 suggests the scope is too large for a single frame — consider splitting.
6. Cross-cutting concerns (auth, logging, error handling) are established within the vertical phases that need them — the tracer bullet wires the minimal cross-cutting path, subsequent phases extend it.

Phase 3 — Detail Each Phase

For each phase, define:

• Components touched — which modules, packages, or layers change.
• Testing strategy — what tests verify this phase works. Prefer TDD: write failing test, implement, verify. For external contracts, include learning tests that verify assumptions about the external system before building on them.
• Verification gate — observable condition proving this phase is correct before proceeding. "Tests pass" is a minimum; add integration-level verification for phases wiring across boundaries.
• Acceptance criteria — what "done" looks like, stated as verifiable conditions.

Phase 4 — Sequence and Dependencies

7. Map phase ordering: which phases must complete first, which can run in parallel, where handoff points exist. Design for maximum parallelism — phases that don't share dependencies should be executable concurrently by independent agents, each in a clean context window.
8. Every phase must appear in the sequence. A phase listed but not sequenced creates orphan work.

Phase 5 — Write Artifact

1. Compose frame.md using the document format below.
2. Number prefix: match existing artifacts (NN-name.alignment.md), or next available in design-docs/.
3. Save to design-docs/NN-name.frame.md.
4. Present to user for review. Revise if requested.

Transition

On user approval:

Frame is complete. Proceed to tasks to decompose phases into trackable work items?

Wide Refactors — the Exception

A wide refactor is one mechanical change — rename a column, retype a shared symbol, swap a logging API — whose blast radius fans across the whole codebase: a single edit breaks every call site at once, so no vertical slice can land green. Don't force it into tracer-bullet phases; sequence it as expand–contract:

1. Expand — add the new form beside the old so nothing breaks. This replaces the tracer bullet as Phase 1.
2. Migrate — move call sites to the new form in batches sized by blast radius (per package, per directory). Each batch is its own phase, depends only on the expand phase, and lands green because the old form still exists — disjoint batches run in parallel. Batch count follows blast radius, not the 3–5 phase target.
3. Contract — delete the old form once no caller remains. The final phase, dependent on every migrate batch.

When even individual batches can't stay green alone, keep the same sequence on a shared integration branch and add a final integrate-and-verify phase — green is promised only there.

Everything else in this skill still applies: per-phase testing strategy, verification gates, and acceptance criteria.

Frame Document Format

Concise outline, not implementation detail. The frame is to the implementation what a C header file is to the source — signatures, types, and boundaries, not logic.

# Frame: {title}

- **Date:** {date}
- **Alignment:** {path or "in conversation context"}

## Phase 1: Tracer Bullet — {short description}

**Components:**

- [Component] — [what changes in this phase]

**Testing strategy:**

- [What to test and how]

**Verification gate:**

- [Observable condition proving this phase works]

**Acceptance criteria:**

- [ ] [Verifiable condition]

## Phase 2: {short description}

**Components:**

- ...

**Testing strategy:**

- ...

**Verification gate:**

- ...

**Acceptance criteria:**

- [ ] ...

## Learning Tests

(Only when unfamiliar external contracts need verification before relying on them.)

- [Contract/API] — [what assumption to verify]

## Phase Sequence

Phase 1 (tracer bullet, no deps)
    ↓
Phase 2 (depends on Phase 1)
Phase 3 (parallel with Phase 2, depends on Phase 1)

## Scope Boundaries

**In scope:** [what this effort covers]
**Out of scope:** [what it does not]

Rules

• Vertical, not horizontal. Every phase must cross layers. A phase that completes one layer (all DB, all API) is a horizontal slice — restructure it. This is structural enforcement; models cannot be prompted into vertical planning. Wide refactors are the one exception — sequence those as expand–contract (see Wide Refactors).
• Living artifact. frame.md may be updated as implementation reveals the plan was wrong. Immutable only when moved to completed/.
• Always persists to disk. Tasks link back to frame.md; it must exist on the filesystem.
• Outline, not implementation. The frame shows what changes and in what order. No function bodies, no production code. Signatures and type definitions are acceptable when they clarify boundaries.
• Create only. One frame per initiative. Revise the living artifact directly; formal update mode deferred.