large-feature

Files (1)

• SKILL.md

SKILL.md (first lines)

# Large Feature Full-Rigor Playbook

Opinionated 7-stage shape for **high-rigor** L-bucket features — multi-slice
features where blast radius is real, the design isn't trivial, or the
deliverable needs to be defensible long after the work ships.

## Relationship to other docs

- **`WORKFLOW.md`** keeps L's *mandatory* shape minimal: written plan + phased
  execution. That doesn't change.
- **This playbook** is an *optional* full-rigor path for L features where the
  baseline two-mandate shape isn't enough.
- Reach for it when: blast radius high, multi-slice work, regulatory or
  audit-relevant change, work spans sessions, or you'd be uncomfortable
  shipping without an audit trail of *why*.
- Skip it when: a `scope`-style plan + per-phase tests is sufficient and
  you're not bottlenecked on uncertainty or review bandwidth.

## Source-tier legend

Each stage is labeled by how well-supported it is in May 2026 SOTA:

- 🅐 **documented practitioner pattern** — explicit in named SOTA sources
- 🅛 **local repo doctrine** — formalized in `shared/AGENTS.md` / `WORKFLOW.md` / `KNOWLEDGE.md`
- 🅡 **research-backed adjacent** — academic or vendor research supports the *concept*; specific shape is interpretation
- 🅔 **experimental synthesis** — extrapolation from neighboring patterns, not yet documented

---

## Stage 0 — Sharpen via `grill-with-docs` 🅐 🅛

**Gate:** Run if domain language uncertainty or prior-decision ambiguity is high. Skip if the request is unambiguous and the project's `CONTEXT.md` / ADRs already settle the relevant terms.

Use the `grill-with-docs` skill against `CONTEXT.md`, `docs/adr/`, and existing skills in the area. Output is **sharpened understanding**, not yet a plan.

If you can already write a clean one-sentence "done" definition, skip this stage — the language is already settled. That does **not** reclassify the work. A clear done definition lowers *uncertainty*; it leaves effort and blast radius exactly where they were, and the bucket is the worst of the three (`WORKFLOW.md`). A well-understood change to a shared contract is still L.

**For greenfield features without a spec yet:** add a pre-stage using `to-prd` to write the spec, then grill against it. This repo's vendored Matt-Pocock pipeline is `to-prd` → `scope` → `to-issues`. (Upstream Matt-Pocock also offers `prd-to-plan` / `plan-from-prd` for finer-grained planning steps; those are not vendored here.)

## Stage 1 — Plan + cross-model plan critique 🅐 🅛

**Gate:** Always for L features under this playbook.

### Stage 1 preflight — discover and run the validation harness 🅐

Before `scope`, before any planning: **run the repo's existing test/lint/typecheck commands.** This is Willison's first-do-no-harm pattern — it teaches the agent the validation harness, surfaces broken baseline state, and puts the agent into testing mode before any change.

- If commands are unknown, discover them: read `package.json`, `pyproject.toml`, `justfile`, `Makefile`, `.github/workflows/`, the project's `CLAUDE.md` / `AGENTS.md`
- Record the discovered validation commands in `.local/plan.md` so every subsequent slice's acceptance contract can reference them
- If existing tests fail on a clean checkout, **stop and declare the verification gap explicitly** before adding new work (per `WORKFLOW.md` universal principle #1)

### Stage 1 plan

1. Use the `scope` skill → `.local/plan.md` with phased plan, test gates per phase, and acceptance criteria. Include the validation commands discovered in preflight.
2. **Cross-model plan critique** per `WORKFLOW.md` cross-model rule. From a different model family (Codex if you're Claude, vice versa). Findings to `.local/plan-review.md`. Apply BLOCKER and IMPORTANT before slicing.

Hashimoto's "planning/execution split" applies: do all the planning before you write the first line of code.

## Stage 2 — Decompose into vertical tracer-bullet slices 🅐

**Strongly SOTA-supported.** Matt Pocock's `to-issues` skill is the canonical shape. ai-hero.dev's argument:

> *"AI wants to produce complete solutions all at once… Force the agent to think small, build end-to-end, get feedback, and move forward with confidence."*

Use the `to-issues` skill to produce a slice list. Each slice must:

- **Cut through every relevant layer** (schema/data → service → API → UI → tests) — vertical, not horizontal
- **Be demoable or verifiable on its own** — not "the API is done, UI next sprint"
- **Be independently revertable** — one slice undone shouldn't break the others

### Ordering

**First the walking skeleton**, then risk-prioritized within dependency constraints.

The thinnest end-to-end slice that proves the spine works comes *first* — even if it's not the highest-risk feature. Once the spine is demonstrable, prioritize subsequent slices by risk, **bounded by dependency order**. Don't disguise enabling work or spikes as feature slices — if a migration or technical spike is needed before an honest vertical slice exists, label it as such.

### Anti-pattern

- **Fake vertical slices** — a "slice" that's actually horizontal layered work hidden behind a slice-shaped issue title. If it's not demoable end-to-end, it's not a slice.
- **Risk-first without a skeleton** — attacking the hardest behavior before proving the path exists. Spike first if needed; don't force the hard slice as #1.
- **Slice inertia between candidates** — "we did A–E so let's do F" is not a reason to do F. Before adding a slice from an audit list, apply the **actively-biting test**: does this seam cause PR friction, recurring bugs, or block a feature? Long ≠ tangled. If just long, scope it tighter or skip.

## Stage 3 — Per-slice red → green → refactor with strict phase isolation 🅐 🅡 🅛

**The TDD core. Strongly supported.** For each slice:

### Red — write the failing test first

- Test behavior through the slice's **public interface**, not implementation shape
- Test must fail for the right reason (not import error, not undefined symbol)
- Tests written against the slice's **acceptance contract** from the per-slice template (see below) — not invented behavior
- **Spec-first (default at M/L)** (`shared/AGENTS.md`): a **different-provider** agent authors+freezes acceptance tests before impl (below). TDD loop governs implementer-level tests inside that frame. Waiver names triage reason.
- **Strict isolation red|green.** Different-provider authorship is default form; context-clear fallback only under named waiver.

The agentic-coding-handbook makes the isolation rule explicit:

> *"Each phase runs in complete isolation: the test writer focuses purely on test design, the implementer sees only the failing test, and the refactorer evaluates clean implementation code. This isolation is the only way to get genuine test-first development from an LLM."*

**Targeted test selection** 🅡: TDAD (arxiv:2603.17973) finds that telling the agent *which specific tests* the change impacts beats generic "run tests." TDAD's result depends on an explicit dependency map / impact-analysis tool. This repo does not currently have that machinery. Pragmatic fallback:

- **When an impact map or reliable code intelligence exists** (Sourcegraph/Amp-style, or a dependency-graph tool): provide the targeted impacted test set
- **Otherwise**: run the new failing test plus the nearest relevant existing tests (same module, same callers). Run broader validation at phase boundary and final integration (Stage 5), not after every green
- A manually guessed impact set is weaker than TDAD's tooled version — do not over-trust it

### Spec-first acceptance tests (default at M/L) 🅛

Contract shape (`shared/AGENTS.md`) — local doctrine, not experimental:

- 🅛 **Cross-model authoring (default)** — different-provider agent writes+freezes acceptance test strictly from acceptance contract + domain docs, before impl; by default same agent then reviews impl (no extra seat). **Separate author** (≠ impl reviewer) allowed for parallel slices / high blast radius. Implementer never edits frozen tests; disputed spec goes back with evidence. Isolation risk: imagined behavior / accidental API shape (Hora et al.) — challenge impl-shape tests.
- 🅡 **Cross-model test review** — author's impl verdict doesn't gate own tests: another-provider seat reviews frozen tests vs requirements (behavior vs impl shape). Byte-identical installation allowed.

### Green — make the test pass

- Smallest impl that makes the failing test pass
- Don't add behavior the test doesn't require
- Run the new failing test plus the nearest relevant existing tests (per "Targeted test selection" above); broader runs come at phase boundary / final integration

### Refactor (micro) — inside the slice 🅐

From clemens33/dotfiles, MIT.

More from clemens33/dotfiles