Review Hog Authoring

---
name: review-hog-authoring
description: >
  How to author custom PostHog Review skills: the review perspectives, blind-spot checks, validation
  criteria, and resolution criteria that drive PostHog Review's automated PR reviews. Use when a user
  wants a new review perspective (a specialist lens on their PRs), a custom blind-spot sweep,
  their own validation bar for which findings get published, or their own bar for which review
  comments get implemented. Trigger on "create a PostHog Review perspective", "custom review
  perspective", "my own blind-spot check", "custom validation criteria", "custom resolution
  criteria", "tune what PostHog Review publishes", "tune what PostHog Review implements".
metadata:
  owner_team: review_hog
  skill_type: authoring
---

# Authoring PostHog Review skills

**PostHog Review** is PostHog's automated PR reviewer. A review splits the PR into chunks, then for each
chunk runs every enabled **perspective** in parallel (independent specialist lenses), a single
**blind-spot check** afterwards (a final sweep conditioned on what the perspectives found), and
finally judges every surviving candidate finding against one **validation criteria** skill — only
findings that pass get published to the pull request. After a published review, the **resolution
stage** goes back over the PR's unresolved review threads and judges each against one **resolution
criteria** skill — worth-and-safe asks get implemented on the PR branch, every thread gets a reply.

All four kinds are team `LLMSkill` rows the review agents pull over MCP at run time. PostHog ships
canonicals; this skill is the guide for authoring **custom** ones. The skill itself is team-level;
whether it _runs_ is a per-user setting in **Inbox → Code review**.

| Kind                | Name contract                   | Cardinality per user                | Canonical example                          |
| ------------------- | ------------------------------- | ----------------------------------- | ------------------------------------------ |
| Review perspective  | `review-hog-perspective-<slug>` | Multi-enable, at least one stays on | `review-hog-perspective-logic-correctness` |
| Blind-spot check    | `review-hog-blind-spots-<slug>` | Exactly one active; selecting swaps | `review-hog-blind-spots-general`           |
| Validation criteria | `review-hog-validation-<slug>`  | Exactly one active; selecting swaps | `review-hog-validation-criteria`           |
| Resolution criteria | `review-hog-resolution-<slug>`  | Exactly one active; selecting swaps | `review-hog-resolution-criteria`           |

## Authoring flow

1. **Ground yourself.** Using the PostHog MCP skill tools, `skill-list` the team's `review-hog-*`
   skills and `skill-get` the canonical of the kind you're authoring (see the table above) — it is
   the reference for structure and tone. For a perspective, skim the descriptions of every existing
   `review-hog-perspective-*` so the new lens doesn't re-cover ground an enabled one already owns
   (overlap gets deduplicated later, but it wastes review passes).
2. **Interview the user.** Ask what the skill should focus on, and offer a few concrete directions
   the current set doesn't cover — grounded in what you saw in step 1 and, when useful, in the
   project itself. Don't start writing until the direction is picked.
3. **Draft the body** following the per-kind guidance below. Keep it a focused instruction set the
   review agent can apply to one chunk in one pass — not an essay.
4. **Create the skill yourself with `posthog:skill-create`** — actually create the team `LLMSkill`
   row; never hand the user a body to copy-paste. Pass the exact name per the contract above
   (lowercase slug), a one-paragraph `description` of what the lens/sweep/bar is, and the body.
   **The name prefix is the whole identity** — it is how the Code review tab and the review runs
   discover the skill. There is no `category` parameter on the skill tools and you don't need one:
   the backend stamps the `review_hog` grouping category itself (it only affects grouping on the
   Skills page) — do not spend turns trying to set or verify it. Iterate with
   `posthog:skill-update` if the user wants changes. Author fresh — don't `skill-duplicate` a
   canonical to edit: seeded metadata rides along with the copy, and the canonical sync may
   overwrite or prune it.
5. **Tell the user how to activate it.** A custom skill starts inactive for them:
   - **Perspective** — toggle it on under Inbox → Code review → Perspectives (it appears disabled
     until they enable it; at least one perspective must stay on).
   - **Blind-spot check / validation criteria / resolution criteria** — select it under the
     matching section; exactly one runs at a time, so selecting it swaps out the current one
     **for their reviews only**.
     Reviews pin skill versions when a run starts, so an edit mid-review applies from the next run.

## Writing a review perspective

The body instructs one specialist review pass over one PR chunk. Match the canonical
logic-correctness skill's shape:

- **The lane** — one sentence on what this lens is responsible for; report everything in lane and
  leave the rest to the other perspectives.
- **Hunting grounds** — a numbered handful of concrete places to look, each a specific check the
  agent can walk against the chunk ("transaction boundaries that split writes that must land
  together"), not an abstract virtue ("ensure correctness").
- **Lane boundary** — which perspective owns each adjacent concern this lens must leave alone.
- **The finding bar** — a publishable finding names the concrete trigger and the concrete
  consequence; close with a completion criterion ("done when every changed file is flagged or
  cleared against every hunting ground").

The review harness already tells the agent the pipeline mechanics — parallel perspectives, later
deduplication, severity levels, the non-test-files rule — so the skill carries only the lens;
restating harness rules dilutes it.

## Writing a blind-spot check

The body instructs the final sweep that runs after every enabled perspective finished a chunk. It
is **conditioned on the covered findings** (the prompt lists which perspectives ran and what they
found), so the body should say how to use that: the covered findings map where attention already
went, and the sweep's value is the negative space — error paths, unhandled inputs, cross-file
interactions, assumptions. It is not scoped to one specialty, and an empty result beats padding. A
custom sweep narrows or re-weights this hunt (e.g. toward a domain the team keeps getting burned
by).

## Writing validation criteria

The body defines the keep/drop bar every candidate finding is judged against before publishing.
Precision over recall is the house default — a reviewer that raises noise gets muted — so define:
what makes a finding real and worth an author's attention (user-affecting correctness, security,
data loss, contract breaks, performance), what gets dropped (overengineering, speculation,
defensive paranoia, unreachable edges, style), and how to treat genuine uncertainty (default:
drop). A custom bar shifts strictness or re-weights concerns; it should still demand evidence from
the live codebase, not vibes.

## Writing resolution criteria

The body defines the bar the resolution stage applies to each unresolved review thread on a PR:
**worth implementing** (a real improvement the PR should carry, in scope for what it changes) and
**safe to implement unattended** (small blast radius, no contract or API changes, no cross-cutting
rewrites, verifiable locally). Define what gets implemented, what gets a reasoned decline
(overengineering asks, scope creep, style-only churn, requests better served by a follow-up), and
what escalates to a human. The harness owns the hard floors — human-authored threads are never
resolved by the bot, escalations never resolve a thread, replies always explain the decision — so
a custom skill may tighten the bar or re-weight what counts as worth it, never loosen those floors.