@gtrabanco/pi-agentic-workflow 0.13.2 → 0.14.0

package/skills/design-feature/SKILL.md

@@ -1,231 +0,0 @@
----
-name: design-feature
-user-invocable: true
-version: 3.5.0
-argument-hint: <idea | NN-slug> [<instruction>]
-author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
-license: MIT
-description: >
-  Turn a raw idea or existing feature into a designed product SPEC by completing
-  entity, integration, role, and expectation closure. Upserts never destroy
-  recorded decisions. Triggers: "design-feature", "design this feature",
-  "define product scope".
----
-
-# Design Feature
-
-Product definition — the stage that turns an idea or a feature request into an
-exhaustive, checkable set of acceptance criteria, before any engineering
-planning happens. **Docs only — no code, no branch.**
-
-## Turn contract
-
-Load and verify the **canonical** [Turn contract](.claude/skills/orchestration-envelope/references/TURN_CONTRACT.md) (11 boxes) before ending every turn. Design-specific closure boxes (product half, capability/role matrix, expectation sweep, upsert) live only in [INTERVIEW.md](references/INTERVIEW.md). Missing reference → STOP.
-
-## When to use
-
-- A rough idea, no issue yet, and no SPEC: `design-feature "<idea>"`.
-- An existing feature slug whose SPEC is not yet marked `designed`:
-  `design-feature <NN-slug>`.
-- Revising an already-designed feature's product definition:
-  `design-feature <NN-slug> "<change>"` (instruction mode), or bare
-  `design-feature <NN-slug>` for review mode (see *Interaction & upsert*).
-- `plan-feature` redirects here when it detects an undesigned feature or a
-  product choice a `review-spec` `NEEDS-DESIGN` verdict returned to the human.
-
-## Step 0 — Discover the project (always first)
-
-Per the agent guide's **Workflow conventions** + **documentation map**, then
-read what THIS skill needs: `docs/features/_TEMPLATE/SPEC.md` (the two-halves
-layout + `## Design status` marker), the roadmap (`docs/features/ROADMAP.md`),
-the **capability inventory** (`docs/CAPABILITIES.md` — the substrate the
-Integration closure walks; if the project has none, derive an ad-hoc inventory
-from the architecture doc + codebase during step 5 and offer to seed the file
-from the template), and — if the slug already has a folder — its existing
-`SPEC.md` and `decisions.md` in full (upsert never starts blind). Skim the
-architecture and domain docs relevant to the idea's area only far enough to
-ground capability closure in the project's real entities and roles — deep
-engineering research is the Engineering half's job, not this one.
-
-Consume the internal [evidence-grounding](<../evidence-grounding/SKILL.md>)
-capability for the ordered passes and the readiness preflight: inventory →
-evidence → draft → cut → readiness. Its outcomes (`READY-FOR-REVIEW |
-NEEDS-EVIDENCE | NEEDS-DESIGN | NEEDS-REPLAN`) are an authoring gate, never an
-approval: only `review-spec` can approve a Product half.
-
-## Research gate (mandatory, fail-closed)
-
-Before the Product half is emitted, run the research gate in the evidence pass
-(step 2 of the ordered passes):
-
-- **Fetch the domain** — acquire **at least two externally fetched sources** on
-  the capability's domain (fetch/WebFetch/browser): how the domain defines and
-  solves this capability. Repo evidence alone cannot ground a design; the bias
-  this gate closes is designing from what the repository already believes.
-  Each fetched source becomes an evidence row (URL and access date).
-- **Cover the full definition** — the rows must state what the capability **is
-  and what it is not**, and the **user's expectation of it** — accepted and
-  rejected inputs, boundaries, semantics — not just the project's current
-  framing of it.
-- **Decompose every enunciated expectation** — expand each expectation the
-  user enunciates into the implicit case decomposition it implies **before**
-  the Product half is cut: valid and invalid values and limits, interaction
-  states, degraded mode, backend validation/filtering/parsing, alternate user
-  paths. The canonical case: a "phone number input" is not a field — it is the
-  whole case vector (prefixes/suffixes, lengths, non-text rejection, focus,
-  no-JS/JS behavior, backend filtering/validation/parsing) that the product
-  owner's one-liner hides.
-- **Fail closed** — offline, or a material question the fetches do not answer,
-  returns `NEEDS-EVIDENCE` with the named owner and next fetch: never a guess,
-  never an invented citation.
-- **Research before encode** — platform semantics a test will encode are
-  verified against authoritative documentation before the test exists (the
-  prevention half of `verification-contract`'s test-immutability contract).
-
-## Progressive loading — resolve status before product detail
-
-The reference allowlist is exactly the paths linked below. Never invent or read
-another `references/` path; in the DEFER column, bare names live in the same
-directory as the links.
-
-**Hard stop for an incomplete raw-idea interview:** LOAD exactly
-`references/INTERVIEW.md` and no other reference. Present its ONE compact
-form-turn — the ≤ 6 fixed rubric slots plus the identity rows, each carrying a
-recommended default the user can accept with one word — then return
-`NEEDS_INPUT` and end the turn when slots remain unresolved; genuine ambiguity
-gets at most **2 follow-up turns**, never a third ask. `WRITE_AND_UPSERT.md` is
-forbidden until every mandatory interview slot is resolved; that resource then
-owns closure rows and writing.
-
-| Condition now | LOAD now | DEFER / SKIP now |
-|---|---|---|
-| Bare existing slug, no instruction | [interview](references/INTERVIEW.md) through its interaction rule; report status and stop | `WRITE_AND_UPSERT.md`, `UPSERT_EXAMPLE.md`, `REPAIR.md`, `PORTABILITY.md` |
-| Brand-new idea with any mandatory interview slot unresolved | [interview](references/INTERVIEW.md) only; present exactly one form-turn (≤ 6 slots + identity, each with a default) and stop | `WRITE_AND_UPSERT.md`, `UPSERT_EXAMPLE.md`, `REPAIR.md`, `PORTABILITY.md` |
-| New idea after every mandatory interview slot resolves | [interview](references/INTERVIEW.md), then [closure, write, and upsert](references/WRITE_AND_UPSERT.md) | `UPSERT_EXAMPLE.md` unless shape is ambiguous; `REPAIR.md`, `PORTABILITY.md` |
-| Existing slug plus instruction | interview, then closure/write/upsert | [upsert example](references/UPSERT_EXAMPLE.md) unless shape is ambiguous; `REPAIR.md`, `PORTABILITY.md` |
-| Existing slug whose `progress.md` carries `SPEC-REVIEW-FAIL` or `NEEDS-DESIGN` | [interview](references/INTERVIEW.md), then [review repair](references/REPAIR.md) | `UPSERT_EXAMPLE.md`, `PORTABILITY.md` |
-| A named platform primitive is absent | the selected row above plus [portability](references/PORTABILITY.md) | only unrelated rows |
-
-Do not load write/upsert while an interview slot is unresolved. A supported
-primitive is not absent merely because the current task does not use it.
-
-All resources are one hop from this file. Closure rows, role matrices,
-expectation counts, fixed status blocks, and Spec-lint are normative. A missing
-required resource or unresolved mandatory slot returns NEEDS_INPUT; never guess.
-
-## Guardrails
-
-- **No review authority.** This skill authors and repairs the Product half; it
-  never approves it. Neither `## Design status: designed` nor a readiness
-  `READY-FOR-REVIEW` line is a review verdict: `review-spec` owns that, in a
-  context that did not write these bytes. Never write or "sync" a
-  `PreExecutionReviewReceipt` — the reviewer persists its own.
-- **Rotate the revision on every write.** Each write of the Product half is a new
-  `artifactRevisionId`, a revert to previously published bytes included, and the
-  closing handoff carries it. Skipping the rotation revives a stale PASS.
-- Docs only — no code, no branch (that is `execute-phase`), no engineering content
-  (architecture, design, phases, testing — `plan-feature`'s Engineering half; do
-  not pre-fill it even when the answer seems obvious).
-- Never stamp `## Design status: designed` with a blank Capability closure row,
-  a skipped inventory subsystem, an incomplete role matrix, or an unresolved
-  Expectation sweep row — a skipped row silently un-does the entire point of
-  this skill.
-- The Expectation sweep enumerates **domain conventions**, not new scope: it
-  may only route each expectation to in-scope / out-of-scope / deferred — it
-  never silently grows the feature beyond what the user confirms.
-- No market or competitive research — the mandatory research gate above is
-  this skill's only external research; no global skill/MCP discovery
-  sweep (`product-audit`'s job); no `--update` flag — upsert is always the
-  default behavior, not an opt-in.
-- Don't build a separate `DESIGN.md` — one SPEC, two halves, always.
-- **Composition tier.** This skill is planning-class (judgment work — run it
-  on your strongest model / highest effort). `plan-feature-from-issue`
-  composing this skill in-turn for a thin issue is allowed only when it runs
-  at ≥ this skill's tier; otherwise it must hand off (`run /design-feature
-  <slug>`) rather than under-power it.
-- Otherwise per the project's **Workflow conventions** (docs-language).
-
-## Normalized Repository State
-
-Consume frozen facts and decisions from `docs/workflow/REPOSITORY_STATE.md`.
-An absent fact may be inspected; a conflict becomes a resolver contradiction.
-Documentation and inference are never implementation evidence.
-
-## Architectural invariants
-
-Discover the optional project invariant document declared in the documentation
-map (normally `docs/architecture/ARCHITECTURAL_INVARIANTS.md`) before defining a
-capability. If absent, record `n/a: no project invariants declared` in the SPEC
-and continue. For every applicable rule, cite its ID and repository evidence and
-classify the proposal as `preserves`, `violates`, `introduces`, or `changes`.
-Only `preserves` may proceed to capability closure. A violation, new rule, or
-changed rule stops design for an explicit architectural decision through the
-project's declared authority; never make a SPEC, implementation plan, or test
-retroactively authorize it. When NRS exists, consume its frozen facts first;
-the repository remains authoritative and a conflict routes to the resolver.
-
-
-## Portability
-
-Do not read [portability](references/PORTABILITY.md) on a supported platform.
-Read it only after detecting that a named interaction primitive is absent. The
-interview, closure, upsert, and fixed output contracts stay identical.
-
-## Relationship to other skills
-
-- `review-spec` is the gate this skill hands to: a designed half is reviewed
-  independently before `plan-feature` may consume it. `plan-feature` fails closed
-  without that current receipt, so handing off here — not to `plan-feature` — is
-  what keeps the pipeline honest.
-- `plan-feature` **redirects here** (no bypass flag) when a feature's product
-  half is not marked `designed` or has no current review; once `review-spec`
-  passes, `plan-feature` fills the Engineering half and scaffolds the artifacts.
-- `plan-feature-from-issue` may compose this skill in-turn for a thin issue
-  (only at ≥ tier — see *Guardrails*), or hand off to it directly. It stops at
-  the Product half and `review-spec` — it no longer continues into engineering
-  planning in the same turn.
-- `evidence-grounding` owns the passes and the readiness vocabulary this skill
-  consumes; it never emits a review verdict either.
-- `triage-issue`'s `promote-to-feature` verdict routes through `plan-feature`,
-  which redirects here if the promoted issue is still undesigned.
-- `execute-phase` never calls this skill — it only executes an already-planned
-  SPEC's Engineering half.
-
-## Done when
-
-- The Product half of the SPEC is filled and every Capability closure row is
-  resolved (filled surface or explicit `n/a`).
-- `## Design status` accurately reflects the outcome (`designed` only when
-  closure is complete).
-- The roadmap row exists (created at `idea` if this was a brand-new feature)
-  and its status matches the outcome — `defined` when `designed`, left at
-  `idea` on `NEEDS_INPUT`.
-- The readiness preflight ran and returned `READY-FOR-REVIEW`, or the turn ended
-  with its exact blocking outcome.
-- The handoff states the current `artifactRevisionId`.
-- **The closing `→ Next:` block is printed:**
-
-  ```
-  → Next: /review-spec <slug> — product half designed and readiness-clean; it needs an
-      independent review before any engineering planning
-    · more to design → re-run /design-feature <slug> "<instruction>" (upsert, destroys nothing,
-      rotates the artifact revision)
-    · recurring gap in this project's capability closure → /product-audit (a systemic pattern,
-      not a one-off design fix)
-  ```
-
-  When ending `NEEDS_INPUT` instead:
-
-  ```
-  → Next: answer the pending question, then re-run /design-feature <slug>
-    · unsure how to scope it → propose the smallest version and confirm
-  ```
-
-  When readiness returned `NEEDS-EVIDENCE` or `NEEDS-REPLAN`:
-
-  ```
-  → Next: /design-feature <slug> "<the missing evidence>" — readiness returned
-      NEEDS-EVIDENCE for <rows>; do not invoke /review-spec on an artifact that is
-      not readiness-clean
-    · the gap is engineering, not product → it belongs to plan-feature's evidence, not here
-  ```

package/skills/design-feature/references/INTERVIEW.md

@@ -1,74 +0,0 @@
-## Process
-
-1. **Resolve the slug.** A raw idea with no existing folder → propose a number
-   (next free roadmap slot) and a kebab-case slug; confirm before writing. An
-   existing `NN-slug` → that folder's `SPEC.md` (create the folder + copy the
-   template if the roadmap has the row but no folder yet).
-2. **Interaction rule (fixed — no interpretation):**
-   - **Bare `design-feature <slug>`** (existing SPEC/decisions found): print a
-     summary of what the feature currently does (or would do, from a fresh
-     idea) → ask what to add / remove / change. This doubles as review mode.
-   - **`design-feature <slug> <instruction>`**: apply the instruction
-     directly, no questions — touch only what the instruction implies. Still
-     re-reads the existing SPEC/decisions first (upsert, never blind).
-   - **Nothing exists yet** (brand-new idea, no prior SPEC): go straight to
-     step 3 (interview), since there is nothing to review or upsert.
-3. **Raw-idea interview (folded in, only when starting from zero or the
-   instruction leaves genuine gaps).** Fixed protocol — structural, not
-   judgement:
-   - **One form-turn, then at most 2 follow-up turns.** The first interview
-     turn is ONE compact form covering every rubric slot below plus the
-     identity slots, each row carrying a recommended default the user accepts
-     with one word (or edits in place). Ask nothing the docs or the instruction
-     already answer. Genuine ambiguity the form cannot resolve gets at most
-     **2 follow-up turns** — never a third ask.
-   - **Vagueness rubric (fixed slots — the form rows ARE this list).**
-     Probe each slot until it is filled or explicitly `n/a: <reason>`:
-     1. **Affected users/roles** — who uses it; who must not.
-     2. **Error & edge states** — what happens on failure / empty / invalid.
-     3. **Data shape** — what is stored and shown, roughly.
-     4. **Boundaries & limits** — sizes, counts, rates, thresholds.
-     5. **Out of scope** — what this deliberately does NOT do.
-     6. **Success criteria** — how we verify it worked.
-   - **Mandatory-question rule.** A stated requirement that has no verifiable
-     acceptance criterion yet is automatically the next question — no
-     requirement enters the SPEC without one.
-   - **Reframe, don't interrogate.** Restate each vague requirement as
-     measurable criteria ("fast" → "list renders < 200 ms at 1k rows") and
-     ask: "are these the right targets?" — a yes converts directly into
-     acceptance criteria.
-   - **Deferred decisions.** An answer of "decide later" is recorded as a row
-     in the SPEC's `### Deferred decisions` (with a decide-by trigger) —
-     never dropped, never silently guessed.
-   - **Escalation (structural).** If, after the interview, **≥ 3 rubric slots
-     remain empty** (neither filled nor `n/a`), do not guess: end the turn
-     `NEEDS_INPUT`, listing the empty slots verbatim as the pending
-     questions — the feature is not designable yet. Ambiguity that survives the
-     follow-up budget escalates the same way (`interview:ambiguity-cap`): the
-     2-turn cap never licenses a third ask.
-   - The identity questions ride the same form-turn: problem & goal, business
-     goals, size estimate (`XS/S/M/L` — XS/S stays SPEC-only, M/L gets the
-     full artifact set), non-goals / future work, traceability (offer a
-     tracking issue; if created, the eventual PR will `Closes #n`).
-4. **Proportional research.** Capability closure (step 5) is cheap and comes
-   first. Reach for external or domain research **only** when the feature
-   touches a domain genuinely new to the project (a regulation, an unfamiliar
-   integration, an industry convention with no precedent in the codebase) —
-   never as a systematic per-feature step.
-
-## Turn contract — design closure boxes
-
-```text
-✓ Product half written with every capability-closure row resolved (filled surface
-  or explicit `n/a: <reason>`) — zero blank rows
-✓ Spec-lint product boxes ticked, and `## Design status` set to what they prove
-  (never optimistically); roadmap row never written past `defined` here
-✓ Evidence rows: every material claim `proven`/`decision` at `current` freshness,
-  or `unknown` naming its owner and the next evidence step
-✓ `stage: spec` readiness block printed; the artifact is handed off only on
-  `READY-FOR-REVIEW`
-✓ `artifactRevisionId` rotated for the bytes just written and named in the
-  closing block
-✓ Repair turns: one batch over the whole open findings set, each finding's repair
-  class recorded, no receipt text touched
-```

package/skills/design-feature/references/PORTABILITY.md

@@ -1,15 +0,0 @@
-## Portability (agents other than Claude Code)
-
-The workflow is the contract; Claude Code features are conveniences. On an
-agent that lacks one, apply the fallback — never skip the step the feature
-enables:
-
-- **No slash-command menu** — where this skill says `/<skill>`, open that
-  skill's `SKILL.md` (wherever your agent installed the skills) and follow it
-  literally, in a fresh conversation: hand-offs assume a clean context.
-- **No per-skill `model:`/`effort:`** — on the `#claude` branch the
-  frontmatter pins these tiers; here, pick tiers yourself: capability closure
-  is judgment work — run it on your **strongest** model available.
-- **No `/loop`** — re-invoke this skill by hand when a review round or an
-  instruction-mode revision is needed; follow the closing `→ Next:` block each
-  time.

package/skills/design-feature/references/REPAIR.md

@@ -1,88 +0,0 @@
-## Repair a reviewed Product half
-
-Load this resource only when the unit's `progress.md` carries a
-`SPEC-REVIEW-FAIL` or `NEEDS-DESIGN` receipt from `review-spec`, or when the user
-asks to close such findings. This is the author's repair pass — the reviewer's
-findings are input, never a to-do list to be renegotiated.
-
-### 1. Take the whole findings set as one batch
-
-Read every open finding of the newest spec-stage receipt plus every open finding
-this unit previously recorded. Classify each by root cause
-(`product | plan | source | environment | runtime`) before touching any file.
-
-Then apply **one evidence-bounded repair batch** to the owning artifact(s) and
-request one re-review of the new snapshot. Rules:
-
-- Do not fix one finding, re-review, fix the next, re-review. Findings from one
-  review are one batch, because the root cause is usually shared (an un-inventoried
-  obligation, a role the matrix never listed, an "obvious" domain convention that
-  skipped the expectation sweep).
-- Do not split a batch because the findings landed in different files; a Product
-  half and its `decisions.md` are one owning artifact set.
-- Findings classified outside `product` are **not** repaired here: leave them
-  open, name their owner (`review-plan`/`plan-feature` for plan defects, the
-  executor for source defects), and say so in the repair note. Repairing a plan
-  defect by editing the Product half is scope creep with extra steps.
-- Never dismiss a finding by re-arguing with it: dismissal requires recorded
-  counter-evidence that falsifies the claim (`pre-execution-review/references/POLICY.md`
-  §2), written into the
-  `planning-findings.md` row's resolution evidence, never into chat.
-
-### 2. Three repair classes — pick one per finding and record which
-
-| Class | Allowed when | Who acts | Evidence required |
-|---|---|---|---|
-| Mechanical, intent-preserving | wording, heading order, pointer format, a copy-paste slip in a row that already resolves correctly | this skill, autonomously | a dated `decisions.md` line: which finding ids, why intent is unchanged |
-| Closure completion | a blank/`n/a`-less closure row, a missing sweep row, an unlabelled criterion, an unowned unknown | this skill, after acquiring the evidence | new/updated evidence rows at `current` freshness |
-| Product change | scope, intent, role, authority, or user outcome actually changes | the human, through this skill's interview | a dated SPEC `## Amendments` row or `Product decisions` entry quoting the user's decision |
-
-The first two stay autonomous **only while reviewed product intent is
-unchanged**. If the repair would add, remove, or redirect scope, it is the third
-class: stop and ask, one bounded question at a time. The reviewer proved a gap
-exists; it never chose how to fill it, and neither does this skill.
-
-### 3. New revision, new review
-
-1. Apply the batch to the Product half and, when a decision was made, to
-   `decisions.md` (append, dated — never rewrite a prior decision).
-2. Re-run the Spec-lint product boxes and the `stage: spec` readiness preflight;
-   paste both results.
-3. Mint a **new** `artifactRevisionId` — mandatory even when the bytes came back
-   to a previous state. A revert is an authoring event; reusing the old id is how
-   a stale PASS gets resurrected.
-4. Hand off to `/review-spec <slug>` for a re-review of the new snapshot. Never
-   self-certify the repair, never reuse the reviewer's verdict for the new bytes.
-
-### 4. Second cycle = anomaly, not routine
-
-Cycle rules have one owner: `pre-execution-review/references/POLICY.md` §4 — a repeat needs a changed
-snapshot or a named falsifiable question plus a new evidence route, and a second
-consecutive repair/re-review cycle prints the `CONVERGENCE-ANOMALY` block (repeated
-and new finding ids, the snapshots that moved, the evidence or obligation missed,
-the owning stage, and why the prior readiness/review/repair failed) **before** any
-further edit, then routes to that owner. The repair cycles are the correction
-path; they never earn a PASS, and an exhausted cycle budget does not downgrade an
-open finding. A third cycle never starts without explicit user instruction: the
-orchestrator's `stop-review-loop-cap` refusal stops the invocation and names
-`design-feature` as the human route, and a PASS resets the count.
-
-The cap counts review invocations, never repairs: a repair responding to a
-persisted verdict produces a new snapshot by design, so the repair turn itself is
-never a loop defect. An open finding is never downgraded or waved through to
-satisfy a count.
-
-The spec-stage detail this skill adds: the owning stage of a Product-half miss is
-`product` unless the evidence proves the plan asked for something the SPEC never
-said — then it is `plan`, and it leaves this skill for `plan-feature`.
-
-### 5. Guardrails
-
-- Never edit `SPEC-REVIEW-PASS` text, a receipt block, or a finding's severity to
-  make a gate pass. Receipts are the reviewer's output.
-- Never create a forge issue to hold a current-unit obligation so this batch looks
-  closed (descope guard). Amending scope requires the human's dated amendment
-  first, an issue second, never the reverse.
-- Never widen scope while "already in the file": new obligations re-enter the
-  inventory pass with a dated note.
-- Upsert rules still apply: append, date, and preserve recorded decisions.

package/skills/design-feature/references/UPSERT_EXAMPLE.md

@@ -1,8 +0,0 @@
-## Interaction & upsert (worked shape)
-
-```
-design-feature <slug>                → print summary → ask what to add/remove/change
-design-feature <slug> "<instruction>" → apply directly, no questions, scoped to the instruction
-design-feature "<new idea>"           → interview from zero (no prior SPEC to review)
-design-feature <slug> "delete and redesign, <new direction>" → the only from-zero reset path
-```

package/skills/design-feature/references/WRITE_AND_UPSERT.md

@@ -1,115 +0,0 @@
-## Closure, write, and upsert
-
-0. **Inventory before drafting** (the `evidence-grounding` passes, Product stage).
-   List every normative obligation, affected role/use case, failure state,
-   compatibility boundary, recorded decision, and material unknown, then acquire
-   one evidence row per material claim
-   (`claim-or-obligation | authority-kind | source-and-location |
-   observed-revision | freshness | status | owner-or-next-evidence`). Product
-   conclusions freeze in the SPEC's Product half and `decisions.md`. A claim you
-   cannot evidence stays `status: unknown` with an owner — it never becomes a
-   plausible rationale. A repeated read that answers no new question is
-   no-progress: stop and report the missing evidence.
-
-5. **Capability closure (the core).** Walk the SPEC template's **three fixed
-   checklists** (`docs/features/_TEMPLATE/SPEC.md` → `### Capability closure`
-   is the authoritative block — instantiate it, never paraphrase it) and write
-   the result into the SPEC's `### Capability closure` section. Every row
-   resolves to a filled surface **or** an explicit `n/a: <reason>` — a blank
-   row is not a valid state, it is an unfinished design:
-   1. **Entity closure** — for every entity the feature introduces or
-      touches: Create/Read/Update/Delete/state-transitions, each with UI
-      entry point + API surface + test.
-   2. **Integration closure** — reconcile the feature against **every**
-      subsystem in the capability inventory (`docs/CAPABILITIES.md`), one row
-      per subsystem, none skipped: how does this feature touch auth, ACL,
-      navigation, notifications, search, audit, settings, …? ("blog" ⇒ ACL
-      gets a `blog:write` permission; the dashboard gets an "Articles" link
-      with drafts above published and a "New article" button; auth is
-      required to write.) **No inventory file** → derive the inventory from
-      the architecture doc + codebase, record it in the section, walk it, and
-      offer to seed `docs/CAPABILITIES.md` from the template (upsert-safe,
-      user confirms).
-   3. **Role matrix** — for every capability, EVERY role in the inventory is
-      explicitly `allowed` or `denied` — no role unlisted, no "admins
-      obviously can" left implicit.
-
-   The filled rows **become the Acceptance criteria** — copy each resolved row
-   (or its `n/a` line) into `## Acceptance criteria` as an objective, checkable
-   condition. Do not restate them loosely; the checklist row *is* the
-   criterion.
-6. **Expectation sweep (the implicit-knowledge gate).** Enumerate **≥ 10
-   candidate expectations** (M/L; **≥ 5** for XS/S) a competent human would
-   assume ship with a feature of this kind without being told — domain
-   conventions, not project specifics ("a blog has drafts and a publish
-   action", "a list has an empty state", "a delete asks for confirmation").
-   Fill the SPEC's `### Expectation sweep` table: each row resolves to exactly
-   one of `in-scope` (add/point to an acceptance criterion), `out-of-scope`
-   (add to *Out of scope / non-goals*), or `deferred` (row in *Deferred
-   decisions*) — **never left unmentioned**. Rows the user rejects are
-   recorded as out-of-scope, not dropped: a rejected expectation is a future
-   surprise defused. When a resolution genuinely needs the user's call, it
-   rides the step-3 interview protocol (one question per turn, recommended
-   default).
-7. **Scale-down for XS features.** The gate stays uniform — every closure row
-   and inventory subsystem is still walked, the sweep still runs (≥ 5 rows) —
-   but for a small feature most rows resolve to `n/a: out of scope for this
-   slice` in one pass, and the interview (step 3) may be a single confirming
-   question. Passing the gate is cheap; the gate itself never opens.
-9. **Per-feature tooling notes.** Check which installed skills/MCPs are
-   relevant to *this* feature (e.g. a payments MCP for a billing feature) and
-   record them in `## Tooling`. This is not a global discovery sweep — that is
-   `product-audit`'s job; record only what this feature will actually use.
-10. **Write the Product half.** Fill `Context`, `Business goals`, `Scope`
-   (in/out), `Capability closure`, `Acceptance criteria`, `Tooling`,
-   `Product decisions`, and `Deferred decisions` (`none` if empty) in the
-   SPEC. When instantiating the closure, **replace** the template's fenced
-   example block with the filled rows (keeping it fails the spec-lint's
-   placeholder box). Record every non-obvious call in `Product decisions`
-   with its rationale, and log any residual unknown as an open question in
-   `decisions.md` rather than guessing.
-11. **Run the Spec-lint product boxes, then stamp.** Mechanically check the
-   SPEC template's `### Spec-lint` **product boxes**
-   (`docs/features/_TEMPLATE/SPEC.md`) and paste the box results. All
-   product boxes tick → set the marker to `designed` **and**
-   set this feature's `docs/features/ROADMAP.md` row status to `defined` (the
-   `idea → defined` transition this skill owns — see the roadmap's Status
-   legend). If the row doesn't exist yet (brand-new feature, no prior `idea`
-   row), add it first at `idea` (number, slug, dependencies), then promote it
-   to `defined` in the same edit — no feature is ever registered directly at
-   `defined` without passing through `idea`. Any spec-lint product box FAILing
-   (a blank closure row, an unlabelled prose criterion, an in-scope item with
-   no criterion, …), or an unresolved question blocking closure → leave
-   `## Design status` at `not designed`, leave the roadmap row at `idea` (or
-   unadded), and end the turn with the failed boxes / pending question stated
-   plainly instead of a false `designed` stamp or a premature `defined` write.
-12. **Confirm the roadmap row.** The row from step 11 carries the right number,
-    slug, dependencies, and status (`defined`). Beyond `defined`, status
-    transitions (`planned`, `in-progress`, `done`) are `plan-feature-scaffold`'s
-    and `execute-phase`'s job — this skill never writes past `defined`.
-12b. **Readiness preflight, then rotate the revision.** Before handing off, run
-    the `stage: spec` readiness boxes owned by the internal
-    [`evidence-grounding`](<../../evidence-grounding/SKILL.md>) skill (its ordered
-    passes route to its own readiness reference) and paste the fixed
-    `READINESS — <NN-slug> spec <outcome>` block. Only
-    `READY-FOR-REVIEW` may hand off; `NEEDS-EVIDENCE` / `NEEDS-DESIGN` /
-    `NEEDS-REPLAN` keep the artifact at home with the named missing row. Readiness
-    is an authoring gate: it licenses a review request, never a review verdict.
-    Then mint the new `artifactRevisionId` for the bytes just written (every write
-    rotates it — a revert included) and carry it in the handoff.
-13. **Upsert semantics (never destroy).** Re-running on an existing slug
-    re-reads the SPEC and `decisions.md` first; a revision **appends** to
-    `decisions.md` (dated, with what changed and why) — it never rewrites or
-    deletes a prior decision. The only path that starts the product half from
-    zero is an explicit "delete and redesign" in the prompt; even then, record
-    that reset itself in `decisions.md`. **This is the retrofit path
-    `audit-pr`'s closure-integrity gate routes to:** a legacy SPEC with no
-    `Capability closure` block trips that gate's dated `design-debt:
-    closure absent, SPEC predates the rule` warning (never a blocker) on the
-    next PR touching the feature; re-running `design-feature <slug>` there
-    fills only the missing closure rows via this same upsert — it never
-    rewrites what's already recorded.
-14. **Hand off.** Once `designed` and readiness-clean, print the closing block
-    (see *Done when*) recommending `/review-spec <slug>` with the current
-    `artifactRevisionId`. Do **not** recommend `/plan-feature`: engineering
-    planning is gated on an independent Product review this skill cannot supply.