rsc-universal 0.1.1

package/skills/review/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: review
+description: "Use when giving OR receiving an adversarial code review in the rsc SDD chain — after implement/verify and before ship. Triggers: 'review this PR', 'review my diff', 'revisa este código', 'critique this change', 'be my reviewer', 'tear this apart', 'what's wrong with this code', plus the receiving side: 'the reviewer said X', 'address this review comment', 'they want me to change Y', 'do I have to do what the review says', 'PR feedback', 'someone left comments on my PR'. Covers the full loop: producing a rigorous, evidence-backed review keyed to the spec/plan/constitution under 02-DOCS/wiki/sdd/, AND processing incoming feedback with technical rigor — verify each finding against the code before agreeing, push back on the wrong ones, fix the real ones. NOT running lint/type/test gates (that's the verify phase) and NOT merging/closing the branch (that's ship). No performative agreement; points to ship when the diff survives review."
+tags: [sdd, review, code-review]
+recommends: [ship]
+profiles: [core, full]
+origin: risco
+---
+
+# Review — adversarial code review, both directions
+
+Review is the **penultimate gate** of the rsc SDD chain: `constitution → specify → clarify → plan → tasks → analyze → implement → verify → **review** → ship`. By the time a diff reaches review, the `verify` phase has already proven that lint, types, tests and the stack `verify.sh` are green. Review answers a different question: **is the green diff actually correct, well-scoped, and faithful to the spec — or did it pass for the wrong reasons?**
+
+This skill owns **two roles that share one discipline**:
+
+- **Giving** a review — read a diff adversarially, find the real defects, rank them by impact, ship the verdict as evidence not opinion.
+- **Receiving** a review — take incoming feedback (human or machine), verify each point against the code *before* acting, fix the real findings, and push back — with proof — on the wrong ones.
+
+The discipline is the same in both directions: **claims are backed by evidence, never by deference.** A reviewer who waves through a bug to be agreeable, and an author who edits working code because a comment *sounded* authoritative, are making the same mistake. This skill exists to kill both.
+
+## Read these first
+
+1. `02-DOCS/wiki/harness/user-profile.md` — the **accompaniment dial** (L0..L3). It sets how much you narrate, not how rigorous you are. Rigor is fixed; verbosity is dialled. See "Accompaniment dial" below.
+2. `02-DOCS/wiki/sdd/specs/<slug>.md` and `02-DOCS/wiki/sdd/plans/<slug>.md` — what the diff was *supposed* to do. A review with no spec is a review of vibes.
+3. `02-DOCS/wiki/sdd/constitution.md` — the project's non-negotiables (stack canon, quality bars, conventions). Constitution violations are findings even when the code "works".
+
+If there is no spec/plan (someone jumped straight to code), say so and review against the constitution + the diff's own stated intent. Don't pretend a spec exists.
+
+## When to use / When NOT to use
+
+Use when:
+
+- A diff, branch, or PR is ready and you want it torn apart before it ships.
+- You are the author and a review landed — comments from a teammate, a bot, or another agent — and you need to decide what to actually change.
+- A "review comment" feels wrong, vague, or technically questionable and you're tempted to just comply.
+
+Do NOT use when (route elsewhere):
+
+- You need lint / type-check / test / audit to run and go green → that's the **verify** phase, run before review.
+- The diff has survived review and you want to PR / merge / close the branch → that's the **ship** phase (and ship enforces Eric-only git authorship).
+- It's specifically a *security* threat-model / OWASP pass → `../secure-coding/SKILL.md` (review folds in its findings, but the deep pass is owned there).
+- The "review" is really framework-level "is this idiomatic React/FastAPI/Go" — pull the relevant stack skill (`../nextjs/SKILL.md`, `../fastapi/SKILL.md`, `../go/SKILL.md`, `../postgresdb/SKILL.md`, `../flutter/SKILL.md`) for the idiom, then judge against it here.
+
+## The one rule
+
+> **Every finding and every rebuttal carries evidence. No agreement without verification, no objection without a defect.**
+
+Everything below is in service of that rule.
+
+## Confidence filtering
+
+A review's value is its signal-to-noise. Every finding you report costs the author triage time, so report only what you can stand behind:
+
+- **>80% sure, or it doesn't ship.** If you're not >80% confident a finding is a real defect, either trace it until you are, or downgrade it to `[question]` and ask. Plausible-looking ≠ verified.
+- **Zero findings is an acceptable verdict.** A clean diff gets `APPROVE`, not a manufactured nit. Padding a report to look thorough is the opposite of thorough.
+- **Common false positives to skip:** patterns guarded two functions up; "unsafe" calls on values that are provably constant/internal; missing checks the framework already enforces; style the linter owns; defects behind a flag that's off everywhere (note as `nit`, not blocker); test-only or generated code held to prod standards.
+- **No severity inflation.** A `should-fix` dressed as a `blocker` burns the same trust as a missed bug. Rank by actual blast radius and reachability — if everything is a blocker, nothing is.
+
+## Executable review
+
+This skill is the **discipline**; the **`rsc-review` bundle is its automated counterpart**. When you want the doctrine above run for you over a real diff:
+
+- **`/code-review [pr]`** — fans the diff out to the per-language reviewer fleet (`code-reviewer`, `web-reviewer`, `python-reviewer`, `go-reviewer`, `sql-reviewer`, `flutter-reviewer`) in parallel and aggregates one ranked verdict.
+- **`/security-scan`** — two-layer security pass: automated scanners plus the `security-reviewer` agent, merged into one exploitability-ranked report.
+
+Those commands and agents enforce the same evidence bar and the same confidence filtering described here — they are this skill, executed.
+
+---
+
+## GIVING a review
+
+A good review is not a list of everything you'd have done differently. It is a ranked set of **defects that matter**, each one reproducible from the diff itself.
+
+### The pass order
+
+Run these passes in order; each is cheap and catches a different class of defect. Stop padding the report once a pass is clean — a clean pass is a finding too ("auth path: checked ownership scoping, correct").
+
+| Pass | The question | Typical defects |
+| --- | --- | --- |
+| **1. Spec fidelity** | Does the diff do what the spec/plan said — no more, no less? | Missing acceptance criteria; scope creep; a TODO masquerading as done |
+| **2. Correctness** | Is it right on the boundaries, not just the happy path? | Off-by-one, null/empty/zero, error paths swallowed, race, wrong operator |
+| **3. Contracts & data** | Do the interfaces and data shapes hold? | Breaking API change, nullable mismatch, migration that loses data, N+1 |
+| **4. Security boundary** | Any untrusted input reaching a sink? | Injection, authz gap (authenticated ≠ authorized), secret in diff, SSRF |
+| **5. Tests as evidence** | Do the tests actually exercise the change, or just pass? | Asserts on mocks, no failing case, happy-path-only, deleted assertions |
+| **6. Constitution & fit** | Does it honor the project's canon and read like the codebase? | Banned pattern, wrong layer, duplicated logic, dead code left behind |
+
+Passes 1–5 are correctness/safety — those produce **blocking** findings. Pass 6 is fit — usually **non-blocking** unless it violates a stated constitution rule.
+
+### Severity — rank or it's noise
+
+Tag every finding. An unranked review forces the author to triage your opinions; a ranked one tells them exactly what blocks the merge.
+
+- **`blocker`** — ships a bug, a vuln, data loss, or breaks the spec. Merge does not happen until resolved.
+- **`should-fix`** — real defect, narrow blast radius; fix now or file a tracked follow-up the author agrees to.
+- **`nit`** — style/preference with no correctness impact. Explicitly labelled, never blocking, the author may decline freely.
+
+If everything is a blocker, nothing is. If everything is a nit, you didn't review.
+
+### Finding format
+
+Each finding is a quoted location, the defect, the evidence, and a concrete fix. No "consider maybe looking at error handling here."
+
+```text
+[blocker] auth: authenticated user can read any document
+  where:  api/documents.py:42  return db.get(Document, doc_id)
+  why:    doc_id comes from the path; no owner check. Any logged-in
+          user enumerates every document by id.
+  repro:  GET /documents/<other_users_id> with a valid session → 200 + body.
+  fix:    scope the query — WHERE id == doc_id AND owner_id == current_user.id;
+          return 404 (not 403) on miss to avoid leaking existence.
+```
+
+A finding without a `repro` or a mechanism is a *suspicion*. Label it `[question]` and ask, don't assert it as a defect.
+
+### Verify before you flag
+
+The reviewer is held to the same evidence bar as the author. Before writing a `blocker`:
+
+- **Read the surrounding code**, not just the diff hunk. The check you think is missing may live two functions up.
+- **Trace the value**, don't pattern-match. "This looks like SQL injection" is not a finding; "this f-string interpolates `request.args['q']` straight into `execute()`" is.
+- **Confirm the path is reachable.** A defect behind a flag that's off in every environment is a `nit`, not a `blocker` — say so.
+
+A reviewer who cries blocker on a non-bug burns the same trust as an author who ships one.
+
+### The verdict
+
+End every review you give with one of three, and nothing mushy in between:
+
+- **`APPROVE`** — no blockers, no unresolved should-fix. Say it plainly and **point to ship**.
+- **`APPROVE WITH NITS`** — mergeable; the nits are the author's call.
+- **`CHANGES REQUESTED`** — one or more blockers/should-fix. List exactly what unblocks it.
+
+---
+
+## RECEIVING a review
+
+This is the half everyone skips. Feedback arrives and the reflex is to either comply with all of it (looks cooperative, ships bugs) or dismiss the annoying parts (looks confident, ships bugs). Both skip the only step that matters: **checking whether the finding is true.**
+
+### Process every comment through this gate
+
+For each incoming finding, before touching a line of code:
+
+```text
+1. RESTATE   — what is the reviewer actually claiming is wrong? (in one sentence)
+2. VERIFY    — go to the code. Is the claim true? Trace it. Can you reproduce it?
+3. CLASSIFY  — true defect / partially-true / false / unclear
+4. ACT       —
+     true        → fix it, and add the test that would have caught it
+     partial     → fix the real part, reply on the rest with evidence
+     false       → DON'T change the code. Reply with the proof it's already handled
+     unclear     → ask one specific question; don't guess and don't pre-emptively edit
+```
+
+The expensive failure is step 2 skipped. Editing working code because a comment *sounded* right introduces bugs the original author (you) already prevented.
+
+### Pushback is a feature, not rudeness
+
+Disagreeing with a wrong finding — **with evidence** — is doing the job, not being difficult. The reply is not "you're wrong"; it's the trace:
+
+```text
+> Reviewer: this can NPE if `user` is null.
+Verified: `user` is non-null here — it's the return of `require_auth()` on
+line 12, which raises 401 before this line on a null session. Added a test
+(test_get_doc_unauthenticated) that asserts the 401 so this stays true.
+Leaving the code as-is.
+```
+
+That reply *strengthens* the diff (it added a regression test) while declining the change. That's the bar.
+
+### Performative agreement is the failure mode
+
+The tells, and what to do instead:
+
+| Tell | Reality | Do instead |
+| --- | --- | --- |
+| "Good catch!" then editing without checking | You don't yet know if it's a catch | Verify first; *then* "good catch" or "checked — already handled" |
+| Rewriting a whole function to satisfy a nit | Scope creep dressed as responsiveness | Make the minimal change the nit asks for, or decline it as a nit |
+| Silently making the change the bot suggested | Bots flag plausible-looking non-bugs constantly | Trace it like any other finding; reply with the verdict |
+| "You're probably right" with no trace | Probably-right is not verified | There is no probably. Reproduce it or refute it |
+
+### Author's verdict
+
+When you've processed the review, summarize for the reviewer (and the decisions log): findings accepted + fixed (with the commit/test), findings declined + why (with evidence), findings deferred + tracked. Then the diff is ready to re-review or, if clean, to ship.
+
+---
+
+## Accompaniment dial (L0..L3)
+
+Read the level from `02-DOCS/wiki/harness/user-profile.md`. **It changes the narration, never the rigor** — every level runs the same passes and the same evidence bar.
+
+- **L0** — verdict + the blocker list, terse. `CHANGES REQUESTED: 1 blocker (auth, documents.py:42), 1 nit. Fix the auth scope and re-run verify.`
+- **L1** — each finding gets its one-line *why*.
+- **L2** — full finding format (where/why/repro/fix); explain why each blocker blocks.
+- **L3** — the above plus teaching: name the defect class (IDOR, N+1, TOCTOU), why the boundary matters, and how to not reintroduce it. For non-technical authors, translate the impact ("any logged-in person could read everyone else's documents").
+
+When no profile exists, default to L2 and proceed — don't stall a review to ask for a dial setting.
+
+## Anti-patterns → STOP
+
+| Rationalization | Reality |
+| --- | --- |
+| "It passed verify, so it's correct" | Green gates prove it runs and tests pass, not that the logic is right. Review is the logic gate. |
+| "I'll list everything I'd do differently" | A review is ranked defects, not your preferences. Tag nits as nits or drop them. |
+| "This pattern usually means a bug" | Usually isn't a finding. Trace this instance or label it `[question]`. |
+| "The reviewer is senior, they're probably right" | Seniority isn't evidence. Verify the claim against the code like any other. |
+| "Just apply all the comments, it's faster" | Applying a false finding ships a regression. Each comment goes through the gate. |
+| "Pushing back will look defensive" | Pushing back *with a trace* strengthens the diff. Silent compliance hides bugs. |
+| "I'll approve it, the issues are minor" | If they're truly minor, label them nits and approve. If they block, don't approve. No mushy middle. |
+| "No spec, so I'll just eyeball it" | Say there's no spec and review against the constitution + stated intent. Don't fake a baseline. |
+
+## Where this writes
+
+Review is mostly a conversation, but two artifacts persist into the harness wiki so the knowledge model grows:
+
+- **Accepted/declined findings** of consequence → append to `02-DOCS/wiki/sdd/decisions.md` (e.g. "declined NPE finding on documents.py:42 — guarded by require_auth; added regression test"). This is the same append-only log `implement` writes to.
+- If a finding reveals a **missing constitution rule** (a defect class the project keeps hitting), propose adding it to `02-DOCS/wiki/sdd/constitution.md` so the next review catches it earlier.
+
+Index both under the root `CLAUDE.md` `## Knowledge map` (the `sdd/` topic) — the harness owns that map; this skill just keeps its rows honest.
+
+## Next in the chain
+
+When the diff carries an **APPROVE** / **APPROVE WITH NITS** verdict and every blocker is resolved, hand off to **ship** — close the branch via PR / merge / cleanup, with **git authorship as Eric, never Claude**. If the review came back **CHANGES REQUESTED**, the loop goes back to **implement** (fix), then **verify** (re-prove green), then back here for re-review. Don't ship a diff that hasn't earned its verdict.

package/skills/review/evals/README.md

@@ -0,0 +1,84 @@
+# Eval harness — review
+
+These evals run through an **agent harness** (an agent that loads skills on
+demand), not a plain shell script. `cases.yaml` is the fixture; this file is the
+procedure. Two things are measured: **triggering** (does `review` fire when it
+should and stay quiet when it shouldn't, vs its siblings) and **capability**
+(does loading `review` make the answer materially better — sharper findings when
+giving a review, correct verify-before-acting when receiving one).
+
+## Setup
+
+- Use the same agent/model for every trial; vary only which skills are loaded.
+- Triggering trials: load the **full skill catalog** so the agent can route to a
+  sibling, then observe which skill it selects.
+- Capability trials: compare **only `review` loaded** vs **no skill loaded**.
+
+## 1. Triggering
+
+For each item in `should_trigger` and `should_not_trigger`:
+
+1. Start a fresh agent session with the full catalog available.
+2. Feed the `prompt` verbatim as the user message.
+3. Record which skill (if any) the agent invokes.
+4. Run **3–5 trials** per prompt — selection is stochastic.
+
+Pass conditions:
+
+- `should_trigger`: **review** is invoked in the majority of trials. This set
+  deliberately mixes the two roles — *giving* a review ("review this PR", "tear
+  this apart", "critique against the spec") and *receiving* one ("do I have to
+  change it?", "which bot comments should I act on?"). Both must fire `review`.
+- `should_not_trigger`: review is **not** invoked; ideally the agent routes to
+  the listed `route_to` sibling (or declines when appropriate).
+
+**Pass bar: >= 90% trigger accuracy** across all trials. A prompt that flaps
+below majority counts as a fail for that prompt; >= 90% of prompts must pass
+clean.
+
+## 2. Capability
+
+For each `capability` scenario, run two arms:
+
+- **WITH**: only `review` loaded.
+- **WITHOUT**: no skill loaded (baseline model behavior).
+
+Run each arm 3 times. Grade every response against the scenario's `must_include`
+rubric — one point per item that is genuinely present (correct, traced to the
+code, not hand-waved). The two scenarios test opposite halves of the skill: one
+**receiving** a *false* finding (the win is declining the change with evidence
+and adding a regression test, not editing working code), one **giving** a review
+of a real IDOR (the win is a ranked, repro-backed blocker with a concrete fix and
+an explicit verdict).
+
+Pass conditions:
+
+- **WITH** the skill covers **>= 80%** of `must_include` items on average.
+- The skill **measurably improves** the output: WITH coverage must beat WITHOUT
+  by a clear margin (target **>= 25 percentage points**). The receiving scenario
+  is the discriminating one — baselines tend to performatively "fix" the false
+  NPE finding; the skill's verify-before-acting gate should flip that to a
+  correct, evidenced decline.
+
+## Scoring summary
+
+| Dimension | Metric | Pass bar |
+|---|---|---|
+| Triggering | trigger accuracy across all prompts/trials | >= 90% |
+| Capability | rubric coverage WITH skill | >= 80% |
+| Capability | WITH minus WITHOUT (lift) | >= 25 pts |
+
+## Notes / honesty
+
+- These are LLM-graded, stochastic evals — re-run on skill edits and treat small
+  score deltas as noise, not signal.
+- `route_to` targets name the sibling skill the prompt should land on instead of
+  `review`. The adjacent SDD phases this skill hands off to — **verify** before it
+  and **ship** after it — are present as their own skills in this repo, so the two
+  phase-boundary near-misses route straight to them (`verify` for the run-the-gates
+  prompt, `ship` for the open-the-PR-and-merge prompt). Every `route_to` target
+  must resolve to a real sibling skill; a mis-route to the wrong sibling counts
+  against `review`'s triggering accuracy.
+- The receiving-side capability scenario is intentionally a *false* finding. A
+  pass means the skill declined the edit with a trace; "fixed the NPE" is a
+  failure even though it looks responsive.

package/skills/review/evals/cases.yaml

@@ -0,0 +1,55 @@
+skill: review
+
+should_trigger:
+  - prompt: "Can you review this PR before I merge it? It refactors the order-total calculation and adds a discount field."
+    why: "Explicit 'review this PR before merge' — the flagship giving-a-review trigger, on a correctness-sensitive money path. Squarely the review phase."
+  - prompt: "Revisa este diff y dime qué está mal antes de hacer ship."
+    why: "Spanish 'review this diff, tell me what's wrong, before ship' — same trigger in the user's other language, and explicitly the gate that sits before ship."
+  - prompt: "The reviewer left a comment saying my function can NPE if the user is null. Do I actually have to change it?"
+    why: "Non-obvious RECEIVING-side trigger: the user is processing incoming feedback and is unsure whether to comply. The skill's verify-before-acting half owns exactly this."
+  - prompt: "A bot left like twelve comments on my PR. Most look like nitpicks. Which ones should I actually act on?"
+    why: "Receiving a machine review and needing to triage real findings from noise — the gate (restate/verify/classify/act) and the nit-vs-blocker ranking are the core capability."
+  - prompt: "Tear this change apart for me — I want the harshest review you can give before it goes out."
+    why: "Adversarial framing with no literal 'review the PR' phrasing ('tear this apart', 'harshest'). This is the giving-a-review role at full rigor."
+  - prompt: "My teammate said I should rewrite this whole module, but I think the current code already handles the case they're worried about. What do I do?"
+    why: "Receiving a review that may be a false finding; the user wants to push back with evidence rather than blindly comply. The skill's pushback-with-a-trace discipline applies."
+  - prompt: "Critique my implementation against the spec — did I actually build what we specified or did I drift?"
+    why: "Spec-fidelity pass (pass 1) explicitly invoked: checking the diff against 02-DOCS/wiki/sdd specs for scope drift. A giving-a-review trigger keyed to the SDD artifacts."
+
+should_not_trigger:
+  - prompt: "Run lint, type-check and the test suite on my branch and tell me if it's green."
+    route_to: "verify"
+    why: "Running the gates to green is the verify phase, not review — the verify skill owns exactly 'lint/type/test before merge', 'run the checks', 'are we green'. Review judges an already-green diff; this routes out to verify."
+  - prompt: "The code's been reviewed and approved. Open the PR and merge it into main."
+    route_to: "ship"
+    why: "Closing the branch / opening the PR / merge with Eric-only authorship is the ship phase — the ship skill owns 'open the PR', 'merge into main', 'close the branch'. It is post-review, not review, so it routes out to ship."
+  - prompt: "Do a security threat-model of this endpoint that fetches a user-supplied URL — what's the SSRF risk?"
+    route_to: "secure-coding"
+    why: "A deep OWASP/SSRF threat-model is owned by secure-coding. Review folds its findings in but defers the dedicated security pass; this is explicitly routed out in 'When NOT to use'."
+  - prompt: "Is this the idiomatic way to write a Server Component data fetch in Next.js 15?"
+    route_to: "nextjs"
+    why: "A pure 'is this framework-idiomatic' question with no diff to judge belongs to the stack skill that owns the idiom, not the adversarial review gate."
+  - prompt: "Write me a Postgres query for the top 5 customers by monthly order value."
+    route_to: "postgresdb"
+    why: "Authoring new SQL from scratch — there is no existing change to review. Query design is owned by the postgresdb skill."
+  - prompt: "Rename this Go helper and split the formatting logic out — no behavior change, just tidy it up."
+    route_to: "go"
+    why: "A trivial mechanical refactor the author is performing themselves, not a review of someone's change. Routes to the Go skill for the idiom; nothing to review adversarially."
+
+capability:
+  - scenario: "Receiving review: a reviewer commented 'this can throw NPE if `user` is null' on the line `return user.documents.filter(owner=user.id)`. Two lines up, `user = require_auth(request)`. require_auth raises 401 on a null/absent session. Decide what to do."
+    must_include:
+      - "Runs the receiving gate: restates the claim, then VERIFIES it against the code instead of immediately editing."
+      - "Traces that require_auth raises 401 before the flagged line, so `user` cannot be null there — classifies the finding as FALSE."
+      - "Declines to change the working code (no performative 'good catch' edit)."
+      - "Replies to the reviewer with the evidence/trace (require_auth raises 401), not just an assertion of disagreement."
+      - "Adds or proposes a regression test (e.g. unauthenticated request asserts 401) so the guarantee stays true, strengthening the diff while declining the change."
+      - "Logs the declined finding + reasoning to 02-DOCS/wiki/sdd/decisions.md."
+  - scenario: "Giving review: review this diff before ship — `@router.get('/invoices/{invoice_id}') def get(invoice_id: int, db=Depends(get_db)): return db.get(Invoice, invoice_id)`, behind login. Spec said 'a user can view their own invoices'."
+    must_include:
+      - "Flags a [blocker]: authenticated != authorized — any logged-in user reads any invoice by id (IDOR / broken access control), and ties it to the spec ('their OWN invoices') as a fidelity failure."
+      - "Provides evidence/repro (GET another user's invoice_id with a valid session returns 200 + body), not a vague 'consider authorizing'."
+      - "Gives a concrete fix: scope the query by owner (WHERE id == invoice_id AND owner_id == current_user.id) and return 404 (not 403) on miss to avoid leaking existence."
+      - "Ranks findings by severity (blocker vs nit) rather than an unranked list of opinions."
+      - "Ends with an explicit verdict — CHANGES REQUESTED — and states exactly what unblocks the merge."
+      - "Points to the next phase (ship) only once the blocker is resolved; routes the deep security angle to secure-coding if a fuller pass is wanted."

package/skills/review-management/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: review-management
+description: "Use when a public review just landed and needs an on-voice reply, or you need to earn more reviews legally, or your aggregate rating is slipping across Google Business Profile, Trustpilot, the App Store, or Google Play. Use when a 1-star feels unfair and you want it removed not just answered, when you must decide reply-vs-flag, or when wiring programmatic replies (GBP v4 updateReply, Trustpilot, App Store Connect, Play). Triggers: 'responder a esta reseña de Google', 'conseguir más reseñas sin saltarnos la ley', 'respon aquesta ressenya d''una estrella', 'aconseguir més ressenyes sense saltar-nos la llei', 'a 1-star landed and I want it removed not just answered', 'are we allowed to ask only happy customers for reviews', 'draft a reply to this 2-star', 'set up a review-request flow', 'build a reputation scorecard across Google and the App Store'. NOT a private 1:1 support ticket against an SLA (that is customer-support), NOT churn/NPS/save plays (that is retention)."
+tags: [reviews, reputation, google-business-profile, trustpilot, ftc, responses, app-store]
+recommends: [customer-support, retention, seo-geo, brand-voice, social-publisher]
+origin: risco
+---
+
+# review-management
+
+You run public reputation as a program. A review is the one customer message every
+future prospect also reads, so it rolls up into an aggregate that moves local rank and
+the buy decision. Your job is three artifacts: a **review-request flow** (earn more,
+the legal way), a **response playbook** (reply on-voice, within the SLA, to every
+rating), and a **reputation scorecard** (the aggregate signal across surfaces).
+
+You do not write the brand's voice — you consume it. You do not run the private inbox.
+You do not make the page rank. You own what is public and what it averages to.
+
+## What this owns vs route elsewhere
+
+The dividing line is one question: **can a stranger read it?** If your reply is visible
+to every future prospect, it's a review — yours. If it's a private channel, it's not.
+
+| The ask | Route to | Why |
+|---|---|---|
+| Private email/chat/ticket against an SLA | `../customer-support/SKILL.md` | 1:1, non-public, macro library + queue — not a public reply |
+| Churn risk, NPS, save plays, win-back | `../retention/SKILL.md` | A bad review may *signal* churn; the save play lives there |
+| Make the profile rank (schema, GEO, local pack beyond reviews) | `../seo-geo/SKILL.md` | Reviews feed rank, but on-page/schema is a different lever |
+| Repurpose a 5-star into a social post | `../social-publisher/SKILL.md` | Scheduling/cadence of the post, not the review reply |
+
+The reply voice — traits, word bank, tone matrix — comes from `../brand-voice/SKILL.md`.
+This skill applies that guide; it never authors it.
+
+## The legal floor — read before you ask
+
+The **FTC Consumer Review Rule** is in force (final rule effective **2024-10-21**) and
+being enforced — the FTC sent warning letters to 10 companies on **2025-12-22**.
+Penalties run up to **$53,088 per violation** (per the FTC 2025-12 warning letters /
+press release, the inflation-adjusted figure in force from Jan 2025). Four moves are
+banned. Internalize them before you draft a single request:
+
+1. **No fake or insider reviews.** Don't write, buy, or solicit reviews from people who
+   didn't transact. *Why: they're deceptive on their face and the per-violation fine is
+   ruinous.*
+2. **No review gating (suppression).** You may **not** screen for sentiment before the
+   ask — no "rate us 1–5, and only the happy ones get routed to Google." Routing unhappy
+   customers to a private form while sending happy ones to the public link is illegal
+   suppression. *Why: it manufactures a rating that doesn't reflect reality — the exact
+   harm the rule targets.*
+3. **No incentivizing a particular sentiment.** You may offer an incentive to review
+   (if disclosed) — you may **not** condition it on the review being positive. *Why:
+   "$10 for a 5-star" buys sentiment, not feedback.*
+4. **No misrepresenting that reviews are independent** when they're insider/company-controlled.
+
+The one rule that resolves 90% of cases: **you may ask everyone; you may not condition
+the ask, the routing, or the reward on how they feel.**
+
+```text
+Bad  (gating — illegal):  "Loved us? Leave a 5-star here →. Had a problem? Email us instead."
+Good (neutral — clean):   "Thanks for choosing us. Share your honest experience here → [link]."
+```
+
+## Earn reviews cleanly
+
+Ask within **24–48h** of the transaction — peak emotional recency. Pick the channel by
+context; a hybrid SMS-then-email (48–72h gap) lifts total collection **40–60%**.
+
+| Channel | Use when | Open / reply | Note |
+|---|---|---|---|
+| SMS | You have a verified mobile + recent transaction | ~98% open, 15–25% reply | Highest yield; keep it one line + link |
+| Email | No phone, or B2B with work addresses | ~20% open, 2–5% reply | Personalization merge tags lift response 20–30% |
+| QR on receipt | On-site retail / hospitality | walk-up | Print it; ask at the moment of satisfaction |
+| In-app prompt | Mobile app, after a success moment | varies | Triggers the OS review sheet (App Store / Play) |
+
+**Message anatomy** (two sentences): name → one specific reference to what they bought →
+direct link to the review surface. No sentiment screen, no "if you're happy."
+
+```text
+Hi Marta — thanks for the kitchen install last Tuesday. If you have 30 seconds,
+your honest review helps other homeowners decide → [direct Google review link].
+```
+
+The link points **straight to the review form** (GBP "write a review" deep link,
+Trustpilot service-review invite, the app's store page). Never to an internal star-picker
+that branches on the rating — that's gating.
+
+## Respond — the playbook
+
+Reply to **every** review within **48h** (within 24h correlates with better local
+ranking; 52% of customers expect a reply within 7 days). On Google Play a developer
+response raises that review's rating by **~0.7 stars on average** — replies are not
+optional hygiene, they move the number.
+
+| Review type | The move | Reply shape | SLA |
+|---|---|---|---|
+| 5-star praise | Thank + reinforce one specific they mentioned | 1–2 sentences, named, warm, on-voice | 48h |
+| Positive + a question/ask | Thank, then answer the question publicly | Answer first, gratitude second | 48h |
+| Vague 1–2 star (no detail) | Acknowledge, invite the detail offline | "Sorry to hear this — we'd like to understand, reach us at…" | 48h |
+| Specific complaint (fair) | Own it, move offline, state the fix | The sequence below | 24–48h |
+| Suspected fake / off-topic | Flag for removal **and** post a calm holding reply | See "Flag vs reply" | 48h |
+
+**The negative-review sequence** (write it fresh every time; never paste a template):
+
+1. **Acknowledge** the person and the feeling, by name. No "we're sorry you feel that way."
+2. **Own the specific** thing that went wrong — name it, don't deflect.
+3. **Move it offline** — give a direct contact (name + email/phone), once.
+4. **State the concrete fix** or what you've changed, briefly.
+5. **Invite an update** — leave the door open for them to revise the review.
+
+```text
+Bad  (defensive, public argument):
+  "That's not what happened. Our records show you were 40 minutes late, which is
+   why the install ran over. We followed our standard process."
+
+Good (own → offline → fix → invite):
+  "Hi James — you're right that the install ran past the window we promised, and
+   that's on us. I'd like to make it right; please email me directly at
+   ops@acme.co. We've since added a buffer to every booking so this doesn't
+   repeat. — Lena, Ops Lead"
+```
+
+## Flag vs reply
+
+Replying is the default. Flagging is the exception — and mass-flagging legitimate
+negatives is itself a reputation and policy risk. **Flag for removal only when the
+review is:**
+
+- **Fake** — from someone who never transacted.
+- **Off-topic** — not about your business / a different location.
+- **Conflict of interest** — competitor, ex-employee, personal feud.
+- **Policy violation** — profanity, hate, doxxing, illegal content.
+
+A review that is negative, harsh, or even partly inaccurate but reflects a real
+experience is **not** flag-eligible. Answer it. Per-platform flag paths and dispute forms
+are in `references/platform-apis.md`.
+
+## The platforms (programmatic)
+
+Most of this is offloaded to `references/platform-apis.md` (endpoints, scopes, roles,
+limits, gotchas). The three facts you must not get wrong, inline:
+
+- **GBP reply is live and still on v4** — not migrated to v1, no announced deprecation:
+  ```text
+  PUT https://mybusiness.googleapis.com/v4/{name=accounts/*/locations/*/reviews/*}/reply
+  scope: https://www.googleapis.com/auth/business.manage   # verified locations only
+  ```
+  This single `PUT` both creates and updates the reply.
+- **The Google Q&A API is dead** (shut down November 2025). Do **not** build against
+  Questions-and-Answers endpoints — review listing + reply survive, Q&A does not.
+- **Apple allows exactly one editable response per review** via App Store Connect
+  (get/create/update/delete; requires Account Holder, Admin, or Customer Support role).
+  Apple also surfaces AI review summaries on iOS 18.4+, so themes in your reviews now
+  feed an auto-generated digest — fix recurring complaints, don't just reply to them.
+
+## Reputation scorecard
+
+Track six metrics per surface, reviewed **weekly**:
+
+| Metric | What it is | Target signal |
+|---|---|---|
+| Rating | Aggregate stars | Trend, not snapshot |
+| Volume | Total reviews | More = more trust + rank weight |
+| Velocity | Reviews/month | Steady inflow beats a stale 5.0 |
+| Recency | Days since last review | Fresh reviews are weighted heavier |
+| Response rate % | Replies ÷ reviews | Aim ~100% — the +0.7-star Play effect compounds |
+| Sentiment by theme | Complaints/praise clustered | Drives fixes, feeds Apple's AI summary |
+
+Cluster the negatives by theme weekly. Three reviews about "slow checkout" is a product
+ticket, not three replies — route the fix, then close the loop in your replies.
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails | Do instead |
+|---|---|---|
+| Gating (route unhappy away from the public link) | Illegal FTC suppression, up to $53,088/violation | Ask everyone the same neutral way |
+| Buying / incentivizing-by-sentiment | Banned; deceptive; fines | Disclose any incentive, never tie it to positivity |
+| Copy-paste reply on every review | Reads robotic; kills the +0.7-star effect | Write fresh, name one specific each time |
+| Arguing in public / "that's not what happened" | Every prospect reads you losing | Own it, move offline, state the fix |
+| Ignoring positive reviews | Leaves trust + ranking weight on the table | Reply to 5-stars too, within SLA |
+| Replying off the brand-voice guide | Inconsistent, off-brand surface | Pull traits from `../brand-voice/SKILL.md` |
+| Building on the Google Q&A API | Shut down Nov 2025 — it's gone | Use v4 reviews + `updateReply` only |
+| Mass-flagging legitimate negatives | Policy risk; doesn't remove real feedback | Flag only fake/off-topic/conflict/policy |
+
+## Verify the copy
+
+Before you ship any request template or reply, run the copy-banlist linter — it fails on
+gating, sentiment-incentive, and dead-Q&A-API phrasing:
+
+```bash
+./scripts/verify.sh path/to/review-copy.md
+```
+
+It's read-only and exits 0 on clean or empty input. See `evals/README.md` for how the
+capability eval is graded.
+
+## Cross-references
+
+- `../customer-support/SKILL.md` — the private 1:1 ticket against an SLA
+- `../retention/SKILL.md` — churn, NPS, save plays a bad review may signal
+- `../seo-geo/SKILL.md` — making the profile rank beyond review signals
+- `../brand-voice/SKILL.md` — the voice your replies are written in
+- `../social-publisher/SKILL.md` — repurposing a glowing review into a post
+- `references/platform-apis.md` — per-surface endpoints, scopes, roles, limits, gotchas

package/skills/review-management/evals/README.md

@@ -0,0 +1,13 @@
+# Evals — review-management
+
+`cases.yaml` holds three groups. `should_trigger` lists prompts that must load this
+skill (including a non-obvious compliance question and a Catalan phrasing);
+`should_not_trigger` lists near-miss prompts that must route to a real sibling
+(`customer-support`, `retention`, `seo-geo`, `brand-voice`, `social-publisher`) with the
+reason; `capability` is a graded scenario with a `must_include` rubric. There is no
+automated runner here — drive a model with each prompt, check routing for the trigger
+sets, and score the capability answer against every rubric bullet (own-it reply,
+do-NOT-flag-a-legit-negative, the 24-48h SLA, an FTC-clean no-gating request flow, and
+the +0.7-star / $53,088 rationale). For the copy this skill emits, also run
+`../scripts/verify.sh` against a request template or reply to confirm it has no gating,
+sentiment-incentive, or dead-Q&A-API phrasing.

package/skills/review-management/evals/cases.yaml

@@ -0,0 +1,60 @@
+skill: review-management
+
+# review-management owns the PUBLIC review and the AGGREGATE reputation it rolls
+# up to: earning reviews legally (FTC-clean request flow), replying on-voice within
+# the 24-48h SLA, deciding reply-vs-flag, and the cross-surface scorecard (Google
+# Business Profile, Trustpilot, App Store, Google Play). It does NOT handle private
+# 1:1 tickets (customer-support), churn/save plays (retention), ranking beyond
+# reviews (seo-geo), authoring the voice (brand-voice), or scheduling posts
+# (social-publisher).
+should_trigger:
+  - prompt: "A customer left us a 2-star Google review complaining about wait times — draft a reply."
+    why: "Core job: an on-voice public reply to a specific negative, within the 48h SLA, own-it-and-move-offline shape."
+
+  - prompt: "We want more Trustpilot reviews but only have 12 — set up a request flow."
+    why: "Earn-reviews flow: Trustpilot Invitation API, 24-48h timing, channel choice, FTC-clean no-gating ask."
+
+  - prompt: "Are we allowed to only ask our happy customers to leave reviews?"
+    why: "Non-obvious: the user doesn't name reviews-management, they ask a compliance question. The FTC gating rule lives here and the answer must be a clear NO."
+
+  - prompt: "Someone posted an obviously fake 1-star — can we get it removed or just reply?"
+    why: "The reply-vs-flag decision is owned here: flag only for fake/off-topic/conflict/policy, else reply."
+
+  - prompt: "Respon aquesta ressenya d'una estrella d'un client emprenyat."
+    why: "Catalan phrasing for a public 1-star reply — same skill regardless of language; the negative-review sequence applies."
+
+  - prompt: "Build me a dashboard of our rating and response rate across Google and the App Store."
+    why: "The reputation scorecard (rating, volume, velocity, recency, response-rate, sentiment-by-theme) across surfaces is owned here."
+
+  - prompt: "How do I post a developer reply to a Google review programmatically — what endpoint and scope?"
+    why: "Non-obvious wiring trigger: the GBP v4 updateReply PUT endpoint + business.manage scope + verified-location gate are the load-bearing facts this skill holds."
+
+should_not_trigger:
+  - prompt: "A customer emailed support angry about a refund — write the reply."
+    route_to: customer-support
+    why: "Private 1:1 channel against an SLA; no future prospect reads it. The public-vs-private line routes this to support."
+
+  - prompt: "Our churn is up; build a save play for at-risk accounts."
+    route_to: retention
+    why: "A bad review may signal churn, but the save play / win-back sequence is retention's job."
+
+  - prompt: "Make our location page rank in the Google local pack."
+    route_to: seo-geo
+    why: "Ranking levers beyond reviews — schema, on-page, GEO, local-pack signals — are seo-geo."
+
+  - prompt: "Define our brand's tone of voice so replies sound consistent."
+    route_to: brand-voice
+    why: "This skill consumes the voice guide; brand-voice authors it (traits, word bank, tone matrix)."
+
+  - prompt: "Turn this 5-star review into an Instagram carousel and schedule it."
+    route_to: social-publisher
+    why: "Repurposing + scheduling the post is social-publisher; review-management only owns the reply to the review itself."
+
+capability:
+  - scenario: "We got a specific, fair 1-star Google review about a botched install. Reply on-voice, tell me whether to flag it, and what to put in our review-request flow so this doesn't tank our rating."
+    must_include:
+      - "A reply that names the specific issue (the botched install), owns it, moves the customer to a private channel, states a concrete fix, and shows no defensiveness or public arguing."
+      - "An explicit 'do NOT flag this — it is a legitimate negative' with the flag-only-for-{fake / off-topic / conflict-of-interest / policy-violation} rule."
+      - "The 24-48h response SLA stated for the reply (within 24h helps ranking; reply to every review within 48h)."
+      - "An FTC-clean request flow: ask EVERY customer (no gating), within 24-48h of the transaction, via SMS and/or email with a direct link to the public review form."
+      - "Rationale citing the ~+0.7-star average lift from a developer/business response AND the FTC gating penalty of up to $53,088 per violation."