/**
 * Score-explainer — the deterministic WHY behind a low measured score (C4 of the
 * measurement-authority pivot; the strongest pairing in it).
 *
 * The MEASUREMENT layer finds a behavioral SYMPTOM: "this skill underperforms",
 * "the wrong skill fires", "this agent fails its task". A behavioral symptom alone
 * is not actionable — you can drop the skill, but you don't know WHY it lost. The
 * cross-reference engine (the linting layer) already detects the deterministic
 * CAUSES: two skills with near-identical descriptions can't be told apart by the
 * selector; a never-available / typo'd tool is silently dropped from a subagent; a
 * hook on a misspelled event never fires. This module BRIDGES the two: given the
 * `ScanReport` the linter already computes, it surfaces — per affected surface —
 * the deterministic cause of a behavioral symptom and the one-line fix.
 *
 *   Measurement says   "caveman underperforms"
 *   the explainer says "...BECAUSE its description overlaps `compress` (0.86) —
 *                       differentiate them so the selector can disambiguate."
 *
 * It REUSES the scan findings (one-detector-no-drift) — it never re-detects. So
 * it's pure over a `ScanReport`, free, model-less, and consistent with `vigiles
 * lint`/`scan`. It's the diagnostic the per-repo optimizer (`vigiles optimize`,
 * A2) prints next to each "drop / swap" recommendation. See
 * `research/measurement-authority.md` ("what becomes of the linting", role 2).
 */
import type { ScanReport } from "./scan.js";
/**
 * The behavioral failure a MEASUREMENT would observe — the symptom an explanation
 * accounts for. Discriminated so a consumer can group/filter by symptom and so an
 * explanation can never carry a symptom it has no cause for.
 */
export type BehavioralSymptom = "wrong-skill-fires" | "skill-never-fires" | "agent-underperforms" | "hook-never-runs" | "subagent-never-dispatches";
/**
 * How firmly the deterministic finding EXPLAINS the symptom:
 * - `"likely"` — a hard structural dead-end (a missing script can't run, a
 *   never-available tool can't be called); the cause is near-certain.
 * - `"possible"` — a high-precision PROXY for a behavioral risk (a description
 *   overlap / a foreign-script description); deterministic to detect, but whether
 *   it actually moved behaviour is confirmed by the `audit` trigger tier.
 */
export type ExplanationConfidence = "likely" | "possible";
export interface ScoreExplanation {
    /** The affected surface (a skill/agent/hook name or path) the symptom attaches to. */
    readonly surface: string;
    /** What a measurement would SEE. */
    readonly symptom: BehavioralSymptom;
    /** The deterministic finding (the scan/lint detector's own message — no drift). */
    readonly cause: string;
    /** The lint rule that found it, so a reader can open `docs/rules/<detector>.md`. */
    readonly detector: string;
    /** A single, actionable fix. */
    readonly fix: string;
    readonly confidence: ExplanationConfidence;
}
/**
 * Explain every behavioral symptom the report's deterministic findings account
 * for. Returns one `ScoreExplanation` per finding, `"likely"` causes first (a hard
 * dead-end is more certain than a proxy). Pure over the report.
 */
export declare function explainScore(report: ScanReport): ScoreExplanation[];
/**
 * The explanations that attach to ONE underperforming surface — the call the
 * benchmark/optimizer makes when a measurement flags a single skill/agent. Matches
 * a surface name case-insensitively, including the `"a ↔ b"` overlap pairs (so
 * explaining "caveman" surfaces an overlap with another skill).
 */
export declare function explainSurface(report: ScanReport, surface: string): ScoreExplanation[];
/** Render explanations for a CLI/report — grouped under the symptom, fix called out. */
export declare function formatExplanations(exps: readonly ScoreExplanation[]): string;
//# sourceMappingURL=score-explainer.d.ts.map