| name | findings-diff |
| description | Compare two lean-findings.json files for the same subject across time and report real progress deltas — findings resolved, new, persisting, and severity shifts. Use this skill whenever the user asks "did we improve", "compare this audit to the last one", wants progress since a previous audit, or re-runs an audit on a subject that already has a findings file. Part of Lean Agentic AI Skills; a transformer — emits a diff report plus a merged findings file with status annotations. |
Findings Diff
Transformer skill — the suite's progress engine. Input: two findings files for the same subject.identifier (baseline and current). Output: a diff summary + an annotated findings file consumers can render.
This is the one place the module produces legitimate quantitative progress claims: counts of findings resolved, introduced, and persisting between two dated audits are real, countable deltas — no estimation involved.
Procedure
- Validate comparability. Same subject identifier and same producer skill(s); if the audits' methodologies differ materially (different scope, different fetch depth), say so up front — a "resolved" finding that merely fell out of scope is not progress. Scope changes go in the diff report's caveats, always.
- Match findings by
id. IDs are stable slugs by contract. For unmatched-but-similar pairs (same location + same pattern URL, different id), list as "probably renamed" for human confirmation rather than auto-matching.
- Classify every finding:
- Resolved — in baseline, not in current (and still in scope).
- New — in current, not in baseline.
- Persisting — in both; note severity or evidence changes.
- Out-of-scope shift — in baseline, but current audit couldn't assess the area. NOT counted as resolved.
- Report — a short summary table (resolved/new/persisting by severity), the honest headline ("3 high-severity findings resolved, 1 new medium introduced"), notable evidence changes on persisting items (e.g. image count dropped from 11 to 4 — partial progress is progress), and
passed items gained or lost.
- Emit the annotated current findings file with a
status field per finding so lean-dashboard's trend view and lean-report-writer's progress section can consume it directly.
Honesty rules
Resolved counts are only claimable when scope held constant — the caveat mechanism above is not optional. Never extrapolate deltas into energy/carbon savings; the honest sentence is "N findings resolved; measured impact requires before/after instrumentation." A regression (new highs) is reported as prominently as progress.
Not this skill's job
Producing findings (any producer), rendering the trend UI (lean-dashboard), gating builds on regressions (lean-regression-gate).
