> ## Documentation Index
> Fetch the complete documentation index at: https://meganharrisonconsulting.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# AI Engineering Playbook
> The single source of truth for how work gets done in this repo with AI agents — task tiers, one skill per step, and the retirement list for overlapping skills.
We don't have too few skills. We have too many that overlap, so every session
re-litigates "which verification skill?" / "which review skill?" / "do I need a plan?".
This page removes the choice.
## The rule
**Each skill owns exactly one (tier × step) cell.** If a skill isn't the named owner of
a cell, you don't run it — it's either retired or it's an auto-firing gate you never
invoke by hand. There is never a menu.
Two questions decide everything:
1. **Which tier is this change?** (Quick / Standard / Large)
2. **What's the next step in that tier's row?** Run the one skill in that cell. Done.
***
## Step 1 — Classify the task (do this first, every time)
Pick the tier by **uncertainty × blast radius**, NOT by line count. A 1-line change to
auth is Large. A 20-file mechanical rename is Quick.
| Tier | What it is | Examples | Plan? |
| ------------ | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | -------------- |
| **Quick** | Known path, reversible, single surface | Copy/CSS fix, one-function bug, rename, styling tweak, single field | No |
| **Standard** | A feature on a known pattern, a few files, one surface | New table page, new detail page, a form, one API route + its UI | Lightweight |
| **Large** | New capability, or touches a dangerous surface | Net-new feature, DB schema/migration, auth/permissions/RLS, AI/RAG pipeline, money paths, multi-surface | Required (PRP) |
**Dangerous-surface override:** anything touching auth, RLS, permissions, migrations,
billing/money, or the RAG/embedding pipeline is **Large** regardless of size.
***
## Step 2 — Follow your tier's row. One skill per cell.
Steps run left to right. A blank cell means **that step is skipped at this tier** — not
"use judgment," just skip it.
| Step | Quick | Standard | Large |
| --------------------------------- | ------------------------------------------------------- | --------------------------------------------------- | --------------------------------------------------------------------------- |
| **1. Frame** | inline (bug → `systematic-debugging`) | `brainstorming` *(if any ambiguity)* | `brainstorming` |
| **2. Plan** | — | `writing-plans` → short `tasks.md` | `prp-create` → PRP |
| **3. Build** | edit directly; UI gates auto-fire | the **one** domain build skill (picker below) | `prp-execute` + domain build skill |
| **4. Verify** *(built it right?)* | read your own diff | `code-review` (fresh context) | `code-review` (fresh, Opus) **+** `parity-audit`/`fk-audit` if forms/detail |
| **5. Test** *(does it work?)* | Haiku sub-agent: targeted typecheck/lint + the one test | sub-agent: `npm run quality` + targeted Playwright | `verify-feature` (full flow: DB + API + screenshots) |
| **6. Validate** *(right thing?)* | — | `impeccable-alleato` *(UI only)* | `impeccable-alleato` **+ human (you)** |
| **7. Ship** | `verification-before-completion` → commit to `main` | `verification-before-completion` → `commit-push-pr` | `verification-before-completion` → PR |
### The Build-skill picker (Step 3)
You never choose between build skills — the *surface* chooses:
| Building… | Skill (auto-enforced by its gate) |
| -------------------------- | -------------------------------------------------------- |
| A list/table page | `alleato-table-page` |
| A detail/record page | `alleato-detail-page` |
| A form with FK dropdowns | `fk-audit` + `FORM-FK-VALIDATION-GATE` |
| Net-new UI from scratch | `frontend-design` |
| Procore-mirroring behavior | `procore-docs-rag` first (confirm real Procore behavior) |
Gates (`DESIGN-SYSTEM-GATE`, `DETAIL-PAGE-GATE`, `TABLE-PAGE-GATE`, `FORM-FK-VALIDATION-GATE`,
`RAG-DOCS-GATE`, `FILE-ORGANIZATION-GATE`) are **not skills you invoke** — they fire on
commit. Don't think about them; they think about you.
***
## The three skills that kept colliding — now disambiguated
These three competed because nobody assigned them altitudes. They are **not** redundant;
they live at different heights and now own different cells:
**Verify (Step 4).** "Did the diff build what we said, correctly?" Reads code, no
browser. The **only** review skill. Runs at every tier ≥ Standard.
**Test/Validate (Step 5–6, Large only).** "Does the real user flow work and is the
outcome *good*?" Drives the browser, checks the DB, takes screenshots. Heavy.
**Ship gate (Step 7, all tiers).** "Show the passing output before you claim done."
The one skill that runs on every task — because declaring victory without evidence
happens at every tier.
They never compete again because they're in different rows/columns.
***
## Retire these (stop reaching for them)
When you're about to invoke one of these, use its canonical replacement. The table above
is the only menu.
| Stop using | Use instead | Cell |
| --------------------------------------------------------------------------------------- | ------------------------------------------------------------ | ------------------ |
| `local_review`, `my-code-review`, `code-review-excellence`, `feature-dev:code-reviewer` | `code-review` | Verify (4) |
| `verify:verify`, `verify:verify-task`, `local-action-verification`, `verify` | `verify-feature` (Large) or sub-agent quality run (Standard) | Test (5) |
| `audit`, `design:design-audit`, `web-design-reviewer`, generic `impeccable` | `impeccable-alleato` | Validate (6) |
| `prp-pipeline`, `prp:prp-*` variants, `writing-plans` for big features | `prp-create` → `prp-execute` | Plan/Build (Large) |
| `test-scenario-run*`, ad-hoc `e2e-test-writer` | folded into `verify-feature` | Test (5) |
> One review skill. One deep-QA skill. One UI-validation skill. One universal closer.
> One planning skill per weight class. Everything else is an auto-firing gate or retired.
***
## Models per step
| Step | Model | Why |
| ----------------------------------------------- | --------------------------- | ----------------------------------------------------- |
| Frame / Plan / Large-tier Verify | **Opus 4.8** | Reasoning depth changes the outcome |
| Build (most) | **Sonnet 4.6** | The workhorse — 90% of feature code |
| Test runs, lint/typecheck/build, log monitoring | **Haiku 4.5** | The "lower-cost sub-agent" CLAUDE.md already mandates |
| Final Verify before merge | **Opus 4.8, fresh context** | A miss here is expensive |
**Fresh context > different vendor.** The review payoff comes from a reviewer that
didn't write the code and only sees requirements + diff — not from switching to a
non-Claude model. Use a fresh Claude context with a reviewer role prompt; only go
cross-vendor if you've *measured* a gap.
***
## The one-paragraph version
> Classify the task Quick / Standard / Large by uncertainty × blast radius (auth, RLS,
> migrations, money, RAG → always Large). Then walk that tier's row: Frame → Plan → Build
> → Verify → Test → Validate → Ship, running the **one** skill named in each cell and
> skipping blank cells. Review = `code-review`. Deep QA = `verify-feature`. UI judgment =
> `impeccable-alleato`. Always close with `verification-before-completion`. Never pick
> from a menu of overlapping skills again.