@rules/seo-workflow.md
@rules/validation.md
SEO Maker
Audit and improve a project's search visibility across traditional search engines and AI answer engines.
Default all user-facing deliverables, saved artifacts, reports, plans, generated docs, summaries, handoff notes, commit/message drafts, and validation notes to Korean, even when this canonical skill file is written in English.
Preserve source code identifiers, CLI commands, file paths, schema keys, JSON/YAML field names, API names, package names, proper nouns, and quoted source excerpts in their required or original language.
Use a different language only when the user explicitly requests it, an existing target artifact must stay in another language for consistency, or a machine-readable contract requires exact English tokens. If a localized template or reference exists (for example *.ko.md or *.ko.json), prefer it for user-facing artifacts.
- Audit website or project SEO in a systematic way.
- Cover on-page SEO, technical SEO, content SEO, and Core Web Vitals.
- Evaluate AEO readiness for featured snippets, voice search, and direct-answer surfaces.
- Evaluate GEO readiness for citation likelihood in generative AI responses.
- Evaluate LLMO readiness for AI crawler access, freshness, and model-readable context.
- Save prioritized recommendations and evidence under
.hyper/seo-maker/[slug]/.
- Update existing reports so SEO improvement history remains traceable.
- If the user asks for highest score, max score, maximum score, perfect score, or continuous improvement, run an audit to fix/recommendation to re-audit loop and keep the best result.
Use seo-maker when the main outcome is an SEO/AEO/GEO/LLMO audit, optimization report, or evidence-backed search visibility improvement plan.
Route neighboring work elsewhere:
- Page or product UI design: use
designer or the relevant frontend design skill.
- Competitor or market research without site audit: use
research.
- Pre-release build and deployment checks: use
pre-deploy.
- Pure performance engineering without search context: use the relevant performance or optimization workflow.
- Broad AI search trend research without a target site or content set: use
research.
Positive examples:
- "Audit this site's SEO."
- "Check metadata and structured data."
- "Create an SEO audit report."
- "Review search-engine optimization status and give improvement recommendations."
- "Summarize how to improve Core Web Vitals scores."
- "Optimize our content so AI search engines can cite it."
- "Check whether ChatGPT or Perplexity can surface our brand."
- "Analyze this site from AEO and GEO perspectives."
- "Keep iterating fixes until the SEO score is as high as possible."
- "Audit, fix, and re-verify until the search optimization score is close to perfect."
Negative examples:
- "Design this landing page." -> use
designer.
- "Research competitor market positioning." -> use
research.
- "Check the pre-deploy checklist." -> use
pre-deploy.
Boundary examples:
- "Optimize this page's performance."
Use
seo-maker only when performance is evaluated through SEO/Core Web Vitals impact.
- "Research AI search trends."
Use
seo-maker only when the output is tied to a target site, page, or content inventory.
| Situation |
Mode |
| Full SEO audit for a new project or site |
create |
| On-page SEO review for a specific page |
create |
| Add a new analysis to an existing SEO report |
update |
| Focused Core Web Vitals or technical SEO analysis |
create |
| Re-check after SEO improvements |
update |
| Iterative improvement toward best or perfect score |
optimize |
| AEO/GEO citation readiness analysis |
create |
| Add AEO/GEO analysis to an existing report |
update |
- Metadata and SEO elements in HTML pages and Next.js/React components.
robots.txt, sitemap.xml, llms.txt, canonical tags, and structured data.- Core Web Vitals signals such as LCP, INP, and CLS.
<head> elements including title, meta description, Open Graph, and Twitter Card.- Heading hierarchy from
h1 through h6.
- Image alt text and internal link structure.
- Schema.org JSON-LD markup, including AI trust signals.
- AEO elements such as Q&A formats, direct-answer structure, and featured-snippet optimization.
- GEO elements such as citable sentence structure, statistics with sources, and entity authority.
- LLMO elements such as
llms.txt, AI crawler accessibility, and content freshness.
| Complexity |
Signals |
Handling |
| Simple |
Single-page review, one SEO element, quick metadata audit |
Direct: write report.md immediately |
| Complex |
Full-site audit, many pages, technical SEO plus content SEO plus Core Web Vitals, competitor comparison |
Tracked: use flow.json for phase tracking |
Before starting, record:
Complexity: [simple/complex] — [one-line reason]
Mode: [create/update/optimize]
Target: [site/page/project path]
Proof surface: [commands, browser checks, web sources, or local files]
Before scoring any project, classify the audit context so this skill works across stacks:
target_type: live-url, local-static, nextjs, react-spa, docs-site, ecommerce, blog, or app-with-marketing-pagesaccess_level: live URL, local files only, Search Console available, analytics available, field Core Web Vitals available, or AI citation probe availableallowed_action: audit-only, recommend, edit-code, or optimize-loopmeasurement_confidence: lower confidence when live URL, Search Console, field Core Web Vitals, or AI citation probes are unavailableevaluator: comparable target set, scoring rubric, tools/versions, dates, and evidence channels
Classify every finding and score input as exactly one of official, live, field, tool, lab, synthetic, or heuristic. Do not treat one class as evidence from another: a local scan is not live or field evidence, and a tool/lab result is not an official requirement.
Record unavailable checks as unknown and irrelevant checks as not-applicable; exclude not-applicable checks from category denominators. Do not hide missing evidence. If a recommendation is based on static files, lab data, synthetic probes, or heuristics, label it that way in results.json.
When live browsing, Search Console, field data, AI probes, or a named tool is unavailable, use the strongest available lower-grade method, state the capability limitation and fallback, and do not make live-performance, ranking, inclusion, or citation claims.
Create or update .hyper/seo-maker/[slug]/.
Expected files:
.hyper/seo-maker/[slug]/
├── dashboard.html # Browser-readable dashboard
├── results.json # Structured audit results
├── results.js # File URL fallback for browser rendering
├── report.md # Markdown report
├── sources.md # Source and evidence log
└── flow.json # Required for complex or optimize mode
For simple mode, report.md and sources.md are the minimum. For complex or optimize mode, all files are expected.
Follow references/artifact-spec.md for the file schema.
For new reports, use assets/report.template.ko.md by default. Use assets/report.template.md only when English is explicitly required.
Render order:
- Gather evidence and write/update
results.json.
- Generate
results.js for direct local browser viewing.
- Render
dashboard.html from the current results.
- Write
report.md and sources.md with links or file references. sources.md is a source ledger: for every external or official claim, record its URL, accessed or published date, applicable claim, evidence class, and any scope/availability limitation.
When results.json is finalized, render the dashboard with scripts/render-dashboard.mjs <artifact-dir>.
Read in this order:
- Core
SKILL.md to confirm the task is an SEO/AEO/GEO audit, optimization report, or score loop.
- rules/seo-workflow.md for the execution phases.
- references/seo-fundamentals.md for E-E-A-T, Core Web Vitals, ranking factors, entity SEO, and schema markup criteria.
- references/aeo-geo-guide.md for AEO/GEO/LLMO strategy, the GEO CORE framework, platform benchmarks, and
llms.txt guidance.
- references/seo-checklist.md for the practical audit checklist.
- references/artifact-spec.md for
results.json, dashboard lifecycle, and workspace schema.
- For new reports, read assets/report.template.ko.md by default; read assets/report.template.md only when English is explicitly required.
- When rendering a dashboard, read assets/dashboard-template.html.
- Before completion, read rules/validation.md.
| Phase |
Task |
Output |
| 0 |
Determine target, mode, complexity, proof surface, and universal intake fields |
Execution brief |
| 1 |
Establish measurement methods and confidence limits |
measurement_methods |
| 2 |
Collect evidence from local code, pages, browser checks, and web sources |
Evidence log |
| 3 |
Audit technical SEO, platform policy, AEO, GEO, LLMO, Core Web Vitals, and structured data |
Structured findings |
| 4 |
Separate official requirements from field/tool/lab/synthetic/heuristic findings |
Evidence-graded findings |
| 5 |
Prioritize issues by impact, confidence, effort, and source tier |
Recommendation set |
| 6 |
Write artifacts and dashboard |
.hyper/seo-maker/[slug]/ |
| 7 |
If optimize mode, apply or recommend fixes and re-audit |
Best verified result |
| 8 |
Summarize score, wins, confidence limits, risks, and next actions |
Final report |
Check these dimensions when relevant to the target:
- Technical SEO: crawlability, indexability, canonicalization, sitemap, robots directives, response status, redirects, and duplicate pages.
- Platform policy: audit Googlebot, Google-Extended, OAI-SearchBot, GPTBot, and ChatGPT-User as separate controls; inspect snippet controls and X-Robots-Tag. Their purposes differ and a rule for one must not be inferred for another.
- On-page SEO: title, description, heading hierarchy, keyword alignment, URL readability, and internal links. Character counts, heading counts, and link density are context-dependent heuristic observations, never official pass/fail failures.
- Content SEO: intent match, depth, freshness, topical coverage, uniqueness, and readability. Word count is context-dependent; do not use a minimum length as an official requirement.
- Core Web Vitals: LCP, INP, CLS, render-blocking resources, image sizing, and interaction latency.
- Structured data: JSON-LD validity, Schema.org fit, visible-content parity, entity identifiers, breadcrumbs, FAQs, products, articles, or organization markup. Do not imply structured data guarantees rich results or AI citations.
- AEO: concise visible answer blocks, Q&A structure, snippet-ready summaries, voice-search phrasing, and direct-answer clarity. Treat answer length and platform-content preferences as heuristics, not platform requirements.
- GEO: citable claims, statistics with sources, entity authority, author or brand trust signals, and content that AI systems can quote safely. This assesses readiness only; it cannot promise a citation.
- LLMO: optional
llms.txt, AI crawler access, clean markdown or semantic HTML, clear entity relationships, and updated canonical content. llms.txt is an optional proposal, not a standard, ranking factor, or citation requirement.
- Google AI features: assess ordinary SEO fundamentals and index/snippet eligibility where relevant. Do not prescribe special AI schema or text files; indexed, snippet-eligible pages may be considered but inclusion is not guaranteed.
Use a transparent 100-point score when enough evidence exists:
- Technical SEO: 20
- On-page SEO: 20
- Content SEO: 15
- Core Web Vitals: 15
- Structured data: 10
- AEO readiness: 10
- GEO/LLMO readiness: 10
If evidence is incomplete, mark affected categories as unknown; mark irrelevant categories as not-applicable and exclude them from the score denominator. Do not invent certainty or convert heuristics into official failures.
Each finding should include:
- Severity:
critical, warning, or info (use impact/effort fields for prioritization beyond severity).
- Confidence: high, medium, or low.
evidence_grade: official, live, field, tool, lab, synthetic, or heuristic.measurement_method: scan, tool, probe, source, or command used.source_tier: official-doc, observed-file, live-observation, field-data, tool-output, lab-result, synthetic-probe, or research-backed-heuristic.- Evidence: command output, URL, local file path, browser observation, or saved probe result.
- Recommendation: specific action and expected impact.
- Owner surface: code, content, infrastructure, analytics, or external platform.
Use optimize mode when the user requests a maximum score, perfect score, continuous iteration, or "keep fixing until it passes" behavior. Interpret such requests as a bounded optimization process, never an unbounded loop.
Loop rules:
- Set and record a finite iteration budget, target, stable evaluator, baseline audit, and regression guards before changes. The default budget is three iterations unless the user sets a smaller bound.
- Pick the highest-impact fix or recommendation with the best confidence/effort ratio.
- Apply safe local code/content fixes when they are in scope; otherwise record an actionable recommendation.
- Re-run only comparable relevant checks and record the evidence class, capability limitations, and unknown/not-applicable states.
- Keep a change only if comparable evidence improves without triggering a regression guard; otherwise revert it where possible or mark it
discarded.
- Stop at the target, budget, plateau, a guard failure, no safe local fixes, or when remaining work requires external credentials or business decisions.
Do not fake a perfect score. If external evidence is unavailable, report the unknowns, the best comparable verified result, and no guarantee of ranking, AI-feature inclusion, or citation.
At completion, .hyper/seo-maker/[slug]/ should contain:
results.json with structured audit results and status complete for complex or optimize mode.dashboard.html rendered from the latest results when dashboard output is expected.results.js for local browser fallback when dashboard output is expected.report.md with prioritized findings, score, and recommendations.sources.md with the evidence log.
Validate:
- Every critical or warning finding has evidence.
- Recommendations are specific enough for an engineer, marketer, or content owner to act on.
- Scores are derived from observed evidence, with
unknown and not-applicable handled explicitly, not assumptions.
- Google AI features are described as using ordinary SEO fundamentals; eligible indexed/snippet-eligible pages can be considered, but inclusion is not guaranteed and no special schema or AI text file is required.
- FAQPage recommendations distinguish Google rich-result eligibility from answer-friendly visible FAQ content.
sources.md is a source ledger with URL, date, applicable claim, evidence class, and limitations for source-sensitive claims.- Optimize mode records the baseline, evaluator, finite budget, guards, changes/recommendations, re-audit evidence, discarded iterations, stop reason, and best comparable verified result.
1---2name: seo-maker3description: [Hyper] Create integrated SEO, AEO, GEO, and LLMO audits and optimization reports. Use for on-page, technical, content, Core Web Vitals, answer-engine, generative-engine, AI search visibility, metadata, citation readiness, or score-improvement loops saved under `.hyper/seo-maker/[slug]/`.4---56@rules/seo-workflow.md7@rules/validation.md89# SEO Maker1011> Audit and improve a project's search visibility across traditional search engines and AI answer engines.1213<output_language>1415Default all user-facing deliverables, saved artifacts, reports, plans, generated docs, summaries, handoff notes, commit/message drafts, and validation notes to Korean, even when this canonical skill file is written in English.1617Preserve source code identifiers, CLI commands, file paths, schema keys, JSON/YAML field names, API names, package names, proper nouns, and quoted source excerpts in their required or original language.1819Use a different language only when the user explicitly requests it, an existing target artifact must stay in another language for consistency, or a machine-readable contract requires exact English tokens. If a localized template or reference exists (for example `*.ko.md` or `*.ko.json`), prefer it for user-facing artifacts.2021</output_language>2223<purpose>2425- Audit website or project SEO in a systematic way.26- Cover on-page SEO, technical SEO, content SEO, and Core Web Vitals.27- Evaluate AEO readiness for featured snippets, voice search, and direct-answer surfaces.28- Evaluate GEO readiness for citation likelihood in generative AI responses.29- Evaluate LLMO readiness for AI crawler access, freshness, and model-readable context.30- Save prioritized recommendations and evidence under `.hyper/seo-maker/[slug]/`.31- Update existing reports so SEO improvement history remains traceable.32- If the user asks for highest score, max score, maximum score, perfect score, or continuous improvement, run an audit to fix/recommendation to re-audit loop and keep the best result.3334</purpose>3536<routing_rule>3738Use `seo-maker` when the main outcome is an SEO/AEO/GEO/LLMO audit, optimization report, or evidence-backed search visibility improvement plan.3940Route neighboring work elsewhere:4142- Page or product UI design: use `designer` or the relevant frontend design skill.43- Competitor or market research without site audit: use `research`.44- Pre-release build and deployment checks: use `pre-deploy`.45- Pure performance engineering without search context: use the relevant performance or optimization workflow.46- Broad AI search trend research without a target site or content set: use `research`.4748</routing_rule>4950<activation_examples>5152Positive examples:5354- "Audit this site's SEO."55- "Check metadata and structured data."56- "Create an SEO audit report."57- "Review search-engine optimization status and give improvement recommendations."58- "Summarize how to improve Core Web Vitals scores."59- "Optimize our content so AI search engines can cite it."60- "Check whether ChatGPT or Perplexity can surface our brand."61- "Analyze this site from AEO and GEO perspectives."62- "Keep iterating fixes until the SEO score is as high as possible."63- "Audit, fix, and re-verify until the search optimization score is close to perfect."6465Negative examples:6667- "Design this landing page." -> use `designer`.68- "Research competitor market positioning." -> use `research`.69- "Check the pre-deploy checklist." -> use `pre-deploy`.7071Boundary examples:7273- "Optimize this page's performance."74 Use `seo-maker` only when performance is evaluated through SEO/Core Web Vitals impact.75- "Research AI search trends."76 Use `seo-maker` only when the output is tied to a target site, page, or content inventory.7778</activation_examples>7980<trigger_conditions>8182| Situation | Mode |83|------|------|84| Full SEO audit for a new project or site | create |85| On-page SEO review for a specific page | create |86| Add a new analysis to an existing SEO report | update |87| Focused Core Web Vitals or technical SEO analysis | create |88| Re-check after SEO improvements | update |89| Iterative improvement toward best or perfect score | optimize |90| AEO/GEO citation readiness analysis | create |91| Add AEO/GEO analysis to an existing report | update |9293</trigger_conditions>9495<supported_targets>9697- Metadata and SEO elements in HTML pages and Next.js/React components.98- `robots.txt`, `sitemap.xml`, `llms.txt`, canonical tags, and structured data.99- Core Web Vitals signals such as LCP, INP, and CLS.100- `<head>` elements including title, meta description, Open Graph, and Twitter Card.101- Heading hierarchy from `h1` through `h6`.102- Image alt text and internal link structure.103- Schema.org JSON-LD markup, including AI trust signals.104- AEO elements such as Q&A formats, direct-answer structure, and featured-snippet optimization.105- GEO elements such as citable sentence structure, statistics with sources, and entity authority.106- LLMO elements such as `llms.txt`, AI crawler accessibility, and content freshness.107108</supported_targets>109110<complexity_routing>111112| Complexity | Signals | Handling |113|------|------|------|114| **Simple** | Single-page review, one SEO element, quick metadata audit | **Direct**: write `report.md` immediately |115| **Complex** | Full-site audit, many pages, technical SEO plus content SEO plus Core Web Vitals, competitor comparison | **Tracked**: use `flow.json` for phase tracking |116117Before starting, record:118119```text120Complexity: [simple/complex] — [one-line reason]121Mode: [create/update/optimize]122Target: [site/page/project path]123Proof surface: [commands, browser checks, web sources, or local files]124```125126</complexity_routing>127128<universal_intake>129130Before scoring any project, classify the audit context so this skill works across stacks:131132- `target_type`: `live-url`, `local-static`, `nextjs`, `react-spa`, `docs-site`, `ecommerce`, `blog`, or `app-with-marketing-pages`133- `access_level`: live URL, local files only, Search Console available, analytics available, field Core Web Vitals available, or AI citation probe available134- `allowed_action`: `audit-only`, `recommend`, `edit-code`, or `optimize-loop`135- `measurement_confidence`: lower confidence when live URL, Search Console, field Core Web Vitals, or AI citation probes are unavailable136- `evaluator`: comparable target set, scoring rubric, tools/versions, dates, and evidence channels137138Classify every finding and score input as exactly one of `official`, `live`, `field`, `tool`, `lab`, `synthetic`, or `heuristic`. Do not treat one class as evidence from another: a local scan is not live or field evidence, and a tool/lab result is not an official requirement.139140Record unavailable checks as `unknown` and irrelevant checks as `not-applicable`; exclude `not-applicable` checks from category denominators. Do not hide missing evidence. If a recommendation is based on static files, lab data, synthetic probes, or heuristics, label it that way in `results.json`.141142When live browsing, Search Console, field data, AI probes, or a named tool is unavailable, use the strongest available lower-grade method, state the capability limitation and fallback, and do not make live-performance, ranking, inclusion, or citation claims.143144</universal_intake>145146<artifact_contract>147148Create or update `.hyper/seo-maker/[slug]/`.149150Expected files:151152```text153.hyper/seo-maker/[slug]/154├── dashboard.html # Browser-readable dashboard155├── results.json # Structured audit results156├── results.js # File URL fallback for browser rendering157├── report.md # Markdown report158├── sources.md # Source and evidence log159└── flow.json # Required for complex or optimize mode160```161162For simple mode, `report.md` and `sources.md` are the minimum. For complex or optimize mode, all files are expected.163164Follow [references/artifact-spec.md](references/artifact-spec.md) for the file schema.165166For new reports, use [assets/report.template.ko.md](assets/report.template.ko.md) by default. Use [assets/report.template.md](assets/report.template.md) only when English is explicitly required.167168Render order:1691701. Gather evidence and write/update `results.json`.1712. Generate `results.js` for direct local browser viewing.1723. Render `dashboard.html` from the current results.1734. Write `report.md` and `sources.md` with links or file references. `sources.md` is a source ledger: for every external or official claim, record its URL, accessed or published date, applicable claim, evidence class, and any scope/availability limitation.174175When `results.json` is finalized, render the dashboard with `scripts/render-dashboard.mjs <artifact-dir>`.176177</artifact_contract>178179<support_file_read_order>180181Read in this order:1821831. Core `SKILL.md` to confirm the task is an SEO/AEO/GEO audit, optimization report, or score loop.1842. [rules/seo-workflow.md](rules/seo-workflow.md) for the execution phases.1853. [references/seo-fundamentals.md](references/seo-fundamentals.md) for E-E-A-T, Core Web Vitals, ranking factors, entity SEO, and schema markup criteria.1864. [references/aeo-geo-guide.md](references/aeo-geo-guide.md) for AEO/GEO/LLMO strategy, the GEO CORE framework, platform benchmarks, and `llms.txt` guidance.1875. [references/seo-checklist.md](references/seo-checklist.md) for the practical audit checklist.1886. [references/artifact-spec.md](references/artifact-spec.md) for `results.json`, dashboard lifecycle, and workspace schema.1897. For new reports, read [assets/report.template.ko.md](assets/report.template.ko.md) by default; read [assets/report.template.md](assets/report.template.md) only when English is explicitly required.1908. When rendering a dashboard, read [assets/dashboard-template.html](assets/dashboard-template.html).1919. Before completion, read [rules/validation.md](rules/validation.md).192193</support_file_read_order>194195<workflow>196197| Phase | Task | Output |198|------|------|------|199| 0 | Determine target, mode, complexity, proof surface, and universal intake fields | Execution brief |200| 1 | Establish measurement methods and confidence limits | `measurement_methods` |201| 2 | Collect evidence from local code, pages, browser checks, and web sources | Evidence log |202| 3 | Audit technical SEO, platform policy, AEO, GEO, LLMO, Core Web Vitals, and structured data | Structured findings |203| 4 | Separate official requirements from field/tool/lab/synthetic/heuristic findings | Evidence-graded findings |204| 5 | Prioritize issues by impact, confidence, effort, and source tier | Recommendation set |205| 6 | Write artifacts and dashboard | `.hyper/seo-maker/[slug]/` |206| 7 | If optimize mode, apply or recommend fixes and re-audit | Best verified result |207| 8 | Summarize score, wins, confidence limits, risks, and next actions | Final report |208209</workflow>210211<audit_dimensions>212213Check these dimensions when relevant to the target:214215- Technical SEO: crawlability, indexability, canonicalization, sitemap, robots directives, response status, redirects, and duplicate pages.216- Platform policy: audit Googlebot, Google-Extended, OAI-SearchBot, GPTBot, and ChatGPT-User as separate controls; inspect snippet controls and X-Robots-Tag. Their purposes differ and a rule for one must not be inferred for another.217- On-page SEO: title, description, heading hierarchy, keyword alignment, URL readability, and internal links. Character counts, heading counts, and link density are context-dependent heuristic observations, never official pass/fail failures.218- Content SEO: intent match, depth, freshness, topical coverage, uniqueness, and readability. Word count is context-dependent; do not use a minimum length as an official requirement.219- Core Web Vitals: LCP, INP, CLS, render-blocking resources, image sizing, and interaction latency.220- Structured data: JSON-LD validity, Schema.org fit, visible-content parity, entity identifiers, breadcrumbs, FAQs, products, articles, or organization markup. Do not imply structured data guarantees rich results or AI citations.221- AEO: concise visible answer blocks, Q&A structure, snippet-ready summaries, voice-search phrasing, and direct-answer clarity. Treat answer length and platform-content preferences as heuristics, not platform requirements.222- GEO: citable claims, statistics with sources, entity authority, author or brand trust signals, and content that AI systems can quote safely. This assesses readiness only; it cannot promise a citation.223- LLMO: optional `llms.txt`, AI crawler access, clean markdown or semantic HTML, clear entity relationships, and updated canonical content. `llms.txt` is an optional proposal, not a standard, ranking factor, or citation requirement.224- Google AI features: assess ordinary SEO fundamentals and index/snippet eligibility where relevant. Do not prescribe special AI schema or text files; indexed, snippet-eligible pages may be considered but inclusion is not guaranteed.225226</audit_dimensions>227228<scoring>229230Use a transparent 100-point score when enough evidence exists:231232- Technical SEO: 20233- On-page SEO: 20234- Content SEO: 15235- Core Web Vitals: 15236- Structured data: 10237- AEO readiness: 10238- GEO/LLMO readiness: 10239240If evidence is incomplete, mark affected categories as `unknown`; mark irrelevant categories as `not-applicable` and exclude them from the score denominator. Do not invent certainty or convert heuristics into official failures.241242Each finding should include:243- Severity: `critical`, `warning`, or `info` (use impact/effort fields for prioritization beyond severity).244- Confidence: high, medium, or low.245- `evidence_grade`: `official`, `live`, `field`, `tool`, `lab`, `synthetic`, or `heuristic`.246- `measurement_method`: scan, tool, probe, source, or command used.247- `source_tier`: `official-doc`, `observed-file`, `live-observation`, `field-data`, `tool-output`, `lab-result`, `synthetic-probe`, or `research-backed-heuristic`.248- Evidence: command output, URL, local file path, browser observation, or saved probe result.249- Recommendation: specific action and expected impact.250- Owner surface: code, content, infrastructure, analytics, or external platform.251252</scoring>253254<optimize_loop>255256Use optimize mode when the user requests a maximum score, perfect score, continuous iteration, or "keep fixing until it passes" behavior. Interpret such requests as a bounded optimization process, never an unbounded loop.257258Loop rules:2591. Set and record a finite iteration budget, target, stable evaluator, baseline audit, and regression guards before changes. The default budget is three iterations unless the user sets a smaller bound.2602. Pick the highest-impact fix or recommendation with the best confidence/effort ratio.2613. Apply safe local code/content fixes when they are in scope; otherwise record an actionable recommendation.2624. Re-run only comparable relevant checks and record the evidence class, capability limitations, and unknown/not-applicable states.2635. Keep a change only if comparable evidence improves without triggering a regression guard; otherwise revert it where possible or mark it `discarded`.2646. Stop at the target, budget, plateau, a guard failure, no safe local fixes, or when remaining work requires external credentials or business decisions.265266Do not fake a perfect score. If external evidence is unavailable, report the unknowns, the best comparable verified result, and no guarantee of ranking, AI-feature inclusion, or citation.267268</optimize_loop>269270<validation>271272At completion, `.hyper/seo-maker/[slug]/` should contain:273274- `results.json` with structured audit results and status `complete` for complex or optimize mode.275- `dashboard.html` rendered from the latest results when dashboard output is expected.276- `results.js` for local browser fallback when dashboard output is expected.277- `report.md` with prioritized findings, score, and recommendations.278- `sources.md` with the evidence log.279280Validate:281282- Every critical or warning finding has evidence.283- Recommendations are specific enough for an engineer, marketer, or content owner to act on.284- Scores are derived from observed evidence, with `unknown` and `not-applicable` handled explicitly, not assumptions.285- Google AI features are described as using ordinary SEO fundamentals; eligible indexed/snippet-eligible pages can be considered, but inclusion is not guaranteed and no special schema or AI text file is required.286- FAQPage recommendations distinguish Google rich-result eligibility from answer-friendly visible FAQ content.287- `sources.md` is a source ledger with URL, date, applicable claim, evidence class, and limitations for source-sensitive claims.288- Optimize mode records the baseline, evaluator, finite budget, guards, changes/recommendations, re-audit evidence, discarded iterations, stop reason, and best comparable verified result.289290</validation>
alpoxdev