Insight Report Schema

{
  "metadata": {
    "scan_id": "<string — shared across all reports in one scan run>",
    "data_source": "<source_code | git_history | github_data | agent_logs | agent_context | context_inventory>",
    "repository": "<string — org/repo-name or filesystem path>",
    "analysis_timestamp": "<ISO 8601 datetime>",
    "analyzer_model": "<string — model identifier>",
    "scope": {
      "description": "<string — what was analyzed, sampling strategy used, and any limitations>",
      "metrics": {},
      "time_range": "<optional string — date range for temporal data sources>"
    }
  },

  "context_inventory": "<optional object — only the `analyze-context-inventory` report includes this; see that skill's SKILL.md for shape>",

  "executive_summary": "<string — 2-3 paragraphs covering: what was analyzed and the most significant findings>",

  "summary_statistics": {
    "total_insights": "<number>",
    "by_category": {
      "KCG": 0, "CAS": 0, "SCX": 0, "RAF": 0, "TCG": 0
    },
    "by_impact": {
      "critical": 0, "high": 0, "medium": 0, "low": 0
    },
    "by_effort": {
      "trivial": 0, "low": 0, "medium": 0, "high": 0
    },
    "top_quick_wins": ["<array of insight IDs with highest priority_score>"]
  },

  "insights": ["<array of Insight objects — see below>"]
}

{
  "id": "<PREFIX-NNN>",
  "category": "<KCG | CAS | SCX | RAF | TCG>",
  "subcategory": "<e.g., KCG-1, CAS-2>",
  "title": "<string — short, specific, descriptive>",
  "description": "<string — detailed explanation: what the issue is, why it matters for agent performance, and how it manifests>",

  "evidence": [
    {
      "type": "<file_reference | code_snippet | git_log | pr_comment | ci_output | agent_conversation | config_file | review_comment | statistical>",
      "location": "<string — file path, PR URL/number, commit SHA, session ID, etc.>",
      "detail": "<string — what this evidence shows>",
      "snippet": "<optional string — relevant code or text excerpt>"
    }
  ],

  "impact": {
    "score": "<1-10 integer>",
    "level": "<critical | high | medium | low>",
    "reasoning": "<string — why this score: frequency, blast radius, severity>"
  },

  "effort": {
    "score": "<1-10 integer (1 = trivial, 10 = massive rewrite)>",
    "level": "<trivial | low | medium | high>",
    "reasoning": "<string — what the fix involves and roughly how long it would take>"
  },

  "priority_score": "<number — impact.score / effort.score, higher is better>",

  "affected_areas": ["<array of file paths or directory patterns>"],
  "confidence": "<high | medium | low>",
  "data_source_exclusive": "<boolean — could this insight ONLY have been discovered from this data source?>"
}