Findings Schema

{
  "metadata": {
    "scan_id": "<string — shared across all reports in one scan>",
    "repository": "<string — org/repo-name or filesystem path>",
    "generated_at": "<ISO 8601 datetime>",
    "data_sources_used": [
      {
        "source": "<source_code | git_history | github_data | agent_logs | agent_context | context_inventory>",
        "report_file": "<relative path to the source report, e.g. reports/source-code.json>",
        "contributor": "<optional string — username for agent log reports>",
        "tools": "<optional array of strings — agent harnesses represented in this report; only set for source=agent_logs. Allowed values: \"claude_code\", \"cursor\", plus any other harness slug (e.g. \"copilot\", \"gemini_cli\"). Almost always length 1 — a single contributor typically drives one harness per project. The array form is kept for the rare case where one contributor's logs span multiple harnesses.>",
        "findings_contributed": "<number — how many findings this report contributed to>"
      }
    ]
  },

  "context_inventory": "<object — passed through VERBATIM from reports/context-inventory.json (never re-derived). REQUIRED when reports/context-inventory.json exists with a context_inventory block; omit only if the analyzer report is absent. Carries the per-file catalogue rendered by the HTML report's Context Inventory section as a filterable file tree. See skills/analyze-context-inventory/SKILL.md for shape.>",

  "overall_score": {
    "level": "<blocked | constrained | productive>",
    "reasoning": "<string — 1-2 sentences citing the specific finding IDs (e.g. F-001, F-003) that drove the classification>"
  },

  "executive_summary": "<string — short markdown prose, 2–3 sentences (~60 words max), plain-English state of affairs. No APEX category codes (KCG/CAS/SCX/RAF/TCG), no finding IDs (F-001, …), no severity-count tables. Describe the shape of the issues in the reader's own words — not the taxonomy.>",

  "summary": {
    "total_findings": "<number>",
    "by_severity": {
      "critical": 0,
      "high": 0,
      "medium": 0,
      "low": 0
    },
    "by_effort_size": {
      "pebble": 0,
      "stone": 0,
      "rock": 0,
      "boulder": 0
    },
    "top_categories": ["<array of top 2-3 APEX category codes by finding count>"],

    "commit_authors_impacted": {
      "value": "<number — copied from the git-history report's scope.metrics.commit_authors_impacted (distinct authors of the commits cited as evidence)>",
      "total": "<number — copied from the git-history report's scope.metrics.authors_seen (total distinct authors in the analysed window)>"
    },
    "sessions_with_frustration_signals": {
      "value": "<number — sum across all agent-logs reports of scope.metrics.sessions_with_frustration_signals>",
      "total": "<number — sum across all agent-logs reports of scope.metrics.sessions_parsed>"
    }
  },

  "findings": ["<array of Finding objects — see below>"]
}

{
  "id": "F-<NNN>",
  "category": "<KCG | CAS | SCX | RAF | TCG>",
  "subcategory": "<e.g., KCG-1, CAS-2>",
  "title": "<string — short, specific, descriptive>",
  "description": "<string — 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>",
      "source": "<source_code | git_history | github_data | agent_logs | agent_context | context_inventory>"
    }
  ],

  "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>"
  },

  "priority_score": "<number — impact.score / effort.score, higher is better>",
  "confidence": "<high | medium | low>",
  "data_sources": ["<array of source identifiers that contributed to this finding>"],

  "action": {
    "title": "<string — concise imperative description of what to do>",
    "description": "<string — detailed explanation of the action and why it helps>",
    "type": "<create_context | update_code | add_skill | add_rule | refactor | add_tests | add_docs | configure_tools | create_plugin | update_plugin | remove_plugin>",
    "effort_size": "<pebble | stone | rock | boulder>",
    "example_fix": "<optional string — concrete example of what the fix looks like>"
  }
}