rule_id: decision_maker_peer_comparison_chart
name: Decision-Maker Peer Comparison Chart
type: visualization
domain: all

applies_to:
  agent: visualization
  triggers:
    - recommendation type is "peer_positioning"
    - audience tier is "decision_maker"
    - peer set size between 2 and 10

conditions:
  - all entities have data for all periods being compared
  - statistical context (mean, std dev) is available

action:
  chart_type: horizontal_bar_chart_with_peer_mean_reference_line
  data_binding:
    x_axis: metric_value
    y_axis: entity_name
    sort_by: value_descending
    reference_line: peer_mean
    annotations:
      - standard_deviation_bands
  color_palette: brand_aligned_neutral
  narrative_wrapper:
    headline_template: "{{entity}} {{position_phrase}} peer mean ({{position_summary}})"
    supporting_template: "{{statistical_context_sentence}}"
    constraints:
      - no_causal_claims
      - quantify_where_possible
  format:
    primary: static_image_png
    secondary: pdf_embed
    fallback: tabular_summary

disclosure_policy:
  audience_clearance_check: required
  default_allowed_tiers:
    - decision_maker
    - internal_partner
  default_restricted_tiers:
    - external_unverified

confidence_framework:
  base_confidence: inherited from upstream recommendation confidence
  adjustments:
    - if rendering fidelity check passes -> no adjustment
    - if any narrative template token cannot be filled from inputs -> subtract 0.10

rationale: |
  Decision-maker audiences need quick visual interpretation. Horizontal bar charts with
  reference lines communicate peer position more effectively than tables or line charts
  for this tier. The narrative wrapper provides context without overclaiming. SMEs
  encode tier mappings for their organization (e.g., what "decision_maker" means in
  their context — board, C-suite, partner committee, etc.) and add variants for other
  tiers (analyst, manager, external client).

  Audience tiers are intentionally generic. The framework supports any tier set the
  SME-encoded mapping defines. Common tiers include: decision_maker, manager,
  analyst, external. Specific role-to-tier mappings live in the organization's
  encoded audience-tier configuration, not in the framework or the rule itself.

declared_by: framework_foundation
declared_date: 2026-05-26
last_reviewed: 2026-05-26
status: active

notes: |
  Rendering itself is the responsibility of a downstream renderer; this rule produces
  the visual specification (chart kind, data binding, narrative wrapper, format).
  The Visualization agent does not embed a charting library — keeping the framework
  channel-and-render agnostic, same architectural pattern as the channel adapter
  registry in src/decision/channel-registry.ts.