methodology_id: peer_positioning_narrative
name: Peer Positioning Narrative Framework
type: insight_framework
domain: all

applies_to:
  agent: insight_synthesis
  triggers:
    - input contains peer comparison outputs
    - comparison method involved was peer benchmarking
    - business context requests entity positioning insights

definition:
  insight_construction_rules:
    - For each entity in the peer set, generate exactly one positioning claim
    - Each claim describes the entity's position relative to the peer set's central tendency
    - Position is expressed in standard deviation distance from peer mean, AND in plain language
    - Claims are factual statements about position; they do not assert causation
    - Outliers (>1.5 std dev from mean) are explicitly identified as such
    - Median performers (within 0.5 std dev) are explicitly identified as in-line with peers

  evidence_citation_rules:
    - Every claim cites the specific comparison_output_id it draws from
    - Every claim cites the underlying metric_id and metric_value
    - Every claim cites the peer set composition (which entities, which period)
    - Claims without citable evidence are removed before output (Standard 4)

  language_constraints:
    - Use neutral, descriptive language; avoid evaluative terms like "strong" or "weak"
    - Quantify wherever possible (specific values, specific differences)
    - Acknowledge statistical noise where dispersion is high
    - Do not extrapolate beyond what the comparison shows

  output_structure:
    - One insight object per entity
    - Each insight contains claim, supporting_evidence array, confidence_score, and statistical_context

inputs:
  - source: comparisons_synthesis_output
    field: comparisons
    required: true
  - source: job_request
    field: business_context
    required: false

outputs:
  - insights of type peer_positioning_insights, with per-entity structure containing claim, evidence_citations, statistical_context, confidence, and a summary containing peer_mean, peer_std_dev, outlier_count, in_line_count

rationale: |
  This is the framework's foundational methodology for converting peer comparison output into
  evidence-cited narrative claims. It enforces narrative-data fidelity (Standard 4 applied to
  qualitative output) by requiring every claim to cite its supporting comparison and metric.

  The methodology is intentionally neutral - it produces factual positioning statements, not
  evaluative or causal claims. It does not interpret "why" an entity is positioned where it
  is, only "where" it is positioned relative to peers, and with what evidence.

  Domain SMEs should encode more specific insight frameworks for cases where domain
  conventions, evaluative norms, or interpretive context matter (e.g., banking-specific
  performance framing, insurance-specific underwriting context). When a more specific
  framework applies, the agent will select that one over this default.

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

notes: |
  Foundational methodology. Provides a neutral, evidence-cited narrative framework for cases
  where no domain-specific insight methodology has been encoded. SMEs should encode richer
  frameworks for their domains; this default applies only when nothing more specific matches.

  Notable: this methodology intentionally avoids causal or evaluative claims. Statements like
  "Bank X outperforms because of strategy Y" are out of scope. Causal interpretation is a
  separate analytical task requiring domain expertise and additional evidence.