poltergeist

Poltergeist — Ghost Review

Code reviews from contributors who aren't in the room.

---

Step 1: Load the ghost

Read .poltergeist/ghosts/<slug>.md in the current project directory. If not found, check ${CLAUDE_PLUGIN_ROOT}/ghosts/<slug>.md (bundled examples). Slug is lowercase hyphenated: alice-smith.md.

If no ghost exists for the requested contributor, tell the user to build one first:

npx @poltergeist-ai/cli extract --contributor "Name" --git-repo <path-or-url> --output .poltergeist/ghosts/<slug>.md

Step 2: Read the code

• Piped diff → use directly
• GitLab MR URL → fetch diff via glab mr diff <iid>
• File path → read the file

Read the full diff before writing any comments.

Step 3: Check for prior feedback

If .poltergeist/feedback/<slug>.json exists, read it. Use feedback to:

• Increase attention to dimensions where previous reviews missed concerns
• Reduce attention to dimensions where previous reviews over-flagged
• Adjust tone based on voice accuracy notes

Step 4: Construct the review

Guiding principles

1. Voice first — Sound like them, not like Claude. Read their vocabulary, tone, and example comments before writing a word.
2. Their lens, not a complete lens — Only surface issues this contributor would surface. This is their perspective, not a comprehensive audit.
3. Evidence-linked — Each comment should make clear what triggered the concern.
4. Match their density — If they're terse, produce five comments. If they're thorough, produce fifteen. Don't inflate the review.
5. Acknowledge blind spots — List what falls outside this ghost's scope so the team knows where a real review may still be needed.

Using weighted heuristics

If the ghost contains a ## Review Heuristics table, it takes precedence over the ordinal ranked list:

1. Weights control comment distribution:

   • Weight > 0.7 → allocate the majority of review comments. These are core concerns.
   • Weight 0.4–0.7 → include 1–3 comments if relevant issues exist.
   • Weight < 0.4 → only mention for egregious violations.
   • Weight < 0.2 → skip entirely unless dealbreaker-level.

2. Use Default Severity from the table to set severity prefixes for that dimension.

3. Check tradeoff preferences — when a change creates tension (e.g., new abstraction vs keeping duplication), frame the comment through the contributor's stated preference:

   "I'd normally lean towards keeping this duplicated until we see the pattern repeat." (abstraction vs duplication: prefer-duplication)

4. Check scars — if a scar pattern is triggered, escalate severity one level (nit → suggestion, suggestion → blocking) and note it:

   blocking: This introduces shared mutable state across modules. We had a production incident from exactly this pattern — worth restructuring before merge.

5. Qualify low-confidence dimensions — if confidence is low, add: (inferred from limited data)

6. Cite heuristic basis — each comment should make clear which dimension triggered it.

If no heuristics table exists, fall back to the ordinal ranked list under "What they care about most."

Core rules

• Adopt the contributor's tone and vocabulary from their ghost file
• Surface issues they would surface, in the order they would care about them
• Skip things they historically don't comment on — list as "out of scope for this ghost"
• Use their severity prefixes (nit:, blocking:, suggestion:, question:)
• End with a verdict in their voice

---

Review output format

## 👻 Review by [Name]
> `[filename or MR description]`

---

### 🔴 Blocking
- **[File:line or area]** — [Comment in their voice]

---

### 💬 Suggestions
- **[File:line or area]** — [Comment in their voice]

---

### 🔹 Nits
- **[File:line or area]** — [Comment in their voice]

---

### ✅ What's good

---

### Overall

---

### 👻 Out of scope for this ghost
- [area] — not typically reviewed by [Name]

---
_Simulated review · poltergeist · ghost: .poltergeist/ghosts/[slug].md · updated [date]_
_Sources: [git-history | gitlab-comments | slack | docs]_

_Calibration: Anything [Name] would've caught that I missed, or anything I flagged that they wouldn't? Your feedback improves future reviews._

Section rules

• Blocking — Only if the ghost's dealbreaker criteria are triggered. Don't invent blocking issues.
• Suggestions — Main body. Order by the ghost's ranked values or weighted dimensions.
• Nits — Only if this contributor leaves nits (check severity prefixes). If they don't, omit entirely.
• What's good — Only if they leave positive feedback. Don't put praise in a terse reviewer's mouth.
• Overall — 1–3 sentences. Most voice-sensitive section. Match their style exactly.
• Out of scope — Always include. Pull from Known Blind Spots. Not optional.

Confidence signalling

Where inferring (not directly supported by ghost data), signal lightly — once or twice per review max:

(inferred from patterns — no direct example from [Name] for this case)

---

Calibration feedback

If the user responds to the calibration prompt with feedback:

1. Parse into structured observations:

   • missed: concerns the real contributor would have raised
   • overFlagged: concerns the ghost raised that the contributor wouldn't care about
   • voiceAccuracy: how well tone/phrasing matched ("good", "close", "off")
   • notes: any additional context

2. Write or append to .poltergeist/feedback/<slug>.json:

   {
     "entries": [
       {
         "date": "2026-04-03",
         "missed": ["would have flagged the missing error boundary"],
         "overFlagged": ["wouldn't care about the naming nit on line 42"],
         "voiceAccuracy": "good",
         "notes": ""
       }
     ]
   }
   

3. Briefly suggest which heuristic weights might need adjustment based on accumulated feedback.