@poltergeist-ai/cli 0.1.5 → 0.1.9

package/dist/index.js

@@ -734,31 +734,115 @@ function sampleMatching(comments, patterns, max) {
   }
   return matches;
 }
-function extractThemes(comments) {
+function extractThemes(comments, commentSeverities) {
   if (comments.length === 0) return [];
   const themes = [];
+  const severities = commentSeverities ?? [];
   for (const def of THEME_DEFS) {
     const matchingComments = [];
-    for (const comment of comments) {
+    const matchingSeverities = [];
+    let totalLength = 0;
+    for (let i = 0; i < comments.length; i++) {
+      const comment = comments[i];
       const lower = comment.toLowerCase();
       if (def.patterns.some((p) => p.test(lower))) {
         matchingComments.push(comment);
+        totalLength += comment.length;
+        if (i < severities.length) {
+          matchingSeverities.push(severities[i]);
+        }
       }
     }
     if (matchingComments.length < 2) continue;
     const ratio = Math.round(matchingComments.length / comments.length * 100) / 100;
     const snippets = matchingComments.filter((c) => c.length > 20 && c.length < 300).slice(0, 3).map((c) => c.length > 150 ? c.slice(0, 150) + "..." : c);
+    const severityBreakdown = {};
+    for (const sev of matchingSeverities) {
+      severityBreakdown[sev] = (severityBreakdown[sev] ?? 0) + 1;
+    }
     themes.push({
       theme: def.theme,
       label: def.label,
       count: matchingComments.length,
       ratio,
-      exampleSnippets: snippets
+      exampleSnippets: snippets,
+      severityBreakdown: matchingSeverities.length > 0 ? severityBreakdown : void 0,
+      avgCommentLength: Math.round(totalLength / matchingComments.length)
     });
   }
   themes.sort((a, b) => b.count - a.count);
   return themes;
 }
+var HIGH_SEVERITY = /* @__PURE__ */ new Set(["blocking", "major"]);
+var MED_SEVERITY = /* @__PURE__ */ new Set(["suggestion", "question", "thought"]);
+var LOW_SEVERITY = /* @__PURE__ */ new Set(["nit", "minor"]);
+function dominantSeverity(breakdown) {
+  if (!breakdown) return "unknown";
+  let bestCategory = "unknown";
+  let bestCount = 0;
+  let highCount = 0;
+  let medCount = 0;
+  let lowCount = 0;
+  for (const [sev, count] of Object.entries(breakdown)) {
+    if (HIGH_SEVERITY.has(sev)) highCount += count;
+    else if (MED_SEVERITY.has(sev)) medCount += count;
+    else if (LOW_SEVERITY.has(sev)) lowCount += count;
+  }
+  if (highCount > bestCount) {
+    bestCategory = "blocking";
+    bestCount = highCount;
+  }
+  if (medCount > bestCount) {
+    bestCategory = "suggestion";
+    bestCount = medCount;
+  }
+  if (lowCount > bestCount) {
+    bestCategory = "nit";
+    bestCount = lowCount;
+  }
+  return bestCategory;
+}
+function computeWeightedDimensions(themes) {
+  if (themes.length === 0) return [];
+  const maxRatio = Math.max(...themes.map((t) => t.ratio));
+  const maxAvgLen = Math.max(
+    ...themes.map((t) => t.avgCommentLength ?? 0),
+    1
+  );
+  return themes.map((theme) => {
+    const frequencyScore = maxRatio > 0 ? theme.ratio / maxRatio : 0;
+    let severityScore = 0.5;
+    if (theme.severityBreakdown) {
+      const total = Object.values(theme.severityBreakdown).reduce(
+        (a, b) => a + b,
+        0
+      );
+      if (total > 0) {
+        let highCount = 0;
+        for (const [sev, count] of Object.entries(theme.severityBreakdown)) {
+          if (HIGH_SEVERITY.has(sev)) highCount += count;
+        }
+        severityScore = highCount / total;
+      }
+    }
+    const avgLen = theme.avgCommentLength ?? 0;
+    const specificityScore = maxAvgLen > 0 ? avgLen / maxAvgLen : 0;
+    const rawWeight = frequencyScore * 0.5 + severityScore * 0.3 + specificityScore * 0.2;
+    const weight = Math.round(Math.min(1, Math.max(0, rawWeight)) * 100) / 100;
+    let confidence;
+    if (theme.count >= 20) confidence = "high";
+    else if (theme.count >= 10) confidence = "moderate";
+    else confidence = "low";
+    return {
+      dimension: theme.theme,
+      label: theme.label,
+      weight,
+      confidence,
+      commentCount: theme.count,
+      defaultSeverity: dominantSeverity(theme.severityBreakdown)
+    };
+  });
+}
 function buildToneProfile(comments) {
   if (comments.length < 5) return void 0;
   const n = comments.length;
@@ -802,10 +886,13 @@ function summariseReview(signals) {
       indices.filter((i) => i >= 0 && i < n).map((i) => sorted[i])
     )
   ];
-  obs.reviewThemes = extractThemes(comments);
+  obs.reviewThemes = extractThemes(comments, signals.commentSeverities);
   obs.toneProfile = buildToneProfile(comments);
   obs.recurringQuestions = extractRecurringQuestions(comments);
   obs.recurringPhrases = extractRecurringPhrases(comments);
+  if (obs.reviewThemes.length > 0) {
+    obs.weightedDimensions = computeWeightedDimensions(obs.reviewThemes);
+  }
   return obs;
 }
 
@@ -815,6 +902,7 @@ function extractGitLabSignals(exportPath, contributor, verbose) {
     reviewComments: [],
     commentLengths: [],
     severityPrefixes: {},
+    commentSeverities: [],
     questionComments: 0,
     totalComments: 0,
     source: "gitlab"
@@ -852,7 +940,11 @@ function extractGitLabSignals(exportPath, contributor, verbose) {
     signals.totalComments += 1;
     const prefixMatch = body.match(prefixRe);
     if (prefixMatch) {
-      increment(signals.severityPrefixes, prefixMatch[1].toLowerCase());
+      const severity = prefixMatch[1].toLowerCase();
+      increment(signals.severityPrefixes, severity);
+      signals.commentSeverities.push(severity);
+    } else {
+      signals.commentSeverities.push("none");
     }
     if (body.endsWith("?") || body.toLowerCase().startsWith("do we") || body.toLowerCase().startsWith("should we")) {
       signals.questionComments += 1;
@@ -945,6 +1037,7 @@ async function extractGitHubSignals(owner, repo, contributor, token, verbose) {
     reviewComments: [],
     commentLengths: [],
     severityPrefixes: {},
+    commentSeverities: [],
     questionComments: 0,
     totalComments: 0,
     source: "github"
@@ -988,7 +1081,11 @@ async function extractGitHubSignals(owner, repo, contributor, token, verbose) {
       signals.totalComments += 1;
       const prefixMatch = body.match(prefixRe);
       if (prefixMatch) {
-        increment(signals.severityPrefixes, prefixMatch[1].toLowerCase());
+        const severity = prefixMatch[1].toLowerCase();
+        increment(signals.severityPrefixes, severity);
+        signals.commentSeverities.push(severity);
+      } else {
+        signals.commentSeverities.push("none");
       }
       if (body.endsWith("?") || body.toLowerCase().startsWith("do we") || body.toLowerCase().startsWith("should we")) {
         signals.questionComments += 1;
@@ -1096,6 +1193,18 @@ function extractDocsSignals(docsDir, contributor, verbose) {
 }
 
 // src/generator.ts
+import { readFileSync as readFileSync4 } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+function getCliVersion() {
+  try {
+    const dir = dirname(fileURLToPath(import.meta.url));
+    const pkg = JSON.parse(readFileSync4(join(dir, "..", "package.json"), "utf-8"));
+    return pkg.version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
 function formatPairs(pairs, suffix = "") {
   return pairs.map(([name, count]) => `${name}${suffix} (${count})`).join(", ");
 }
@@ -1121,23 +1230,66 @@ function buildGhostMarkdown(input) {
   const { contributor, slug, gitObs, codeStyleObs, reviewObs, slackObs, docsSignals, sourcesUsed } = input;
   const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
   const domains = gitObs.inferredDomains?.length ? gitObs.inferredDomains.join(", ") : "_[fill in manually]_";
+  const cliVersion = getCliVersion();
   const lines = [
     `# Contributor Soul: ${contributor}`,
     "",
     "## Identity",
     `- **Slug**: ${slug}`,
+    `- **Version**: 0.1.0`,
+    `- **Status**: draft`,
     "- **Role**: _[fill in manually]_",
     `- **Primary domains**: ${domains}`,
     `- **Soul last updated**: ${today}`,
     `- **Sources used**: ${sourcesUsed.join(", ")}`,
+    `- **Generated by**: @poltergeist-ai/cli@${cliVersion}`,
+    "",
+    "---",
+    ""
+  ];
+  const weighted = reviewObs.weightedDimensions;
+  const themes = reviewObs.reviewThemes;
+  if (weighted && weighted.length > 0) {
+    lines.push(
+      "## Review Heuristics",
+      "",
+      `_Inferred from ${reviewObs.totalReviewComments ?? "?"} review comments \u2014 adjust weights as needed_`,
+      "",
+      "| Dimension | Weight | Confidence | Default Severity |",
+      "|---|---|---|---|"
+    );
+    for (const dim of weighted) {
+      lines.push(
+        `| ${dim.label} | ${dim.weight.toFixed(2)} | ${dim.confidence} (${dim.commentCount} comments) | ${dim.defaultSeverity} |`
+      );
+    }
+    lines.push("");
+  }
+  lines.push(
+    "### Tradeoff Preferences",
+    "_How this contributor resolves common engineering tensions. Fill in from review patterns._",
+    "",
+    "- abstraction vs duplication: _[prefer-abstraction | prefer-duplication | balanced]_",
+    "- readability vs performance: _[prefer-readability | prefer-performance | balanced]_",
+    "- speed vs correctness: _[prefer-speed | prefer-correctness | balanced]_",
+    "- local vs system optimization: _[prefer-local | prefer-system | balanced]_",
+    ""
+  );
+  lines.push(
+    "### Scars",
+    "_Historical incidents that make this contributor unusually sensitive to certain patterns._",
+    "_Format: **pattern** (multiplier) \u2014 description. Amplifies: dimension names._",
     "",
+    "_[Fill in manually \u2014 e.g.: **shared-mutable-state** (\xD71.8) \u2014 production incident. Amplifies: error_handling, readability]_",
+    ""
+  );
+  lines.push(
     "---",
     "",
     "## Review Philosophy",
     "",
     "### What they care about most (ranked)"
-  ];
-  const themes = reviewObs.reviewThemes;
+  );
   if (themes && themes.length > 0) {
     lines.push(
       `_Inferred from ${reviewObs.totalReviewComments ?? "?"} review comments \u2014 verify and re-order as needed_`

package/ghosts/example-ghost.md

@@ -0,0 +1,152 @@
+# Contributor Ghost: Alex Chen
+
+## Identity
+- **Slug**: alex-chen
+- **Version**: 0.2.0
+- **Status**: active
+- **Role**: Senior Frontend Engineer
+- **Primary domains**: Vue.js, GraphQL, component architecture, DX
+- **Soul last updated**: 2025-01-15
+- **Sources used**: git-history, gitlab-comments, slack-export
+- **Generated by**: @poltergeist-ai/cli@0.1.6
+
+---
+
+## Review Heuristics
+
+| Dimension | Weight | Confidence | Default Severity |
+|---|---|---|---|
+| Error handling / edge cases | 0.92 | high (28 comments) | blocking |
+| Decomposition / single responsibility | 0.85 | high (22 comments) | suggestion |
+| Naming clarity | 0.78 | moderate (15 comments) | nit |
+| Testing / test coverage | 0.74 | moderate (12 comments) | blocking |
+| Consistency with existing patterns | 0.61 | moderate (10 comments) | suggestion |
+| Readability / clarity | 0.45 | low (6 comments) | suggestion |
+
+### Tradeoff Preferences
+
+- abstraction vs duplication: balanced
+- readability vs performance: prefer-readability
+- speed vs correctness: prefer-correctness
+- local vs system optimization: prefer-system
+
+### Scars
+
+- **unhandled-api-errors** (×1.8) — production 500 from missing error handling on a third-party API call. Amplifies: error_handling
+- **untested-business-logic** (×1.5) — regression shipped because a critical code path had no test coverage. Amplifies: testing
+
+---
+
+## Review Philosophy
+
+### What they care about most (ranked)
+1. Correctness — does this work in all states (loading, error, empty)?
+2. Naming — is this self-documenting without needing to read the implementation?
+3. Component boundaries — is this doing one thing?
+4. Test coverage — are the failure paths tested, not just happy paths?
+5. Consistency — does this follow what we've already established?
+
+### What they tend to ignore
+- Minor formatting (defers entirely to linter/prettier)
+- Build config / bundler changes
+- Dependency bumps unless breaking changes are involved
+- Comment documentation unless the logic is genuinely non-obvious
+
+### Dealbreakers
+- API calls with no error handling
+- Business logic with no tests
+- Breaking changes with no migration path or callout in the MR description
+- TypeScript `any` types without a justifying comment
+
+### Recurring questions they ask
+- "What does the user see when this fails?"
+- "Do we need this complexity right now?"
+- "Is this the right abstraction or are we solving the wrong problem?"
+- "Can we test this?"
+
+---
+
+## Communication Style
+
+### Tone
+Direct but constructive. Doesn't over-explain. Not snarky. Will say when something is good — but rarely.
+
+### Positive feedback
+Sparse and genuine. A single "nice." carries weight. Never leaves a meaningless LGTM.
+
+### How they frame critiques
+Prefers questions over directives — "Do we need this?" not "Remove this."
+Explains *why* when it's not obvious, but skips the why when it is.
+
+### Severity prefixes they use
+- `nit:` — minor, genuinely optional
+- `suggestion:` — worthwhile, not blocking
+- `question:` — genuinely curious, not necessarily a problem
+- `blocking:` — must resolve before merge
+- _(no prefix)_ — treated as a suggestion
+
+### Vocabulary / phrases they use
+- "I'd lean towards..."
+- "This feels like it could bite us later"
+- "Happy path looks good, but..."
+- "Can we test this?"
+- "Not sure I follow the logic here — can you add a comment?"
+- "nit: I'd call this X rather than Y — [brief reason]"
+- "This is clean."
+
+### Comment length
+Very brief. 1–2 sentences unless explaining an alternative approach. Rarely writes paragraphs.
+
+---
+
+## Code Patterns
+
+### Patterns they introduce / prefer
+- Composables over mixins
+- Early returns to avoid deep nesting
+- Named exports (easier to grep and refactor)
+- Constants extracted to the top of the file with descriptive names
+- Explicit TypeScript interfaces over inline types
+- `useQuery` / `useMutation` from vue-query rather than ad-hoc fetch logic
+
+### Patterns they push back on
+- Boolean props that should be variant strings (`type="primary"` not `:isPrimary="true"`)
+- Components over ~200 lines without a good reason
+- Prop drilling more than 2 levels deep
+- Inline styles
+- `any` types without justification
+- Side effects inside computed properties
+
+### Refactors they commonly suggest
+- "Extract this into a composable"
+- "This component is doing two things — can we split it?"
+- "Replace this magic number with a named constant"
+
+---
+
+## Known Blind Spots
+
+- Accessibility (aria attributes, keyboard navigation, focus management)
+- Loading states on UI components
+- Mobile / responsive edge cases
+- i18n completeness (sometimes misses that new strings need translating)
+
+---
+
+## Example Review Comments
+
+> `nit:` I'd name this `useSubmissionState` rather than `submissionHelper` — the `use` prefix makes it clear it's a composable.
+
+> `blocking:` No error handling on the API call on line 42. What does the user see if this 500s?
+
+> `question:` Do we need both the `v-if` and the `loading` prop here? Wondering if one can drive the other.
+
+> `suggestion:` This could be a composable — we have similar logic in the disclosure form. Worth extracting before this grows.
+
+> This is clean. Nice use of the composable pattern.
+
+> `blocking:` No tests for the failure case. The happy path test is there but if the API errors we have no coverage.
+
+> `nit:` `handleClick` doesn't say much — `handleSubmitForm` or `onSubmit` would be clearer.
+
+> Not sure I follow the logic here — can you add a brief comment explaining why we check `isLoaded` before `hasPermission`?

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poltergeist-ai/cli",
-  "version": "0.1.5",
+  "version": "0.1.9",
   "description": "Build contributor ghost profiles from git, GitLab, Slack, and docs for simulated code reviews",
   "license": "MIT",
   "type": "module",
@@ -14,11 +14,16 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "skills",
+    "ghosts"
   ],
   "engines": {
     "node": ">=18.17.0"
   },
+  "dependencies": {
+    "@poltergeist-ai/llm-rules": "0.1.0"
+  },
   "devDependencies": {
     "@types/node": "^22.0.0",
     "tsup": "^8.0.0",

package/skills/extract/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: extract
+description: >
+  Build a contributor ghost profile by extracting signals from git history,
+  GitHub/GitLab review comments, Slack exports, and design docs.
+  Trigger when the user says "build ghost for <name>", "extract ghost",
+  "create a ghost profile", "update ghost for <name>", or asks how to
+  capture a contributor's review style.
+---
+
+# Extract Ghost Profile
+
+Build a contributor ghost by running the poltergeist extractor CLI.
+
+## Gather information
+
+Ask the user for the following:
+
+**Required:**
+- **Contributor name** (`--contributor`): Use their GitHub username for best GitHub PR comment extraction.
+
+**At least one data source:**
+- **Git repo** (`--git-repo`): Local path or remote URL (GitHub/GitLab). If a GitHub URL is provided, the CLI auto-fetches PR review comments.
+- **GitLab export** (`--gitlab-export`): Path to GitLab MR comments JSON export. Most valuable data source for review heuristics.
+- **Slack export** (`--slack-export`): Path to Slack export directory.
+- **Docs directory** (`--docs-dir`): Path to design docs or ADRs.
+
+**Optional:**
+- **Email** (`--email`): For git log filtering when contributor name differs from git author.
+- **GitHub token** (`--github-token`): For higher GitHub API rate limits (5000 vs 60 req/hr). Also reads from `GITHUB_PERSONAL_ACCESS_TOKEN` or `GITHUB_TOKEN` environment variables or `.env` file.
+- **Output** (`--output`): Defaults to `.poltergeist/ghosts/<slug>.md`.
+- **Verbose** (`--verbose`): Detailed extraction progress.
+
+## Build and present the command
+
+Construct the `npx` command and present it to the user:
+
+```bash
+npx @poltergeist-ai/cli extract \
+  --contributor "<name>" \
+  --git-repo <path-or-url> \
+  [--email <email>] \
+  [--gitlab-export <path>] \
+  [--slack-export <path>] \
+  [--docs-dir <path>] \
+  [--github-token <token>] \
+  [--output <path>] \
+  [--verbose]
+```
+
+## After extraction
+
+1. Read the generated ghost file
+2. Check that the `## Review Heuristics` table populated (requires review comment data — GitHub PRs or GitLab exports)
+3. Identify gaps — especially `_[fill in manually]_` sections
+4. Ask the user to validate the ranked values, example comments, and tradeoff preferences
+5. Help fill in scars (historical incidents) and blind spots — these require human knowledge
+6. Update `Status` from `draft` to `active` once validated
+
+## Ghost file locations
+
+- Generated ghosts: `.poltergeist/ghosts/<slug>.md`
+- Feedback data: `.poltergeist/feedback/<slug>.json`
+- Slug format: lowercase hyphenated (`alice-smith.md`)

package/skills/poltergeist/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: poltergeist
+description: >
+  Perform a code review from the perspective of a specific contributor — using their
+  voice, values, heuristics, and communication style — even when they are not present.
+  Trigger when the user says "review as @name", "review with [name]'s lens",
+  "what would [name] say about this", "summon [name]'s ghost", or any phrasing that
+  asks for a review through a specific contributor's perspective.
+---
+
+# 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:
+
+```bash
+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`:
+   ```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.