/review-hog-authoring

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

Authoring ReviewHog skills

**ReviewHog** 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.

All three 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` |

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** — 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 swe