codeprobe-interpret

name

codeprobe-interpret

description

Interpret `.codeprobe/scan.sarif` and produce a layered human-readable findings report (Layer 1 dashboard, Layer 2 source explanations, Layer 3 execution flow risk, Layer 4 remediation previews). Use when the user asks to 'interpret scan', 'explain findings', or 'what did the scan find'. DO NOT use when `.codeprobe/scan.sarif` is absent — run codeprobe-probe or `uv run codeprobe scan .` first. DO NOT use for running the scan itself — this skill only reads existing artifacts.

Interpret Codeprobe Scan Results

Analyze .codeprobe/scan.sarif (merged SARIF v2.1.0) and produce a layered findings report. The report uses progressive disclosure: static dashboard first, then source-level explanations, then graph-informed execution flow analysis, then remediation code.

Data Sources

Read .codeprobe/scan.sarif (required), then check for supplementary data:

• .codeprobe/heuristic_summary.json -- enriched index metrics (volume, health, git, complexity, gitnexus)
• .codeprobe/git_hotspots.json -- git churn data for hotspot cross-referencing
• GitNexus MCP tools -- structural context (blast radius, execution flows, communities)

For schema details, field descriptions, and GitNexus query scenarios, consult references/data-sources.md.

Analysis Procedure

1. Parse SARIF and Count Findings

Read .codeprobe/scan.sarif. Count findings grouped by:

• Tool: run.tool.driver.name
• Severity: error, warning, note per tool
• Category: lint (ruff), typecheck (ty), sast (semgrep, bandit), secrets (betterleaks), deps (osv), complexity (radon), dead-code (vulture), graph (gitnexus)

2. Read Supplementary Data

If .codeprobe/heuristic_summary.json exists, read for volume context, pre-computed health metrics, git signals, complexity rankings, and GitNexus structural metadata.

If .codeprobe/git_hotspots.json exists, read for churn data. Files appearing in both SARIF results AND git hotspots are risk hotspots (high churn + many findings = high regression risk).

3. Identify Critical Findings

Select the top 10 most critical findings, prioritized by:

1. error level findings (always included)
2. Security findings from semgrep/bandit (SAST)
3. Secrets findings from betterleaks
4. Dependency vulnerabilities from osv
5. Type errors from ty
6. High-complexity functions (radon complexity > 10)

4. Generate Structural Context (if GitNexus available)

For files with the most findings, check blast radius using mcp__gitnexus__impact with direction: "upstream". A file with 5 findings AND 30 upstream dependents is far more critical than one with 5 findings and 0 dependents.

Report Format — Progressive Disclosure

The report has four depth layers. A static tool can produce Layer 1. Only an agentic AI can produce Layers 2-4 because they require reading source code, querying the knowledge graph, and synthesizing narrative.

For all layer templates, examples, and output format, consult references/report-templates.md.

Layer Gating Rules

Layer	Name	Always Produce?	What the Agent Does
1	Dashboard	Yes	Count findings, build tables, cross-reference hotspots
2	Deep Finding Analysis	Yes	Read source at each critical finding location, explain what the code does, why it was flagged, what breaks
3	Execution Flow Risk	When GitNexus available + security/complexity/type findings	Query graph for execution flows, trace call chains from entry points to vulnerable code, compute severity amplifiers
4	Remediation Previews	Auto-produce Layer 4 for the top 3 findings that are BOTH (a) error-level AND (b) in files with blast_radius >= 20 (per GitNexus impact). For findings not matching both criteria, produce Layer 4 only when the user explicitly requests remediation.	Read full function, draft minimal before/after fix, check caller impact via graph

Layer Descriptions

Layer 1 — Dashboard: Executive summary, findings table by tool/category/severity, risk hotspots table. This is the "at a glance" view.

Layer 2 — Deep Finding Analysis: For each critical finding, read the actual source file at the reported line (~10 lines of context). Explain: (1) what the code does, (2) why the scanner flagged it, (3) what could go wrong — concrete consequence, not abstract risk. This is what separates an agent from a SARIF pretty-printer.

Layer 2 source quotes: 8-12 lines centered on the finding location, never more than 30 lines. Quote bounds must include enough context to explain the finding without drowning the report.

Layer 3 — Execution Flow Risk: For the riskiest findings, trace execution flows via GitNexus. Show which entry points reach the vulnerable code, the call chain from entry to finding, blast radius of upstream dependents, and a severity amplifier based on whether the path is public-facing or internal. Skip for low-severity lint issues.

Layer 4 — Remediation Previews: For highest-priority findings with clear mechanical fixes, draft before/after code. If the fix changes a function signature, check mcp__gitnexus__impact to identify callers needing updates. Skip for architectural issues (complexity reduction) — describe the decomposition strategy instead.

Semantic Observations (Opportunistic)

While reading code in Layers 2-3, watch for patterns no scanner can detect:

• Impedance mismatch — incompatible assumptions at module boundaries (type narrowing, serialization format, null handling, unit disagreements). Graph community edges are hotspots.
• Implicit invariants — unchecked assumptions (non-empty lists, sorted input, initialized state). High fan-in functions are highest-value targets — more callers = more chances for violated assumptions.
• Business logic vs. infrastructure — classify code at each finding location. Adjust priority: a warning in core billing logic outranks an error in a dev utility. Structural signals: high fan-in (core domain), high fan-out (orchestrator), decision density (business rules).

Do not force this on every finding. Apply when code reading naturally reveals these patterns. For detection strategies, caller audit templates, and severity adjustment guidance, consult references/semantic-analysis.md.

Closing

After all layers, close with a prioritized punch list of recommended actions, ordered by:

1. Security findings on reachable execution flows (Layer 3 informed)
2. Type/correctness errors in high-blast-radius code (Layer 2 + graph)
3. Complexity hotspots with high churn (Layer 1 cross-reference)
4. Dead code and style cleanup (Layer 1 only)

Each action should reference which layer provided the evidence.

Reference Files

• references/data-sources.md -- SARIF schema, heuristic_summary.json schema, git_hotspots.json schema, GitNexus MCP tool reference and query scenarios
• references/report-templates.md -- Output templates for all four layers with examples and "when to skip" guidance
• references/semantic-analysis.md -- Impedance mismatch detection, implicit invariant analysis, business logic classification with caller audit templates and severity adjustment

Pydantic Output Models

The report structure aligns with models in src/codeprobe/models/output.py:

• RiskProfile -- overall risk level with per-area profiles
• AreaRiskProfile -- per-area risk with blast_radius, churn_rank, complexity_score, review_recommendation
• CodeHealthMetrics -- duplication_percentage, unused_symbol_count, code_smell_count
• ArchitecturalRisk -- description, severity, location, mitigation
• ChangeVerdict -- verdict tier (auto_merge/single_review/dual_review/expert_review/block) with signals

Acceptance

Success = the report renders Layer 1 + Layer 2 at minimum; Layer 3 fires when GitNexus is available and security/complexity/type findings are present; Layer 4 fires for the top 3 findings that are both error-level and in files with blast_radius >= 20 (or when the user explicitly requests remediation); every Layer 2 source quote is 8-12 lines (30 max) centered on the finding location; and the closing punch list references which layer provided each recommendation.