Skill: Standing SEO/AEO Principles

The "we already decided this — don't ask" file. Every SEO/AEO skill loads this first. The user has stated each rule below at least once. Do not re-ask.

When a new principle gets stated during work, append it here (via seo-learn) so future sessions inherit it.

1. Quality bar: world-class only

• Default goal is top of category, not "decent SEO". If a debate phase produces a "B-tier" path, it's NO-GO.
• Multi-agent debate (SEO + AEO + CRO + competitive intel) before any cornerstone page or new theme. Single-agent reasoning produces mediocre output.
• Every page must hit seo-autopilot's world-class quality bar checklist. No exceptions.

2. One-ID input, autonomous output

• User types a single ID/keyword/idea. Skills run end-to-end with no further user input until the page is shipped + monitored.
• Open-ended questions back to the user are a design failure. Per feedback_ai_drives_flow: AI proposes next step, user confirms or redirects.
• 3-Strike rule: only escalate to user after 3 failed auto-attempts on the same blocker. Otherwise solve it.

3. Multi-source from day 1

• Every data source goes through ts/src/lib/seo/sources/ adapter interface. No direct vendor API calls in generation scripts.
• Currently implemented: GSC, GA4. Pending: Ahrefs, PostHog, Bing Webmaster.
• Adding a new source = 1 adapter file + 1 line in registry. No skill changes.
• Citation engines (ChatGPT/Claude/Perplexity/Gemini) are 4 sources, not 1. Track share-of-voice per engine, not aggregated.

4. i18n from day 1

• Every new content type creates 3 locale dirs (/, -zh/, -ja/) at scaffolding time, even if zh/ja are empty placeholders.
• Hreflang matrix registers all locale URLs at deploy time. Crawlers see translation discovery on day 1; placeholder pages fall back to English.
• Translation lands asynchronously via pnpm seo:translate; URLs never change.
• Tycoon SEO supports 3 locales (en, zh-CN, ja). Adding a 4th requires only lib/i18n/locales.ts update + scaffold-locale CLI run.

5. Template-first production

• New theme → pnpm seo:new-type (creates locale dirs + prints wiring blocks)
• Existing template → pnpm seo:new-page (single or comma-separated batch)
• Never hand-craft JSON. Always use the CLI; it enforces uniqueness, slug validation, locale-dir creation, audit-gate hookup.
• Programmatic SEO at ≥ 50 pages requires ≥ 300 unique words per page or it gets deindexed.

6. Audit auto-runs, never blocks

• audit-seo.yml GHA runs post-deploy on every push to main.
• Failure → Lark notification + auto-enqueued fix task. Does not block merge or revert.
• Hard merge gates are an anti-pattern in this team — there is no human reviewer waiting to gate things; per lessons.md "no human review gates", design must be safe-by-construction not "we'll catch it in review."

7. Privacy: no internals leaked

• No internal vendor names, internal model IDs, internal skill names, cost data, prompt strings, internal slugs in any public surface (page JSON, llms.txt, ai-plugin.json, OG image, blog, social copy).
• Markdown render strips placeholders. Audit script flags TODO/XXX/FIXME/placeholder strings before publish.
• "Generic capability claim" OK ("AI generates the brief"); implementation detail not OK.

8. AEO is half the game

• Brand mentions correlate with AI citation 3× more than backlinks (Ahrefs 2025, n=75K). Off-page (Reddit / YouTube text-trail / Wikipedia / LinkedIn) is mandatory.
• Markdown layer (.md parallel to HTML) drives +300% citations (G2 experiment). Already wired via lib/seo/markdown-renderer.ts. Every new content type must register a markdown render arm.
• AI engines re-crawl on 30-60 day cycles. Do not declare "X didn't work" before week 8.

9. Memory + continuity

• Every cornerstone page experiment is logged via seo-experiment-log BEFORE shipping. Hypothesis + measure_at date.
• Day 14 retro on every experiment via seo-retro. Day 30 if monthly cadence.
• Patterns extracted via seo-learn monthly → fed back into autopilot Phase 1 debates.
• The user expects perfect memory across sessions. Re-stating a preference is a bug. New preferences land in this file.

10. Visible "Last updated"

• Every page must render Last updated: YYYY-MM-DD visibly (footer or near H1).
• AirOps measured +1.8× citation rate from this single change. Cost is one line of JSX. Always do it.
• updatedAt in JSON drives this; audit checks freshness within 90 days.

11. CTA discipline

• SEO landing CTAs (cold traffic) → signup or chat, never directly to Stripe checkout.
• /pricing (warm traffic) CTAs may go to checkout.
• Per feedback_seo_landing_cta_to_signup: cold → product entry, not paywall.
• No "click here" anchor text. Always descriptive (e.g., "Compare alternatives to Tycoon").

12. Design discipline

• No purple / indigo / violet anywhere. Forest green #1B4D2E brand. Warm parchment #F8F7F4 background.
• Hardcoded hex banned outside lib/tokens.ts. Use semantic Tailwind tokens.
• New components import from @/components/ui/ds only.
• New SEO pages MUST use SeoPageLayout or equivalent — not free-form layouts.

13. PostHog tracking

• Every new SEO page with a primary CTA fires a _ PostHog event server-side AND client-side.
• Event names: seo__view, seo__cta_click, etc.
• Not optional. Page is incomplete without it.

14. Programmatic content gate

• Catalog/directory pages target 100+ entries as default fullness. 12 entries is a starter scaffold, not a shipped product.
• If the data source can't fund 100+ unique-content entries, scope down or wait. Don't ship 12 and call it done.

15. Don't fake content

• AI fills JSON only when it has actual research, real data, real sourced facts. Never invent numbers, statistics, dates, or attributions.
• If a fact-anchor field can't be filled with real data, the page is NO-GO.
• "Industry average" claims need a source; audit script flags unsourced numbers in en content.

16. Don't write death-by-bullets

• Bullet lists mixed with prose. ≥ 30% of body words must be in flowing sentences, not bulleted fragments.
• Tables for comparison data, not for bulleted lists in disguise.

17. Refresh cadence

• Cornerstone pages: refresh every 60-90 days (AI engines weight freshness; AirOps research)
• Programmatic pages: refresh quarterly via batch update of source data
• AEO discovery files (llms.txt, robots.txt, ai-plugin.json): refresh quarterly via aeo-assets
• Old pages without recent edits trigger automatic refresh prompt via seo-monitor

18. Bail conditions for any SEO experiment

• Hit measure_at date with metric < 50% of target → seo-postmortem auto-fires
• Page deindexed within 30 days → emergency review (not auto-revert; investigate cause)
• Citation share-of-voice drops > 30% week-over-week → aeo-postmortem (or general postmortem)
• Negative organic CTR after rewrite → revert to prior title/description, log lesson

19. The user wants Tycoon in Lark

• All SEO automation status / experiment results / weekly retro → Lark webhook (existing webhooks in CLAUDE.md). Not Slack, not email.
• Daily 06:00 morning brief consolidates: shipped pages + GSC delta + AEO delta + 1-3 actions for the day.

20. Tools live in tycoon.us

• All SEO automation reads SEO_CONFIG.siteUrl = https://tycoon.us (ts/src/lib/seo/config.ts).
• Multi-tenant note: when running SEO autopilot for a customer of Tycoon (not for Tycoon itself), workspace context provides domain — never hardcode tycoon.us in skill output.

---

Appendix: when this file should grow

Append to this file whenever:

• The user states a new SEO/AEO preference during a session
• A seo-learn monthly extraction promotes a pattern to a standing rule
• A seo-postmortem finds a recurring root cause that should become a guardrail

Each entry: numbered, one-paragraph. Cite the lesson source if applicable.

Never delete principles. Mark them deprecated with a date if a rule changes.