docs(plans): GEO/SEO strategy design doc + 5 phase files

[matheuspoleza]

Summary

Adds a complete design doc + 5 self-contained phase files for making Vertz discoverable to LLMs and driving organic traffic via GEO (generative engine optimization) + SEO.

The core insight: LLMs in 2026 (ChatGPT search, Claude web, Perplexity, Gemini) cite whatever the top 3 web search results say. Ranking #1 for a long-tail query = instant LLM citation. We do not need to wait for the next training cutoff.

What's in this PR

Main design doc (plans/geo-seo-strategy.md, 461 lines):

• Problem statement, goals (G1-G8), non-goals
• Manifesto alignment (8 principles → how each is honored by the strategy)
• 3-layer architecture: foundation → authority → autonomous engine
• Only 4 content formats allowed (comparison, gotcha, tutorial, opinion)
• Autonomous pipeline design (8 agents, 2 human gates, ~10 min/post human time)
• Success metrics with concrete 6-week acceptance thresholds
• 5 E2E acceptance scenarios
• 9 mapped risks with mitigations
• 6 open questions for reviewer decisions (budget, MCP scope, launch order, etc.)

5 phase files (plans/geo-seo-strategy/phase-NN-*.md):

1. Phase 1 – Foundation Infrastructure (7d): @vertz/docs-mcp public MCP server, llms-full.txt, expanded JSON-LD (TechArticle/SoftwareApplication/FAQPage), IndexNow + Google Indexing API, PostHog+Plausible analytics, citation tracker baseline
2. Phase 2 – Ignition Content (10d, parallel): flagship LLM benchmark post with reproducible benchmarks/llm-codegen/, 3 vs-X comparisons, 30 long-tail landing pages, README rewrite, awesome-list submissions
3. Phase 3 – Distribution Blitz (7d): HN launch, Product Hunt, Reddit (4 subs, 4 angles), newsletter sponsorships (3 budget scenarios), influencer outreach, Stack Overflow seeding, GitHub Discussions
4. Phase 4 – Autonomous Pipeline (11d): 7-agent pipeline on @vertz/agents — topic picker, writer, code validator (runs every snippet through vtz test), adversarial reviewer, publisher, Slack approval UI, optional Semrush signal
5. Phase 5 – Measurement & Iteration (ongoing): daily citation tracker cron, leading-indicator dashboard, weekly retros, pipeline eval loop against golden set, referrer attribution model, rolling 90-day roadmap

Why submit this as a PR now

• Let's review the strategy with the same rigor we apply to code features
• Adversarial review is scheduled in parallel (multiple angles: strategic, technical feasibility, manifesto alignment)
• The 6 open questions need decisions before Phase 3 kicks off
• Merging means the plan is a working document we can iterate on; keeping it on a branch invites it to go stale

Not in scope for this PR

• Implementation of any phase (phases will be their own PRs / branches, per .claude/rules/local-phase-workflow.md)
• Creation of the GitHub issue (per .claude/rules/ticket-system.md — will follow after design approval)
• Budget commitments (one of the 6 open questions)

Test plan

• Review plans/geo-seo-strategy.md top to bottom
• Confirm manifesto alignment claims are honest (no forced fits)
• Challenge the 6 open questions — decide before Phase 3
• Verify phase files are actually self-contained (another agent could pick one up cold)
• Check that acceptance criteria are concrete and testable (not "it works")
• Pressure-test the timeline — is 21-28 days realistic?

🤖 Generated with Claude Code

[matheuspoleza]

Adversarial review — 3 reviewers, consolidated

Full write-ups in reviews/geo-seo-strategy/:

• 00-consolidation.md — agreement matrix + blockers ranked by reviewer-confidence
• 01-strategic-adversarial.md — skeptical-investor lens
• 02-technical-feasibility.md — principal-engineer lens
• 03-manifesto-positioning.md — most-principled-engineer lens

TL;DR verdict

Do not execute as written. Strategic foundation is sound (3/3 reviewers agree on layered architecture, MCP server, citation tracker, 4-format constraint). Execution has 3 compounding defects + 2 manifesto violations that need fixing first.

5 top blockers (ranked by reviewer agreement)

#	Blocker	Confidence
B1	Hidden phase-zero: plan references files only on unmerged feat/2947-blog branch; merging #2947 is not in any phase	1/3 (technical)
B2	Benchmark methodology adversarially fragile — n=5, 1 LLM only, "if competitors ≥80% revise methodology" = p-hacking	3/3
B3	Timeline 50–60% optimistic — realistic 8–10 weeks for full acceptance, not 28 days	2/3
B4	SO secondary-account seeding = sockpuppeting — violates SO ToS + manifesto ethics	2/3
B5	No strategy-level kill-switch — every result justifies continuation; name a week-6 threshold that STOPS	2/3

Manifesto violations (must-fix before Phase 4)

• M1. Writer agent impersonating Matheus's first-person voice = identity laundering. Needs visible author: autonomous-pipeline (reviewed by Matheus) byline, or restrict pipeline to /answer/* surface.
• M2. "Distribution Blitz" / "weaponize" — hype language in the plan itself, same tone writer prompt bans in output.
• M3. "One way to do things" table claim is violated by 11-channel × 4-angle distribution matrix. Be honest: distribution is the one place ambiguity is accepted.

10 open decisions Matheus needs to answer

Full list in 00-consolidation.md. Most critical:

1. Who (external) reviews benchmark methodology pre-run?
2. If benchmark shows Vertz 65% / Next.js 70%, do we publish? (Pre-commit)
3. AI-authorship disclosure — yes or no?
4. SO seeding — remove secondary-account pattern? (Recommended: yes)
5. Timeline: accept 8–10w for full scope, or keep 28d as scope-cut v1?
6. When does feat(landing): blog — dogfood Vertz stack at /blog #2947 merge?
7. What week-6 metric threshold STOPS the strategy? Name it now.

What's genuinely strong (3/3 reviewer agreement)

• MCP docs server (manifesto-aligned, highest integrity, largest leverage)
• Citation tracker as day-1 deliverable (measurement discipline is rare and correct)
• Layered architecture (foundation → authority → engine)
• 4-format content constraint
• "If Vertz <60%, don't publish" acceptance criterion (diagnostic, not marketing)
• Code validator (dogfood of Principle 1 applied to content)

Recommended next moves

1. Don't merge yet. Address 5 blockers as new commits on this branch.
2. Answer the 10 open decisions.
3. Run one more adversarial review on the revised plan.
4. Then merge + open phase issues.
5. Execute Phase 0 (merge feat(landing): blog — dogfood Vertz stack at /blog #2947) + scope-cut Phase 1 in first 14 days. Reassess based on measured pace.

[matheuspoleza]

Round-2 revisions pushed

All 3 remaining blockers + 5 should-fix items from the final adversarial review are fixed in commit 4f72a72bc.

Blockers

• M1 body contradiction (phase-04 line 105): writer prompt now says "informed-but-neutral technical writer." Added militaristic-word ban. No more "Persona: Matheus" impersonation.
• Stop Condition 2 depended on deferred analytics: now notes prerequisite + Cloudflare Worker referer-log fallback as v1 proxy.
• Phase files misaligned with v1 scope: DEFERRED banners added to every task not in v1 scope. phase-01 Task 4, phase-02 Tasks 2-5, phase-03 Tasks 2-5, phase-05 Tasks 2-6.

Should-fix

• Renamed phase-03-distribution-blitz.md → phase-03-distribution-launch.md via git mv. "Reddit blitz" → "Reddit rollout" throughout.
• Fixed Phase 2 done-when arithmetic (was "total 7" with duplicated entries; now correctly 6 posts).
• ASCII layer diagram annotates v1 vs post-v1 content per layer.
• North Star reframed: "nailed it on the first try" is now explicitly internal-only; external comms use comparative+probabilistic framing or "judge transcripts yourself."
• Explicit decision dates added to 3 open questions (case-study task count, external reviewer, stop calibration).

Summary of plan status

All 5 original blockers (B1–B5) verified resolved by last review.
All 3 manifesto issues (M1–M3) now resolved in this round.
All 5 new issues from round-2 review resolved.

Ready for code review from Matheus. If another adversarial pass is desired, I can spawn one — otherwise the plan is merge-ready pending human review.