@poltergeist-ai/cli 0.1.6 → 0.1.9

package/README.md

@@ -17,6 +17,18 @@ npm install -g @poltergeist-ai/cli
 poltergeist extract [options]
 ```
 
+### Set up skills for your AI coding tool
+
+```bash
+npx @poltergeist-ai/cli setup
+```
+
+This installs the poltergeist review and extract skills for Claude Code, Codex, Cursor, Windsurf, or Cline. You can also pass `--tool` to skip the interactive prompt:
+
+```bash
+npx @poltergeist-ai/cli setup --tool claude-code,cursor
+```
+
 Requires Node.js >= 18.17.0.
 
 ## Usage
@@ -70,12 +82,18 @@ npx @poltergeist-ai/cli extract \
   --github-token ghp_xxxxxxxxxxxx
 ```
 
+The CLI also reads `GITHUB_TOKEN` or `GITHUB_PERSONAL_ACCESS_TOKEN` from the environment, so you can skip the flag if either is set.
+
 ## CLI reference
 
 ```
-Usage: poltergeist [extract] [options]
+Usage: poltergeist <command> [options]
 
-Options:
+Commands:
+  extract    Build a contributor ghost profile from data sources
+  setup      Install poltergeist skills for your AI coding tool
+
+Extract options:
   --contributor <name>    Contributor name (required)
   --email <email>         Contributor email for git log filtering
   --slug <slug>           Output filename slug (default: derived from name)
@@ -86,6 +104,11 @@ Options:
   --github-token <token>  GitHub PAT for higher API rate limits
   --output <path>         Output path (default: .poltergeist/ghosts/<slug>.md)
   --verbose               Enable verbose logging
+
+Setup options:
+  --tool <id>             Tool to install for (claude-code,codex,cursor,windsurf,cline)
+                          Comma-separated for multiple. Omit to choose interactively.
+
   --help                  Show help
 ```
 
@@ -124,14 +147,15 @@ Use a Slack admin export (or workspace export) and point `--slack-export` at the
 
 The CLI generates a ghost file in Markdown with these sections:
 
-- **Identity** — name, slug, role, primary domains, sources used
+- **Identity** — name, slug, version, status, role, primary domains, sources used, generator version
+- **Review Heuristics** — weighted dimensions table with confidence levels and default severities, tradeoff preferences, scars
 - **Review philosophy** — ranked values, dealbreakers, what they ignore
 - **Communication style** — tone, severity prefixes, vocabulary, comment length
 - **Code patterns** — patterns they prefer, push back on, and commonly suggest
 - **Known blind spots** — areas they historically under-review
 - **Example review comments** — verbatim excerpts for voice grounding
 
-Sections marked `[fill in manually]` need human input. The manual pass is the most important step — especially ranked values and example comments.
+The Review Heuristics table is auto-generated from review comment analysis — it drives priority and comment distribution during simulated reviews. Sections marked `[fill in manually]` need human input. The manual pass is the most important step — especially ranked values, tradeoff preferences, and example comments.
 
 ### After extraction
 

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { appendFileSync, existsSync, mkdirSync, readFileSync as readFileSync4, writeFileSync } from "fs";
+import { appendFileSync, existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync6, writeFileSync as writeFileSync2 } from "fs";
 import path4 from "path";
 import { execFileSync as execFileSync2 } from "child_process";
 import { parseArgs } from "util";
@@ -742,31 +742,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;
@@ -810,10 +894,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;
 }
 
@@ -823,6 +910,7 @@ function extractGitLabSignals(exportPath, contributor, verbose) {
     reviewComments: [],
     commentLengths: [],
     severityPrefixes: {},
+    commentSeverities: [],
     questionComments: 0,
     totalComments: 0,
     source: "gitlab"
@@ -860,7 +948,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;
@@ -953,6 +1045,7 @@ async function extractGitHubSignals(owner, repo, contributor, token, verbose) {
     reviewComments: [],
     commentLengths: [],
     severityPrefixes: {},
+    commentSeverities: [],
     questionComments: 0,
     totalComments: 0,
     source: "github"
@@ -996,7 +1089,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;
@@ -1104,6 +1201,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(", ");
 }
@@ -1129,23 +1238,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_`
@@ -1416,6 +1568,132 @@ function buildGhostMarkdown(input) {
   return lines.join("\n");
 }
 
+// src/setup.ts
+import { existsSync, mkdirSync, readFileSync as readFileSync5, writeFileSync } from "fs";
+import { dirname as dirname2, join as join2 } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import { createInterface } from "readline";
+import { installRules, supportedTools } from "@poltergeist-ai/llm-rules";
+function getSkillsDir() {
+  return join2(dirname2(fileURLToPath2(import.meta.url)), "..", "skills");
+}
+function loadSkill(filePath) {
+  const raw = readFileSync5(filePath, "utf-8");
+  const fmMatch = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!fmMatch) {
+    return { name: "", description: "", body: raw, raw };
+  }
+  const frontmatter = fmMatch[1];
+  const body = fmMatch[2].trim();
+  let name = "";
+  let description = "";
+  const nameMatch = frontmatter.match(/^name:\s*(.+)$/m);
+  if (nameMatch) name = nameMatch[1].trim();
+  const descMatch = frontmatter.match(/description:\s*>\s*\n([\s\S]*?)$/);
+  if (descMatch) {
+    description = descMatch[1].replace(/\n\s*/g, " ").trim();
+  } else {
+    const descSimple = frontmatter.match(/^description:\s*(?!>)(.+)$/m);
+    if (descSimple) description = descSimple[1].trim();
+  }
+  return { name, description, body, raw };
+}
+function stripPluginRoot(content) {
+  return content.replace(/\$\{CLAUDE_PLUGIN_ROOT\}\//g, ".poltergeist/");
+}
+function prompt(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+async function runSetup(toolFlag) {
+  console.log("\n  Poltergeist Setup\n");
+  const tools = supportedTools();
+  let selectedToolIds;
+  if (toolFlag) {
+    const ids = toolFlag.split(",").map((s) => s.trim().toLowerCase());
+    const valid = ids.filter((id) => tools.some((t) => t.id === id));
+    if (valid.length === 0) {
+      console.error(
+        `Unknown tool(s): ${toolFlag}
+Available: ${tools.map((t) => t.id).join(", ")}`
+      );
+      return 1;
+    }
+    selectedToolIds = valid;
+  } else {
+    console.log("  Available tools:\n");
+    for (let i = 0; i < tools.length; i++) {
+      console.log(`    ${i + 1}. ${tools[i].name} (${tools[i].id})`);
+    }
+    console.log(`    a. All
+`);
+    const answer = await prompt("  Install for (numbers comma-separated, or 'a' for all): ");
+    if (answer.toLowerCase() === "a") {
+      selectedToolIds = tools.map((t) => t.id);
+    } else {
+      const indices = answer.split(",").map((s) => parseInt(s.trim()) - 1).filter((i) => i >= 0 && i < tools.length);
+      if (indices.length === 0) {
+        console.log("No tools selected.");
+        return 0;
+      }
+      selectedToolIds = indices.map((i) => tools[i].id);
+    }
+  }
+  const skillsDir = getSkillsDir();
+  const reviewSkillPath = join2(skillsDir, "poltergeist", "SKILL.md");
+  const extractSkillPath = join2(skillsDir, "extract", "SKILL.md");
+  const rules = [];
+  if (existsSync(reviewSkillPath)) {
+    const skill = loadSkill(reviewSkillPath);
+    rules.push({
+      name: skill.name || "poltergeist",
+      description: skill.description || "Poltergeist review skill",
+      content: stripPluginRoot(skill.raw)
+    });
+  } else {
+    console.error(`  [error] Review skill not found at ${reviewSkillPath}`);
+    return 1;
+  }
+  if (existsSync(extractSkillPath)) {
+    const skill = loadSkill(extractSkillPath);
+    rules.push({
+      name: skill.name || "extract",
+      description: skill.description || "Poltergeist extract skill",
+      content: stripPluginRoot(skill.raw)
+    });
+  }
+  console.log(`
+  Installing for ${selectedToolIds.join(", ")}...`);
+  const results = installRules(rules, {
+    tools: selectedToolIds,
+    force: true,
+    namespace: "poltergeist"
+  });
+  for (const result of results) {
+    console.log(`    \u2713 ${result.path} (${result.action})`);
+  }
+  const exampleGhostPath = join2(skillsDir, "..", "ghosts", "example-ghost.md");
+  if (existsSync(exampleGhostPath)) {
+    const ghostDest = ".poltergeist/ghosts/example-ghost.md";
+    if (!existsSync(ghostDest)) {
+      mkdirSync(dirname2(ghostDest), { recursive: true });
+      writeFileSync(ghostDest, readFileSync5(exampleGhostPath));
+      console.log(`
+    \u2713 ${ghostDest}`);
+    }
+  }
+  console.log("\n  Done. Next steps:");
+  console.log("    1. Build a ghost: npx @poltergeist-ai/cli extract --contributor <name> --git-repo <url>");
+  console.log('    2. Run a review:  git diff main | claude "review as @<slug>"');
+  console.log("");
+  return 0;
+}
+
 // src/cli.ts
 var POLTERGEIST_DIR = ".poltergeist";
 var CACHE_DIR = `${POLTERGEIST_DIR}/repos`;
@@ -1423,25 +1701,27 @@ var GHOSTS_DIR = `${POLTERGEIST_DIR}/ghosts`;
 function ensureReposGitignored() {
   const gitignorePath = ".gitignore";
   const entry = ".poltergeist/repos/";
-  if (existsSync(gitignorePath)) {
-    const content = readFileSync4(gitignorePath, "utf-8");
+  if (existsSync2(gitignorePath)) {
+    const content = readFileSync6(gitignorePath, "utf-8");
     if (content.includes(entry)) return;
     appendFileSync(gitignorePath, `
 # Poltergeist cached clones
 ${entry}
 `);
   } else {
-    writeFileSync(gitignorePath, `# Poltergeist cached clones
+    writeFileSync2(gitignorePath, `# Poltergeist cached clones
 ${entry}
 `);
   }
 }
 function printUsage() {
-  console.log(`Usage: poltergeist [extract] [options]
+  console.log(`Usage: poltergeist <command> [options]
 
-Build a contributor ghost profile from data sources.
+Commands:
+  extract    Build a contributor ghost profile from data sources
+  setup      Install poltergeist skills for your AI coding tool
 
-Options:
+Extract options:
   --contributor <name>    Contributor name (required; use GitHub username for best results)
   --email <email>         Contributor email (for git log filtering)
   --slug <slug>           Output slug (default: derived from name)
@@ -1452,6 +1732,11 @@ Options:
   --github-token <token>  GitHub personal access token (for higher API rate limits)
   --output <path>         Output path (default: .poltergeist/ghosts/<slug>.md)
   --verbose               Enable verbose logging
+
+Setup options:
+  --tool <id>             Tool to install for (claude-code,codex,cursor,windsurf,cline)
+                          Comma-separated for multiple. Omit to choose interactively.
+
   --help                  Show this help message`);
 }
 function isRemoteUrl(value) {
@@ -1464,7 +1749,7 @@ function resolveGitRepo(value, verbose) {
   if (!isRemoteUrl(value)) return value;
   const slug = repoSlug(value);
   const cloneDir = path4.join(CACHE_DIR, slug);
-  if (existsSync(cloneDir)) {
+  if (existsSync2(cloneDir)) {
     console.log(`[extract] Using cached clone at ${cloneDir}`);
     try {
       execFileSync2("git", ["-C", cloneDir, "fetch", "--quiet"], {
@@ -1478,7 +1763,7 @@ function resolveGitRepo(value, verbose) {
     return cloneDir;
   }
   console.log(`[extract] Cloning ${value} into ${cloneDir}...`);
-  mkdirSync(CACHE_DIR, { recursive: true });
+  mkdirSync2(CACHE_DIR, { recursive: true });
   ensureReposGitignored();
   execFileSync2(
     "git",
@@ -1497,6 +1782,16 @@ async function run() {
     printUsage();
     return 0;
   }
+  if (rawArgs[0] === "setup") {
+    const setupArgs = rawArgs.slice(1);
+    let toolFlag;
+    for (let i = 0; i < setupArgs.length; i++) {
+      if (setupArgs[i] === "--tool" && setupArgs[i + 1]) {
+        toolFlag = setupArgs[i + 1];
+      }
+    }
+    return runSetup(toolFlag);
+  }
   const args = rawArgs[0] === "extract" ? rawArgs.slice(1) : rawArgs;
   const { values } = parseArgs({
     args,
@@ -1529,7 +1824,7 @@ async function run() {
   const slug = values.slug ?? slugify(contributor);
   const outputPath = values.output ?? `${GHOSTS_DIR}/${slug}.md`;
   const verbose = values.verbose ?? false;
-  const githubToken = values["github-token"];
+  const githubToken = values["github-token"] ?? process.env.GITHUB_PERSONAL_ACCESS_TOKEN ?? process.env.GITHUB_TOKEN;
   const sourcesUsed = [];
   let gitObs = {};
   let codeStyleObs = { observations: [], totalLinesAnalyzed: 0 };
@@ -1632,9 +1927,9 @@ async function run() {
   });
   const dir = path4.dirname(outputPath);
   if (dir && dir !== ".") {
-    mkdirSync(dir, { recursive: true });
+    mkdirSync2(dir, { recursive: true });
   }
-  writeFileSync(outputPath, ghostMd);
+  writeFileSync2(outputPath, ghostMd);
   console.log(`
 Ghost draft written to: ${outputPath}`);
   console.log("\nNext steps:");

package/dist/index.d.ts

@@ -34,6 +34,8 @@ interface ReviewSignals {
     reviewComments: string[];
     commentLengths: number[];
     severityPrefixes: Record<string, number>;
+    /** Per-comment severity prefix (parallel array to reviewComments) */
+    commentSeverities?: string[];
     questionComments: number;
     totalComments: number;
     source: "github" | "gitlab";
@@ -46,6 +48,10 @@ interface ReviewTheme {
     ratio: number;
     /** Verbatim snippets that matched this theme */
     exampleSnippets: string[];
+    /** Breakdown of severity prefixes for comments matching this theme */
+    severityBreakdown?: Record<string, number>;
+    /** Average character length of comments matching this theme */
+    avgCommentLength?: number;
 }
 interface CommentToneProfile {
     /** Fraction of comments that include praise / positive reinforcement */
@@ -61,6 +67,16 @@ interface CommentToneProfile {
     /** Sample explanatory comments */
     explanationExamples: string[];
 }
+interface WeightedDimension {
+    dimension: string;
+    label: string;
+    /** Composite weight (0.0–1.0) derived from frequency, severity, and specificity */
+    weight: number;
+    confidence: "high" | "moderate" | "low";
+    commentCount: number;
+    /** Most common severity when this theme appears */
+    defaultSeverity: "blocking" | "suggestion" | "nit" | "unknown";
+}
 interface ReviewObservations {
     totalReviewComments?: number;
     avgCommentLength?: number;
@@ -77,6 +93,8 @@ interface ReviewObservations {
     recurringQuestions?: string[];
     /** Phrases/vocabulary the contributor uses repeatedly */
     recurringPhrases?: string[];
+    /** Weighted dimensions computed from frequency, severity, and specificity */
+    weightedDimensions?: WeightedDimension[];
 }
 /** @deprecated Use ReviewSignals instead */
 type GitLabSignals = ReviewSignals;

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.6",
+  "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.