consensus-tools explain

Fetch a plain-language narrative for a guard decision from an audit ID.

Usage

consensus-tools explain <auditId> [--verbose]

explain retrieves a guard decision from the audit log and generates a plain-language narrative describing why the decision was made. Requires an LLM API key.

Options

OptionDescription
<auditId>The audit event ID (e.g. audit_abc123)
--verbosePrint the raw LLM prompt to stderr (for debugging)

Prerequisites

Set one of the following environment variables before running:

export ANTHROPIC_API_KEY=sk-ant-...
# or
export OPENAI_API_KEY=sk-...

Examples

# Explain a decision in plain language
consensus-tools explain audit_abc123

# Include full vote breakdown
consensus-tools explain audit_abc123 --verbose

Example output

Decision: BLOCK
Confidence: 0.92

Summary: The code merge was blocked because two of three reviewers flagged a SQL
injection vulnerability in the user input handling at src/db/query.ts:47. The
security reviewer assigned a score of 0.1 and the compliance reviewer assigned 0.2,
pulling the aggregate below the ALLOW threshold of 0.7.

Reviewers:
  security-reviewer  → score 0.10  (SQL injection risk in raw string interpolation)
  compliance-reviewer → score 0.20  (violates input sanitization policy CT-402)
  quality-reviewer   → score 0.85  (logic is correct, no structural issues)

With --verbose, the full artifact JSON is appended after the narrative.

Related

Previous←policy keysNextaudit→