@gtrabanco/pi-agentic-workflow 0.1.0

package/skills/review-change/references/REVIEW_PROCESS.md

@@ -0,0 +1,86 @@
+## Process
+
+1. **Route selection.** No flag → the default single-reviewer review. With
+   `--adversarial N` → run the **adversarial multi-reviewer mode** below
+   instead (N reviewers FIND, per the *Isolation rule*). With `--synthesize` →
+   skip straight to that mode's fusion step (N findings tables pasted in, per
+   the synthesis contract). Either way, everything from step 2 onward runs
+   once, over the fused table.
+   **Freeze the reviewed commit before any pass:** after the clean/remote-current
+   check, run `git rev-parse HEAD` once and retain its 40-hex output as the
+   **reviewed head SHA**. The final PR receipt may be written only for that exact
+   commit; a PR whose head changes during the review requires a fresh review.
+2. **Frozen acceptance + SPEC drift check (structural).** Locate sibling
+   `ACCEPTANCE.md`, recompute its blob, and require an exact match with the
+   execution receipt before assessing the candidate. Missing/mismatch is a
+   `workflow` fix-now finding and no passing receipt may be posted. Legacy units
+   use the verification contract's committed SPEC-blob fallback. Then build a
+   **per-criterion coverage table** from the manifest — one row per acceptance
+   criterion, no free-form comparison:
+
+   ```
+   | criterion | evidence (file:line or command run) | met | unmet | untouched |
+   ```
+
+   Cross-check manifest IDs against the governing SPEC so neither silently
+   omits a criterion. Then map each diff hunk to a criterion — or to `none`. Findings, axis
+   `spec-drift`: (a) every criterion marked `unmet`/`untouched` that the unit
+   claims delivered, and (b) every `none`-mapped hunk (work the SPEC never
+   asked for — silent scope excess). Catching drift at a phase checkpoint is
+   far cheaper than at the `audit-pr` merge gate. (No SPEC found → note it
+   and skip.)
+3. **Workflow-discipline check (mechanical, every review).** On the branch
+   under review, verify and file findings under axis `workflow`:
+   commits follow `<type>(<scope>): <summary>`; phase labels in touched
+   planning docs are `P1, P2, …` (never `S1`/"Steps"); the phase's per-phase
+   docs were updated (TASKS ticks, progress entry); no commit landed on the
+   default branch; artifacts are in the project's declared docs language;
+   **the tree is clean and the remote current** — run `git status --porcelain`
+   (any tracked modification, code or docs, = a `workflow` finding: work is
+   sitting outside the commits under review) and, when the branch has an open
+   PR, `git fetch` + `git status -sb` (commits ahead of the remote = a
+   `workflow` finding: the PR and CI are judging a stale branch). Both are
+   **fix-now** — a review verdict on a branch whose real state isn't pushed
+   is worthless. Run the greps/`git log`/`git status` — don't infer compliance.
+4. **Applicable pack passes (the finders).** For each axis the matrix +
+   footprint mark as relevant, run the workflow's own internal skill for it
+   (`review-code`, `review-security`, `review-verify`, `review-design`,
+   `review-a11y`, `review-brand`, `review-perf`, `review-seo`) — **isolated,
+   per the *Isolation rule* above**, each returning ONLY its fixed-format
+   findings table + `PASS|FAIL`. **Skip the rest** and say which you skipped and
+   why. The pack ships with the workflow, so an applicable pass can never be
+   "missing". Passes **FIND** only — none of them classifies.
+5. **Optional extras.** If the project recorded additional platform review skills
+   (stack-specific linters, framework skills) and they are installed, run them
+   **in addition** — their findings merge into the same table. Never treat an
+   absent extra as a gap; the pack already covered the axis.
+6. **Synthesize.** Fuse all findings into **one** findings table, deduped by
+   `file:line` + axis, per the synthesis contract (the same fusion rules apply
+   in the default single-reviewer case). Columns: `# | Finding | Axis | Sev |
+   Evidence | Suggested fix` — **unclassified**. Overlapping signals on the same
+   defect collapse into one row. Add a **`Reviewers n/N`** column when running
+   in `--adversarial N` mode (omitted entirely in the default single-reviewer
+   case).
+7. **Classify (once).** Run `review-implementation` over the synthesized table
+   (isolated, per the *Isolation rule*) — the single classification engine
+   (D5). It verifies axis coverage (every applicable axis represented; a
+   missing axis is a `coverage` finding) and applies the current-unit contract:
+   `ignore` first, then fix-now / replan-in-unit / decision-required for
+   current-unit work, `proposal` for genuinely independent future capabilities
+   → the **classified decision table** (Sev, Class, WHY, impl risk, long-term
+   impact, premature-opt?, Route). No per-pass or per-reviewer classification,
+   no re-litigation.
+8. **Debt transform.** Run `review-debt` over the classified table — it
+   transforms debt-shaped findings into explicit TRIGGER-carrying debt items;
+   it does not rescan the diff (SPEC contract).
+9. **Manual-verification checklist.** List what automated review **cannot** confirm
+   and a human must check — visual correctness, real-device/locale behavior, UX
+   feel, perf under load, anything marked *verify*. Be explicit so the dev has zero
+   doubt about what to eyeball.
+10. **Route the outcomes.** fix-now findings fold into the current unit (or gain
+    user-confirmed phases via replan-in-unit); decision-required stops for the
+    user's decision; genuinely independent future capabilities become
+    **non-blocking proposals** — batched in the report with a trigger, and
+    **never** sent to `triage-issue` automatically (D3). `review-change` creates
+    no backlog work. No non-fix-now finding may end without a destination — none
+    silently lost.

package/skills/review-code/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: review-code
+user-invocable: false
+version: 1.0.1
+author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+license: MIT
+description: >
+  Internal correctness + simplification review pass of the agentic-workflow
+  review pack — composed in-turn by review-change and product-audit; not a menu
+  entry. Checks correctness, error handling, duplication, dead code, and
+  simplification opportunities against the project's own conventions. Findings
+  only; never edits code.
+---
+
+# Review Code (internal)
+
+Composed by `review-change` / `product-audit` within their conversation — on any
+agent, follow this file inline as the routed step. **Findings only; never edits,
+never refactors.**
+
+## Scope
+
+The diff or path/glob the caller passes; default the current change vs the
+default branch. State the scope at the top of the returned table.
+
+## Checklist (evaluate EVERY item — none is optional; n/a must be stated)
+
+✓ No logic errors on the changed paths (trace each modified function's inputs →
+  outputs, including boundary values)
+✓ Every error path is handled — no swallowed exceptions, no empty catch, no
+  silently-ignored return codes
+✓ No duplicated logic (a changed block does not re-implement an existing
+  helper — cite the existing one if it does)
+✓ No dead code introduced (unused functions, params, imports, unreachable
+  branches)
+✓ No leftover TODO/FIXME/HACK markers in the diff
+✓ Naming and file conventions match the project's docs (read them first; cite
+  the convention violated)
+✓ No new abstraction beyond what the SPEC requires (an interface/base class
+  with one implementation is a finding)
+✓ No new dependency not justified in the SPEC
+✓ Simplification: any changed block that can lose lines without losing
+  behavior (cite before/after)
+✓ Edge cases the SPEC's dev scenarios name are actually handled in code, not
+  just in tests
+
+## Return exactly
+
+```
+REVIEW CODE — scope: <scope>
+
+| # | Finding | Sev | Evidence | Suggested fix |
+|---|---------|-----|----------|---------------|
+| 1 | <what>  | critical|major|minor | <file:line> | <smallest action> |
+
+Checklist: <n> evaluated, <n> pass, <n> findings, <n> n/a (<which + why>)
+Summary: <1-2 sentences>
+Decision: PASS | FAIL
+```
+
+FAIL if any critical or major finding is open; PASS otherwise. Minor findings
+never block — they route to the caller's triage step.
+
+## Done when
+
+- Every checklist item was evaluated with evidence (file:line or command output)
+  or explicitly marked n/a with the reason.
+- The fixed-format block above is returned — nothing more, nothing less — and
+  no code was changed.

package/skills/review-debt/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: review-debt
+user-invocable: false
+version: 1.1.0
+author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+license: MIT
+description: >
+  Internal tech-debt transform pass of the agentic-workflow review pack —
+  composed in-turn by review-change and product-audit; not a menu entry.
+  Transforms the synthesized findings table into explicit debt items, each with
+  a re-trigger condition; it does not rescan the diff. Findings only; never
+  edits code.
+---
+
+# Review Tech Debt (internal)
+
+Composed by `review-change` / `product-audit` within their conversation — on any
+agent, follow this file inline as the routed step. **Findings only; never edits,
+never refactors.**
+
+## Scope
+
+The caller's **synthesized findings table** (the fused, classified decision
+table). This pass does **not** rescan the diff: debt-shaped findings are already
+in the table, and every ownership decision already happened in the finder axes
+(`review-code`, `review-verify`, …). State the scope — the change the table was
+synthesized over — at the top of the returned table.
+
+## Transform (evaluate EVERY row — none is optional; n/a must be stated)
+
+Turn the table's tech-debt-shaped rows (TODO/FIXME/HACK, duplication, stale or
+orphaned abstractions, dead code, complexity hotspots, missing tests,
+workarounds pinned to upstream fixes) into explicit, payable debt items:
+
+✓ Restate each debt-shaped finding at `file:line` with what it defers
+✓ Attribute it to the axis already recorded in the table — never re-litigate ownership
+✓ Confirm every debt item carries a TRIGGER: the condition under which it must be
+  paid (e.g. "3rd consumer appears", ">100k rows") — a debt item without a
+  trigger is itself a finding
+✓ Verify no current-unit debt was mislabeled non-blocking: current-unit work
+  cannot be `postpone`/`tradeoff`/`wontfix` — a table showing one is flagged back
+  to the classifier, never reclassified here
+✓ Honor the dead-code exception: staged/planned code cross-checked against the
+  roadmap/SPEC/TASKS is not dead code — mark *verify* when unsure, never assert
+
+## Return exactly
+
+```
+REVIEW TECH DEBT — scope: <scope>
+
+| # | Finding | Sev | Evidence | Suggested fix |
+|---|---------|-----|----------|---------------|
+| 1 | <what>  | critical|major|minor | <file:line> | <trigger + smallest action> |
+
+Rows: <n> transformed, <n> with trigger, <n> findings, <n> n/a (<which + why>)
+Summary: <1-2 sentences>
+Decision: PASS | FAIL
+```
+
+For this pass, the Suggested fix column carries the TRIGGER — the condition
+under which the debt must be paid — alongside the smallest action.
+
+FAIL if any critical or major finding is open; PASS otherwise. Minor findings
+never block — they surface in the caller's report as debt notes.
+
+## Done when
+
+- Every debt-shaped row of the synthesized table was transformed with evidence
+  (`file:line`) or explicitly marked n/a with the reason.
+- Every debt item carries a trigger; no current-unit debt was mislabeled.
+- The fixed-format block above is returned — nothing more, nothing less — and
+  no code was changed.

package/skills/review-design/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: review-design
+user-invocable: false
+version: 1.0.1
+author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+license: MIT
+description: >
+  Internal UI/UX design review pass of the agentic-workflow review pack —
+  composed in-turn by review-change and product-audit; not a menu entry.
+  Checks the changed UI against the project's design doc: consistency, states,
+  responsiveness, and reuse — applies only when the project has a UI and the
+  change touches it. Findings only; never edits code.
+---
+
+# Review Design (internal)
+
+Composed by `review-change` / `product-audit` within their conversation — on any
+agent, follow this file inline as the routed step. **Findings only; never edits,
+never refactors.**
+
+## Scope
+
+The diff or path/glob the caller passes; default the current change vs the
+default branch. State the scope at the top of the returned table.
+
+## Checklist (evaluate EVERY item — none is optional; n/a must be stated)
+
+✓ Read the project's design doc first (e.g. docs/frontend/DESIGN.md) — cite the rule for every finding
+✓ Changed components reuse the design system (no one-off styles/colors/spacing duplicating existing tokens or components)
+✓ Every new/changed view handles ALL states: loading, empty, error, success (cite each)
+✓ Responsive behavior stated and honored at the project's breakpoints (n/a if the platform has none)
+✓ No hardcoded user-facing strings where the project declares i18n (cite the i18n doc)
+✓ Visual hierarchy: primary action distinguishable, one primary action per view
+✓ Consistency with sibling screens (same patterns for the same interactions — cite the diverging sibling)
+✓ Destructive actions require confirmation and are visually distinct
+✓ Feedback on every user action (submit, save, fail) — no silent operations
+
+## Return exactly
+
+```
+REVIEW DESIGN — scope: <scope>
+
+| # | Finding | Sev | Evidence | Suggested fix |
+|---|---------|-----|----------|---------------|
+| 1 | <what>  | critical|major|minor | <file:line> | <smallest action> |
+
+Checklist: <n> evaluated, <n> pass, <n> findings, <n> n/a (<which + why>)
+Summary: <1-2 sentences>
+Decision: PASS | FAIL
+```
+
+FAIL if any critical or major finding is open; PASS otherwise. Minor findings
+never block — they route to the caller's triage step.
+
+## Done when
+
+- Every checklist item was evaluated with evidence (file:line or command output)
+  or explicitly marked n/a with the reason.
+- The fixed-format block above is returned — nothing more, nothing less — and
+  no code was changed.

package/skills/review-implementation/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: review-implementation
+user-invocable: false
+version: 1.4.0
+argument-hint: <path-or-glob>
+allowed-tools: Read, Grep, Glob, Bash, WebFetch
+author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+license: MIT
+description: >
+  Internal scope/classification engine composed by review-change (and reused by
+  the audit skills): consumes the synthesized findings table, verifies every
+  applicable axis is represented, and classifies each finding into a decision
+  table (fix-now / replan-in-unit / decision-required / proposal / ignore).
+  Findings only — never refactors.
+---
+
+# Review Implementation (internal scope/classification engine)
+
+The classification engine the review/audit skills compose: it consumes the
+**synthesized findings table** (the fused output of the applicable per-axis
+passes), verifies every applicable axis is represented, and returns the
+classified decision table — then stops. Never refactors or edits code. It owns
+the **scope/axis-coverage contract** and the **classification rubric** (the
+current-unit contract + routing) that `review-change`, `audit-pr`, and
+`product-audit` reference instead of restating.
+
+It does **not** scan the diff: every finding concern has exactly one owning
+pass (see the [axis ownership map](references/FIND.md)) — the per-axis passes
+(`review-code`, `review-security`, `review-verify`, `review-perf`,
+design/a11y/brand/SEO) find, and this engine classifies. No broad findings
+scan here.
+
+## When to use
+
+- Invoked by `review-change` (the user-facing review entry) as its
+  classification engine, over the fused findings table.
+- The audit skills reference its rubric and coverage contract.
+
+## Scope
+
+The caller's scope statement (the branch diff vs. the default branch, or the
+passed path/glob) is authoritative; the synthesized table was gathered over it.
+State the scope at the top of the classified report.
+
+## Step 0 — Discover the project (always first)
+
+Per the agent guide's **Workflow conventions** + **documentation map**, read
+what THIS skill needs: the architecture/layering rules, the testing philosophy,
+and any runtime/platform, security, money, i18n/SEO/a11y and bundle rules. Pull
+the project's specific risk axes from its guardrail skills where present. The
+`FIND.md` axis map is the default; the project's docs refine which axes are
+applicable.
+
+## Step 1 — Verify axis coverage (the synthesized table)
+
+For the declared scope, confirm **every applicable axis is represented** in the
+synthesized findings table — one finding owner per axis, per the `FIND.md`
+map: an axis the change touches that the table says nothing about is a
+**missing-axis finding** (axis `coverage`), not a silent pass. Overlapping
+signals from different passes on the same defect collapse into one row during
+synthesis — the table must contain neither duplicates nor gaps. State which
+axes were applicable and confirm each appears.
+
+## Step 2 — Classify (the current-unit contract)
+
+Read [Classify and route](references/CLASSIFY.md) and classify every row of the
+synthesized table without reopening source files: `ignore` first (the claim),
+then the current-unit contract (fix-now / replan-in-unit / decision-required
+for in-scope work), then `proposal` for genuinely independent future
+capabilities. One pass — no per-pass or per-reviewer classification.
+
+## Context budget
+
+The input is the synthesized table, not the diff. Read at most 10 non-diff
+files in full for surrounding context (callers, contracts, SPEC); targeted
+reads (≤ 50 lines of a named range) and grep/glob results don't count. Record
+each classification as its table row immediately and drop raw file content.
+
+## Guardrails
+
+- **Findings + table only. Never refactor or edit code in this skill.**
+- **One classifier.** Classification happens HERE, once, over the fused
+  table — never per-reviewer, never re-litigated in the per-axis passes.
+- Honor the dead-code exception — staged/planned code is not dead code.
+- Don't inflate severity; separate "correctness/security" from "taste".
+- Don't deflate either: current-unit work is never `postpone`/`tradeoff`/
+  `wontfix`/`disputed` and never a new issue — size routes to
+  `replan-in-unit`, not to a downgrade (current-unit contract in `CLASSIFY.md`).
+- Otherwise per the project's **Workflow conventions** (docs-language,
+  evidence): cite `file:line`, mark uncertainties *verify*.
+
+## Relationship to other skills
+
+- **Classification engine of `review-change`** — the user-facing review skill
+  runs the applicable per-axis passes (the finders), fuses their tables, then
+  composes this engine to classify. `audit-pr` and `product-audit` reuse this
+  rubric.
+- Sits in **Stage 4** of the feature workflow (verification & review).
+- `fix-now` folds into the current unit; `replan-in-unit` appends
+  user-confirmed phases then `execute-phase` on the same branch;
+  `decision-required` blocks for the user; independent work becomes proposals
+  the user routes to `triage-issue` (D3).
+
+## Done when
+
+- A synthesized table consumed, axis coverage verified (no applicable axis
+  missing, no duplicate rows), every finding classified with reasoning and
+  routed — and **no code changed**.

package/skills/review-implementation/references/CLASSIFY.md

@@ -0,0 +1,96 @@
+## Classify and route (no refactor)
+
+The single classification engine is `review-implementation`, run **once** over
+the **synthesized** findings table (D5). Classify each finding into exactly one
+class, in this order. Never reopen source files to classify; the table's
+evidence is authoritative.
+
+### Step 1 — `ignore` first (the claim, not a class choice)
+
+`ignore` claims **"this is not a real defect"** — a false positive or a
+negligible taste/overengineering note. It is decided first, on the claim alone:
+a false positive has no fix and no scope to check, so it never runs through the
+current-unit gate. If the finding IS a real defect, it is not `ignore` — drop it
+only with a rationale.
+
+### Step 2 — Is it current-unit work? (only blocking outcomes)
+
+A finding belongs to the **current unit** when it maps to the governing SPEC, a
+phase, a documented invariant, correctness, security, accessibility, a required
+UX/error state, or an expectation necessary for a competent user to consider an
+in-scope capability complete (D2: complete capabilities, not short unit
+duration). Current-unit work has **only blocking outcomes**:
+
+- **fix-now** — it can fold directly. It is NEVER a tracked issue and NEVER
+  routes to `plan-fix`: it folds into the current unit's open phase (AC 12).
+- **replan-in-unit** — it needs additional user-confirmed phases (see *Large
+  in-scope fix-now → replan, never downgrade* below).
+- **decision-required** — a new product/architecture decision is unavoidable.
+  Stop and surface it; the unit blocks until the user decides.
+
+For current-unit work, `postpone`, `tradeoff`, `wontfix`, `disputed`, and
+reviewer-created issue creation are **forbidden** (AC 10). A previously approved
+trade-off is **cited as existing evidence**, never reinvented by review.
+`disputed` remains a later fold/user outcome, not a reviewer shortcut.
+
+### Step 3 — Independent future capabilities → proposals, never issues
+
+Only a **truly independent future capability** — work the current unit does not
+promise and no competent user expects from it (D3) — may become a
+**non-blocking proposal**: batched in the report with a trigger, and NEVER sent
+to `triage-issue` automatically. `review-change` creates no backlog work; only
+the user routes a proposal to `triage-issue`.
+
+### Large in-scope fix-now → replan, never downgrade
+
+An in-scope fix-now too large to fold as-is (multi-file redesign, or evidence
+the unit should have been split) keeps its **fix-now** class — size is never a
+reason to downgrade. Set its `Route` to **`replan-in-unit`**: the unit's SPEC
+`## Phases` ledger gets one or more new phases covering the work, on the SAME
+branch — proposed to the user for confirmation, then executed via
+`execute-phase`. It never routes to `plan-fix` or a new issue (AC 12). Placement
+depends on whether the final `Hardening & PR` phase has already run:
+
+- **Hardening not yet executed** → insert the new phase(s) BEFORE it; the
+  ledger's existing close-out stays last.
+- **Hardening already executed** → append the new phase(s) AFTER it, plus one
+  fresh final `Hardening & PR` phase closing them out — the ledger must always
+  end with an unexecuted hardening close-out covering every phase before it; a
+  completed hardening never vouches for work added after it ran.
+
+The finding is not folded directly; it is folded by the new phase(s).
+
+### Decision table
+
+For every finding, give the reasoning columns. Example (generic — your findings,
+your domains):
+
+| Finding | Axis | Sev | Class | WHY | Implementation risk | Long-term impact | Premature-opt? | Route |
+|---|---|---|---|---|---|---|---|---|
+| API token committed in a config file | security | high | fix-now | Credential exposure | Low (move to secret store) | Incident risk | no | fold into phase |
+| New export endpoint has no failure-mode test | tests | med | fix-now | Untested error path | Low | Regression risk | no | fold into phase |
+| Fixing this backend bug pulls in an auth redesign | correctness | high | decision-required | Unavoidable product/architecture decision | — | Blocking | no | surface decision, block |
+| Rate limiter reusable across the fleet | architecture | low | proposal | Independent of this unit (D3) | — | — | yes | batch proposal + trigger |
+| Single-caller wrapper around a stdlib call | overengineering | low | ignore | Indirection with no payoff | — | Negligible | no | note rationale |
+
+- **Sev** — **high**: correctness, security, or data-loss risk, or a merge
+  blocker. **med**: degraded behavior, a real untested path, or notable debt.
+  **low**: taste, cosmetics, or micro-optimization without a measured need.
+- **WHY** — one-sentence justification for the class.
+- **Implementation risk** — risk of *fixing* it now (blast radius, churn).
+- **Long-term impact** — cost of *not* fixing it (debt, drift, incident odds).
+- **Premature-opt?** — yes/no: optimizing without a measured need?
+- **Route** — where it goes next (below).
+
+## Routing (what each class feeds)
+
+- **fix-now** → fold directly into the current unit's open phase; never a
+  tracked issue, never `plan-fix` (AC 12).
+- **fix-now / `replan-in-unit`** → new phase(s) appended to the unit's SPEC
+  `## Phases` ledger (user confirms first), then `execute-phase` on the same
+  branch — never a downgrade, never a tracked issue (AC 12).
+- **fix-now / `decision-required`** → stop and surface the decision; the unit
+  blocks until the user decides. No issue is created.
+- **proposal** (independent future capability) → batched in the report with a
+  trigger; the **user** decides whether to route it to `triage-issue` (D3).
+- **ignore** → note the rationale in the report; no further action.

package/skills/review-implementation/references/FIND.md

@@ -0,0 +1,35 @@
+## Axis ownership — one concern, one pass
+
+The internal review pack assigns **every review concern to exactly one owning
+pass**. No pass rescans another's surface; the per-axis passes find, and
+`review-implementation` (the scope/classification engine) verifies coverage and
+classifies the synthesized table.
+
+| Concern | Owning pass | Looks for |
+|---|---|---|
+| Bug / correctness | `review-code` | Logic errors, wrong edge-case handling, races, unhandled rejections, imprecise numeric handling |
+| Simplification / dead code / duplication | `review-code` | Unused exports, unreachable branches, commented-out blocks, obsolete files, duplicate logic — **see exception below** |
+| Overengineering | `review-code` | Unnecessary abstractions, single-caller indirection, speculative generality, micro-opt without a measured bottleneck |
+| Architecture / runtime compatibility | `review-code` | Broken dependency direction, business logic in the wrong layer, abstraction bypass, cross-layer shortcut, runtime-incompatible deps, blocking calls in the request path |
+| Project-rule violations | `review-code` | Whatever the project's docs mandate (e.g. domain value-object rules, no hardcoded UI strings, don't hide user-facing limitations, naming conventions) |
+| Security / cybersecurity | `review-security` | Secrets in code, injection, missing authz, unsafe deserialization, PII exposure, weak crypto, SSRF, over-broad CORS, leaking errors, dependency security |
+| Tests — failing/weak & missing | `review-verify` | Flaky/over-mocked/snapshot-heavy tests, uncovered branches, new use-cases/adapters without tests, SPEC dev-scenario failure modes not exercised |
+| Performance / bundle-size | `review-perf` | Algorithmic/resource/performance evidence, heavy/duplicate deps, accidental large imports, non-tree-shakeable patterns |
+| Design / a11y / brand / SEO | `review-design` / `review-a11y` / `review-brand` / `review-seo` | Only their named surfaces |
+| Tech-debt triggers | `review-debt` | Transform of the synthesized table — every debt-character finding gains an explicit TRIGGER (a debt item without a trigger is itself a finding) |
+
+### Dead-code exception (important)
+
+Do **not** flag code as removable if it is **intentionally staged for an
+in-progress or planned feature**. Before reporting the dead-code concern
+(`review-code`), cross-check the roadmap, feature SPECs/`TASKS.md`, and
+`known-issues.md`: if the code is wired into a planned phase or another
+feature, classify it *intentional / in-progress*, not dead. When unsure, mark
+it **verify** and ask — never assert "dead" on a guess.
+
+### Coverage contract (consumed by `review-implementation`)
+
+The classification engine verifies that every applicable axis for the declared
+scope is represented in the synthesized findings table: an axis the change
+touches with no table row is a **missing-axis finding** (axis `coverage`),
+not a silent pass.

package/skills/review-perf/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: review-perf
+user-invocable: false
+version: 1.1.0
+author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+license: MIT
+description: >
+  Internal performance review pass of the agentic-workflow review pack — composed
+  in-turn by review-change and product-audit; not a menu entry. Checks the
+  changed paths for algorithmic and resource regressions: N+1s, hot-path
+  allocations, asset weight, and leaks. Findings only; never edits code.
+---
+
+# Review Performance (internal)
+
+Composed by `review-change` / `product-audit` within their conversation — on any
+agent, follow this file inline as the routed step. **Findings only; never edits,
+never refactors.**
+
+## Scope
+
+The diff or path/glob the caller passes; default the current change vs the
+default branch. State the scope at the top of the returned table.
+
+## Checklist (evaluate EVERY item — none is optional; n/a must be stated)
+
+- ✓ No N+1 query/IO pattern on changed data-access paths (loop bodies issuing
+  queries/requests — cite)
+- ✓ Algorithmic complexity of new code paths stated where input can grow (an
+  unbounded O(n²) on user data is a major finding)
+- ✓ No blocking IO/sync work added on hot/request paths where the platform is
+  async
+- ✓ Resources opened by the change are closed/released on ALL paths including
+  errors (files, connections, subscriptions, timers)
+- ✓ No unbounded growth introduced (caches without eviction, arrays that only
+  append, listeners never removed)
+- ✓ Web only: bundle/asset impact of the change stated (new dep size, image
+  weight, lazy-loading where the project uses it) — n/a otherwise
+- ✓ Repeated computation hoisted where a loop recomputes an invariant (cite)
+- ✓ Pagination/limits on any new listing that reads user-scaled data
+- ✓ No premature optimization either: complexity added for speed without a
+  cited measurement is a finding (the repo forbids overengineering)
+- ✓ **Measured evidence when declared** — the project's agent guide declares a
+  `Performance commands` block with a `bench` command AND the diff touches
+  paths its benchmarks cover: RUN the benchmark on the base branch and on the
+  change, and cite both numbers in Evidence as
+  `<cmd> → base <x> / change <y> (<±z%>)`. A regression beyond the noise band
+  (the project's declared band, else ±5%) is a **major** finding; a delta
+  inside the band is no finding. The declared command failing (non-zero exit)
+  is itself a finding (the gate can't measure) — never silently skipped.
+- ✓ **No declared perf commands** → state exactly
+  `n/a — no declared perf commands` for the item above (never skip it
+  silently), and if the diff adds algorithmic code on input that can grow,
+  add a **minor** finding recommending the project adopt the tooling via
+  `init-workspace`'s Performance tooling round.
+
+## Return exactly
+
+```
+REVIEW PERF — scope: <scope>
+
+| # | Finding | Sev | Evidence | Suggested fix |
+|---|---------|-----|----------|---------------|
+| 1 | <what>  | critical|major|minor | <file:line — or, for measured findings, `<cmd> → base <x> / change <y> (<±z%>)`> | <smallest action> |
+
+Checklist: <n> evaluated, <n> pass, <n> findings, <n> n/a (<which + why>)
+Summary: <1-2 sentences>
+Decision: PASS | FAIL
+```
+
+FAIL if any critical or major finding is open; PASS otherwise. Minor findings
+never block — they route to the caller's triage step.
+
+## Done when
+
+- Every checklist item was evaluated with evidence (file:line or command output)
+  or explicitly marked n/a with the reason.
+- The fixed-format block above is returned — nothing more, nothing less — and
+  no code was changed.