# 0014. A Well-Architected review step in Discovery, judged in code | | | |---|---| | Status | Accepted | | Date | 2026-11-03 | | Decided by | Product owner, 2026-11-03: expand Discovery to support the Well-Architected Framework (advised to place it in ALZ-F02; chose Discovery) | | Requirements changed | New story ALZ-DSC-10 (to be created); the Discovery report's content for live runs | ## Context The first live GCP run produced a thin report, and the owner wants a Well-Architected review of the provider as a file of its own. Discovery's agents collected inventory, metadata and topology, but no policies or recommendations. Azure's subscription has about 1,776 Advisor recommendations (3.2 MB), more than a model step can take. ## Decision - **A new step, `cp1-well-architected-review-agent`** (ALZ-DSC-10), after the critic and before the report. It answers from code in `pre_process` (`app/waf.py`), like the report agent (ADR 0012): - It reads the in-scope resources, firewall or NSG rules, organisation policies, Azure resource locks and every page of the provider's recommendations, through read-only tools on the existing servers. - It applies fixed checks per pillar, rolls up recommendations by pillar and impact, and adds a guidance reference per pillar from the provider's own server (`_search_well_architected`; changed on 2026-11-04, when `cloud-knowledge` was retired). - It renders `waf_markdown`, `waf_html` and `final_waf_html`. - No model is involved. A pillar with no evidence is "not assessed", never a pass. - With `provider` `sample`, it's "not applicable" and calls nothing. - **Its page is released by the existing approval gate**, through its own Format for UI step (`s12`). The report shows a pillar summary. - **The report gains live sections:** estate overview, asset details from a new `provider_attributes` field (scan, then inventory, which also fills Site), network topology from the network agent's `topology_summary`, the Well-Architected summary, and a Mermaid dependency diagram. Sections empty only because their source was missing collapse into one "Not examined" list. ## Consequences - **The individual pattern has a second agent with code.** Its checks are unit-tested (`tests/test_waf.py`), and a check change needs a test. - **Judgement in Discovery.** This review judges configuration, which ALZ-F02's ALZ-ASM-05 also does for security. ALZ-ASM-05 should take this review as input rather than repeat it. - **Partial pillars.** Performance and sustainability rest on configuration and recommendations only: there's no utilisation telemetry. - **No automatic `.md` file.** The platform registers step outputs as `output.json`, so the Markdown is uploaded after approval with `scripts/kab_publish_report.py` until the platform can save a field as a file.