Agent Discussion Formatter

Overview

When multiple specialist agents contribute opinions, findings, or recommendations, raw text output becomes unreadable. This skill defines a structured terminal format that makes agent debates scannable, severity-aware, and action-oriented.

Core principle: Every agent contribution must be visually distinct, severity-tagged, and traceable to evidence.

Iron Law:

NEVER MIX AGENT OUTPUTS INTO UNSTRUCTURED PROSE — ALWAYS USE THE BOX FORMAT

When to Use

• Rendering output from parallel specialist agents (security, accessibility, performance, etc.)
• Displaying code review findings from multiple reviewers
• Presenting debate/discussion between agents with differing opinions
• Summarizing consensus or disagreement across agent recommendations
• EVAL mode consolidated output

Use this ESPECIALLY when:

• 3+ agents contribute findings on the same topic
• Agents disagree and the user needs to see both sides
• Severity levels vary across findings

When NOT to Use

• Single agent output (no debate to format)
• Non-terminal output (HTML, JSON API responses)
• Log-style sequential output where ordering matters more than structure

Format Specification

Agent Contribution Block

Each agent's finding is rendered in a box with metadata:

┌─ {emoji} {agent-name} ─────────────────────────┐
│ {SEVERITY} [{LEVEL}]: {title}                   │
│ {description spanning multiple lines with       │
│ proper indentation and wrapping}                 │
│                                                  │
│ Evidence: {file:line — code or observation}       │
│ Recommendation: {actionable next step}           │
└──────────────────────────────────────────────────┘

Agent Identifiers

Each agent type has a fixed emoji prefix for visual scanning:

Severity Badges

Severity levels with visual indicators:

Example: Single Finding

┌─ 🔒 security-specialist ──────────────────────────┐
│ 🟠 HIGH: SQL injection risk in user input handling │
│                                                     │
│ Raw string concatenation used to build SQL query    │
│ without parameterization. User-controlled input     │
│ flows directly into the query string.               │
│                                                     │
│ Evidence: api/users.ts:42                           │
│   const q = `SELECT * FROM users WHERE id=${input}` │
│ Recommendation: Use parameterized queries           │
│   const q = `SELECT * FROM users WHERE id=$1`       │
└─────────────────────────────────────────────────────┘

Example: Multiple Agents on Same Topic

┌─ 🔒 security-specialist ──────────────────────────┐
│ 🔴 CRITICAL: Unauthenticated endpoint exposed     │
│                                                     │
│ The /api/admin/users endpoint has no auth guard.    │
│ Any client can list all user records including PII. │
│                                                     │
│ Evidence: api/admin/users.ts:12 — no @UseGuards()  │
│ Recommendation: Add AuthGuard and RolesGuard       │
└─────────────────────────────────────────────────────┘

┌─ 📏 code-quality-specialist ───────────────────────┐
│ 🟡 MEDIUM: Missing input validation                │
│                                                     │
│ Query parameters parsed without validation.         │
│ Unexpected types could cause runtime errors.        │
│                                                     │
│ Evidence: api/admin/users.ts:18 — raw req.query     │
│ Recommendation: Add Zod/class-validator schema      │
└─────────────────────────────────────────────────────┘

Consensus & Disagreement

Consensus Indicator

When agents agree, show a consensus block:

╔══════════════════════════════════════════════════════╗
║ ✅ CONSENSUS (3/3 agents agree)                     ║
║                                                      ║
║ Auth guard must be added to /api/admin/* endpoints.  ║
║ Agents: 🔒 security, 📏 code-quality, 🏛️ architecture ║
╠══════════════════════════════════════════════════════╣
║ Priority: CRITICAL — unanimously recommended         ║
╚══════════════════════════════════════════════════════╝

Disagreement Indicator

When agents disagree, show the split:

╔══════════════════════════════════════════════════════╗
║ ⚖️ SPLIT OPINION (2 vs 1)                           ║
║                                                      ║
║ Topic: Should we add request-level caching?          ║
║                                                      ║
║ FOR (2):                                             ║
║   ⚡ performance — reduces DB load by ~40%           ║
║   🏛️ architecture — fits existing cache layer        ║
║                                                      ║
║ AGAINST (1):                                         ║
║   🔒 security — cache invalidation risks stale       ║
║              auth state for permission changes       ║
║                                                      ║
║ Recommendation: Proceed with cache, add TTL < 60s    ║
╚══════════════════════════════════════════════════════╝

Summary Block

At the end of a multi-agent discussion, render a summary:

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ 📋 DISCUSSION SUMMARY                             ┃
┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
┃ Agents: 4 participated                             ┃
┃ Findings: 7 total                                  ┃
┃   🔴 CRITICAL: 1                                   ┃
┃   🟠 HIGH:     2                                   ┃
┃   🟡 MEDIUM:   3                                   ┃
┃   🟢 LOW:      1                                   ┃
┃ Consensus: 2 items agreed                          ┃
┃ Disputes:  1 split opinion                         ┃
┃                                                    ┃
┃ Action required: Fix 1 CRITICAL + 2 HIGH before    ┃
┃ merge. Review 1 split opinion with team.           ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

Rendering Rules

1. Box width — Adapt to terminal width, minimum 50 characters
2. Text wrapping — Wrap long lines inside box boundaries with proper indentation
3. Ordering — Sort findings by severity: CRITICAL > HIGH > MEDIUM > LOW > INFO
4. Grouping — Group by topic when multiple agents comment on the same code location
5. Deduplication — If two agents report the same issue, merge into one block with both agent names
6. Evidence format — Always include file:line reference when available
7. Spacing — One blank line between agent blocks, two blank lines before consensus/summary blocks