generate-report

Imported from nelsonmiew/website-audit-plugin (skills/generate-report/SKILL.md). Install upstream with npx skills add nelsonmiew/website-audit-plugin --skill generate-report. Copyright stays with the author.

Generate Final Audit Report

This skill merges all per-page audit results into final deliverables. It should ONLY run after the orchestrator confirms the audit is complete.

Workflow

1. Read audit directory from pointer — NEVER call init.sh

   AUDIT_DIR=$(bash "${CLAUDE_PLUGIN_ROOT}/scripts/queue.sh" get-audit-dir)
   echo "Generating report for: $AUDIT_DIR"

   If get-audit-dir fails, stop. Do not create a new directory.

2. Verify audit completion — BOTH queues must be done

   bash "${CLAUDE_PLUGIN_ROOT}/scripts/queue.sh" is-complete "$AUDIT_DIR"

   This checks BOTH queues:

   • Discovery queue (queue/discovery/): must have zero pending/in_progress tasks
   • Audit queue (queue/audit/): must have zero pending/in_progress tasks

   If is-complete returns false:

   • Check which queue still has work: queue.sh status "<audit_dir>" both
   • If discovery queue has tasks → warn: "Discovery is not complete. Run discover-site first."
   • If audit queue has tasks AND MAX_PAGES not reached → warn: "Audit still in progress. Continue auditing."
   • If audit queue has tasks BUT MAX_PAGES reached → proceed with partial report (note budget exhaustion)

   Do NOT generate the final report while either queue has pending work, unless MAX_PAGES is exhausted.

3. Collect all results

   • Read all results/page_<slug>.json files
   • Extract per-page scores, issues, links, and screenshots
   • Build unified data structures for aggregation

4. Calculate site-wide metrics

   • Average scores per category (legal/GDPR, accessibility, content, UX, technical)
   • Weight depth-0 pages 2x for site-wide scores
   • Count using BOTH queues for complete accounting:
     • queue.sh list-done "<audit_dir>" discovery → total pages discovered and link-crawled
     • queue.sh list-done "<audit_dir>" audit → total pages that received compliance checks
     • Cross-reference: every discovery-done page should have a corresponding audit-done page
   • Tally issues by severity and category
   • Screenshot count and coverage
   • Categorize pages: full audit / light audit / HTTP-only / missed

5. Generate deliverables

   a. INDEX.md (primary summary)

   • Header: Domain, audit date, audit mode, audit ID
   • Audit scope: Pages visited | discovered | HTTP-only; full vs light audit breakdown
   • Site-wide scores table (one row per category, show average and depth-0 average)
   • Top 10 issues by severity (🔴 critical, 🟠 high, 🟡 medium, 🔵 low)
   • Per-page results table: slug | audit_type | scores | issue_count
   • UI/UX Summary (see below)
   • Content Quality & AI Assessment (see below)
   • Screenshot summary: total count, coverage estimate
   • If light audits occurred: explain what was skipped and how to run full audit

   UI/UX Summary section (in INDEX.md and report.md):

   Aggregate heuristic, visual design, and first impression data across all pages. Include:

   ## UI/UX Evaluation
   
   | Page | Heuristics (0–10) | Visual Design (0–10) | First Impression (0–10) | UX Average |
   |------|-------------------|----------------------|------------------------|------------|
   | Homepage | 7.4 | 8.0 | 6.5 | 7.3 |
   | ... | | | | |
   | **SITE AVERAGE** | **X.X** | **X.X** | **X.X** | **X.X** |
   

   Followed by a written analysis (~150 words):

   • What is the overall UI/UX impression of the site?
   • Which heuristic fails the most across pages? Quote specific evidence.
   • Is visual design consistent across pages, or does it feel disjointed?
   • What is the site's weakest UX area (navigation, trust signals, CTA clarity, etc.)?
   • Top 3 UI/UX recommendations, prioritised by impact.

   Content Quality & AI Assessment section (in INDEX.md and report.md):

   Aggregate content scores and AI detection findings across all pages. Include:

   ## Content Quality & AI Assessment
   
   ### Content Quality Scores
   | Page | Originality | Relevance | Depth | Readability | Tone | SEO | Average |
   |------|-------------|-----------|-------|-------------|------|-----|---------|
   | Homepage | 6 | 8 | 5 | 7 | 7 | 6 | 6.5 |
   | ... | | | | | | | |
   | **SITE AVERAGE** | | | | | | | |
   
   ### AI Content Risk Assessment
   | Page | AI Risk Level | Confidence | Key Signals |
   |------|--------------|------------|-------------|
   | Homepage | HIGH | 85% | Formulaic sentences, no specifics, generic claims |
   | ... | | | |
   
   ### Content Coherence Issues
   | Page | Issue Type | Description |
   |------|-----------|-------------|
   | /services | Title ↔ H1 mismatch | Title: 'Services' / H1: 'Transform Your Business' |
   | ... | | |
   

   Followed by a written analysis (~150 words):

   • Overall verdict: Is the site's content genuine, human-authored, and relevant? Or does it read as AI-generated filler?
   • What percentage of pages have HIGH AI risk? What does this signal about the brand's content strategy?
   • Are there systematic coherence problems (e.g., meta descriptions that don't match page bodies across the whole site)?
   • Top 3 content recommendations, with specific page callouts.

   Performance & Web Vitals section (in INDEX.md and report.md):

   Aggregate Web Vitals and load timing across all audited pages. Include:

   ## Performance & Web Vitals
   
   | Page | TTFB | FCP | LCP | CLS | TBT | Load | Weight | Overall |
   |------|------|-----|-----|-----|-----|------|--------|---------|
   | Homepage | 290ms ✅ | 1.2s ✅ | 2.8s ⚠️ | 0.12 ⚠️ | 380ms ⚠️ | 3.4s | 1.8MB | ⚠️ |
   | /services | 310ms ✅ | 1.5s ✅ | 3.1s ⚠️ | 0.04 ✅ | 120ms ✅ | 2.9s | 1.1MB | ⚠️ |
   | **SITE AVG** | Xms | X.Xs | X.Xs | X.XX | Xms | X.Xs | XMB | |
   

   Legend: ✅ Good · ⚠️ Needs Improvement · ❌ Poor (Google Core Web Vitals thresholds)

   Followed by a written analysis (~100 words):

   • What is the overall performance story? Is the site fast or slow?
   • Which metric fails the most pages? (LCP and CLS are the most common culprits in PT sites)
   • Is there a pattern — e.g., all pages slow on LCP because images are not optimised?
   • Are third-party scripts (analytics, chat, ad pixels) the main TBT contributor?
   • Top 3 performance recommendations with estimated impact.

   b. [audit_id]_report.md (detailed)

   • Metadata section (same as INDEX)
   • Site-wide UI/UX Analysis (full version of the UI/UX summary from INDEX.md)
     • Per-heuristic breakdown across all pages (radar chart description or table)
     • Visual design consistency assessment — do all pages share the same design language?
     • First impression scores per page with quoted evidence
   • Site-wide Content & AI Analysis (full version of content summary from INDEX.md)
     • Per-page AI content detection findings with quoted text evidence
     • Content coherence issues listed per page
     • Overall content strategy assessment
   • Per-page breakdown (one section per audited page)
     • Page URL, audit type, screenshot count
     • Per-viewport findings (mobile/tablet/desktop if available)
     • All 28 checks and their results
     • Content quality scores with justifications
     • AI detection result with evidence quotes
     • Content coherence check result
     • Heuristic evaluation with scores per heuristic
     • Visual design scores per dimension
     • First impression scores per question
   • Aggregated link inventory (all unique URLs found)
   • Methodology notes

   c. [audit_id]_issues.csv

   • Columns: id, severity, category, page, viewport, description, recommendation, evidence_screenshot
   • Rows: one per issue, sorted by severity then id
   • Global issue IDs (sequential: issue_001, issue_002, etc.)
   • Each row includes page slug and viewport (if applicable)

   d. [audit_id]_links.csv

   • Columns: url, type (internal/external/broken/mailto/tel), discovered_from, http_status, depth
   • All URLs from all pages
   • Mark type: internal (same domain), external (other domain), broken (failed), mailto, tel
   • Depth: 0 for seed pages, 1+ for discovery crawl
   • http_status: 200, 404, 500, timeout, blocked, etc.

   e. screenshots/MANIFEST.csv

   • Columns: filename, page, viewport, type (full/above_fold/issue/form), timestamp
   • List all screenshots captured
   • Type indicates context: full page, above fold, specific issue, form state

6. Update state

   • Set state.json status to "completed"
   • Record completion timestamp

7. Print summary

   • Report files created: INDEX.md, [audit_id]_report.md, [audit_id]_issues.csv, [audit_id]_links.csv
   • Key stats: total pages, critical issues, external links found
   • Next steps: review INDEX.md first, then detailed report

Key Rules

• URL accounting: Every discovered URL must appear in one of these categories: audited (full/light), HTTP-only, or flagged missing. Run counts must sum.
• Issue IDs: Sequential global IDs across entire audit, sorted by severity (critical → high → medium → low), then alphabetically by category.
• Light audit disclosure: If any pages got light audit (due to resource limits or user skip), add a box in INDEX.md explaining what was skipped and command to re-run full audit on those pages.
• Depth weighting: Site-wide scores count depth-0 (seed) pages twice; affects overall audit quality rating.
• Format preference: Markdown (INDEX.md, report.md) are primary deliverables; CSVs are reference data.

Success Criteria

• All files created with correct column headers and data
• No missing URLs
• Issue counts match across files
• Site-wide scores are weighted correctly and reflect audit scope
• User can open INDEX.md and immediately understand audit results