a5-web-audit

name	A5 — Web Audit
description	Research the world. Real web research to find what the best teams do for every technology and pattern in the build, then implement superior approaches now (not later). The only lens that brings outside knowledge.
argument-hint	<group-number> [feature-name]

A5 — Web Audit (Research the World)

The outside-knowledge check — the only lens that brings information from beyond the project. A5 performs real web research (live searches, fetching real URLs, citing real sources) to find what the best teams in the world do for every significant technology, pattern, and domain in the implementation, then evaluates the build against world-class practice. Superior approaches it discovers are implemented immediately, not deferred.

Inputs

• The implementation code in scope (to extract research topics) · the micro specs · the constitution (the tech stack)
• Prior A1–A4 reports · the live web (search + fetch) · the project mode
• On a re-run: the prior A5 report and prior research-learnings.md

Process

1. Identify search topics — analyze the code/templates and extract technologies, patterns, problem domains, and specific challenges; each becomes a research thread.
2. Search the web per topic, targeting authoritative sources: official docs and engineering blogs, conference talks and papers, RFCs and standards bodies, industry-leading implementations, UX/design-pattern libraries. (Content/process mode researches how professionals in the domain do their work.)
3. Evaluate each finding: relevant to what we built (confidence 1–10)? credible source? better than our current approach? implementable now or blocked?
4. Categorize: Superior approach → implement NOW · General learning → log it · Confirms our approach → record as validation · Not applicable → discard with a reason.
5. Implement superior approaches immediately — fixed on the branch, like A2/A3 fixes. If too large to do now, create a new tracked micro spec — never merely note it.
6. Persist general learnings to research-learnings.md, tagged with technology, domain, and source URL — they carry across features.
7. Degrade gracefully: if the web is unavailable, log a skip and do not block the pipeline (run it when connectivity returns).
8. Write the report to audits/{scope}-a5.md: research areas searched (and why), per-finding source URL + relevance + category + action taken + confidence, the improvements implemented, the learnings recorded, validations, reasoning traces, and a competitive-position analysis.

A5 findings carry three extra fields: Source (URL), Relevance (why the source matters), Confidence (1–10).

The Re-Run Protocol

An A5 re-run is not a verification pass (verifying fixes landed is what A2/A3 re-runs do). Because A5 is the only lens importing outside knowledge, every run is a fresh research expedition. A re-run (run N > 1) must:

1. Read the prior A5 report to know what's covered.
2. Research the fixes themselves — run 1's improvements are now part of the codebase; are they world-class? are there better alternatives?
3. Go deeper and wider — subtopics, adjacent domains, genuinely new developments (the web moves).
4. Compound on prior learnings — use prior notes as search seeds.
5. Record new learnings and append new findings; prior findings keep their Fixed status.

A re-run is clean when fresh research across new angles yields zero actionable findings — a judgment call. A clean re-run should still produce learnings even when it files no findings: knowledge always accrues even when nothing needs changing. That is the heart of the protocol.

Shared machinery

Finding format, zero-tolerance loop, and conviction: see docs/the-audit-system.md. A5 runs last in the per-group sequence; after it is clean, run /genesis-accept for the group.

Natural language triggers

- "a5 audit group 1"
- "web audit"
- "research world-class approaches"