Audit — Findings Report

When to use

• The user wants each reported finding to carry its evidence path and a concrete remediation so the report is actionable, not just a list of complaints.
• The findings are ranked and the user wants the audit written up as a shareable report or deliverable, not left as a raw ranked list.
• The user asks for the Top 20 findings by ROI, a quick-wins list, or a strategic backlog view of the audit (топ проблем, быстрые победы).

When NOT to use

• Do not build the full report format when the user only wants a single fix implemented; apply the change instead of producing a deliverable.
• Do not format the report before findings are ROI-scored and ranked; run the prioritization step first, then render the sections.

Core guidance

• Every row shows its evidence path — Each reported finding shows an evidence column with a path:line pointer. A finding with no evidence is dropped from the report, never rendered — a finding without evidence is not a finding.
• Preserve the ranked order the model produced — Render findings in exactly the roi-ranked order the prioritization step produced; the report is a view, not a re-ranking, so it must not silently reorder or re-score.
• Link each finding to a concrete remediation — Every finding carries a remediation — a specific fix, and where a matching skill exists, a link to it (for example the sql-injection-prevention skill for an injection finding) so the reader can act immediately.
• Render the three canonical sections — Every audit report has three sections — Top 20 by ROI, Quick wins (effort <= 2), and Strategic (effort >= 4). Top 20 is the headline ranking; the other two are effort cuts of the same ranked list, so a finding can appear in Top 20 and a cut.

Decision Engine

Walk this section before choosing an implementation path.

Is the finding among the highest ROI, and what is its effort — trivial (<= 2), heavy
(>= 4), or in between?

├── effort <= 2: → Quick wins list — any finding with effort <= 2 goes here, regardless of ROI rank, so
a team can knock out cheap value immediately.

├── effort >= 4: → Strategic backlog — any finding with effort >= 4 goes here so planners can size and
schedule the large, cross-cutting work separately from quick fixes.

└── among the top 20 by ROI: → Top 20 by ROI table — render the finding with its full schema row; it may also
appear in a Quick wins or Strategic cut depending on its effort.

Full engine: references/decision-engine.md — Decision Tree, Priority Matrix, Decision Table.

Workflows

Workflow: Effort Cuts

Progress:
- [ ] From the same ranked list, derive the Quick wins list (effort <= 2) and the
Strategic backlog (effort >= 4), cross-listing findings that qualify for both a cut
and the Top 20
- [ ] Give every row a remediation, linking a matching skill where one exists and an
explicit next step where none does, then emit the report as the audit.report artifact

1. From the same ranked list, derive the Quick wins list (effort <= 2) and the Strategic backlog (effort >= 4), cross-listing findings that qualify for both a cut and the Top 20.
   • Verify: Quick wins holds only effort-2-or-less rows and Strategic holds only effort-4-or-more rows.
2. Give every row a remediation, linking a matching skill where one exists and an explicit next step where none does, then emit the report as the audit.report artifact.
   • Verify: No row has an empty remediation cell and the finished report is emitted.

Workflow: Render Report

Progress:
- [ ] Drop any finding lacking an evidence pointer, then write the summary header — total
findings, counts per P0-P3 band, and the single highest-ROI item
- [ ] Render the Top 20 by ROI as a table with the full schema columns (id, title, domain,
severity, impact, effort, confidence, roi_score, evidence, remediation) in ranked
order

1. Drop any finding lacking an evidence pointer, then write the summary header — total findings, counts per P0-P3 band, and the single highest-ROI item.
   • Verify: Only evidence-backed findings remain and the report opens with a one-screen summary.
2. Render the Top 20 by ROI as a table with the full schema columns (id, title, domain, severity, impact, effort, confidence, roi_score, evidence, remediation) in ranked order.
   • Verify: The Top 20 table is ROI-sorted with one finding per row and no empty cells.

Best practices

• The Top 20 table shows id, title, domain, severity, impact, effort, confidence, roi_score, evidence, and remediation, one finding per row, sorted by roi_score descending, so the ranking and its justification are visible together
• Lead the report with a one-screen summary — total findings, counts by P0/P1/P2/P3 band, and the single highest-ROI item — before the tables, so a reader gets the headline without scrolling

Anti-patterns

See references/anti-patterns.md.

Debugging

1. Rendering findings without their evidence path — An evidence-less row is unverifiable and erodes trust in the whole report. Fix: Keep the evidence column non-negotiable; if space is tight, shorten titles or move detail to an appendix, never remove the path:line pointer.
2. Padding the Top 20 with filler findings — Filler dilutes the signal and trains readers to distrust the ranking. Fix: Show only real findings; rename the section Top findings by ROI when there are fewer than 20 and leave it at that.
3. Quietly re-ranking findings in the report — A hand-reordered report breaks the reproducible link to the ROI model and reintroduces bias. Fix: Render strictly in the roi-ranked order; if the order looks wrong, fix the scores in the prioritization step and re-run, do not edit the report.

Production checklist

• No row is rendered without a path or path-and-line evidence pointer, and evidence-less findings are dropped and logged.
• Findings appear in the exact roi-ranked order from the prioritization step; the report does not re-rank or re-score.
• Each finding carries a remediation or an explicit next step, and links to a matching remediation skill where one exists.
• The report contains a Top 20 by ROI table, a Quick wins list (effort 2 or less), and a Strategic backlog (effort 4 or more).
• The report opens with a one-screen summary of total findings, band counts, and the top item before any table.

Version notes

• Report format is version independent — The three-section report shape is independent of the PHP version, but the remediation links are not — link to the version-appropriate remediation skill (for example the php80 migration skill only when the target runtime is 8.0+).

Security

• Not applicable — no I/O, auth, or untrusted input.

Testing

• Activation and decision behavior are verified in eval/scenarios/audit/findings-report.yaml.

Additional resources

• references/anti-patterns.md
• references/core.md
• references/decision-engine.md
• references/examples.md
• references/pitfalls.md
• references/recipes.md
• references/version-differences.md

Knowledge graph

Prerequisites: audit/roi-prioritization
Related: audit/project-analysis

Skill contract

Produces: audit.report
Requires: audit.roi-ranked
Risk: low · Confidence: 0.9