From beb00560c608b26829a66fac70b02314d71a4b40 Mon Sep 17 00:00:00 2001
From: Eric Hare <ericrhare@gmail.com>
Date: Tue, 27 Oct 2026 11:17:58 -0700
Subject: [PATCH] docs: add Aaron reviewer skill

---
 .agents/skills/aaron-reviewer/SKILL.md        |  53 +++++++
 .../references/review-profile.md              |  63 ++++++++
 .../plans/2026-10-27-aaron-reviewer.md        | 137 ++++++++++++++++++
 .../specs/2026-10-27-aaron-reviewer-design.md |  59 ++++++++
 4 files changed, 312 insertions(+)
 create mode 100644 .agents/skills/aaron-reviewer/SKILL.md
 create mode 100644 .agents/skills/aaron-reviewer/references/review-profile.md
 create mode 100644 docs/superpowers/plans/2026-10-27-aaron-reviewer.md
 create mode 100644 docs/superpowers/specs/2026-10-27-aaron-reviewer-design.md

diff --git a/.agents/skills/aaron-reviewer/SKILL.md b/.agents/skills/aaron-reviewer/SKILL.md
new file mode 100644
index 0000000000..3562736f89
--- /dev/null
+++ b/.agents/skills/aaron-reviewer/SKILL.md
@@ -0,0 +1,53 @@
+---
+name: aaron-reviewer
+description: Use when reviewing or pre-reviewing data-api code, tests, API errors, schemas, comments, or PR scope and the review should match Aaron Morton's correctness-first, direct, pragmatic judgment.
+---
+
+# Aaron Reviewer
+
+## Overview
+
+Review for correctness and for the next maintainer's understanding. Be direct, specific, collaborative, and pragmatic; reproduce Aaron Morton's judgment, not his typos, jokes, or meeting offers.
+
+## Review workflow
+
+1. **Establish facts and scope.** Read the diff, surrounding implementations, call sites, tests, and PR description/template. Compare sibling patterns. Keep the PR to the stated problem and do not rewrite it during review.
+2. **Check in this order:**
+   - **Correctness and state:** failure modes, partial results, invalid/null states, builder reuse, mutable shared state, blocking I/O, concurrency, and `equals`/`hashCode` consistency. Make invalid states impossible at construction where practical.
+   - **Public API and errors:** consistent vocabulary and compatibility. Error titles are stable with no variables; bodies give the known reason, request-specific values, and actionable recovery in the correct family/scope. Never leak driver/Cassandra internals or private links.
+   - **Tests:** independent, self-contained, behavior-focused tests. Put validation logic in direct unit tests; assert values, errors, and effects rather than presence or heavy mocks. Cover changed boundaries, not just aggregate coverage. Pagination needs first, middle, and partial-last pages with exact content/order and terminal page state.
+   - **Ownership and simplicity:** centralize business rules, avoid duplicate logic, one-use `Util`/`Impl` classes, pointless factories, speculative abstractions, and framework/CDI leakage. Use constructor injection and explicit context.
+   - **Comments and PR hygiene:** short human comments explain non-obvious “why,” not other classes or generic trailing filler. Remove unrelated docs, AI filler, private links, and unjustified global behavior.
+3. **Calibrate severity:**
+   - `bug` / `-1`: correctness, public contract, security, or unsafe-scope blocker.
+   - `question`: evidence or intent is genuinely unclear; do not disguise an assertion as a question.
+   - `nit` / `consider`: non-blocking clarity, naming, or idiom improvement.
+   - `follow-up`: useful work that should not grow this PR.
+4. **Write each finding as:** `location -> observable problem -> impact -> concrete fix or test`. Do not stop at “unclear,” “improve,” or “add coverage” without saying what and why.
+5. **Close with the recommendation.** Name blockers separately from tweaks and follow-ups. Approve with requested tweaks when that is safe. State exactly what was not reviewed or verified; never imply complete certainty.
+
+## Quick reference
+
+| Area | Aaron's check | Typical label |
+|---|---|---|
+| Shared builder | Can a later request inherit earlier state? | `bug` |
+| Error title | Is it identical for every instance of the error? | fix before merge |
+| Error body | Known reason, request values, useful action, no driver internals? | fix before merge |
+| Pagination | First, middle, partial-last pages, exact rows/order, terminal state? | `bug` or test follow-up |
+| Tests | Independent, direct, behavior and values rather than presence/mocks? | calibrated |
+| Abstraction | Does a factory/util/interface add meaning or only indirection? | `nit` or `consider` |
+| Comments | Useful local “why,” or generic/other-class filler? | `nit`; remove AI filler |
+| Scope | Only changes required for the stated problem? | `-1` for unsafe scope |
+| Review boundary | Which files/tests remain unread or unrun? | explicit note |
+
+## Common mistakes
+
+| Rationalization | Reality |
+|---|---|
+| “The suite is green and coverage is high.” | Tests can miss the changed branches, depend on order, or assert the wrong thing. |
+| “The error has plenty of detail.” | Raw driver text is not a stable, actionable API contract. |
+| “It is only a comment/document.” | Filler hides intent and makes the next maintainer slower; remove it. |
+| “This cleanup is harmless.” | Unrelated changes obscure the required fix and expand verification scope. Use a follow-up. |
+| “I reviewed everything.” | If tests or files were not read, say which ones. |
+
+For detailed preferences and source-linked examples, read `references/review-profile.md` when a finding needs calibration or evidence.
diff --git a/.agents/skills/aaron-reviewer/references/review-profile.md b/.agents/skills/aaron-reviewer/references/review-profile.md
new file mode 100644
index 0000000000..2093c36702
--- /dev/null
+++ b/.agents/skills/aaron-reviewer/references/review-profile.md
@@ -0,0 +1,63 @@
+# Aaron Morton review profile
+
+## Evidence and use
+
+This profile distills all 217 stargate/data-api PRs where Aaron Morton reviewed or commented: 486 formal reviews, 1,617 inline comments, and 48 discussion comments, totaling 1,835 nonempty text bodies from 2022 through 2026. Feedback on other people's PRs drives the review style; Aaron's replies on his own PRs supply rationale.
+
+Use these as judgment rules, not a quote bank. Current code and sibling conventions remain authoritative.
+
+## Durable likes
+
+### Correctness and explicit invariants
+
+- Trace partial failure, null/empty input, builder reuse, mutable state, and cross-request behavior before style. Examples: [partial insert results](https://github.com/stargate/data-api/pull/24#discussion_r1067693305), [builder reuse is mutable shared state](https://github.com/stargate/data-api/pull/2460#discussion_r3192715176), and [`equals`/`hashCode` fields must agree](https://github.com/stargate/data-api/pull/2473#discussion_r3345227087).
+- Validate construction rather than trusting every caller. Prefer canonical constructors, non-null values or NO-OP implementations, private constructors for controlled factories, and no public path around invariants. Examples: [well-behaved command context](https://github.com/stargate/data-api/pull/1935#discussion_r2011027172) and [record factories should not bypass rules](https://github.com/stargate/data-api/pull/1909#discussion_r1997703418).
+- Fail fast on impossible states and use exhaustive modern switches where they let the compiler prove coverage. Example: [invalid model type must not become an empty optional](https://github.com/stargate/data-api/pull/2583#discussion_r4031815870).
+- Avoid broad catches that hide real failures. Example: [catching and hiding more than expected is an anti-pattern](https://github.com/stargate/data-api/pull/2538#discussion_r3762714337).
+
+### Stable, useful public contracts
+
+- Error titles are static; variables belong in the body. See [title should not have variables](https://github.com/stargate/data-api/pull/2322#discussion_r2663265575).
+- Say what the API knows, include request-specific values, and tell the user what to do next. See [actionable duplicate-index message](https://github.com/stargate/data-api/pull/1117#discussion_r1617900060).
+- Keep error family/scope aligned with request versus server failures, preserve stable ordering for values used in messages, and test the message content where it carries important information. See [request versus server family](https://github.com/stargate/data-api/pull/2322#discussion_r2663287719) and [message assertions with request-specific values](https://github.com/stargate/data-api/pull/1746#discussion_r1861192778).
+- Do not expose driver/Cassandra wording or internals. See [why return the driver message?](https://github.com/stargate/data-api/pull/2145#discussion_r2174121810).
+- Keep public API names separate from driver/CQL names and consistent with existing semantics. See [API names belong in the API package](https://github.com/stargate/data-api/pull/1846#discussion_r1945545524) and [`Desc` for public, `Def` for internal](https://github.com/stargate/data-api/pull/1933#discussion_r2003896905).
+- Incomplete features are disabled by default and enabled deliberately. See [MCP must not accidentally reach production](https://github.com/stargate/data-api/pull/2402#discussion_r2828995828).
+
+### Tests that prove behavior
+
+- Tests are independent and self-contained; no `@Order` dependency. See [tests must run independently](https://github.com/stargate/data-api/pull/1746#discussion_r1861183294).
+- Exercise complete boundaries: first, middle, and partial-last pages, exact rows/order, and terminal state. See [three-page requirement](https://github.com/stargate/data-api/pull/1746#discussion_r1861184939) and [make the partial third page explicit](https://github.com/stargate/data-api/pull/2461#discussion_r3192199882).
+- Test changed logic at the cheapest precise level, usually direct unit tests for validation/deserialization. See [logic that cannot be tested effectively through IT](https://github.com/stargate/data-api/pull/1778#pullrequestreview-2568712996).
+- Assert values, effects, exact errors, and public contracts rather than property presence or mock-heavy setup. See [compare complete billing events](https://github.com/stargate/data-api/pull/2492#discussion_r3361182265), [fragile property checks](https://github.com/stargate/data-api/pull/2619#discussion_r4319497626), and [one behavior per test](https://github.com/stargate/data-api/pull/2619#discussion_r4319497626).
+- Do not weaken a test's original purpose when cleaning it up. See [exact CQL structure matters](https://github.com/stargate/data-api/pull/2461#discussion_r3156420286).
+- Avoid blocking I/O in request paths; use the current asynchronous model. See [blocking health check](https://github.com/stargate/data-api/pull/2527#discussion_r3708767662).
+
+### Ownership, simplicity, and readability
+
+- Put behavior with the object that owns it. `Util` classes are a last resort, not a default. See [deprecation behavior on the command model](https://github.com/stargate/data-api/pull/1397#discussion_r1753002862).
+- Remove duplicate business rules and centralize common checks without creating abstraction for its own sake. See [common provider validation](https://github.com/stargate/data-api/pull/1963#discussion_r2059235966) and [one-use factory is unnecessary](https://github.com/stargate/data-api/pull/1908#discussion_r1994532926).
+- Use constructor injection and explicit context rather than framework/CDI magic. See [avoid adding injection](https://github.com/stargate/data-api/pull/1909#discussion_r1997703265) and [remove CDI where possible](https://github.com/stargate/data-api/pull/2527#discussion_r3708736632).
+- Keep the PR to the current problem. Split risky implementation changes from useful but separable refactors. See [make the plan without changing task execution](https://github.com/stargate/data-api/pull/2637#discussion_r4310542222).
+- Comments are short and local: explain non-obvious “why,” invariants, or surprising inputs. See [why quoted identifiers are used](https://github.com/stargate/data-api/pull/1117#discussion_r1617905200).
+- Delete comments that restate clear code, discuss unrelated classes, or append generic AI filler. See [function name is enough](https://github.com/stargate/data-api/pull/2003#discussion_r2055056861), [comment about another class is unnecessary](https://github.com/stargate/data-api/pull/2475#discussion_r3269358714), and [pointless AI sentence](https://github.com/stargate/data-api/pull/2619#discussion_r4330696757).
+- Remove unrelated AI-generated prose and code instead of polishing it. See [1,000-line file unrelated to a CVE](https://github.com/stargate/data-api/pull/2525#discussion_r3539995263) and [decide intended behavior before letting AI write code](https://github.com/stargate/data-api/pull/2513#pullrequestreview-4521017951).
+
+## Durable dislikes
+
+- Hidden invalid states, stringly typed values, magic defaults, silent fallbacks, and request-time failures that startup or construction could prevent.
+- Driver internals leaked into public errors, unstable error text, generic “failed” messages, and useless “resend” advice.
+- Duplicate validation, one-use factories/utilities, unnecessary interfaces/records, speculative future-proofing, and comments that merely sound knowledgeable.
+- Order-dependent tests, broad mocking, weak presence assertions, redundant integration coverage, and tests that no longer verify their original purpose.
+- Unrelated changes, private repository links, unjustified global behavior, and PR descriptions that are a “mash of words” rather than a clear account of intent.
+- Fabricated completeness. Aaron explicitly marks partial reviews, for example [“I have not read any of the tests”](https://github.com/stargate/data-api/pull/2637#pullrequestreview-5565046603) and [“I have not read through all the tests”](https://github.com/stargate/data-api/pull/1836#pullrequestreview-2584924500).
+
+## One excellent example: calibrated review on PR #2461
+
+Aaron's review of `feat: Increase page sizes` shows how blocker, nit, and follow-up coexist without turning every issue into a veto:
+
+- **Blocker:** [“this changes the nature of the test”](https://github.com/stargate/data-api/pull/2461#discussion_r3156420286). He identifies that a readability cleanup removed the exact CQL assertion that mattered and says to revert it. Observable problem, impact, and remedy are all clear.
+- **Nit:** [“use var when type is obvious”](https://github.com/stargate/data-api/pull/2461#discussion_r3191811075). A one-line idiom improvement, clearly non-blocking.
+- **Follow-up:** [fragile mocking should become a fast follow](https://github.com/stargate/data-api/pull/2461#discussion_r3198204777). He explains why the test model is too complex but does not expand the current PR indefinitely. His [approval](https://github.com/stargate/data-api/pull/2461#pullrequestreview-4240275991) requests the small tweaks and explicitly leaves the larger testability work for later.
+
+The lesson is calibration: protect correctness, make small improvements directly, and move larger learning or refactor work into a named follow-up.
diff --git a/docs/superpowers/plans/2026-10-27-aaron-reviewer.md b/docs/superpowers/plans/2026-10-27-aaron-reviewer.md
new file mode 100644
index 0000000000..8f303922d5
--- /dev/null
+++ b/docs/superpowers/plans/2026-10-27-aaron-reviewer.md
@@ -0,0 +1,137 @@
+# Aaron Reviewer Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Build and validate a project-local skill that reviews data-api changes with Aaron Morton's judgment, priorities, severity calibration, and direct collaborative style, then save the durable profile to Mem0.
+
+**Architecture:** A concise `SKILL.md` supplies the review workflow and output contract, while one evidence reference holds detailed preferences and public GitHub examples. Fresh review agents establish baseline failures before the skill exists and verify the finished skill against the same scenarios and a held-out historical PR.
+
+**Tech Stack:** Markdown agent skills, GitHub REST through `gh`, Python 3 standard-library evidence processing, fresh coder subagents, Mem0 MCP.
+
+**Spec:** `docs/superpowers/specs/2026-10-27-aaron-reviewer-design.md`
+
+## Global Constraints
+
+- Deliver only `.agents/skills/aaron-reviewer/SKILL.md`, `.agents/skills/aaron-reviewer/references/review-profile.md`, the design/plan documents, and the Mem0 profile; raw research stays in `.bob/` and is not a deliverable.
+- Use US English and asynchronous written feedback; no meeting offers, AI attribution, invented findings, or rigid praise template.
+- Historical comments guide judgment but never replace reading current source and sibling code.
+- Fresh review subagents are authorized for baseline, wording, and regression tests.
+- Do not run git commit or push without separate explicit approval.
+
+## Review Focus
+
+- Shared mutable state or builder reuse: identify the correctness risk before any style feedback; covered by the `shared-state-hotfix` scenario in Tasks 1 and 3.
+- Public API errors: require stable titles, request-specific values, actionable recovery, correct family/scope, and no driver internals; covered by `api-error-contract` in Tasks 1 and 3.
+- Fragile tests: reject order dependence, excessive mocking, weak assertions, and missing boundary cases without demanding redundant coverage; covered by `fragile-test-suite` in Tasks 1 and 3.
+- Scope and AI filler: remove unrelated docs, private links, speculative abstractions, and comments the team cannot explain; covered by `scoped-ai-change` in Tasks 1 and 3.
+- Severity and uncertainty: distinguish blockers, nits, questions, and follow-ups and state unreviewed areas; checked by every scenario and the held-out historical review in Task 3.
+
+---
+
+### Task 1: Establish baseline failures and wording controls
+
+**Files:**
+- Create: `.bob/aaron-reviewer-research/scenarios/shared-state-hotfix.md`
+- Create: `.bob/aaron-reviewer-research/scenarios/api-error-contract.md`
+- Create: `.bob/aaron-reviewer-research/scenarios/fragile-test-suite.md`
+- Create: `.bob/aaron-reviewer-research/scenarios/scoped-ai-change.md`
+- Create: `.bob/aaron-reviewer-research/scenarios/rubric.md`
+- Create: `.bob/aaron-reviewer-research/baseline-results.md`
+
+**Interfaces:**
+- Consumes: the evidence profile and public examples in `.bob/aaron-reviewer-research/corpus-*.txt`.
+- Produces: verbatim baseline failures and a scenario rubric used unchanged to evaluate `SKILL.md` in Task 3.
+
+- [ ] **Step 1: Write four pressure scenarios and the rubric**
+
+Each scenario supplies a realistic Java/data-api diff or focused excerpt, a deadline plus authority and sunk-cost pressure, and asks for a review rather than a rewrite. The rubric requires the Review Focus behaviors above, `bug` / `-1` only for blockers, `nit` / `consider` for non-blockers, explicit follow-ups, and candid uncertainty.
+
+- [ ] **Step 2: Run all scenarios with fresh agents and no Aaron skill**
+
+Use one fresh coder agent per scenario. Do not provide the learned profile or any draft skill. Record exact findings, severity, omissions, unsupported certainty, and rationalizations in `baseline-results.md`.
+
+- [ ] **Step 3: Run no-guidance wording controls**
+
+For the comment recipe and severity calibration, run at least five fresh single-shot samples per variant with the same realistic system context. Manually read every flagged output for buried verdicts, generic praise, wrong severity, missing fixes, and template echo. If the control does not exhibit a failure, do not author guidance for that non-failure; record the evidence instead.
+
+- [ ] **Step 4: Derive the minimal content requirements**
+
+List only repeated baseline failures that the skill must address, including the exact agent wording that shows each failure. Expected baseline risks include generic correctness-only checklists, style-first feedback, over-blocking, vague fixes, fabricated confidence, and failure to reject AI filler; keep only what the outputs actually show.
+
+### Task 2: Write the minimal Aaron-reviewer skill
+
+**Files:**
+- Create: `.agents/skills/aaron-reviewer/SKILL.md`
+- Create: `.agents/skills/aaron-reviewer/references/review-profile.md`
+
+**Interfaces:**
+- Consumes: Task 1 baseline failures and the full evidence corpus.
+- Produces: a loadable `aaron-reviewer` skill and its evidence reference for Task 3 validation.
+
+- [ ] **Step 1: Write valid frontmatter and a concise core workflow**
+
+Use:
+
+```yaml
+---
+name: aaron-reviewer
+description: Use when reviewing or pre-reviewing data-api code, tests, API errors, schemas, comments, or PR scope and the review should match Aaron Morton's correctness-first, direct, pragmatic judgment.
+---
+```
+
+The body must explain how to inspect current code and call sites, prioritize the Review Focus classes, label severity, write `observable problem -> impact -> concrete fix/test`, state uncertainty, and keep PR scope narrow. Address Task 1 failures with the guidance form that matches each failure; do not add rules for hypothetical failures not observed.
+
+- [ ] **Step 2: Write the evidence reference**
+
+Document durable likes, dislikes, current-era rules, and representative public GitHub links. Include one excellent annotated example showing a blocker, a nit, and a follow-up rather than a rigid full-review template. Keep raw corpus and narrative research history out of the reference.
+
+- [ ] **Step 3: Check structure and discovery**
+
+Run:
+
+```bash
+python3 - <<'PY'
+from pathlib import Path
+p = Path('.agents/skills/aaron-reviewer/SKILL.md')
+s = p.read_text()
+assert s.startswith('---\nname: aaron-reviewer\ndescription: Use when ')
+assert '\n---\n' in s
+assert len(s.split('description:', 1)[1].split('\n---', 1)[0]) <= 1024
+assert 'references/review-profile.md' in s
+assert Path('.agents/skills/aaron-reviewer/references/review-profile.md').is_file()
+print('Skill structure and discovery checks passed')
+PY
+```
+
+Expected: `Skill structure and discovery checks passed`. Also confirm the main skill has a quick reference, common mistakes, no narrative storytelling, and no flowchart unless the decision is genuinely non-obvious.
+
+### Task 3: Verify, refactor, and save the durable profile
+
+**Files:**
+- Modify: `.agents/skills/aaron-reviewer/SKILL.md`
+- Modify: `.agents/skills/aaron-reviewer/references/review-profile.md`
+- Create: `.bob/aaron-reviewer-research/validation-results.md`
+
+**Interfaces:**
+- Consumes: Task 1 scenarios/rubric and Task 2 skill files.
+- Produces: observed validation evidence and the final profile text to store in Mem0.
+
+- [ ] **Step 1: Run wording micro-tests with the skill**
+
+Repeat the Task 1 variants with the complete skill in the realistic system context. Compare at least five repetitions per variant against the no-guidance control, manually inspect all flagged matches, and record whether outputs converge on the required shape and severity.
+
+- [ ] **Step 2: Run all pressure scenarios with the skill**
+
+Use fresh coder agents and the unchanged Task 1 rubric. Record every remaining miss verbatim. Add explicit counters, rationalization entries, and red flags only for observed misses, then rerun until no new rationalization or severity error appears.
+
+- [ ] **Step 3: Run a held-out historical review**
+
+Select one historical data-api PR not used while drafting the skill. Give a fresh agent the relevant diff and current surrounding code, then compare its findings with Aaron's actual comments for correctness coverage, severity, specificity, tone, and stated review boundaries. Record gaps and refactor once if needed.
+
+- [ ] **Step 4: Save the validated profile to Mem0**
+
+Store a durable `erichare` memory containing Aaron's identity, the evidence scope (217 PRs and 1,835 nonempty bodies), core preferences, the skill path, and the actual validation result. Do not store secrets, raw reviews, or step-by-step task state.
+
+- [ ] **Step 5: Verify final artifacts and report**
+
+Run the Task 2 structure check again and `git status --short`. Report exact scenario counts, observed baseline/regression outcomes, remaining limitations, and the two skill file paths. Leave git commit/push undecided until separately approved by Eric.
diff --git a/docs/superpowers/specs/2026-10-27-aaron-reviewer-design.md b/docs/superpowers/specs/2026-10-27-aaron-reviewer-design.md
new file mode 100644
index 0000000000..33827f7ce6
--- /dev/null
+++ b/docs/superpowers/specs/2026-10-27-aaron-reviewer-design.md
@@ -0,0 +1,59 @@
+# Aaron Reviewer Skill Design
+
+## Intent
+
+Build a reusable data-api review skill that reproduces Aaron Morton's judgment, priorities, severity calibration, and direct but collaborative feedback. Use it to review changes and to pre-review work before requesting Aaron's review.
+
+## Evidence
+
+The profile is grounded in all 217 stargate/data-api PRs where Aaron reviewed or commented: 486 formal reviews, 1,617 inline comments, and 48 discussion comments, totaling 1,835 nonempty text bodies from 2022 through 2026. Feedback on other people's PRs is the primary evidence; Aaron's replies on his own PRs provide supporting rationale rather than review-style examples.
+
+## Goals
+
+- Prioritize correctness, API contracts, failure modes, understandable ownership, and meaningful tests before surface style.
+- Produce specific findings with an observable problem, impact, and concrete fix or test.
+- Distinguish blockers, questions, nits, and follow-ups without blocking every PR.
+- Preserve candid uncertainty, narrow scope, short human comments, and explicit review boundaries.
+- Provide a concise skill, a linked evidence reference, and a durable Mem0 profile.
+- Verify with fresh review agents that the skill changes behavior in useful and repeatable ways.
+
+## Non-goals and anti-goals
+
+- Do not imitate Aaron's typos, jokes, meeting offers, or historical technology positions when current code says otherwise.
+- Do not generate generic style-only reviews, rigid praise templates, invented findings, or performative certainty.
+- Do not turn every nit into a blocker or expand a PR with unrelated refactors.
+- Do not commit the raw review corpus or large generated research artifacts.
+- Do not add AI attribution to repository content or git metadata.
+
+## Constraints
+
+- Keep the skill project-local under `.agents/skills/aaron-reviewer/`, consistent with other agent repositories.
+- Use US English and asynchronous written feedback.
+- Match current source and sibling conventions when reviewing; historical comments are evidence, not a substitute for reading code.
+- Fresh review subagents are authorized for validation.
+- Do not run git commit or push without separate explicit approval.
+
+## Approaches
+
+1. **Validated repo skill (chosen):** concise playbook, evidence reference, Mem0 profile, and fresh-agent baseline/regression tests. Best confidence that the skill works rather than merely sounding plausible.
+2. **Repo skill without agents:** same artifacts, but only self-validation. Faster and less independent evidence.
+3. **Memory-only profile:** no versioned skill. Simplest, but does not meet the goal of a reusable repository capability.
+
+## Parts
+
+- `.agents/skills/aaron-reviewer/SKILL.md`: trigger conditions, review workflow, priority checklist, severity labels, comment recipe, and common mistakes.
+- `.agents/skills/aaron-reviewer/references/review-profile.md`: detailed likes, dislikes, current-era rules, representative public GitHub links, and one excellent annotated example.
+- Mem0: durable summary of the profile, skill location, evidence scope, and validation outcome.
+- `.bob/aaron-reviewer-research/`: temporary raw evidence and test notes only; not a deliverable.
+
+## Validation
+
+1. Create at least three realistic review scenarios covering correctness, API/error design, tests, scope, and tone under time/authority/sunk-cost pressure.
+2. Run fresh agents without the skill and record exact generic or incorrect review behavior.
+3. Micro-test behavior-shaping wording against a no-guidance control with at least five repetitions per variant and manually inspect flagged matches.
+4. Write the minimal skill addressing observed failures, rerun the same scenarios with it, and close new loopholes.
+5. Finish with a held-out historical data-api review scenario and compare coverage, severity, specificity, and tone against Aaron's actual feedback.
+
+## Builder discretion
+
+The builder may choose the final scenario fixtures, concise wording, and whether all evidence fits in one reference file. The deliverable remains the two skill files, Mem0 profile, and observed validation results.