[DOCS] WAF results operator guide — interpreting scores, roadmap, Advisor integration, and remediation workflow

[kristopherjturner]

Summary

Issue #268 covers the WAF rule engine reference (calculations, thresholds, priority scoring, authoring custom rules, full rule catalog). This issue covers the complementary operator-facing guide: how to read, understand, and act on WAF results that Ranger produces.

Operators receiving a Ranger package today have no documentation explaining:

• what their WAF score means in plain English
• why there are two data sources (manifest rule engine + Azure Advisor) and how they relate
• how the compliance roadmap Now/Next/Later buckets were calculated
• how to turn findings into action using Get-RangerRemediation
• what a realistic improvement path looks like (e.g., current 58% to Good with 3 changes)

Proposed file

docs/operator/waf-guide.md

Sections

What Ranger WAF Assessment Covers

• The five pillars: Reliability, Security, Cost Optimization, Operational Excellence, Performance Efficiency
• Two data sources: local manifest rule engine (31 rules evaluated against collected cluster state) and Azure Advisor (live recommendations pulled from the configured subscription)
• How the two sources are separate — manifest rules are deterministic against the collected snapshot; Advisor rules are Azure-sourced and may reflect additional platform context

How to Read Your WAF Score

• Overall score and per-pillar scores: what the percentage means
• Status bands: Excellent (>=80%), Good (>=60%), Fair (>=40%), Needs Improvement (<40%)
• How weighted rules work — a REL rule at weight 3 counts 3x more than one at weight 1
• Warning vs Fail: a warning awards 0.5x weight (partial credit); fail awards 0
• Where to find scores: executive-summary.html scorecard, manifest wafAssessment.summary, waf-findings.csv

How to Read the Compliance Roadmap

• What Now/Next/Later means: ranked by (weight x severity x impact) / effort
• Gap-to-Goal projection: interpreting current 58% to 72% by closing 3 findings
• Dependency ordering: why some rules must be fixed before others

How to Generate Remediation Scripts

• Get-RangerRemediation with -Format md, -FindingId, -Commit, -IncludeDependencies
• Annotated example output for PowerShell, Markdown, and Checklist formats

Understanding Azure Advisor Findings

• How Advisor recommendations map to WAF pillars
• Why an Advisor finding may appear even when the manifest rule for the same area passes
• How to act on Advisor findings outside of Ranger

Common Score Patterns

• What a typical first-run score looks like and why
• Which pillars typically score lowest on a new Azure Local deployment
• Most common high-weight failing rules and their fixes (AHB adoption, AMA coverage, quorum, backup)

Acceptance

• Page exists at docs/operator/waf-guide.md and is wired into mkdocs nav
• All five pillars explained with at least two example rules each
• Scoring methodology explained with a worked example (weighted points, warning factor, threshold bands)
• Compliance Roadmap and Gap-to-Goal sections include annotated example output
• Remediation section includes a working Get-RangerRemediation example with sample output
• Azure Advisor integration clearly distinguished from manifest rule engine
• Links to command-reference and issue docs: WAF rule engine reference — calculations, thresholds, priority, and authoring custom rules #268 rule engine reference

[kristopherjturner]

Tracked in Azure DevOps: https://dev.azure.com/hybridcloudsolutions/Azure%20Local%20Ranger/_workitems/edit/313