Implementation Spec: Detailed Plan from Resolved Sketch

Produces the committed, numbered implementation plan. Input: a sketch with resolved decision forks (from /pb-sketch) or equivalent clarity. Output: a plan document ready for /pb-todo-implement or manual execution.

Resource Hint: opus - Architect-tier work: scope-locking, phase sequencing, verification and rollback design.

Tool-agnostic: Spec framework (scope lock, phase breakdown, verification, rollback) works with any tool. Claude Code users invoke as /pb-spec. Using another tool? Read this file as Markdown for the framework. See /docs/using-with-other-tools.md.

When to Use

• After /pb-sketch with resolved forks – decisions are settled; turn them into numbered steps
• Via /pb-plan wrapper – muscle memory; wrapper runs sketch → presents decisions → spec
• When sketch is unnecessary – the approach is already obvious; skip sketch, spec directly
• Before /pb-todo-implement – spec provides the structure that todo-implement executes

Don’t use for:

• Plans that still have unresolved decision forks (run /pb-sketch first)
• Exploratory research (use /pb-sketch or /pb-think)

Philosophy

Foundation: Assumes sketch-level clarity. The spec is the committed plan – each phase should be independently shippable, verifiable, and rollback-safe.

Core Principles

1. Lock scope before specifying - Scope lock comes first. Without it, the spec drifts.
2. Atomic phases - Each phase is one concern. One commit’s worth of work or a tight sequence of related commits.
3. Verification per phase - Each phase says how to know it worked. “Passes tests” is not enough – name the tests, or the manual check, or the output signal.
4. Rollback per phase - Each phase says how to undo. Most rollbacks are git revert <sha>; some need data migrations or config reverts.
5. Size-gate the output - A 2-file bugfix doesn’t need a release tracker. Match the spec artifact to the work.

Phase 1: Scope Lock (always run)

Before writing steps, lock scope explicitly. This guards against drift during implementation.

Scope Lock Checklist

• Focus area clearly defined in one sentence
• Success criteria are measurable and agreed
• Out-of-scope items explicitly listed
• Risks identified with mitigations
• Phases ordered by priority (do P1 first, P3 can be cut)
• Each phase is independently shippable
• Stakeholders aligned on scope (or noted as solo work)

Scope Lock Statement

v[X.Y.Z] - [Theme]

Goal: [One sentence description of what we're achieving]

In Scope:
- [Specific item 1]
- [Specific item 2]

Out of Scope:
- [Explicit exclusion 1]
- [Explicit exclusion 2]

Success Criteria:
- [Measurable outcome 1]
- [Measurable outcome 2]

Signed off by: [Names/roles or "solo"]
Date locked: [Date]

Do not proceed to step-writing until scope is locked.

Phase 2: Size Gate

Match the spec artifact to the work. Two paths:

Path A: Small Feature / Bugfix

When: single concern, 1-3 files, one or two commits, no release cycle

Output: single file at plan/{generated-kebab-case-name}.md using the Single-Plan Template below.

Path B: Release Cycle / Multi-Phase Work

When: multiple phases, >3 files, shippable over several sessions, release versioning involved

Output: directory scaffold at todos/releases/vX.Y.Z/ using the Release Scaffold below.

Size Signals (pick path by gut; don’t over-index)

When in doubt, start Path A. Promote to Path B if the spec outgrows it. Don’t scaffold a release tracker for a two-file fix.

Phase 3: Write the Spec

Path A: Single-Plan Template

Write to plan/{name}.md:

# Plan: {Title}

**Created:** {YYYY-MM-DD}
**Scope Lock:** locked {YYYY-MM-DD}
**Sketch:** (optional) `sketch/{name}.md`

## Goal

{One sentence from Scope Lock.}

## Scope

**In:** {bullet or inline list}
**Out:** {bullet or inline list}

## Approach

{2-4 sentences. Reference resolved forks from sketch if applicable.}

## Steps

1. **{Step name}** -- {what, where, why}
   - Files: `{path}`
   - Action: {edit/create/delete}
2. **{Step name}** -- {...}
3. **{Step name}** -- {...}

## Verification

- [ ] {How to confirm step 1 worked -- test name, command output, manual check}
- [ ] {...}

## Rollback

{git revert, or specific steps if more involved}

## Notes

{design decisions, trade-offs, out-of-band references -- keep short}

Path B: Release Scaffold

Directory structure:

todos/releases/vX.Y.Z/
├── 00-master-tracker.md    # Current status, scope lock, phases
├── phase-1-{slug}.md       # Active phase detail
├── phase-2-{slug}.md
├── done/                   # Completed phases (archived)
└── ...

Only the active phase needs full detail; done phases move to done/. /pb-todo-implement owns session-by-session execution; this scaffold owns the release-level shape.

Master Tracker Template

# vX.Y.Z - [Release Theme]

## Current Status

**Phase:** [N] - [Name]
**Last commit:** [hash]
**Next:** [Specific next task]

## Scope Lock

**Goal:** [One sentence]

**In Scope:** [bullets]
**Out of Scope:** [bullets]

## Phases

| Phase | Focus | Status |
|-------|-------|--------|
| 1 | [Name] | pending |
| 2 | [Name] | pending |

Update Current Status each session so resume is instant. Scope Lock is permanent once set.

Phase Document Template

# Phase N: [Name]

## Tasks

### Task 1: [Name]

- **Files:** [file:line references]
- **Acceptance:** [specific, verifiable outcome]

## Verification

- [ ] [How to verify changes work]

## Rollback

[How to undo if needed]

Verification Design (applies to both paths)

Each phase (or step in Path A) needs a verification signal. Weak → Strong:

Rule: If verification is a sentence, it’s not verification. Name the test, the command, or the signal.

Rollback Design (applies to both paths)

Every phase (or step in Path A) needs a rollback path.

Common rollbacks (cheap):

• git revert <sha> for code-only changes
• git reset --hard <sha> before push (destructive – requires explicit approval)
• Config revert: restore previous .env or settings value

Expensive rollbacks (require explicit plan):

• Database migrations: need a reverse migration
• Third-party API changes: need a rollback call or feature flag
• User-visible changes: need communication plan

Rule: If rollback is expensive, say so in the spec and design a feature flag or phased release.

Hand-off to Implementation

Spec is complete when:

• Scope lock signed
• Size gate decided (Path A or Path B)
• All steps/tasks written with files and actions
• Verification defined per step/phase
• Rollback defined per step/phase
• File(s) saved at the correct location

Then invoke /pb-todo-implement (or execute manually). For very small changes, the spec itself may be the commit message draft.

Red Flags in Spec Writing

Spec Bloat

• Spec longer than the code change it produces.
• Response: collapse steps, shorten descriptions, trust the reader.

Missing Verification

• Every step says “tests pass” verbatim.
• Response: name the test, the command, or the signal.

Missing Rollback

• “If it breaks, we’ll figure it out.”
• Response: at minimum git revert <sha>. Expensive rollbacks need explicit plans.

Scope Creep in the Spec Itself

• “While writing this step, I realized we should also…”
• Response: add to backlog. Reopen scope lock explicitly if genuinely required.

Wrong Size Path

• Release tracker scaffold for a two-file fix.
• Response: demote to Path A. Release scaffold is for multi-phase work.

SDLC Notes

For planning, implementation, and testing discipline: /pb-standards and /pb-guide. This skill writes the spec; execution discipline lives in those.

Related Commands

• /pb-plan - Orchestrating wrapper; runs decide then hands a resolved sketch to this skill.
• /pb-sketch - Produces the resolved sketch this skill consumes.
• /pb-adr - Document architecture decisions for significant forks.
• /pb-todo-implement - Executes the spec phase-by-phase with commits.
• /pb-start - Alternate entry point for beginning work from a spec.