Deterministically audit and optimise a published guide. Runs a 14-section quality audit, applies 7 rewrite rules for value density, brand discipline, search-intent alignment, and CTR. Reads 28-day GSC query data per URL, produces a 100-point score delta across 11 dimensions, commits changes, and updates the per-guide report. Handles guides without GSC data. Load identity and brand-voice first.
Deterministically audit and optimise a published guide. Runs a 14-section quality audit, applies 7 rewrite rules for value density, brand discipline, search-intent alignment, and CTR. Reads 28-day GSC query data per URL, produces a 100-point score delta across 11 dimensions, commits changes, and updates the per-guide report. Handles guides without GSC data. Load identity and brand-voice first.
metadata
{"version":"3.0.1","git_hash":"dc0c940"}
Guide Optimiser
Run a deterministic, data-driven audit and rewrite on a single published guide. This skill is the complete lifecycle tool for guide quality: audit, fix, score, commit, log. Every decision is grounded in a quantitative rule or a 28-day Google Search Console signal. No vibes, no "use your judgement" gaps.
Critical rule: Section 14 (Search Intent Resolution) is a critical override. If Section 14 fails, the entire audit fails regardless of how many other sections pass. A guide that does not resolve the searcher's intent has no value, regardless of how well it scores on technical criteria.
Dependencies
Load identity and brand-voice before this skill.
identity — positioning, ICP, messaging hierarchy, what the brand actually stands for
brand-voice — the cliche list, terminology rules, em-dash ban, and voice targets
Source of Truth
Read these before starting:
/var/www/html/systemprompt-web/reports/seo/seo-strategy-master.md — pillar health, objectives, active hypotheses
/var/www/html/systemprompt-web/reports/seo/data/keyword-targets.json — canonical keyword registry with assigned guides, volumes, difficulty, target positions. Find the entry where assigned_guide matches this guide's slug to identify the primary keyword and its current metrics.
The latest reports/seo/daily/YYYY-MM-DD/daily-seo-brief.md — per-guide CTR, impressions, position, quick-wins list
/var/www/html/systemprompt-web/reports/seo/data/hypothesis-ledger.md — check if an S-### hypothesis exists for this guide's title/meta rewrite. If yes, note the hypothesis ID in your output so we can score it later.
/var/www/html/systemprompt-web/reports/content/guides/{slug}/guide-report.md — the per-guide report (search intent analysis, FAQ mappings, external resources, asset inventory, action log, metadata rationale). If this file does not exist, create it from the template in the "Per-Guide Report Template" section below before proceeding. Populate with available data from keyword-targets.json and any GSC data pulled in Phase 0.
Inputs
Caller must provide:
Guide slug (e.g. getting-started-anthropic-marketplace), OR the absolute path to the guide's index.md
Phases
The skill runs sequentially: 0 -> 1 -> 2 -> 2.5 -> 3. Do not skip. If any phase aborts, exit cleanly without committing.
Phase 0 — GSC Query Ingestion
Pull the 28-day Google Search Console query data for this specific guide URL. 28 days (not 7) so recent guides have enough signal and the result isn't biased by a single bad week.
Authenticate
Use the service account at /var/www/html/systemprompt-web/.keys/gsc.json. Read scope is https://www.googleapis.com/auth/webmasters.readonly.
python3 <<'PY' > /tmp/gsc_token
import json, time, base64
from urllib.request import urlopen, Request
from urllib.parse import urlencode
from pathlib import Path
key = json.loads(Path('/var/www/html/systemprompt-web/.keys/gsc.json').read_text())
now = int(time.time())
claims = {
'iss': key['client_email'],
'scope': 'https://www.googleapis.com/auth/webmasters.readonly',
'aud': 'https://oauth2.googleapis.com/token',
'iat': now, 'exp': now + 3600,
}
try:
import jwt as pyjwt
token = pyjwt.encode(claims, key['private_key'], algorithm='RS256')
except ImportError:
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding
h = base64.urlsafe_b64encode(json.dumps({'alg':'RS256','typ':'JWT'}).encode()).rstrip(b'=').decode()
p = base64.urlsafe_b64encode(json.dumps(claims).encode()).rstrip(b'=').decode()
pk = serialization.load_pem_private_key(key['private_key'].encode(), password=None)
sig = pk.sign(f'{h}.{p}'.encode(), padding.PKCS1v15(), hashes.SHA256())
token = f'{h}.{p}.{base64.urlsafe_b64encode(sig).rstrip(b"=").decode()}'
data = urlencode({'grant_type':'urn:ietf:params:oauth:grant-type:jwt-bearer','assertion':token}).encode()
resp = json.loads(urlopen(Request('https://oauth2.googleapis.com/token', data=data, method='POST')).read())
print(resp['access_token'], end='')
PY
Cache both files. If the guide has no rows, record no_gsc_data: true and proceed — content rules still apply.
Build the working set:
top_queries: sorted by impressions, filter impressions >= 20 (signal floor)
mandatory_queries: top_queries where impressions >= 20 (the set that drives Rule 4)
page_metrics: {impressions, clicks, ctr, position} from the page aggregate
Initialise Guide Report
Read the per-guide report at reports/content/guides/{slug}/guide-report.md. If it does not exist, create it from the template (see "Per-Guide Report Template" section below) and populate with:
Primary keyword data from keyword-targets.json
GSC data just pulled (impressions, clicks, CTR, position)
Any existing FAQ, resource, and asset data extractable from the guide's current content
This ensures every optimiser run has a guide report to work with, even for guides created before this upgrade.
Phase 1 — 14-Section Audit
Run the full 14-section checklist against the target guide. Record pass/fail per check. This phase writes nothing to disk — it produces a dict held in memory for Phase 2.5 scoring.
When Phase 1 produces a failing check, Phase 2 is responsible for fixing it only where the fix is covered by the rewrite rules below. Out-of-scope failures (e.g. broken external links pointing to 404s) are reported but not auto-fixed.
Section 1: Frontmatter Completeness
title present and under 60 characters
description present and under 160 characters
description starts with a verb, not "This guide" or "In this article"
No AI cliches (revolutionize, game-changer, unlock, supercharge, seamlessly, cutting-edge, harness, next-generation, paradigm shift, disrupt, empower, leverage as verb, reimagine)
No fabricated personal stories or "When I was building..." narratives
No generic filler ("Let's dive in", "Without further ado", "In today's fast-paced world")
Uses correct Anthropic terminology (plugins not apps, skills not prompts, agents not bots, MCP servers not APIs)
Zero occurrences of systemprompt, systemprompt.io, or systempromptio (case-insensitive) in guide body content. Run grep -ci 'systemprompt' body_content to verify. Exceptions: founder-narrative guides (the-growth-chart-nobody-shows-you, building-on-quicksand-claude-breaking-changes), or guides where the product IS the topic.
No product CTAs of any kind in body content
No "we recommend", "our solution", "try our", or first-person product language
Competitive frame is build-vs-buy (not product vs other platforms)
Section 8: Actionability and Completeness
A reader with stated prerequisites can complete the guide's goal without external help
Every "how to" section has exact steps, not vague direction ("configure your settings" without showing how)
Error scenarios and common mistakes are addressed
"After reading this" outcomes are all achievable by following the guide
Guide does not end abruptly (has a conclusion with next steps or related resources)
If the guide recommends a tool or approach, it shows the actual implementation (not just "use X")
Section 9: External Resources
Every guide must link to authoritative external sources that substantiate its claims and provide further reading. These resources demonstrate that the guide is built on research, not opinion.
At least 5 distinct external resource links in the guide body (not counting frontmatter links array)
All external links point to primary sources (official documentation, research papers, RFCs, GitHub repositories, specification documents), not blog posts summarising documentation
External links are contextually placed inline where relevant (not dumped in a "resources" or "further reading" section at the end)
External links are to current, live pages (not 404, not deprecated, not archived)
No external links to competitor products presented as recommendations
External resources are recorded in the per-guide report's "External Resources Audit" section
Section 10: Homemade Visual Assets
Every guide must include original visual assets based on real data. Charts, tables, and graphs make content more useful and harder to replicate. They also signal to readers (and search engines) that the content is original research, not a rewrite.
At least 2 homemade visual assets in the guide (SVG charts, data tables with real data, comparison graphs, architecture diagrams)
Each visual asset cites a real data source (pricing page, benchmark results, API documentation, research paper, official statistics)
Visual assets contain real data, not placeholder or illustrative numbers
SVG charts and diagrams are well-formed and render correctly
Data tables have proper markdown formatting (headers, column alignment)
Every visual asset is wrapped with copy and share buttons for external sharing:
Copy button (using <sp-copy-button> web component) copies asset content to clipboard
Share button copies a permalink URL with backlink to systemprompt.io/guides/{slug}#{asset-anchor}
Source attribution line citing the data source is visible
Visual assets are recorded in the per-guide report's "Homemade Asset Inventory" section with their data sources
Section 11: FAQ and Long-Tail Keyword Validation
FAQs drive structured data in search results. Every FAQ must be grounded in actual search behaviour, not invented questions.
At least 4 FAQ entries in frontmatter
Each FAQ question maps to a documented long-tail keyword (from keyword-targets.json or GSC query data)
FAQ-to-keyword mapping is recorded in the per-guide report's "FAQ and Long-Tail Keyword Match" section
FAQ answers are self-contained (useful without reading the full guide)
FAQ answers include specific numbers, steps, or data points (not vague generalities)
No FAQ question is generic or unresearchable (e.g., "What is X?" must have keyword volume backing it)
Section 12: Topic Research Evidence
Every guide must demonstrate that its topic was researched before writing. This section validates the per-guide report's research sections.
Per-guide report exists at reports/content/guides/{slug}/guide-report.md
Search Intent Analysis section is complete:
Intent classification (informational/commercial/navigational/transactional) with evidence
User profile: who is searching, what role, what problem they have
What they need: the specific answer or outcome they seek
Evidence: how we know (GSC queries, keyword intent data, SERP analysis)
Keyword map with primary, secondary, and long-tail keywords, each with volume and source date
Competing content audit with at least 3 competitor URLs analysed (word count, strengths, gaps)
Differentiation statement: what this guide offers that competing content does not
All keyword volumes cite their source (keyword-targets.json pull date or GSC date range)
Section 13: Metadata Rationale and Action Traceability
The title, description, and keywords of every guide must be backed by data, and every change to them must be traceable. This prevents repeated edits without evidence.
Guide report Section 7 (Title, Description and Keywords Rationale) is complete
Title rationale cites keyword volume data with source and date
Description rationale explains which search intent it addresses
Keywords rationale justifies each keyword with volume/difficulty data
Every metadata change in the guide's history has a corresponding Action Log entry
Every Action Log entry that produced an artifact links to it using a relative path
No metadata was changed without GSC data or keyword volume evidence justifying the change
Title/description "Last changed" date is present and accurate
This is the most important section. If Section 14 fails, the entire audit result is FAIL regardless of how many other sections pass. A guide that does not resolve the searcher's intent is not a world-class resource, no matter how well-structured or SEO-optimised it is.
The assessment here is structured but requires judgement. Each check must be supported by specific evidence from the guide and the per-guide report.
Intent match: The documented search intent (from the guide report) matches what the content actually delivers. If the report says users want "empirical cost reduction strategies," the guide must contain specific, tested strategies with measured outcomes, not general advice.
Quick resolution: The guide answers the title's implied question within the first 300 words. A reader who arrived from Google should know within 30 seconds that this page will solve their problem.
Complete resolution: A reader searching the primary keyword finds their question fully answered, not just discussed. "How to reduce Claude Code costs" must contain actual cost reduction techniques with expected savings, not just an explanation of how pricing works.
Actionable value: The guide provides specific steps, real numbers, working code, or clear recommendations. Every strategy and recommendation must be something the reader can act on immediately.
Empirical evidence: Strategies and recommendations are backed by evidence (benchmarks, measurements, documented behaviour, official sources), not presented as unsupported assertions. "This saves 40% on token costs" must cite where that number comes from.
Competitive superiority: The guide is demonstrably better than the competing content documented in the guide report. It must go deeper, be more accurate, or provide unique value that competitors miss.
Trust signals: The content shows WHY readers can trust it. Methodology is stated. Sources are cited. Real numbers have provenance. The reader understands the basis for every claim.
Unique perspective: The guide offers something no other resource does. This is documented in the guide report's differentiation statement and must be visible in the content itself.
Phase 2 — Deterministic Rewrite
Seven hard rules. Each is mechanically enforceable.
Handling guides without GSC data: When no_gsc_data: true (new or unindexed guides), Phase 2 still applies Rules 1, 2, 5, and 7 (brand cleanup, length floor, cliche/voice, external resources). Only Rule 3 (title/meta CTR rewrite), Rule 4 (query alignment), and Rule 6 (FAQ/GSC alignment) are skipped because they need search data. No guide gets a free pass.
Rule 1 — Brand-mention discipline
The core ask: guides are littered with brand references that dilute value density.
Definition of a brand mention: any occurrence of systemprompt, systemprompt.io, or systempromptio (case-insensitive) in the guide body. Exclude:
Frontmatter (--- to ---)
The final "About / Further reading / Next steps" block (last H2 or H3 of the guide, whichever is last)
Code blocks that legitimately import or reference the crate (e.g. use systemprompt::..., cargo add systemprompt)
The links frontmatter array
Topic terms are NOT brand mentions — Claude, Anthropic, Claude Code, MCP, Cursor, Copilot, LangChain are topics. Leave them.
Budget:
Hard cap: max 3 brand mentions per guide body, AND
Density cap: max 1 mention per 1,500 words of body
Whichever is stricter wins
Earn-it test for each remaining mention: would the paragraph be strictly weaker without it? If removing the mention leaves the paragraph intact, remove it.
Replacement rules:
"systemprompt.io's governance pipeline evaluates" -> "a governance pipeline evaluates"
"At systemprompt we believe" -> delete entire phrase, keep the underlying claim
"systemprompt is the only self-hosted" -> "self-hosted deployments that" (reframe as category, not product)
First-person marketing ("we built X to solve Y") -> stripped entirely
Exception: founder-narrative guides are exempt from Rule 1. Current list:
the-growth-chart-nobody-shows-you
building-on-quicksand-claude-breaking-changes
These can reference the brand freely because the guide is the founder's story.
Rule 2 — Length floor
Non-pillar guides: minimum 3,500 words body
Pillar guides: minimum 5,000 words body
Pillar list (from seo-strategy-master.md):
claude-code-vs-cursor
self-hosted-ai-governance
getting-started-anthropic-marketplace
claude-code-mcp-servers-extensions
claude-code-daily-workflows
claude-code-organisation-rollout
If the guide is below the floor after Rule-1 stripping, add substantive content:
A missing troubleshooting section (grounded in real errors, often in the GSC query log as error queries)
A worked example with realistic input and output
A common-pitfalls block
A comparison table if the guide is comparing things
Expanded FAQ answers driven by GSC question-style queries
Never pad. No restating points, no synonym chains, no "in summary" repetition. If the guide can't honestly reach the floor, flag it as needs_content_investment: true in the report and stop at the word count you can justify — better to under-deliver length than to lie with filler.
If the guide is already above 5,000 words and dense, do not expand it further. The length rule is a floor, not a target.
Rule 3 — Title and meta description rewrite (CTR-driven, with rationale tracking)
If the guide has no GSC data (new, not indexed, no_gsc_data: true from Phase 0): leave title and meta alone. A rewrite without signal is guessing. Note title_meta_skipped_no_signal in the report.
Before rewriting, check the guide report's Section 7 (metadata rationale):
Read the "Last changed" date for the title and description.
Hard rule: if the title or description was last changed less than 28 days ago AND the previous hypothesis (S-###) has not matured (check hypothesis-ledger.md for window_end date), do NOT change it again. Wait for the data to come in. Note title_meta_skipped_hypothesis_pending: {S-###} in the report.
Read the previous rationale so you understand why the current values were chosen.
If the guide has GSC data and the 28-day cooldown has passed: rewrite both. Use the following hard rules.
Title rules:
50-60 characters hard cap (Google truncates above 60)
Must start with a strong verb or comparison frame: How to ..., Build ..., Configure ..., X vs Y, N ways to ..., Install ..., Deploy ...
Must contain the guide's primary keyword (frontmatter keywords[0] or derived from the top GSC query)
Must include a specificity hook: a number, a year (2026), an outcome, or a differentiator
Banned: colon sandwich (Foo: The Complete Guide to X), bracketed tags ([2026 Guide]), "Ultimate", "Definitive", "Complete"
Must accurately represent the content — no clickbait, no overpromise
Meta description rules:
130-160 characters hard cap
Starts with a verb (Learn, Compare, Configure, Build, Deploy, Troubleshoot)
Primary keyword in the first 100 characters
Tells the reader what they will be able to DO, not what the article covers
Unique across the site — grep services/content/guides/*/index.md for collision before writing
Selection of primary keyword: from the Phase-0 GSC data, the top query (by impressions, signal >= 20) is the primary keyword if it matches the guide's topic. Otherwise fall back to keywords[0] in frontmatter. Cross-check: the chosen primary keyword must appear in at least two top-20 GSC queries, or the signal is too narrow.
Do not rewrite titles on breakout performers. If the guide's current CTR is already within 80% of the position-expected CTR (see Phase 2.5 CTR curve), the title is working. Leave it. Only rewrite the meta description in this case.
After rewriting, update the guide report's Section 7:
Record the new title/description values
Record the rationale: which GSC data justified the change (impressions, CTR, position, top queries)
Record the S-### hypothesis ID (create one in the hypothesis ledger if a title rewrite was made)
Record the previous values and their rationale (so the change can be reversed if the hypothesis fails)
Skipped when no_gsc_data: true. Without search data, query alignment cannot be grounded.
For each query in mandatory_queries (Phase 0, impressions >= 20, 28 days):
Verbatim presence check: grep the guide body (case-insensitive) for the exact query string. If absent, it must be added naturally — as an H2, an H3, a lead sentence, or an FAQ question. Never keyword-stuff.
Intent classification (deterministic mapping):
Starts with how to, how do I -> how-to intent -> needs numbered steps
Otherwise: informational -> needs an H2 or H3 explaining it
Format match check: does the guide contain the format the intent demands? If the top query is "failed to install anthropic marketplace" (troubleshooting intent), the guide must contain a clearly labelled troubleshooting section. If not, add one.
Position in document: high-impression queries should appear in the first 500 words or in a heading — not buried.
Produce a query coverage matrix in the report:
| Query | 28d Impressions | 28d CTR | In body? | In heading? | Intent covered? | Action |
|-------|----------------:|--------:|:--------:|:-----------:|:---------------:|--------|
| anthropic marketplace | 724 | 1.1% | yes | no | yes | Add H2 with exact phrasing |
| failed to install anthropic marketplace | 364 | 1.1% | no | no | no | Add troubleshooting section |
Every row with a no triggers a rewrite action. This is how the skill ensures the guide "accurately, precisely, and informatively provides value based on the keywords that are actually driving search traffic."
Filler transitions:Let's dive in, Without further ado, In today's fast-paced world, In this guide, we will, This article will cover, By the end of this guide, As we've seen, It goes without saying, At the end of the day
Punctuation: em dashes — -> replace with commas, periods, or parentheses (brand-voice rule)
Other: hashtags, fabricated "when I was building this" stories (unless founder-narrative exception), vague "teams say" / "companies report" / "studies show" without a source
Run a final pass against brand-voice skill's full cliche list and Anthropic terminology rules (plugins not apps, skills not prompts, agents not bots, MCP servers not APIs).
Rule 6 — FAQ and GSC long-tail alignment
Skipped when no_gsc_data: true. Without search data, FAQ alignment cannot be grounded.
After Phase 0 produces the GSC query data:
Extract question-form queries from GSC data: any query containing how, what, why, when, can, does, is, or ending with ?.
Cross-reference with existing FAQ questions in the guide's frontmatter.
For any GSC question-query with >= 20 impressions that has no matching FAQ: add it as a new FAQ entry with a complete, specific answer (2-4 sentences, includes numbers where applicable). The FAQ question should use the GSC query phrasing verbatim or as a natural variant.
For any existing FAQ question that matches no GSC query AND no keyword-targets.json keyword: flag for removal or replacement. Do not remove without flagging — the FAQ may be too new for GSC data.
Update the guide report's "FAQ and Long-Tail Keyword Match" table with all current mappings, noting which are GSC-validated and which are keyword-targets-only.
Rule 7 — External resource and shareable asset enforcement
External resources: Count distinct external links in the guide body (exclude frontmatter, exclude internal links). If count < 5:
Identify additional relevant primary sources from the guide's topic domain (official documentation, research papers, specifications, GitHub repositories).
Add them as inline links in contextually appropriate locations where they support specific claims. Do not dump them in a "resources" section.
Update the guide report's "External Resources Audit" section.
Homemade visual assets: Count SVG elements, markdown data tables (with real data, not just structural tables), embedded charts, and architecture diagrams. If count < 2:
Flag needs_visual_assets: true in the report.
Do NOT generate placeholder assets. List specific data sources that could be used to create real assets (e.g., "Anthropic pricing page data could power a cost comparison chart," "benchmark results from the guide's code examples could populate a performance table").
Update the guide report's "Homemade Asset Inventory" section.
Shareable asset compliance: For each visual asset found, check that it is wrapped with:
A copy button (using <sp-copy-button> web component)
A share button with permalink backlink to systemprompt.io/guides/{slug}#{asset-anchor}
A source attribution line
If missing, flag needs_share_buttons: true in the report.
Phase 2.5 — Scoring
Every guide gets a 100-point score across eleven dimensions. Compute both pre- and post-rewrite. The delta is the proof of work.
Handling guides without GSC data: When no_gsc_data: true, GSC-dependent dimensions (Search traffic, CTR performance) score N/A and the max drops to 75. Query coverage gets a neutral score of 8 (cannot be penalised without signal). All other dimensions score normally.
Rubric
Dimension
Max
Data source
Search traffic
15
GSC 28d impressions for this URL
CTR performance
10
GSC 28d CTR vs position-expected CTR
Query coverage
15
Fraction of top-20 queries where verbatim+intent are covered
matched = FAQs with documented keyword match (in guide report or GSC-validated)
total = total FAQ count (minimum 1 to avoid division by zero)
score = round(8 * (matched / total))
4/4 matched = 8. 2/4 = 4. 0/4 = 0.
External resources (8 max):
count = distinct external resource links in guide body
score = min(8, round(8 * (count / 5)))
5+ = 8. 3 = 5. 1 = 2. 0 = 0.
Homemade assets (5 max):
count = shareable visual assets (SVGs + data tables + charts) with cited sources and share buttons
score = min(5, round(5 * (count / 2)))
2+ = 5. 1 = 3. 0 = 0.
Search intent resolution (5 max):
5 points if: guide report has completed "Search Intent Analysis" section (all fields populated with evidence) AND the guide's first 500 words address the documented intent AND the intent resolution verdict is "RESOLVED".
3 points if: guide report exists but intent analysis is partial or verdict is "PARTIALLY RESOLVED".
0 points if: no guide report, no intent analysis, or verdict is "NOT RESOLVED".
Score tiers
85-100: Top-tier asset. No further action.
70-84: Acceptable. Rewrite opportunities exist but guide is not broken.
Below 70: Failing. Priority candidate for rewrite.
Word count — must be >= floor. If not, report as needs_content_investment and abort commit.
Brand-mention count — must be within budget. Re-grep to verify.
Re-run the 14-section audit. Sections 1, 6, 7 must all pass. Other sections must be no worse than the baseline from Phase 1.
Title and meta lengths — validate hard caps.
Meta description uniqueness — grep all other guides' descriptions, confirm no collision.
Diff the guide file. If diff is empty or trivially whitespace-only, abort with no_material_change. Never commit a no-op.
Recompute the score. If post_score < pre_score, abort and roll back — this is a bug in the rules, not an improvement. Report the regression.
Commit with the message format above.
Write the structured per-guide artifact report to reports/content/artifacts/optimiser/YYYY-MM-DD/{slug}.md.
Update the canonical guide report at reports/content/guides/{slug}/guide-report.md:
Append Action Log entry: date, "Optimised", "guide-optimiser", "Score {pre} -> {post}", link to artifact report, hypothesis ID (if title/meta changed), commit SHA
Update "Current Scores > Optimiser Score" with the new score breakdown table
Update "Current Scores > Revision Audit" with the Phase 1 section results
Update "FAQ and Long-Tail Keyword Match" table with any new mappings from Rule 6
Update "External Resources Audit" with current resource inventory
Update "Homemade Asset Inventory" with current asset inventory
Update Section 7 (metadata rationale) if title/description/keywords were changed (with new rationale, previous values, S-### hypothesis ID)
Append a GSC performance snapshot row to Section 8 with today's data
Per-Guide Report Template
When a guide report does not exist, create it at reports/content/guides/{slug}/guide-report.md using the following template. Populate what you can from keyword-targets.json and the guide's current content:
# Guide Report: {title}**Slug:** {slug}
**Path:** services/content/guides/{slug}/index.md
**Created:** {YYYY-MM-DD}
**Last updated:** {YYYY-MM-DD}
**Primary keyword:** {keyword} (volume: {N}, difficulty: {N}, intent: {type})
**Status:** draft | published | needs-revision | optimised
## 1. Search Intent Analysis### Who is searching and why?-**Primary intent:** {informational|commercial|navigational|transactional}
-**User profile:** {who is this person, what role, what problem}
-**What they need:** {the specific answer or outcome they are seeking}
-**Evidence:** {how we know: GSC queries, keyword intent data, SERP analysis}
### How have we addressed their intent?-**Core value delivered:** {what the guide gives them that resolves their search}
-**Unique perspective:** {what we offer that no other resource does}
-**Evidence quality:** {are strategies empirical? are claims backed by data?}
-**Trust signals:** {methodology stated, sources cited, real numbers with provenance}
-**Intent resolution verdict:** RESOLVED | PARTIALLY RESOLVED | NOT RESOLVED
### Keyword Map
| Keyword | Volume | Difficulty | Classification | Source | Status |
|---------|-------:|----------:|---------------|--------|--------|
### Competing Content Audit
| URL | Word count | Strengths | Gaps we exploit |
|-----|----------:|-----------|----------------|
### Our Differentiation
{What this guide offers that nothing else does, with evidence}
## 2. FAQ and Long-Tail Keyword Match
| FAQ Question | Matched Keyword | Volume | Source | Validated? |
|-------------|----------------|-------:|--------|:----------:|
Rule: every FAQ must map to a researched keyword. No guessing.
## 3. External Resources Audit
| # | URL | Type | Relevance | In Guide? |
|---|-----|------|-----------|:---------:|
Minimum: 5 primary-source external resources.
## 4. Homemade Asset Inventory
| # | Type | Description | Data Source | Location |
|---|------|------------|------------|---------|
Minimum: 2 visual assets (SVG chart, data table, graph) with cited real data sources.
## 5. Action Log
Every action on this guide is recorded here. Every entry links to the artifact report and hypothesis ID where applicable. This is the audit trail. It must be complete.
| Date | Action | Skill | Details | Artifact Report | Hypothesis | Commit |
|------|--------|-------|---------|----------------|------------|--------|
Rules:
- Every skill run on this guide MUST append a row here
- Artifact reports are linked using relative paths
- Hypothesis IDs (S-###) cross-reference the SEO hypothesis ledger
- Commit SHAs link to the actual code change
- This log is append-only. Rows are never edited or removed.
## 6. Current Scores### Optimiser Score: pending/100### Revision Audit: pending/14 sections passing## 7. Title, Description and Keywords Rationale### Current Title-**Value:** "{title}"
-**Primary keyword:** {keyword} (volume: {N}, source: keyword-targets.json, date: {YYYY-MM-DD})
-**Rationale:** {why this title was chosen, linked to keyword data or CTR evidence}
-**Last changed:** {YYYY-MM-DD} by {skill} (action: {S-### hypothesis ID or "initial"})
-**CTR at time of change:** {N}% (position {N})
### Current Description-**Value:** "{description}"
-**Rationale:** {why this description, what search intent it addresses}
-**Last changed:** {YYYY-MM-DD} by {skill} (action: {S-### or "initial"})
### Current Keywords-**Value:** "{keywords}"
-**Rationale:** {each keyword justified by volume/difficulty data from keyword-targets.json}
-**Last changed:** {YYYY-MM-DD} by {skill}
Rule: title, description, and keywords must NOT be changed without GSC or keyword data justifying the change. Every change must reference an S-### hypothesis ID or cite specific volume/CTR evidence. This prevents repeated edits without data backing.
## 8. GSC Performance History
| Date | 28d Impressions | 28d Clicks | CTR | Avg Position |
|------|----------------:|-----------:|----:|-------------:|
