Audit — ROI Prioritization

When to use

• The user wants findings grouped into priority bands (P0/P1/P2/P3) or asks which findings are critical versus deferrable.
• The audit has produced findings and the user wants them prioritized or ranked by return on investment rather than left as an unordered list.
• The user asks how to score findings by ROI or how to weigh impact, severity, confidence, and effort against each other (приоритезация по ROI).

When NOT to use

• Do not prioritize before findings exist; run the domain scans and collect evidence-backed findings first, then rank them.
• Do not run the ranking model for a single known issue; ranking a list of one adds ceremony without changing the order.

Core guidance

• Keep effort at a minimum of 1 to avoid divide-by-zero — Effort is always at least 1. A finding with genuinely trivial effort scores effort 1, never 0, so the ROI division stays finite and rankings stay stable.
• Score every finding with the ROI formula — Compute roi_score = (impact * severity * confidence) / effort for each finding. Reward high impact, high severity, and high confidence; divide by effort so cheap fixes rise. Round to one decimal for stable, comparable numbers.
• Use fixed 1-5 scales and a 0.5-1.0 confidence band — Score impact, severity, and effort on a 1-5 scale and confidence on a 0.5-1.0 band. Confidence never drops below 0.5, because a finding you would not stand behind at all should not be recorded.
• Break ties deterministically, severity first — When two findings share an ROI score, break the tie in this order — higher severity, then higher impact, then lower effort, then higher confidence, then finding id. The chain ends on the id so the ranking is fully deterministic.

Decision Engine

Walk this section before choosing an implementation path.

Is the finding a severity-5 security issue, and if not, how does its computed ROI
score compare to the band thresholds?

├── severity-5 security or highest ROI: → P0 band — fix now. Any severity-5 security finding, plus the highest-ROI findings,
go here regardless of effort.

├── high ROI, not critical: → P1 band — schedule this cycle. High-ROI findings that are not P0 critical belong
here and drive the near-term plan.

└── mid or low ROI: → P2 or P3 band — backlog. Mid-ROI findings land in P2 for the backlog; low-ROI,
cosmetic, or low-confidence findings land in P3 as nice-to-have.

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

Workflows

Workflow: Assign Bands

Progress:
- [ ] Walk the sorted list top-down and assign P0/P1/P2/P3 by ROI, then apply the security
override so any severity-5 security finding is promoted to P0
- [ ] Emit the roi-ranked artifact — findings in ROI order, each showing its four inputs,
computed score, band, and evidence pointer — as the input the report stage consumes

1. Walk the sorted list top-down and assign P0/P1/P2/P3 by ROI, then apply the security override so any severity-5 security finding is promoted to P0.
   • Verify: Every finding has a band and no severity-5 security finding sits below P0.
2. Emit the roi-ranked artifact — findings in ROI order, each showing its four inputs, computed score, band, and evidence pointer — as the input the report stage consumes.
   • Verify: The output is ROI-ordered, each row shows its math and band, and it hands off cleanly.

Workflow: Score Findings

Progress:
- [ ] For every finding assign impact (1-5), severity (1-5), effort (1-5, floor 1), and
confidence (0.5-1.0), anchoring each to concrete evidence rather than a hunch
- [ ] Compute roi = (impact * severity * confidence) / effort, round to one decimal, and
sort descending, breaking ties by severity, impact, lower effort, confidence, id

1. For every finding assign impact (1-5), severity (1-5), effort (1-5, floor 1), and confidence (0.5-1.0), anchoring each to concrete evidence rather than a hunch.
   • Verify: Each finding has four in-range inputs and each cites what justifies it.
2. Compute roi = (impact * severity * confidence) / effort, round to one decimal, and sort descending, breaking ties by severity, impact, lower effort, confidence, id.
   • Verify: The list is sorted by ROI and re-running it yields the identical order.

Best practices

• After ranking, assign bands — P0 for critical, high-ROI findings to fix now, P1 for high value this cycle, P2 for the backlog, P3 for nice-to-have
• Print the four inputs and the computed roi_score next to each finding so a reviewer can recompute it, for example (impact 4 * severity 5 * confidence 0.9) / effort 2

Anti-patterns

See references/anti-patterns.md.

Debugging

1. Ranking speculative findings as if they were certain — Confidence is the term that keeps unproven findings from dominating the plan. Fix: Set confidence to reflect the evidence strength (0.5 for a hunch, 0.9+ for a proven pattern) and drop anything you cannot justify at 0.5.
2. Guessing effort with no basis inverts the ranking — Effort sits in the denominator, so a wrong effort swings ROI more than any other input. Fix: Anchor effort to a concrete size (files touched, tests needed, review risk) and keep the 1-5 scale consistent across all findings.
3. Letting a costly critical sink below cheap wins — Raw ROI optimizes for cheap value and can rank away an exploitable, business-ending risk. Fix: Apply the security override so every severity-5 security finding jumps to P0 no matter what its computed ROI is.

Production checklist

• Every finding carries a P0-P3 band and every severity-5 security finding is forced to P0 regardless of raw ROI.
• Every finding is scored with roi = (impact times severity times confidence) divided by effort, not by gut feel.
• Each ranked finding shows its four inputs and computed roi_score so a reviewer can recompute and challenge it.
• Impact, severity, and effort are each 1-5, effort is never below 1, and confidence stays in the 0.5-1.0 band.
• Equal ROI scores are ordered by the severity-first tie chain ending on finding id, so the ranking is reproducible.

Version notes

• Scoring model is language-version independent — The ROI model itself is independent of the PHP version, but the severity you assign a finding often is not — a deprecation is severity-2 on PHP 7.4 yet severity-4 once the project moves to 8.x, so rescore severity against the resolved runtime.

Security

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

Testing

• Activation and decision behavior are verified in eval/scenarios/audit/roi-prioritization.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

Related: audit/project-analysis

Skill contract

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