feat(skills): small-model hardening — context budgets, handoff schema, spec-lint, interview rubric, isolated reviews (#105)

## What

One coordinated hardening pass so the workflow skills run reliably on
**small/cheap executor models** (modest context windows, no prompt
caching). Six improvements, minimal diffs, all extending existing
in-repo mechanisms:

1. **Explicit context budgets** — `execute-phase` 2.7.0 (≤ 10 full-file
reads per phase beyond the unit's own docs; targeted ≤ 50-line reads and
greps free; fixed Step 0 minimum set; summarize-don't-hold),
`review-implementation` 1.3.0 (diff + ≤ 10 context files, findings
reduced to table rows immediately), and a per-pass budget in
`review-change` 2.6.0.
2. **Fresh context per phase + file-based handoff** — `progress.md` gets
a fixed per-phase entry schema (`Done / Remains / Gotchas / Files /
Next`), created beside the SPEC on P1 for phased XS/S and `--fix` units;
the same-session re-read shortcut is removed (one phase = one fresh
conversation). `plan-feature-scaffold` 1.11.0 documents the file
accordingly.
3. **Structural vagueness detection** — `design-feature` 2.2.0: one
question per turn (never batched), a fixed six-slot vagueness rubric
(affected users/roles · error & edge states · data shape · boundaries &
limits · out of scope · success criteria), the mandatory-question rule
(no requirement without a verifiable AC), the reframe-as-measurable
technique, a new `### Deferred decisions` SPEC section, and structural
escalation (≥ 3 empty slots → `NEEDS_INPUT`). `plan-feature-from-issue`
1.5.0 mirrors the rubric and gains a fixed ≥ 3-slot hand-off threshold
to `design-feature`.
4. **Deterministic gates on artifacts** — new **Spec-lint** (modeled on
the Phase-lint: presence checks only, fail-closed) in both SPEC
templates; run by `design-feature` (product boxes, before stamping
`designed`), `plan-feature-scaffold` (all boxes, before its report), and
`plan-fix` 2.4.0 (fix-template boxes, before the draft commit).
5. **Reviews isolated per axis, tables only** — `review-change` 2.6.0:
new default *Isolation rule* (subagent / headless / fresh-conversation
tiers, same as `--adversarial`); each pass receives only scope + its
checklist + named docs and returns only its fixed table + PASS|FAIL; the
orchestrator holds tables, never sources; in-turn composition stays as
the documented inline fallback.
6. **Other strong-model-judgment steps fixed** — structural
per-criterion SPEC-drift table in `review-change`; fixed numeric
cheap-fix bound (≤ ~15 lines, ≤ 2 files, no public API/schema change) in
`review-implementation`; dev-scenario failure-mode seed categories in
the feature SPEC template; README (EN+ES) guidance for running the whole
flow on a homogeneous small-model fleet.

## Why

The skills are executed day to day by small models (Qwen3.6,
DeepSeek-V4-Flash, MiMo-2.5 class) with modest context and no caching.
Steps that assumed strong-model judgment (open-ended discovery reads,
batched interviews, in-turn review composition, "a few lines"
heuristics) degrade there; this pass converts them to caps, fixed
schemas, and presence gates.

## Evidence

- `npx skills add . --list` discovers all skills (run, output clean).
- `bump-skill` authoring lints on the 7 changed skills: `→ Next:` / `##
Portability` / `## Turn contract` present; no `S1`/"Step N" phase labels
(only the standard "Step 0" section names).
- Versions bumped + CHANGELOG.md / CHANGELOG.es.md rows + release-log
entries; README.md / README.es.md updated in the same change
(bilingual-sync rule honored).

## Pending

- `docs/workflow/GOLDEN_FIXTURE.md` smoke test with the weakest fleet
model (manual procedure) — recommended before merge for the
`execute-phase` / `plan-feature-scaffold` / `design-feature` /
`review-*` wording changes.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Author: gtrabanco

CHANGELOG.es.md

@@ -286,6 +286,30 @@ se mueve rápido; contrástalo con un leaderboard actual antes de fijar nada):
   **Gemma 3 27B**, **Phi-4-mini** — corren en local, suficientes para trabajo
   tipo grep.
 
+### Ejecutar todo el flujo con una flota de modelos pequeños/baratos
+
+Los skills están endurecidos para modelos ejecutores pequeños (ventanas de
+contexto modestas, sin caché de prompt): checklists fijas en lugar de juicio,
+las puertas de presencia Phase-lint y Spec-lint, un esquema fijo de handoff en
+`progress.md` con conversación nueva por fase, presupuestos de contexto por
+fase/pasada, y revisiones aisladas por eje que devuelven solo tablas de
+hallazgos. En una flota sin ningún modelo de clase frontier:
+
+- **Ejecución** (`execute-phase`, `log-session`, mantenimiento de docs) está
+  diseñada para el tier más barato — una fase por conversación, handoff vía
+  `progress.md`, máximo 10 lecturas de fichero completo por fase.
+- **Planificación, revisión y auditoría** (`design-feature`, `plan-feature`,
+  `plan-fix`, `review-change`, `audit-pr`, `product-audit`) siguen usando el
+  **modelo más fuerte que tengas**, aunque no sea frontier — y nunca uno más
+  débil que el que escribió el cambio.
+- **Revisiones**: mantén el aislamiento por eje por defecto (cada pasada un
+  contexto nuevo, retorno solo-tabla) y prefiere `--adversarial 2` en cambios
+  `L` o sensibles — N revisores baratos y descorrelacionados recuperan parte
+  de lo que un único revisor pequeño no ve.
+- **Divide más.** La regla de división obligatoria (≤ ~5 fases, una capa por
+  fase) es la palanca principal: fases más pequeñas son lo que hace fiable la
+  ejecución barata. Ante la duda, corta más pequeño.
+
 #### <img src="docs/assets/nan-cloud.svg" alt="Logo de NaN Cloud" width="20" height="19"> Ejecutar sobre [NaN.builders](https://cloud.nan.builders/r/7GK06FX8)
 
 [NaN Cloud](https://cloud.nan.builders/r/7GK06FX8) sirve la frontera open-weight

CHANGELOG.md

@@ -277,6 +277,30 @@ fast; sanity-check against a current leaderboard before pinning):
 - **Small & cheap** (⇔ Haiku): **Qwen3 4–14B**, **Mistral Small 3.1**,
   **Gemma 3 27B**, **Phi-4-mini** — local-friendly, fine for grep-shaped work.
 
+### Running the whole flow on a small/cheap fleet
+
+The skills are hardened for small executor models (modest context windows, no
+prompt caching): fixed checklists instead of judgment calls, the Phase-lint
+and Spec-lint presence gates, a fixed `progress.md` handoff schema with a
+fresh conversation per phase, per-phase/per-pass context budgets, and reviews
+isolated per axis returning findings tables only. On a fleet with no
+frontier-class model at all:
+
+- **Execution** (`execute-phase`, `log-session`, doc bookkeeping) is designed
+  for the cheapest tier — one phase per conversation, handoff via
+  `progress.md`, at most 10 full-file reads per phase.
+- **Planning, review, and audit** (`design-feature`, `plan-feature`,
+  `plan-fix`, `review-change`, `audit-pr`, `product-audit`) still get the
+  **strongest model you have**, even if that model isn't frontier-class —
+  and never one weaker than the model that wrote the change.
+- **Reviews**: keep the per-axis isolation default (each pass a fresh
+  context, table-only return) and prefer `--adversarial 2` on `L` or
+  sensitive changes — N cheap, decorrelated reviewers recover part of what a
+  single small reviewer misses.
+- **Split more.** The mandatory-split rule (≤ ~5 phases, one layer per
+  phase) is the main lever: smaller phases are what make cheap execution
+  reliable. When in doubt, cut smaller.
+
 #### <img src="docs/assets/nan-cloud.svg" alt="NaN Cloud logo" width="20" height="19"> Running on [NaN.builders](https://cloud.nan.builders/r/7GK06FX8)
 
 [NaN Cloud](https://cloud.nan.builders/r/7GK06FX8) serves the open-weight

README.es.md

@@ -115,6 +115,52 @@ sweep — that is `product-audit`'s job). n/a if none apply.
 Product-definition decisions the project lead must make (or has made) before
 implementation starts. Record the chosen option and the rationale.
 
+### Deferred decisions
+
+Decisions deliberately postponed instead of resolved now — the interview's
+"we'll decide later" answers land here, never silently dropped. One row per
+decision; a deferred decision with no decide-by trigger is not deferred, it
+is lost. Write `none` when the section is empty.
+
+| Decision | Why deferred | Decide by (trigger or phase) |
+|---|---|---|
+
+### Spec-lint (mechanical — presence checks only)
+
+Structural gate on this SPEC, modeled on the Phase-lint: every box is a
+presence check a weak model can verify without judgement — fail-closed, no
+quality opinion. Two runners: `design-feature` runs the **product boxes**
+before stamping `## Design status: designed`; `plan-feature-scaffold` runs
+**all boxes** (product boxes re-run as a regression check) before its
+completion report. Any FAIL → fix the SPEC or end `NEEDS_INPUT` — never
+stamp `designed` or report the scaffold over a failed box.
+
+Product boxes:
+
+- [ ] No template placeholders left in the product half —
+      `grep -nE '<(where|surface|name|reason|list|role)'` over the sections
+      above returns nothing. The fenced Capability-closure template block is
+      **replaced** by the instantiated rows when the closure is walked — a
+      SPEC still containing the generic block fails this box.
+- [ ] `#### Out of scope / non-goals` has ≥ 1 concrete bullet — never empty.
+- [ ] Every Capability closure row is filled or `n/a: <reason>` — zero blank
+      rows.
+- [ ] Every `#### In scope` bullet maps to ≥ 1 Acceptance criterion (same
+      wording or an explicit reference) — an in-scope item with no criterion
+      FAILs.
+- [ ] Every Acceptance criterion is a runnable command OR labelled
+      `read-verified` — an unlabelled prose criterion FAILs.
+- [ ] `### Deferred decisions` exists; every row has a decide-by trigger, or
+      the section reads `none`.
+
+Engineering boxes (additionally, at scaffold time):
+
+- [ ] `### Dev scenarios` has ≥ 1 failure-mode row, or an explicit
+      `n/a: <reason>`.
+- [ ] Every phase passes the 8-box Phase-lint below (already mandatory).
+- [ ] No template placeholders left anywhere in the file (same grep, whole
+      file).
+
 ## Design status
 
 `not designed` — capability closure not yet complete. `design-feature` sets
@@ -164,7 +210,12 @@ prefers integration and architecture tests over heavy mocking.
 
 The situations this feature introduces that must be reproducible in local
 dev — happy path **and** failure modes (empty/degraded state, races,
-outages, mass changes, data loss). For each, name it and state how it is
+outages, mass changes, data loss). Seed the failure modes from this **fixed
+category list** — walk every category and write a scenario or
+`n/a: <reason>` (unaided recall under-enumerates; the list makes coverage a
+presence check): empty/zero state · invalid or oversized input · permission
+denied / wrong role · dependency outage or timeout · concurrent/duplicate
+action · limit or threshold hit. For each, name it and state how it is
 reached through an **existing** mechanism (queued message, guard threshold,
 manual override, stubbed source) — scenarios are orchestration, never new
 domain. If the project has a runnable dev-scenario harness, register each

README.md

@@ -48,7 +48,21 @@ own fix folder or feature where each belongs.
 
 ## Acceptance
 
-Objective, verifiable conditions for "done".
+Objective, verifiable conditions for "done". Each criterion is a runnable
+command where possible, or labelled `read-verified` — never unlabelled prose.
+
+### Spec-lint (mechanical — presence checks only)
+
+Run by `plan-fix` before committing the draft; fail-closed, no quality
+judgement. Any FAIL → fix the SPEC before the commit.
+
+- [ ] No template placeholders left (`grep -nE '<(topic|n|task|command|expected)'`
+      over the filled sections returns nothing — the `### P1` scaffold lines
+      are replaced, not kept).
+- [ ] `### Out of scope` has ≥ 1 concrete bullet — never empty.
+- [ ] Every `## Acceptance` criterion is a runnable command OR labelled
+      `read-verified`.
+- [ ] Every phase passes the 8-box Phase-lint below (already mandatory).
 
 ## Phases
 

docs/features/_TEMPLATE/SPEC.md

@@ -32,9 +32,16 @@ listado).
 
 `design-feature <slug>`:
 
-- Incorpora la entrevista de idea-en-bruto (problema y objetivo, alcance
-  dentro/fuera, pistas de arquitectura, preocupaciones transversales) cuando
-  se parte de cero.
+- Incorpora la entrevista de idea-en-bruto cuando se parte de cero — **una
+  pregunta por turno, nunca en lote**, cada una con un valor por defecto
+  recomendado. La lista de preguntas es una **rúbrica de vaguedad** fija de
+  seis huecos (usuarios/roles afectados · estados de error y borde · forma de
+  los datos · límites y umbrales · fuera de alcance · criterios de éxito);
+  todo requisito sin criterio de aceptación verificable es automáticamente la
+  siguiente pregunta, la redacción vaga se reformula como objetivos medibles,
+  las respuestas "decidir más tarde" aterrizan en la sección
+  `### Deferred decisions` del SPEC, y ≥ 3 huecos vacíos terminan el turno en
+  `NEEDS_INPUT` en lugar de adivinar.
 - Ejecuta **investigación proporcional**: primero la checklist de cierre de
   capacidades (barata), investigación externa/de dominio solo cuando el
   dominio es nuevo para el proyecto — sin investigación de mercado
@@ -61,8 +68,11 @@ listado).
   mantiene uniforme, pero pasarla es barato.
 
 Una vez que cada fila de cierre está rellenada o explícitamente marcada
-`n/a`, `design-feature` fija `## Design status` en `designed` y entrega el
-control a `/plan-feature <slug>`.
+`n/a` **y todas las casillas de producto del Spec-lint de la plantilla de SPEC
+marcan** (comprobaciones mecánicas de presencia: sin placeholders,
+fuera-de-alcance no vacío, cada criterio ejecutable o `read-verified`,
+decisiones diferidas presentes), `design-feature` fija `## Design status` en
+`designed` y entrega el control a `/plan-feature <slug>`.
 
 ### La puerta de redirección
 
@@ -159,8 +169,11 @@ equivalente, `docs/fix/<n>-<topic>/review-findings.md`.
    trabaja sobre `main`). **En P1 primero confirma los artefactos de
    planificación por separado** (`docs(NN-slug): planning artifacts`), de
    modo que el historial de planificación quede aparte de la implementación.
-2. Lee `progress.md` (qué hicieron las fases anteriores), luego `SPEC.md` +
-   `TASKS.md` de la fase solicitada.
+2. Lee `progress.md` (el **registro de handoff de fase** — una entrada fija
+   `Done / Remains / Gotchas / Files / Next` por fase), luego `SPEC.md` +
+   `TASKS.md` de la fase solicitada. Ese es todo el handoff — cada fase corre
+   en una conversación nueva bajo un presupuesto de contexto explícito (≤ 10
+   lecturas de fichero completo más allá de los docs propios de la unidad).
 3. Implementa **solo esa fase** — **tests primero** en el trabajo de
    core/dominio y orquestación: los tests de aceptación/integración de la
    fase se escriben en rojo, y luego se implementa hasta verde (los
@@ -170,7 +183,8 @@ equivalente, `docs/fix/<n>-<topic>/review-findings.md`.
    build). **Nunca confirma en rojo** — un fallo que no se puede arreglar
    dentro del alcance va a `known-issues.md` y la ejecución se detiene con un
    informe.
-5. Actualiza `TASKS.md`, `progress.md`, `testing.md`, `known-issues.md` (y
+5. Actualiza `TASKS.md`, `progress.md` (añadiendo la entrada de handoff de la
+   fase en el esquema fijo), `testing.md`, `known-issues.md` (y
    `decisions.md` si la arquitectura se movió). Cuando la realidad
    contradice el plan, se actualizan `TASKS.md`/`PLAN.md` y el porqué se
    registra en `decisions.md` — nunca una divergencia silenciosa.

docs/fix/_TEMPLATE/SPEC.md

@@ -28,8 +28,14 @@ view).
 
 `design-feature <slug>`:
 
-- Folds in the raw-idea interview (problem & goal, scope in/out, architecture
-  hints, cross-cutting concerns) when starting from zero.
+- Folds in the raw-idea interview when starting from zero — **one question per
+  turn, never batched**, each with a recommended default. The question list is
+  a fixed six-slot **vagueness rubric** (affected users/roles · error & edge
+  states · data shape · boundaries & limits · out of scope · success criteria);
+  any requirement without a verifiable acceptance criterion is automatically
+  the next question, vague wording is reframed as measurable targets, "decide
+  later" answers land in the SPEC's `### Deferred decisions` section, and ≥ 3
+  rubric slots left empty ends the turn `NEEDS_INPUT` instead of guessing.
 - Runs **proportional research**: the capability-closure checklist first
   (cheap), external/domain research only when the domain is new to the project
   — no systematic per-feature market research.
@@ -50,8 +56,11 @@ view).
   closure rows resolve to `n/a` — the gate stays uniform, but passing it is
   cheap.
 
-Once every closure row is filled or explicitly `n/a`, `design-feature` sets
-`## Design status` to `designed` and hands off to `/plan-feature <slug>`.
+Once every closure row is filled or explicitly `n/a` **and the SPEC template's
+Spec-lint product boxes all tick** (mechanical presence checks: no placeholders,
+out-of-scope non-empty, every criterion runnable or `read-verified`, deferred
+decisions present), `design-feature` sets `## Design status` to `designed` and
+hands off to `/plan-feature <slug>`.
 
 ### The redirect gate
 
@@ -140,16 +149,20 @@ ledger. `execute-phase`'s fold cycle ticks each folded row `folded: yes`;
    (it never works on `main`). **On P1 it first commits the planning artifacts
    separately** (`docs(NN-slug): planning artifacts`), so planning history
    stays apart from implementation.
-2. Reads `progress.md` (what prior phases did), then `SPEC.md` + `TASKS.md`
-   for the requested phase.
+2. Reads `progress.md` (the **phase handoff record** — a fixed
+   `Done / Remains / Gotchas / Files / Next` entry per phase), then `SPEC.md`
+   + `TASKS.md` for the requested phase. That is the whole handoff — each
+   phase runs in a fresh conversation under an explicit context budget (≤ 10
+   full-file reads beyond the unit's own docs).
 3. Implements **only that phase** — **tests first** on core/domain and
    orchestration work: the phase's acceptance/integration tests are written
    red, then implemented to green (the SPEC's dev scenarios are the test
    list). No bundling, no premature abstraction, no unrelated refactors.
 4. Runs the project's verification gate (type-check, tests, build). **Never
    commits red** — an unfixable-within-scope failure goes to
    `known-issues.md` and execution stops with a report.
-5. Updates `TASKS.md`, `progress.md`, `testing.md`, `known-issues.md` (and
+5. Updates `TASKS.md`, `progress.md` (appending the phase's handoff entry in
+   the fixed schema), `testing.md`, `known-issues.md` (and
    `decisions.md` if architecture moved). When reality contradicts the plan,
    `TASKS.md`/`PLAN.md` are updated and the why recorded in `decisions.md` —
    never a silent divergence.

docs/workflow/FEATURE_WORKFLOW.es.md

@@ -33,8 +33,10 @@ proyecto (chequeo de tipos, tests, build).
 ## Cómo invocarla
 
 - `/review-change` — el orquestador: ejecuta los ejes aplicables a esta
-  plataforma y sintetiza una tabla + una checklist de verificación manual.
-  Úsala antes de un PR.
+  plataforma — cada pasada **aislada por defecto** (contexto limpio, devuelve
+  solo su tabla de hallazgos; la composición en el mismo turno es el fallback
+  para agentes que no pueden abrir contextos nuevos) — y sintetiza una tabla
+  + una checklist de verificación manual. Úsala antes de un PR.
 - `/review-implementation` — solo el motor; por defecto usa el **diff de la
   rama actual frente a `main`**.
 - Pasa una ruta/glob para ampliar o acotar el alcance, p. ej.

docs/workflow/FEATURE_WORKFLOW.md

@@ -29,7 +29,10 @@ tests, build).
 ## How to invoke
 
 - `/review-change` — the orchestrator: runs the applicable axes for this platform
-  and synthesizes one table + a manual-verification checklist. Use this before a PR.
+  — each pass **isolated by default** (context-clean, returns only its findings
+  table; in-turn composition is the fallback for agents that can't spawn fresh
+  contexts) — and synthesizes one table + a manual-verification checklist. Use
+  this before a PR.
 - `/review-implementation` — just the engine; defaults to the **current branch diff
   vs `main`**.
 - Pass a path/glob to widen or narrow scope, e.g. *"review-implementation on