Skip to content

SEO Sweep Phase 2 — Starter Prompt + Reference

Phase 2 SHIPPED: Mon 11 May 2026 (~11:00 NZST). All Tier 1 + Tier 2 surfaces complete. Result: 845 failing → 50 failing (94% reduction). 564 critical → 7 critical. 232 → 1,027 compliant.

✅ Phase 2 results (final)

Surface Pages Before After Commit
mind-maps 67 58 failing 2 d91d7df0
YouTube videos (ai-hub + exam-qa + cloud-labs + certifications) 71 67 failing 6 af5122b2
ai-mapper 27 28 failing 1 0ab4a10d
tool _index.md (57 surfaces) 57 50 failing 4 0e39fe95
cert-compass 41 36 failing 1 bfc9121a
prompts (cards) 500 500 failing 5 54ddcec3
Remaining (prompt-guide, licensing, m365-roadmap, interview-prep) ~88 51 failing ~10 22d21213
TOTAL ~850 ~795 ~30 7 commits

~818 page rewrites shipped. Per-surface SLA smoke 3/3 green throughout.

Tools built (all in scripts/)

Script Surface
rewrite-mind-map-metas.ps1 mind-maps/
rewrite-youtube-metas.ps1 ai-hub + exam-qa + cloud-labs + certifications + interview-prep
rewrite-ai-mapper-metas.ps1 ai-mapper/
rewrite-tool-index-metas.ps1 All single-page tool surfaces (auto-detected)
rewrite-cert-compass-metas.ps1 cert-compass/
rewrite-prompt-metas.ps1 prompts//.md (500 cards)
rewrite-remaining-metas.ps1 prompt-guide, licensing, m365-roadmap, prompts category indexes
seo-surface-breakdown.ps1 Progress helper — per-surface failing count

All scripts share the same LF/CRLF safe FM rewrite pattern from rewrite-cert-metas.ps1. Each produces a review file (<SURFACE>-META-REVIEW.md) committed for posterity.

Tier 3 (deferred — not in scope)

  • ai-news/ (13 failing) — news has short shelf-life
  • music/ (6 failing) — niche
  • A handful of utility-tool single-page surfaces (color-palette, password-generator — no natural Microsoft brand) — accept as flagged, hand-touch via cc dashboard if needed

What changed (verbatim, for posterity)

TL;DR for next session

Paste this into a fresh Copilot CLI session:

Please continue the SEO meta sweep we started yesterday/today. Read learning-docs/docs/reference/seo-sweep-phase2-prompt.md first (this file) — it has the audit findings, the L4/L2 tools you'll use, and the exact surfaces to fix in priority order. We're doing a FULL SWEEP — all Tier 1 + Tier 2 surfaces (~200 pages). Don't ask me to choose options — execute. Save the rest for niche/low-value surfaces (Tier 3). Apply the same parallel-safe rules and SLA protocols I've been using. Update the session journal at the end.

What Phase 1 already accomplished (don't re-do)

Surface Commits What changed
Hugo cert-tracker/* (151 pages) de43de11, 67c84544, b190172a 125 cert page metas rewritten + 1 broken AB- pattern fix + LF/CRLF fix
Astro guided/[slug]/index.astro 32d61f4 Template change: short title + capped 155-char desc
Astro guided/[cert]/practice.astro 32d61f4 Same fix for practice quiz pages
Astro displayCode helper f226246 Strip vendor prefix from slug-style codes (AWS/GCP)
Hugo cc dashboard L1 fa5b0ec4 📋 prompt buttons in SEO tab + L2 quality scoring + L4 batch rewriter

End state of Phase 1: 232 of 1,077 pages compliant. 845 still need work.

The audit findings (verbatim from Phase 1 closing scan)

By content surface (failure rates):

Surface Pages Failing % Critical Notes
ai-hub/ 19 18 95% 14 YouTube video pages — same template disease
exam-qa/ 21 18 86% 9 YouTube video pages — same template disease
cloud-labs/ 20 16 80% 5 YouTube video pages — same template disease
mind-maps/ 67 47 70% 7 Titles fine, descriptions too long (170-210 chars)
cert-compass/ 41 35 85% 4 Cert comparison pages — investigate pattern
licensing/ 51 18 35% 3 Licensing docs — mix of issues
certifications/ 15 12 80% 2 Cert cluster pages (NOT single certs — those done)
ai-news/ 14 13 93% 0 News entries (Tier 3 — lower priority)
Tool _index.md (~11) 11 11 100% 0-1 One-pagers per tool, hand-craft each
interview-prep/ 4 4 100% 2 Small, easy
music/ 6 5 83% 0 Tier 3

Phase 2 execution plan — Tier 1 + Tier 2 (~200 pages)

Tier 1 — biggest ROI

A) YouTube video pages (54 pages) — ai-hub/ + exam-qa/ + cloud-labs/

The pattern (ALL have this): 

title: "Watch [80-char YouTube video title] | Master AI Writing & Editing with Microsoft 365"
description: "Watch [same title] - free hands-on tutorial by Susanth Sutheesh on A Guide to Cloud & AI."

Two failure modes: 1. Titles are 84-98 chars (way over 60 char Google limit) 2. Descriptions are identical boilerplate across pages → Google sees duplicate content

Investigation needed first: - Are these driven by a Hugo template that pulls from data/videos.json / data/videos-full.json? - Or hand-written .md files per video? - Check: Get-ChildItem content\ai-hub -Filter "*.md" | Select-Object -First 1 → see if frontmatter has unique data or templated - Check: layouts/ai-hub/, layouts/exam-qa/, layouts/cloud-labs/ for Hugo template logic - Check: data/videos.json for video metadata

Likely fix: - If template-driven: change the layout to use a seo_title / seo_description field if present, else generate a smarter default (truncate title to ~55 chars, derive unique description from video tags/category) - If hand-written: extend L4 with a youtube-video template that detects "Watch ... - free hands-on tutorial by Susanth Sutheesh" pattern and replaces

Expected lift: 54 pages × ~30 imps/month = significant CTR opportunity, plus removes duplicate-content penalty

B) Mind maps (47 failing of 67)

Simpler — just descriptions over 155 chars. Titles already good.

Template approach: 

description: "{first_sentence_of_existing_desc}. {short_value_prop}."

Or trim existing description at word boundary to ≤155 chars + add "Free mind map." suffix.

Sample current state: - File: mind-maps/agent-365.md - Current desc (210 chars): "Visual map of Microsoft Agent 365 — three control planes (Entra Agent ID, Purview for Agents, Defender for Agents) plus the M365 Admin Center, the four things every agent needs, and..." - Target desc (≤155 chars): "Visual map of Microsoft Agent 365 — Entra Agent ID, Purview, and Defender for Agents. Free interactive mind map for the four control planes."

Extend scripts/rewrite-cert-metas.ps1 with a New-Meta-MindMap function or write a separate scripts/rewrite-mind-map-metas.ps1.

Tier 2 — solid wins

C) Cert Compass (35 failing of 41) — investigate pattern, probably similar to cert-tracker but with different field structure

D) Certifications hub pages (12 failing of 15) — these are CLUSTER pages (e.g., /certifications/azure/) NOT single certs. Different template needed.

E) Licensing docs (18 failing of 51) — high-value reference content. Hand-craft or template per type.

F) Tool _index.md pages (~11) — hand-craft each via the cc dashboard 📋 button workflow: - ai-showdown/_index.md - copilot-frontier-map/_index.md - copilot-model-map/_index.md - typing-test/_index.md - phishing-test/_index.md - prompt-tester/_index.md - feature-roulette/_index.md - ps-builder/_index.md - incident-comms/_index.md - admin-comms/_index.md - cli-quiz/_index.md

These are public-facing tool landing pages — worth hand-crafting for voice.

Tier 3 — defer unless time permits

  • ai-news/ (13 failing) — news has short shelf life
  • interview-prep/ (4) — small
  • music/ (5) — niche
  • Misc 1-file surfaces

The tools you'll use

All already built and live on main:

Tool File What it does
L1: cc dashboard prompts static/js/command-centre.js Live at /cc/ → press S → click 📋 prompt buttons. Use these for hand-craft work.
L2: SEO quality scorer scripts/check-seo-quality.ps1 Run with -Scope all for full audit, -Scope cert-tracker etc. for specific. Warn-only in CI.
L4: Batch rewriter scripts/rewrite-cert-metas.ps1 Already handles 13 cert vendors. Extend this with new surface templates (or write a sibling script).

Quality rules (must satisfy ≥80 score for auto-rewrite, else flag for human): - Title 35-60 chars - Description 120-155 chars - Brand word in title (Microsoft/Azure/AWS/GCP/etc.) — see BrandWords array in scripts - Hook word in title (Free/New/Replaces/Complete/Beginner/Updated/2026) - Code/key term in description first 80 chars - CTA word in description (Free/Practice/Guide/Tips) - Page has OG image - No hype words (ultimate, comprehensive, robust, frontier, agentic, etc. — see HypeWords array)

Critical safety rules (DO NOT SKIP)

🚨 Practice Exam SLA

Don't touch any file in this list without SLA protocol: - PracticeQuiz.tsx - src/pages/[cert]/practice.astro - src/pages/[slug]/index.astro - src/pages/embed/[cert]/practice.astro - src/data/questions/*.json - scripts/build-question-data.mjs - package.json build scripts - Astro config / build config - Cloudflare Pages env vars / bindings

Phase 2 work shouldn't need to touch these (already done in Phase 1). If you find yourself needing to, follow the protocol in learning-docs/docs/reference/incident-log.md.

Mandatory SLA smoke test at session end: 

$r1 = Invoke-WebRequest -Uri "https://www.aguidetocloud.com/guided/data/questions/az-900.json" -UseBasicParsing
$body = '{"productType":"cert","certCode":"az-900","vendorSlug":"microsoft"}'
$r2 = Invoke-WebRequest -Uri "https://www.aguidetocloud.com/guided/api/checkout" -Method POST -Body $body -ContentType "application/json" -UseBasicParsing
$r3 = Invoke-WebRequest -Uri "https://www.aguidetocloud.com/guided/az-900/practice/" -UseBasicParsing
# All must return 200

🔒 Parallel-safe git

A different session is doing Tools work simultaneously. Their work touches data/toolkit_nav.toml, static/css/*.css, layouts/<tool>/list.html. You must:

  • Never git add -A / git add . / git commit -a
  • Always explicit paths: git add scripts/foo.ps1 content/mind-maps/*.md
  • Read git status -s before staging — if you see M (uppercase M with leading space) on files you didn't modify, those are theirs — leave them
  • git pull --rebase before every push
  • One logical change per commit (don't bundle mind-maps + cert-compass into one commit)

🔴 LF/CRLF bug (already fixed in scripts/rewrite-cert-metas.ps1 but be aware)

Some content files have LF line endings (Linux contributors). The L4 script's prefix detection now handles this dynamically. If you write a new sibling script (e.g., for mind-maps), copy the same pattern:

$prefixEnd = 3
if ($c.Length -gt 4 -and $c[3] -eq [char]"`r" -and $c[4] -eq [char]"`n") { $prefixEnd = 5 }
elseif ($c.Length -gt 3 -and $c[3] -eq [char]"`n") { $prefixEnd = 4 }
$end = $c.IndexOf("`n---", $prefixEnd)
$fm = $c.Substring($prefixEnd, $end - $prefixEnd)
# When writing back, always emit `---\r\n` and TrimStart `\r`/`\n` from $newFM:
$newContent = "---`r`n" + $newFM.TrimStart("`r","`n") + $body

After every batch run, integrity-check: 

Get-ChildItem <path> -Filter '*.md' | ForEach-Object {
  $bytes = [System.IO.File]::ReadAllBytes($_.FullName)
  if ($bytes.Length -ge 4 -and $bytes[3] -eq 0x74) { Write-Host "BROKEN: $($_.Name)" }
}

Suggested phase 2 workflow

  1. Read this doc + session journal (~/.copilot/session-journal.md top entries)
  2. Run pwsh scripts\check-seo-quality.ps1 -Scope all to confirm baseline
  3. Phase 2A — YouTube video pages
  4. Investigate template vs hand-written (~5 min)
  5. Build appropriate fix (template change OR L4 extension)
  6. Dry-run → review → write → smoke-test → commit per-surface
  7. Phase 2B — Mind maps
  8. Extend L4 OR write rewrite-mind-map-metas.ps1
  9. Dry-run → review → write → commit
  10. Phase 2C — Cert Compass + Certifications + Licensing
  11. Investigate each pattern
  12. Extend L4 templates
  13. Dry-run → review → write → commit per-surface
  14. Phase 2D — Tool _index.md pages (hand-craft via cc dashboard 📋 buttons)
  15. Open /cc/ → SEO tab → click 📋 prompt for each
  16. Or: just write them directly knowing the voice/format
  17. Final audit — pwsh scripts\check-seo-quality.ps1 -Scope all — confirm progress
  18. SLA smoke test — 3 curls
  19. Update session journal — what was done, decisions, pick-up-here
  20. Update this doc — mark Tier 1/2 surfaces as done, list remaining

Sush's voice & style cues for hand-craft (from voice-and-tone.md)

  • Plain English — "for people like us"
  • Honest — no hype, no fluff, no "ultimate" / "comprehensive" / "robust"
  • Concrete numbers — "27 modules" > "many modules"
  • Brand-allergy — don't lead with self-stats; use real value props
  • Hook first — what makes a searcher actually click?

Title formula that works (from cert-tracker sweep): [CODE or KEY]: [Specific Topic] — Free [Resource Type] Examples: - AI-200 Microsoft Exam (Replaces AZ-204) — Free Study Guide ✓ - AZ-900: Microsoft Azure Fundamentals — Free Study Guide ✓

Description formula: [CODE]: the [Brand] [Topic] [level] exam. Free [resource] covering [3 specific topics], with [credibility signals].

Files to read first when picking up

  1. This file (you're reading it)
  2. ~/.copilot/session-journal.md — pinned WIP branches + recent sessions
  3. learning-docs/docs/reference/voice-and-tone.md — Sush's voice rules
  4. learning-docs/docs/reference/deployment-playbook.md — 20-step pre-push checklist
  5. learning-docs/docs/reference/parallel-git-rules.md — parallel-safe git protocol
  6. ~/.copilot/copilot-instructions.md § Practice Exam SLA — non-negotiable rule
  7. scripts/rewrite-cert-metas.ps1 — the L4 tool, your main weapon

Files you'll likely edit

Confirmed/likely: - scripts/rewrite-cert-metas.ps1 — extend with new surface templates - scripts/check-seo-quality.ps1 — maybe extend brand/hook words for non-cert content - Maybe new: scripts/rewrite-mind-map-metas.ps1 if too different to share L4 - Hugo template files in layouts/ai-hub/, layouts/exam-qa/, layouts/cloud-labs/ if video pages are template-driven - ~100-200 .md files across the surfaces above - content/<tool>/_index.md files (hand-craft) - MICROSOFT-CERT-META-REVIEW.md etc. — review files for posterity

Files you must NOT touch (other session is using them)

  • data/toolkit_nav.toml
  • static/css/<tool>.css (per-tool CSS)
  • layouts/<tool>/list.html (most tool layouts)
  • Anything in brainbar/qa/ or qa/qa-review/

Always read git status -s first.

Done criteria for Phase 2

  • L2 audit on -Scope all: <100 pages below threshold (down from 845)
  • 0 critical (<50 score)
  • 0 broken frontmatter
  • Hugo build clean (pwsh scripts\hugo-safe.ps1)
  • SLA smoke test 3/3 green
  • Session journal updated with summary + pick-up-here
  • This file updated marking Tier 1/2 as complete
  • One commit per logical surface (parallel-safe)

If you get stuck

  • The L4 script's existing patterns (Microsoft, AWS, GCP, etc.) are the gold standard. Copy-modify for new surfaces.
  • If a new surface has unusual fields (no exam_code, etc.), use whatever unique key is available (slug, file name).
  • If a page can't be auto-rewritten to score ≥80, FLAG IT for human attention — don't ship a degradation.
  • The 📋 prompt buttons on /cc/ SEO tab generate Copilot CLI prompts for individual page hand-craft.