How AI reviews work

PerfCopilot generates review drafts grounded in evidence — not in vibes. This page walks through what the AI sees, how it produces ratings and prose, and how you (the manager) drive the final output.

The short version

For each review you generate:

1. PerfCopilot pulls every signal we've ingested for the employee in the cycle's window — GitHub PRs, Slack messages, Jira tickets, manual notes you've left, peer feedback, etc.
2. Signals are aggregated per source into a structured summary (counts, top items, distributions).
3. The summary plus your skill preset, your org guidelines, and a few comparative baselines are stitched into a Claude prompt.
4. Claude writes a rating per skill (1–5) plus prose for strengths, areas for improvement, and an overall summary.
5. You edit the draft. Your edits — both structural (changing ratings) and stylistic (rewording) — feed back into future drafts as guidelines.
6. When you're ready, you submit the review to HR. PerfCopilot generates a sealed PDF snapshot and a magic-link the report can use to view and acknowledge.

What the AI sees

Every prompt has these blocks (in order):

• Subject — name, role, department.
• Skill framework — the skills you're rating against (configurable per preset), each with a description and a weight on the relevant signal sources.
• Signal data — the actual aggregated counts, with timestamps. One block per source (GitHub, Slack, Jira, etc.).
• Peer feedback — submitted peer reviews for this employee whose response date falls in the cycle's window. Includes the rating, strengths, improvements, and overall comments. Anonymous responses are surfaced without the peer's name.
• Examples — sample reviews you've uploaded as a tone reference (optional).
• Baselines — comparative medians from the employee's cohort (manager peers → department → org cascade). So Claude can ground claims like "above the team median for PR throughput" instead of asserting absolute thresholds.
• Org guidelines — stylistic notes you've accumulated by editing past reviews ("Keep an authoritative tone", "Avoid the word 'crushing it'"). Influences prose only, not ratings.
• Instructions — the actual generation request: produce a rating per skill with explanation, then strengths / improvements / overall.

The output is parsed into structured fields that show up in the dashboard's review editor.

Ratings: 1 to 5

We use a 1–5 numeric rating per skill instead of category labels (Exceeds / Meets / Needs Improvement). Concretely:

• 1 — Poor
• 2 — Fair
• 3 — Satisfactory
• 4 — Good
• 5 — Excellent

The overall rating is the average of all skill ratings (PerfCopilot computes this client-side — Claude doesn't write the overall line). Both display as "X.Y / 5" everywhere.

Internally there's also a 0–99 score derived from the ratings (with hash jitter so two 4.0s don't collide on the visual ring). That score drives the visual fill on the rating ring; you don't usually need to think about it.

Tuning ratings vs. tuning prose

Two distinct channels influence reviews. Don't mix them up:

• Structured fields influence ratings. If you want Claude to weight Slack help-replies less for an engineer, change the skill weight from /admin?tab=presets. If you want a particular signal source to count more, raise its weight.
• Freeform org guidelines influence prose only. Adding "Be more concise" or "Always cite a specific PR when claiming impact" changes how Claude writes — not what rating it gives.

When a manager wants to bump a rating up or down, the right move is to edit the rating directly (and PerfCopilot remembers your edit), not to write a guideline saying "rate this person higher" — that gets ignored on purpose to keep the system uncalibratable.

Regenerate

The Regenerate button re-runs the prompt against the latest data. It's most useful after:

• A fresh Sync All that pulled new signals
• Adding or editing a manual note
• Receiving new peer feedback

If the underlying data hasn't changed since the last draft, PerfCopilot's prompt cache short-circuits the request and returns the cached draft (the button shows a "No changes since last draft — sync signals or add a note to regenerate" tooltip). This avoids paying for identical Claude calls.

Heads up: Regenerate overwrites any text you've manually edited. If you've made meaningful edits, click Save before regenerating to preserve them as the final version.

Closed-loop learning

When you save a review with substantive edits to the AI draft, PerfCopilot prompts you with an inline "Note for next time?" input. Whatever you write gets appended to your organization's review_guidelines, which feeds into every subsequent prompt as stylistic context.

Over time, the AI drafts converge on your team's voice without you having to nudge each one. You can also edit the whole guideline blob from /admin?tab=presets.

Delivering a review

When you're satisfied with a draft, click Submit to HR. This:

1. Locks the review's text as the final version.
2. Generates a sealed PDF with your organization's branding (logo, address) — the PDF is the customer's document, not PerfCopilot's.
3. Creates a magic-link the report can use to view and acknowledge the review.
4. Stores a SHA-256 hash of the PDF for tamper-verification (publicly verifiable from the link).

The report receives an email with the magic-link. They can read the review, leave an acknowledgment, and download the PDF. Everything is logged for HR's audit trail.

History

Every submitted review shows up in the History tab on the employee's dashboard, with the cycle, the snapshot date, the PDF, and the report's acknowledgment status. Reviews are immutable once submitted — if you need to change something, you generate a new review for a follow-up cycle.