@genius-revius/insight-engine

Report generation engine for Revius -- aggregates observations into HTML recaps, task lists, and AI-ready prompts, and applies review packs (thematic production-readiness checklists) to review sessions.

Install

npm install @genius-revius/insight-engine

Usage

import { generateInsightPackage } from "@genius-revius/insight-engine";

const insight = await generateInsightPackage(session, observations);

Typically called by @genius-revius/server when a review session is stopped. See the main README for full documentation.

Review packs

A review pack is a versioned, Zod-validated checklist that is applied to a review session and produces prioritized findings in the Review Packet. Each check declares an id, category, severity, description, evidenceHints, and remediation. Applying a pack evaluates every check against the session evidence:

• fail -- negative or console observations matched an evidence hint;
• pass -- only positive observations matched an evidence hint;
• needs-evidence -- nothing conclusive matched; the finding tells the reviewer what to verify manually;
• not-applicable -- returned by a custom evaluator when the check does not apply.

Findings are sorted failures-first (by severity), then needs-evidence, then passes.

Built-in packs

| Pack | Checks | Categories | |------|--------|------------| | review-production | 28 | security, auth, secrets, edge-cases, tests, monitoring, backups, rollback, recovery, cost | | review-mcp-supply-chain | 21 | inventory, scopes, auth, logs, ownership, approval, skills, provenance, skill-card, quarantine | | review-agents | 24 | background-jobs, permissions, hook-matchers, notifications, failure-reporting, worktree, loop-contract, iteration-caps, heartbeat, autonomy | | review-telemetry-privacy | 25 | access-control, consent, debug-logs-client, otel, prompts, redaction, retention, secrets, trace-logs, websocket-payloads | | review-cost-autonomy | 24 | headless, ci, scheduled-agents, remote-triggers, long-context, model-routing, tokenizer-drift, tool-use, cost-tracking, budget-alerts | | review-code-research | 23 | code-review-usage, code-review-coverage, code-review-token-efficiency, deep-research-verification, deep-research-sourcing, diff-freshness, diff-scope, benchmarks-before-after, benchmarks-regression, research-artifact-retention |

Applying a pack

import {
  aggregateReviusObservations,
  applyReviewPack,
  createDefaultReviewPackRegistry,
  generateTasksMarkdown,
  renderReviewPackResultMarkdown,
} from "@genius-revius/insight-engine";

const aggregate = aggregateReviusObservations({ project, session, observations, consoleEvents });

const registry = createDefaultReviewPackRegistry();
const pack = registry.get("review-production")!;
const result = applyReviewPack(pack, aggregate);

// Standalone markdown report (used by `revius pack apply` and the MCP server)
const report = renderReviewPackResultMarkdown(result);

// Or include the findings in the generated tasks.md / prompts.md
const tasksMarkdown = generateTasksMarkdown(aggregate, { packResults: [result] });

Defining a custom pack

import { defineReviewPack, applyReviewPack } from "@genius-revius/insight-engine";

const myPack = defineReviewPack({
  id: "review-accessibility",
  name: "Review Accessibility",
  version: "0.1.0",
  description: "A11y checklist applied to review sessions.",
  checks: [
    {
      id: "a11y-focus-visible",
      category: "keyboard",
      severity: "high",
      description: "Interactive elements have a visible focus state.",
      evidenceHints: ["focus", "keyboard", "tab order"],
      remediation: "Add :focus-visible styles to all interactive elements.",
    },
  ],
});

// Custom evaluators override the default evidence-hint engine per check id.
const result = applyReviewPack(myPack, aggregate, {
  evaluators: {
    "a11y-focus-visible": ({ matchedEvidence }) =>
      matchedEvidence.length === 0
        ? { status: "not-applicable", justification: "No keyboard flows in this session." }
        : { status: "fail", justification: "Focus issues observed.", evidence: matchedEvidence },
  },
});

Where packs surface

• Insight generation -- add "reviewPacks": ["review-production"] to .revius/config.json; when a session is stopped, tasks.md and prompts.md include the pack findings.
• CLI -- revius pack list and revius pack apply --session <id> [--pack <id>] (writes .revius/artifacts/<sessionId>/pack-<packId>.md).
• MCP -- the revius_pack_list and revius_pack_apply tools expose the same reports to Claude Code sessions.

Review Packet

The Review Packet is the structured, sellable session audit: one object that aggregates session metadata, annotated observations, review-pack findings grouped by severity, prioritized tasks, AI-ready prompts, and an executive summary (verdict + top risks). Its Zod schema lives in @genius-revius/shared (reviewPacketSchema, format version 1.0.0) so every layer validates the same shape.

import {
  aggregateReviusObservations,
  applyReviewPacks,
  buildReviewPacket,
  renderReviewPacketMarkdown,
  renderReviewPacketHtmlSection,
} from "@genius-revius/insight-engine";

const aggregate = aggregateReviusObservations({ project, session, observations });
const packResults = applyReviewPacks(packs, aggregate);

// Pure, schema-validated JSON object
const packet = buildReviewPacket(aggregate, { packResults });

// Three renderings of the same packet
const json = JSON.stringify(packet, null, 2);
const markdown = renderReviewPacketMarkdown(packet);
const htmlSection = renderReviewPacketHtmlSection(packet); // embeddable <section>

Where the packet surfaces

• CLI -- revius packet --session <id> [--pack <id>] writes .revius/artifacts/<sessionId>/packet.{json,md,html}.
• Session insight generation (Shift+G) -- stopping a session also writes <insightId>.packet.json and <insightId>.packet.md alongside the existing tasks.md / prompts.md artifacts.