What is the Programmatic SEO agent skill?

How to design and run a programmatic SEO program that produces durable traffic instead of penalty-bait. It stands out by giving search and SEO workflows a defined shape, so the agent asks for better context and returns a more usable result.

What inputs does Programmatic SEO need?

Context for search and SEO workflows: your goals, audience, constraints, and any source material the skill asks for.

What does Programmatic SEO output?

A ready-to-use result for search and SEO workflows: the analysis, copy, or recommendations the agent produces.

Programmatic SEO

Quick answer

01What is it?: How to design and run a programmatic SEO program that produces durable traffic instead of penalty-bait. It stands out by giving search and SEO workflows a defined shape, so the agent asks for better context and returns a more usable result.
02Inputs: Context for search and SEO workflows: your goals, audience, constraints, and any source material the skill asks for.
03Output: A ready-to-use result for search and SEO workflows: the analysis, copy, or recommendations the agent produces.

Add this skill

Install-only

Install as a package

Installs this one skill package for your coding agent, including any supporting files that skill ships with — not every skill in the repository. Read the tutorial.

Terminal

$ npx skills add rampstackco/claude-skills --skill programmatic-seo

Skill instructions

The instruction file for this skill. The skill also includes other files you need to install to use it.

SKILL.md

Preview only — coding agent install

Programmatic SEO

A senior SEO strategist's playbook for designing and running programmatic SEO programs that produce durable traffic instead of penalty-bait.

Programmatic SEO has a complicated reputation. Sites like Zillow, Airbnb, TripAdvisor, Indeed, and Yelp have built billion-dollar traffic engines on pSEO. Other sites have built pSEO programs that got hit by Google's helpful-content updates and lost 80% of their traffic in a week. The difference is rarely the technique; it is the underlying data quality and the quality control discipline at scale.

This skill is the playbook for getting that distinction right. It assumes you have decided what keyword space to target (see seo-keyword) and how the broader content program is shaped (see content-strategy). It does not write individual editorial pieces (see content-and-copy for that) and does not architect editorial topic hubs (see pillar-content-architecture for that). What it does is teach the discipline of generating high-volume pages programmatically from structured data sources without producing thin content, duplicate content, or scale-without-substance pages that get penalized.

When to use this skill: deciding whether pSEO is a fit for the program at all (the most important question), designing a new pSEO system, auditing an existing pSEO set that is not ranking or has been hit by an algorithm update, or building quality-control discipline for a pSEO program that grew faster than its quality processes.

What this skill is for

This skill spans scaled-content programs from data source through quality control. It composes with five sister and adjacent skills, and the distinction between them is what keeps each one sharp.

content-strategy is program-scope: editorial pillars, calendar, governance. Decides whether pSEO fits the program at all.
pillar-content-architecture is hub-scope: one topic with 10 to 15 intentional editorial pieces. Editorial in nature.
content-brief-authoring is per-piece scope: brief for one editorial artifact.
content-and-copy is execution scope: writing individual editorial pieces.
This skill is scaled scope: 100s to 100,000s of pages generated programmatically from structured data sources, each targeting a long-tail query.

The clean reading order: content-strategy decides whether pSEO is a fit, seo-keyword surfaces the long-tail keyword space, this skill designs the pSEO system, editorial-qa (forthcoming) provides the QA discipline for sampled quality control across the set. content-and-copy and content-brief-authoring are not in the loop for pSEO at scale; those skills are for editorial pieces, not data-driven generated pages.

The audience: SEO content strategists, content engineers, agencies running pSEO programs, in-house teams considering pSEO as a growth lever. The voice is senior SEO strategist to junior PM or marketer. Specific, opinionated, honest. The reputation problem is not pSEO; it is pSEO without underlying value.

When pSEO is the right answer

The keystone question. pSEO works when all of the following are true.

1. Real underlying data. A genuine structured data source with depth: 10+ fields per record, ideally 20+, with first-party data, expert-curated data, or licensed datasets. Not just scraped data or AI-generated facts dressed as structured records.

2. Long-tail query volume justifies the effort. The queries the program would target have meaningful aggregate volume even if individual queries are small. Real estate "homes for sale in {neighborhood}" works at scale. "Blue widget reviews 2026" generated for every adjective times widget combination does not, because the queries are not actually searched.

3. User intent is queryable. The user's question can be answered through structured data presented well. Not through narrative explanation, judgment, or analysis the data cannot supply.

4. Update cadence aligns with query volatility. Real estate listings update daily and the data refresh aligns. "Best [thing] for [year]" pages get stale annually and need a refresh discipline budgeted in.

5. Quality control is operationally feasible. The team has the capacity to sample-audit the set, fix failures, and maintain quality as the set grows. Not aspirationally; budgeted in headcount.

pSEO does NOT work when:

The underlying data is shallow (3 to 5 fields, mostly AI-generated, no first-party signal)
The query volume is illusory (long-tail keywords nobody actually searches)
User intent requires narrative or judgment that data cannot supply
Quality control is not budgeted (write a bunch of pages, ignore them)
The program is scaling AI-generated thin pages without unique data

The honest framing. Most teams that ask "should we do pSEO?" should hear "probably not, unless the underlying data is unique or first-party expertise makes the pages actually useful." The reputation problem is not the technique; it is the technique applied without underlying value.

Detail in references/when-pseo-works-decision.md.

Data source identification

The data source is the pSEO program. Common sources with different defensibility profiles.

First-party data. Customer transactions, content database, user-generated content. Defensible because nobody else has it. Examples: Glassdoor's employee reviews, Yelp's user ratings, TripAdvisor's traveler reviews.

Licensed datasets. Industry databases, regulatory data, government datasets, licensed third-party feeds. Defensible by license terms and integration depth. Examples: Zillow's MLS partnerships, real estate brokerage feeds, sports statistics licenses.

Aggregated public data. Scraped, cleaned, enriched. Judgment call on legality (often gray area depending on robots.txt, terms of service, jurisdictional rules). Defensibility depends on the cleaning and enrichment work. Easy to copy if the cleaning is shallow.

Expert-curated content. The dataset is built by hiring experts to populate it. Slow, high-quality, defensible. Examples: Wirecutter's product testing, expert-reviewed medical content, curated editorial databases.

Synthesized data. Combining multiple sources into a unique view. "Neighborhoods times schools times prices" combining three datasets into a comparison view. Defensibility comes from the synthesis logic and the ongoing maintenance of multi-source pipelines.

The "moat" question. Would a competitor be able to replicate the data source? If yes, the pSEO program has no defensibility; anyone can copy. If no, the data source becomes a moat that compounds. Zillow's MLS partnerships, Glassdoor's employee reviews, Crunchbase's funding data, are moats. "Scraped Wikipedia plus AI rewrite" is not.

Detail in references/data-source-identification-patterns.md.

Template design

The template is the structure that data fills. Design principles.

Above-the-fold answer. The user's specific question answered in the first 200 words of the rendered page, structured for both human reading and AI extraction. The answer is what gets cited; the rest is supporting depth.

Variable density. The template accommodates records with sparse fields (some have 5 data points, others have 50) without looking broken. Sparse pages need fallback patterns; dense pages need progressive disclosure to avoid overwhelming.

Heading hierarchy that reflects data. H2s and H3s map to data sections (overview, details, comparisons, related). The heading structure is not decorative; it tells crawlers and AI engines what the page covers.

Schema markup as part of template. Structured data (JSON-LD, microdata, or RDFa depending on the stack) embedded in the template renders machine-readable signals at scale across the entire set. Without schema, the set is invisible to the structured-data extraction layer search and answer engines run.

Internal linking placeholders. The template includes link slots for related-record cross-references, parent-category links, and sibling-record links. 5 to 15 internal links per page is typical for a well-linked set.

Distinctive value per page. Each generated page must offer something the user could not get by going up to the parent or sideways to a sibling. If the page is just a re-pivot of the parent's data, the page is filler.

The template's quality bar. A randomly sampled page from the set, viewed in isolation, should answer the user's likely query competently. If a randomly sampled page is thin, the entire set is thin.

Detail in references/template-design-patterns.md.

Schema design

The data shape that drives the template. Design principles.

Field count signals depth. 5 fields per record is thin. 15 to 20 is competent. 30+ is deep. The field count is not a vanity metric; it determines what the template can render at depth versus what falls back to filler.

Required vs optional fields. Which fields must populate for a page to ship; templates need graceful degradation for optional gaps. A page with 3 of 30 optional fields populated should not ship; a page with 25 of 30 should.

Computed fields. Derived from source data. Average price per square foot computed from listings adds depth without requiring more source data. Computed fields are the pSEO equivalent of the writer adding analysis: the data does the analysis once, every page benefits.

Cross-record fields. Fields that reference other records in the set enable internal linking and comparison. The "5 most similar neighborhoods" field on every neighborhood page powers the sibling-link section without manual curation.

Update frequency tags. Which fields are static (geographic features, founding date) versus which need refresh tracking (current pricing, availability, current statistics). Without tagging, refresh becomes "audit everything" instead of "refresh the volatile fields."

The "schema-as-product" principle. The schema that drives pSEO IS the product surface. Treat it with the same rigor as a database schema for a customer-facing application. Versioned, reviewed, documented, breaking-change-aware.

Detail in references/schema-design-patterns.md.

Quality control at scale

Auditing all 100,000 pages individually is infeasible. The discipline.

Sampling strategy. Random sample 50 to 200 pages per audit cycle, balanced across data shape (sparse, dense, recent, old, popular categories, niche categories). The sample is not "the latest 50 pages"; it is a stratified sample that exposes problems specific to particular data shapes.

Automated checks. Heading structure, schema validity, internal link count, word count thresholds, duplicate-content checks, broken-link checks. Run on every page on a cadence; surface failures as a queue.

Manual review checklist. For sampled pages, check the top-200-word answer quality, check whether the page would satisfy the user's query, check whether the page reads as distinctive versus templated. The manual review is the layer automated checks miss.

Failure thresholds. If more than 5% of sampled pages fail the manual review, halt new generation and fix the template or data before scaling further. The threshold is not negotiable; without it, quality drift compounds invisibly until the algorithm update reveals it.

Cohort tracking. Pages generated in one period rank differently from pages generated in another? That signals a template change or data quality drift; investigate. Cohort tracking is the pSEO equivalent of the experimentation team's drift detection.

The team budget question. A 10,000-page pSEO set requires roughly 0.5 to 1.0 FTE of ongoing quality control discipline. If that is not budgeted, the program will decay. The set will look fine on launch and degrade over 6 to 12 months as data drifts, templates ship without QC, and the gap between the QC plan and the actual cadence widens.

Detail in references/quality-control-at-scale.md.

Internal linking across the set

pSEO sets need intentional internal linking architecture to compound.

Hub pages. Parent-level pages (e.g., "homes for sale in Denver") that link to all child pages (specific neighborhoods). Hub pages are linked from main navigation; they are the entry point for the set's traffic.

Sibling linking. Each page links to 5 to 15 related sibling pages: similar neighborhoods, similar price ranges, similar features. Sibling links are computed from cross-record fields in the schema; they are not manual curation at scale.

Reverse-direction linking. Child pages link up to hub; sibling links go both directions. The graph is bidirectional; PageRank flows both ways.

Anchor text variation. Avoid every page using the same anchor text. Vary by record characteristic (the record name, a descriptive phrase, the parent category). Uniform anchor text at scale signals manipulation to ranking systems.

Crawl-friendly architecture. Hub pages are linked from main navigation. Child pages are reachable via hub or via segmented sitemaps. No orphan child pages.

The PageRank flow principle. Internal linking is what makes pSEO sets compound. A well-linked set distributes ranking signal across all pages; a poorly-linked set has hub pages ranking and child pages orphaned. The link architecture is half the program; the data is the other half.

Detail in references/internal-linking-at-scale.md.

Crawl budget management

Search engines have crawl budgets. Large pSEO sets can exhaust them.

Sitemap segmentation. Split sitemaps by category or recency so crawlers prioritize active pages. A single sitemap with 100,000 entries is harder for crawlers to process than 10 segmented sitemaps with 10,000 entries each, organized by category or last-update.

Noindex on thin pages. Pages with insufficient data should noindex rather than ship as bait. The discipline: pages that fail the schema's required-field threshold do not get a public URL; they sit in the system as drafts until their data populates.

Canonical handling. Comparison pages (X vs Y) often have inverse pages (Y vs X). Canonicalize to one. Comparison-pivot duplicates without canonicalization split ranking signal.

Crawl rate signals. Monitor Google Search Console crawl stats. If crawl rate is plateauing while page count grows, the set is hitting budget limits. The fix is not "publish more pages"; it is "noindex thin pages and improve internal linking so crawlers prioritize better."

Pruning criteria. Pages that fail to attract clicks or impressions for 6+ months should noindex or 410. Pruning is hygiene, not failure. A 100,000-page set with 60% earning traffic is healthier than the same set with 40% earning traffic plus 60% dead weight crawlers waste budget on.

Detail in references/crawl-budget-management.md.

AEO and GEO for programmatic pages

Answer engines treat programmatic pages differently from editorial pages.

Direct-answer extraction. AI engines extract the top-200-word answer; templates that lead with the answer get cited. The opening of the page is the citation candidate; everything after it is supporting depth.

Structured data signals. JSON-LD with comprehensive schema is read by AI engines as authority signal at scale. Programmatic pages with minimal schema lose to programmatic pages with deep schema even when the underlying data is similar.

Citation patterns. AI engines tend to cite programmatic data pages for factual queries (prices, statistics, comparisons, factual details) and editorial pages for analytical queries (why, how, what should I think). Design templates to fit the factual-query lane; do not try to make programmatic pages compete for analytical queries that editorial content owns.

Quality crackdown sensitivity. AI engines have their own quality signals beyond search engines. Thin programmatic content gets deprioritized faster in AI surfaces than in traditional search. The pSEO penalty risk has migrated to AI surfaces; the same quality-at-scale discipline applies, with less tolerance.

The "two-engine optimization" framing applies. pSEO pages should serve both search engines and answer engines. Most pSEO programs were designed pre-AEO and need template updates for the new surface: stronger top-200-word answers, deeper schema markup, FAQPage schema where the page contains FAQ structure.

Detail in references/aeo-geo-for-programmatic-pages.md.

Refresh and maintenance at scale

pSEO sets decay if not maintained.

Data refresh cadence. Quarterly minimum for most datasets. Daily or weekly for time-sensitive data (real estate listings, prices, availability, current statistics). The refresh cadence is set when the program launches; retrofitting is expensive.

Template version migration. When the template improves, all existing pages need migration. Cohort-by-cohort migration with monitoring beats big-bang migration. Each cohort gets the new template, sits for 30 days under monitoring, then the next cohort migrates.

Pruning lifecycle. Pages generated 2+ years ago that have not earned traffic should be evaluated for noindex or removal. The 24-month checkpoint is the standard cutoff; some categories warrant earlier or later pruning.

Set-level refresh. Occasionally the entire set's template needs a refresh as user expectations evolve, AI engine signals shift, or category conventions change. Set-level refreshes are 6-month projects, not weekend cleanups.

Detail in references/refresh-at-scale.md.

Common failure modes

Rapid-fire. Diagnoses in references/common-pseo-failures.md.

"We generated 50,000 pages and got penalized." Thin content, scaled too fast, no QC discipline.
"We have 10,000 pages but only 200 rank." Internal linking architecture missing; child pages are orphans.
"Crawl rate plateaued." Crawl budget exhausted; noindex thin pages and improve sitemap segmentation.
"Pages look identical." Template lacks variable density; data is too sparse to differentiate.
"We cannot update the templates without 10,000 manual fixes." Template versioning was not designed for scale.
"Our quality control is whoever has time." No sampling discipline, no thresholds, no ownership.
"AI engines do not cite our pages." Top-200-word answer was not designed; structured data is thin.
"We are at 100,000 pages and engagement is dropping." The set has outgrown its data depth.
"Competitors copied our pages." The data source was not a moat.
"Refresh is overwhelming." Cadence was not designed for scale; templates are not migration-friendly.
"Our pSEO drives traffic but no conversions." Query intent does not match buyer intent; reconsider whether pSEO was the right channel for the program goal.

The framework: 12 considerations for programmatic SEO

When designing or auditing a programmatic SEO program, walk these 12 considerations.

Right answer for the program. pSEO needs real underlying data, queryable intent, and quality-control budget. Default to no if any is missing.
Data source as moat. Replicable data is not defensible; first-party, licensed, expert-curated, or synthesized data is.
Schema depth. 15+ fields per record minimum; 30+ for competitive depth.
Template variable density. Accommodates sparse and dense records gracefully.
Above-the-fold answer. First 200 words answer the user's specific query.
Schema markup at scale. Structured data on every page; this is the AEO/GEO signal.
Internal linking architecture. Hub-and-spoke plus sibling linking, no orphans.
Quality control sampling. 50 to 200 pages per audit, balanced across data shape.
Failure thresholds. 5% sample failure halts generation until template or data fixes ship.
Crawl budget discipline. Sitemap segmentation, noindex on thin pages, canonicalization on duplicates.
Refresh cadence. Quarterly minimum data refresh; cohort-by-cohort template migration.
Pruning lifecycle. Pages that fail to earn traffic in 12 to 24 months get noindexed or removed.

The output of the framework is a pSEO design document the team can reference at every stage: data source named, schema versioned, template specified, QC discipline budgeted, internal linking architecture mapped, refresh cadence set.

If required data is unavailable

This skill's output depends on data, measurements, or tool results it cannot generate on its own. When a required input, tool, or data source is unavailable or unverifiable, the sanctioned output is the deliverable with the gap stated: what was needed, what was actually obtained or verified, and which parts of the output are affected. Fabricating, estimating, or interpolating a required number to complete the deliverable is never sanctioned. A stated gap is a complete answer.

Reference files

references/when-pseo-works-decision.md - Five-criterion decision framework with worked examples of yes, no, and maybe.
references/data-source-identification-patterns.md - First-party, licensed, public, expert-curated, synthesized; defensibility analysis.
references/template-design-patterns.md - Variable density, above-the-fold answer, heading hierarchy, schema integration, link slots.
references/schema-design-patterns.md - Field count, computed fields, cross-record fields, update tags, schema-as-product.
references/quality-control-at-scale.md - Sampling strategy, automated checks, manual review checklist, failure thresholds, cohort tracking.
references/internal-linking-at-scale.md - Hub-and-spoke, sibling linking, anchor text variation, orphan prevention.
references/crawl-budget-management.md - Sitemap segmentation, noindex patterns, canonicalization, crawl rate monitoring, pruning criteria.
references/aeo-geo-for-programmatic-pages.md - Direct-answer extraction, structured data signals, citation patterns, two-engine optimization.
references/refresh-at-scale.md - Data refresh cadence, template versioning, cohort migration, pruning lifecycle.
references/common-pseo-failures.md - Eleven-plus failure patterns with diagnoses and fixes.

Closing: quality at scale or not at all

The only durable pSEO programs are the ones that hold quality at scale. The temptation to scale quantity at the cost of quality has produced the entire bad reputation pSEO carries. Sites that resist that temptation, that maintain real data depth, real quality control, real refresh discipline, keep producing meaningful traffic for years. Sites that do not get penalized within months of an algorithm update.

The discipline is not optional and it is not free. Budget for it before generating the first page, or do not start at all.

When in doubt about whether a pSEO program is ready, ask: is the data source actually unique, is the schema deep, does the template lead with the answer, is the internal linking architecture mapped, is QC budgeted in headcount, is the refresh cadence set? If yes to all of those, ship the design document and let the engineering work begin. If no to any of them, fix the gap before any pages generate.

Supporting file: references/aeo-geo-for-programmatic-pages.md

AEO and GEO for programmatic pages

Direct-answer extraction, structured data signals, citation patterns, two-engine optimization.

Answer engines treat programmatic pages differently from editorial pages. The differences shape how pSEO templates should be designed for the AI search era.

Direct-answer extraction

AI engines extract the top-200-word answer; templates that lead with the answer get cited.

The pattern. The opening of the page is the citation candidate. AI engines pull from the first answer-shaped paragraph, FAQPage schema entries, and structured-data fields. Everything after the opening is supporting depth that justifies the citation but is rarely cited directly.

Template implication. The first 200 rendered words must answer the user's specific query in a self-contained way. A page about "homes for sale in Denver under $500k" should answer that exact query in the opening: count of listings, average price, top neighborhoods, with structured data backing each claim.

Anti-pattern. Welcome paragraphs, navigation hints, "below you will find" filler. These dilute the citation candidate and reduce the page's AI-engine pull.

Snippet-bait paragraphs at H2 level. Beyond the top-200-word answer, each H2 should have a 40 to 60 word snippet-bait paragraph. AI engines often quote multiple snippet-bait paragraphs as multi-paragraph citations.

Structured data signals

JSON-LD with comprehensive schema is read by AI engines as authority signal at scale.

The "thin schema" penalty. Programmatic pages with minimal schema (just the basic Article or Product type, with required fields only) lose to programmatic pages with deep schema (complete schema graph, optional fields populated, cross-entity references). The underlying data may be similar; the schema markup is what AI engines see.

Schema patterns that signal quality at scale.

Type-appropriate schema. Product for product pages, LocalBusiness for location pages, Article for editorial pages, FAQPage for FAQ sections, BreadcrumbList for navigation context.
Cross-entity references. Schema entries that reference other entities in the dataset (relatedProduct, parentOrganization, hasPart) signal a connected knowledge graph rather than isolated pages.
Aggregate schema. Reviews, ratings, statistics presented as structured aggregateRating, aggregateOffer, aggregateProperty fields.
FAQPage schema on FAQ sections. AI engines (Perplexity especially) cite FAQPage-marked content heavily; programmatic pages that include FAQ sections should mark them.

Schema validation. Run schema validation on every page; failures produce silent invisibility in AI surfaces. The validation is automated and gates publish.

Citation patterns

AI engines cite programmatic data pages and editorial pages for different query types.

Factual-query lane. AI engines tend to cite programmatic data pages for factual queries: prices, statistics, comparisons, factual details, specifications, locations, ratings. The page renders the fact as structured data; the AI engine cites the structured data as the answer.

Analytical-query lane. AI engines tend to cite editorial pages for analytical queries: why, how, what should I think, recommendations with reasoning, opinions, judgments. Programmatic pages cannot compete in this lane; the data does not supply the analysis the user wants.

Implication for pSEO design. Design templates to fit the factual-query lane. Do not try to make programmatic pages compete for analytical queries that editorial content owns. The two lanes coexist; pSEO is one half of a two-lane content strategy.

The "hybrid page" pattern. Some pSEO programs add an editorial layer to programmatic pages (per-page expert commentary, AI-summarized analysis with human review). Hybrid pages can compete in both lanes when the editorial layer is genuinely substantive. Without substantive editorial layer, hybrid pages read as factual pages with filler attached and lose in both lanes.

Quality crackdown sensitivity

AI engines have their own quality signals beyond search engines. Thin programmatic content gets deprioritized faster in AI surfaces than in traditional search.

The migration of penalty risk. Pre-AI search era, thin pSEO sets could rank for 12 to 24 months before quality crackdowns hit. AI engines apply quality signals more aggressively. Thin pSEO sets in 2026 lose AI citations within 3 to 6 months even when traditional search rankings are still holding.

Signals AI engines use beyond traditional search signals.

Distinctiveness. Pages that read as templated boilerplate get deprioritized. Pages that surface page-specific data prominently get cited.
Source credibility. Pages with named authors, expert credentials, and citation chains get cited preferentially. Anonymous pSEO pages with no attribution lose to attributed pages.
Citation traceability. Pages that cite their underlying data sources (with links to the source) get treated as authoritative. Pages that present facts without sourcing get treated as unreliable.
Freshness. Pages with recent update dates get cited preferentially for time-sensitive queries. Stale pages lose AI citations even when traditional search rankings hold.

The implication. pSEO programs designed pre-AEO need template updates: stronger above-the-fold answers, deeper schema markup, FAQPage schema on FAQ sections, source citations on factual claims, named authorship where the program supports it.

Two-engine optimization

pSEO pages should serve both search engines and answer engines.

Both engines reward depth. Search engines reward comprehensive coverage; AI engines reward citation-ready depth. Same content, different extraction.

Both engines reward structure. Search engines parse heading hierarchy for ranking; AI engines parse heading hierarchy for citation extraction. Same structure, different use.

Both engines reward freshness. Search engines reward recent updates; AI engines re-index recently updated content more aggressively. Same updates, different cadence.

The two-engine implication. Designing for AEO does not trade off against SEO. The template improvements that earn AI citations (top-200-word answers, FAQPage schema, named authorship, source citations) also earn search rankings. Teams that treat AEO and SEO as separate optimizations under-invest in both.

Set-level reputation signals

Beyond individual page signals, AI engines apply set-level reputation. The set's overall quality affects each page's citation likelihood.

Domain-level reputation. A domain with a substantive editorial content layer plus a high-quality pSEO set ranks both layers more strongly than a domain with only pSEO. The editorial layer establishes the domain's expertise; the pSEO layer benefits.

Set-level signal compounds. A 10,000-page pSEO set with 90% high-quality pages and 10% thin gets the entire set treated as high-quality. The same set with 60% high-quality pages and 40% thin gets the entire set deprioritized. The bad pages drag the good ones down.

The implication. Set-level QC discipline (covered in quality-control-at-scale.md) is also AEO discipline. Holding the quality threshold across the set protects the set's AI-citation reputation, not just its search ranking.

Measurement

Hub-level AEO/GEO metrics worth tracking on the pSEO set:

Brand mention rate from AI search visibility tools (Profound, Frase visibility tracking, AirOps AEO data)
Citation share by engine (ChatGPT, Perplexity, Gemini, Claude, Google AI Mode) on the set's target queries
Top-cited pages within the set (which template patterns get cited most)
AI crawler hit frequency from server logs (GPTBot, PerplexityBot, ClaudeBot)

Track at the set level, not just per page. Aggregate trends surface patterns that per-page tracking misses.

Supporting file: references/common-pseo-failures.md

Common pSEO failures

Eleven-plus failure patterns with diagnoses and fixes. Cross-references to other reference files where applicable.

The pattern across most failures: pSEO programs that ship without one of the five readiness criteria (real data, queryable intent, sufficient volume, refresh cadence, QC budget) and assume the gap will close later. The gap rarely closes; the failure compounds.

"We generated 50,000 pages and got penalized"

Symptom. Algorithm update lands; the set loses 60 to 90% of its traffic in days.

Diagnosis. Thin content scaled too fast without QC discipline. The set was generating filler pages, sometimes from AI-summarized public data, sometimes from sparse first-party data with bolt-on AI text. The algorithm update detected the scale-without-substance pattern.

Fix. Halt new generation. Run a triage audit: which pages have substantive data backing them, which are filler. Noindex the filler. The remaining pages may recover ranking once the set's quality signal improves; the filler ones will not. Sometimes the right call is removing the entire pSEO surface and rebuilding from a higher-quality data source.

Prevention. The five-criterion check (when-pseo-works-decision.md) before launch. The QC discipline (quality-control-at-scale.md) before scaling.

"We have 10,000 pages but only 200 rank"

Symptom. Pages exist in the set; few of them rank for their target queries.

Diagnosis. Internal linking architecture missing or incomplete. Hub pages rank because they receive site-wide navigation links. Child pages do not rank because they have no in-page link votes; they are partial orphans reachable only via sitemap.

Fix. Build the link graph. Add sibling-link slots to the template. Compute cross-record similarity to populate sibling links. Backfill the link graph across the existing set. Audit for orphans; surface them in the QC queue (internal-linking-at-scale.md).

"Crawl rate plateaued"

Symptom. Page count grows; pages crawled per day stays flat or declines.

Diagnosis. Crawl budget exhaustion. The set has more pages than the search engine's crawl budget supports.

Fix. Noindex thin pages. Segment sitemaps. Improve internal linking so crawlers prioritize substantive pages. Reduce server response time. Prune the dead-page tail. Detail in crawl-budget-management.md.

The wrong fix: publishing more pages to "catch up" on traffic targets. More pages without crawl budget produces more dead weight, not more traffic.

"Pages look identical"

Symptom. Random sampling of pages from the set finds them indistinguishable in substance, only different in identifiers.

Diagnosis. Template lacks variable density, or the data is too sparse to differentiate. The template renders the same boilerplate for every record because the records do not actually differ on the dimensions the template surfaces.

Fix. Two paths.

If the template is the problem (the data has variation but the template hides it): redesign the template to surface distinctive fields prominently. Move the differentiating data above the fold; demote the boilerplate.
If the data is the problem (the records genuinely lack distinctive fields): the schema is too thin. Either deepen the schema with more source data, or accept that the program does not justify pSEO and pivot to editorial content.

"We cannot update the templates without 10,000 manual fixes"

Symptom. A template change requires manually editing every existing page.

Diagnosis. Template versioning was not designed for scale. Pages were generated as static output rather than as renders from the schema; updating the template now requires updating each rendered page.

Fix. Architectural rebuild. Pages need to be re-rendered from the schema each time the template changes. The schema is the source of truth; the rendered pages are the output. Without this discipline, every template change becomes a per-page migration project.

Prevention. Design pages as renders from data, not as static artifacts. The specific stack choice (build-time generation that re-runs on template change, server rendering with template version in the cache key, hybrid approaches) varies by team; the methodology principle is the same.

"Our quality control is whoever has time"

Symptom. No regular QC cadence. Sample audits happen sporadically when someone notices a problem.

Diagnosis. No sampling discipline, no thresholds, no ownership. The QC was assumed to be everyone's job, which means it is nobody's job.

Fix. Assign a QC owner. Set the sampling cadence (monthly minimum for active programs). Codify the failure threshold (5% sample failure halts new generation). Track cohort metrics. Detail in quality-control-at-scale.md.

"AI engines do not cite our pages"

Symptom. Traditional search rankings are stable; brand mention rate from AI search visibility tools is flat or declining.

Diagnosis. Multiple possible causes.

The top-200-word answer was not designed; pages start with welcome paragraphs instead of answers.
Schema markup is thin; AI engines see the pages as low-authority.
FAQPage schema is missing on FAQ sections.
Source citations are missing on factual claims.
The pages read as templated boilerplate rather than as distinctive answers.

Fix. Audit the template against the AEO/GEO patterns (aeo-geo-for-programmatic-pages.md). Update the template; migrate cohorts; monitor citation count by cohort to confirm the fix earned gains.

"We are at 100,000 pages and engagement is dropping"

Symptom. Traffic continues but bounce rate climbs, time-on-page falls, conversion rate decays.

Diagnosis. The set has outgrown its data depth. Early pages were the highest-data-quality records; later pages were lower-quality data backfilled to grow the set. Users are landing on pages that do not satisfy their query.

Fix. Reverse the growth and prune. The set should be smaller and higher-quality, not larger and lower-quality. Identify the data-quality threshold below which pages do not satisfy queries; noindex pages below the threshold; let the set's average quality recover.

Prevention. The required-field threshold in the schema enforces a quality floor. Pages that fail the threshold should not have shipped in the first place.

"Competitors copied our pages"

Symptom. A competitor launched a similar pSEO set; the brand's traffic share is shrinking.

Diagnosis. The data source was not a moat. The pSEO pages were replicable.

Fix. Two paths.

Deepen the data source. First-party data accumulation, expert curation investment, licensed-feed integration that competitors cannot match. The defensibility comes from the data, not from the pSEO build.
Pivot. If the data cannot be deepened, the program does not have a long-term moat. Consolidate the strongest pages, prune the rest, redirect the team to higher-defensibility work.

Prevention. The defensibility test (data-source-identification-patterns.md) before launch. If competitors could replicate the data source within 6 months at reasonable cost, do not launch the program.

"Refresh is overwhelming"

Symptom. Quarterly refresh cycles are missed or partially completed; data drifts; pages get stale.

Diagnosis. Refresh cadence was not designed for scale. The team thought "we will refresh quarterly" but the actual work to refresh 10,000 to 100,000 pages exceeds the team's quarterly capacity.

Fix. Automate the volatile-field refresh through data pipelines (mostly hands-off after pipeline build). Reduce slow-changing-field refresh frequency to annual on most fields. Cohort-migrate the template refresh rather than big-bang. Detail in refresh-at-scale.md.

If the work still exceeds capacity after these fixes, the set is too large for the team's resources. Prune to a sustainable size.

"Our pSEO drives traffic but no conversions"

Symptom. Traffic from pSEO pages is high; signups, sales, or engagement on the funnel goal are flat or low.

Diagnosis. Query intent does not match buyer intent. The pSEO pages are answering informational queries; the buyer the program needs to capture is searching with different intent.

Fix. Audit the queries the pSEO traffic is coming from. If the queries are not in the buyer's funnel, the program is producing non-converting traffic regardless of how well the pages are optimized. The fix is not "add more CTAs to pSEO pages"; the fix is recognizing that pSEO was not the right channel for the program's conversion goal.

The reconsider-pSEO moment. If the program's metric is conversions and the pSEO traffic does not convert, pSEO is the wrong tool. Editorial content with stronger buyer-intent alignment, paid acquisition with conversion tracking, or product-led growth surfaces may be the better fit.

"Our QC discipline drifted over time"

Symptom. The program launched with strong QC. Months in, the cadence slipped, the threshold became aspirational rather than enforced, the cohort tracking went unread.

Diagnosis. QC ownership rotated, accountability dispersed, the metric dashboard stopped being reviewed. The pattern is the same as the "set and forget" failure for editorial pillar maintenance.

Fix. Assign a durable QC owner with quarterly accountability. Reinstate the cadence. Audit the set for the drift that accumulated; fix or noindex pages that ship below the threshold.

Prevention. The QC owner is named in the program's planning doc and renewed annually. The dashboard that tracks cohort metrics has an actual owner who reviews it monthly. The threshold is treated as enforced, not aspirational.

The pattern across all failures

Most pSEO failures are designed-in. They were predictable from the program's launch shape. The five-criterion check, the schema-as-product principle, the QC budget, the refresh cadence, the link architecture: each one shipped or did not at design time. The set's eventual success or decay was largely determined before the first page generated.

The discipline is upstream. Hold the line at design time; the operational discipline at scale becomes manageable. Skip the design discipline; the program produces filler at scale and gets penalized.

Supporting file: references/crawl-budget-management.md

Crawl budget management

Sitemap segmentation, noindex on thin pages, canonicalization on duplicates, crawl rate monitoring, pruning criteria.

Search engines have crawl budgets. Large pSEO sets can exhaust them. Crawl budget management is the discipline that keeps the set crawlable as it scales past 10,000+ pages.

Sitemap segmentation

A 100,000-page sitemap is harder for crawlers to process than 10 segmented sitemaps with 10,000 entries each.

Segmentation by category. One sitemap per top-level category. Crawlers prioritize sitemaps differently; segmentation helps the crawler prioritize active categories over dormant ones.

Segmentation by recency. A "recent" sitemap surfaces pages generated in the last 30 days. Crawlers find new content faster; existing content remains crawlable through category sitemaps.

Segmentation by update frequency. A "frequently-updated" sitemap surfaces pages whose volatile fields refresh weekly or daily. Crawlers re-crawl these pages on a tighter cadence.

Sitemap index. A parent sitemap-of-sitemaps points to all segmented sitemaps. The index is what gets submitted to Search Console; the segments handle the actual page lists.

Sitemap size limits. 50,000 URLs per sitemap is the hard limit. 10,000 to 25,000 per segmented sitemap is the typical practical size; smaller is fine for niche categories, larger is fine for high-volume categories.

Noindex on thin pages

Pages with insufficient data should noindex rather than ship as bait.

The discipline. Pages that fail the schema's required-field threshold do not get a public URL. They sit in the system as drafts until their data populates.

Why noindex matters. Thin pages drag down the entire set's quality signal. Search engines and AI engines both apply set-level quality scoring; a set with 10,000 thin pages and 90,000 substantive pages scores worse than a set with just the 90,000 substantive pages, even though the absolute page count is lower.

Noindex implementation patterns.

The thin pages render with a noindex meta tag in the head.
The thin pages are excluded from the sitemap.
The thin pages are not linked from any other page in the set.

The "we'll fix it later" trap. Teams ship thin pages with index, follow and plan to backfill data later. The data backfill rarely happens; the thin pages accumulate; the set's quality signal degrades over time.

Canonical handling

Comparison pages and other pivot patterns produce duplicate-content risks.

The X-vs-Y pattern. A page comparing X to Y often has an inverse page comparing Y to X. The two pages cover the same content from different orderings. Canonicalize one to the other.

Canonical decision. Pick the canonical based on search volume, alphabetical order, or category hierarchy. The choice itself matters less than picking one consistently.

Other pivot patterns.

Filter pivots. "Homes in Denver under $500k" and "Homes under $500k in Denver" should canonicalize to one.
Sort pivots. "Top hotels in Paris by rating" and "Top hotels in Paris by price" might be distinct enough to live separately, or might canonicalize depending on the user-intent overlap.
Date pivots. "Best [thing] for 2025" and "Best [thing] for 2026" usually live separately because the content genuinely differs by year; canonicalization would lose the time-relevance signal.

The discipline. Canonical decisions are designed at template time, not retroactively. The template either generates canonical-pair URLs (and chooses one as canonical from the start) or it does not generate the duplicate at all.

Crawl rate monitoring

Search engines publish crawl statistics. Monitor them.

Google Search Console crawl stats. Pages crawled per day, average response time, crawl request distribution by category. Monitor monthly; investigate drops or plateaus.

Crawl rate plateauing while page count grows. The set is hitting crawl budget limits. The fix is not "publish more pages." The fix is:

Noindex thin pages to remove low-value crawl targets
Improve internal linking so crawlers prioritize the substantive pages
Segment sitemaps so the crawler can prioritize active categories
Reduce server response time so crawlers can crawl more in the same budget

Crawl rate dropping unexpectedly. Investigate. Common causes: server errors that the crawler is encountering, robots.txt changes that excluded important paths, sitemap submissions that broke, large-scale URL pattern changes without redirects.

Pruning criteria

Pages that fail to attract clicks or impressions for 6+ months should noindex or 410.

The 6-month checkpoint. A page that has been in the set for 6+ months and has earned zero impressions in Search Console is dead weight. The fix is not "wait longer."

Pruning options.

Noindex. The page stays accessible to direct visitors but is removed from the search index. Reversible if the page later starts earning impressions.
410 Gone. The page is removed entirely; the URL returns 410. Permanent; appropriate for genuinely obsolete content.
301 Redirect. The page redirects to a more-relevant alternative. Appropriate when the user's intent for the dead page can be served by an alternative page that still exists.

The 12-month and 24-month checkpoints. Pages that have not earned traffic by month 12 should be reviewed for noindex or removal; pages that have not earned traffic by month 24 should be removed unless there is a specific strategic reason to keep them.

Why pruning matters. Dead pages waste crawl budget. Crawlers visit them, find nothing useful, and the set's average quality signal degrades. Pruning concentrates the set's PageRank on the pages that earn traffic.

When the set is too large for the budget

Symptoms:

Crawl rate is permanently below the page count's natural crawl demand
New pages take weeks or months to get indexed
Existing pages drop out of the index unexpectedly
The site's overall ranking is degrading despite the set being substantively unchanged

The diagnosis is usually crawl budget exhaustion. The fix is set reduction (prune to the substantive pages), set restructuring (split into multiple subdomains or sites if appropriate), or technical optimization (server response time, sitemap discipline).

The temptation is to publish more pages to "catch up" with traffic targets. The temptation is wrong. More pages without crawl budget produces more dead weight, not more traffic.

Methodology vs implementation

The principles above are methodology: which pages to noindex, when to canonicalize, how to segment sitemaps, how to read crawl stats.

The specific implementation (the framework's noindex meta tag pattern, the sitemap generation library, the canonical link helpers, the deployment-time crawl-test integration) is stack-specific. Each team implements crawl budget management within their own stack's tooling; the methodology applies regardless of the implementation choice.

Supporting file: references/data-source-identification-patterns.md

Data source identification patterns

First-party, licensed, public, expert-curated, synthesized. Defensibility analysis for each pattern.

The data source IS the pSEO program. A weak data source produces a weak set regardless of template quality, internal linking, or QC discipline. A strong data source produces durable traffic that compounds across years.

Pattern 1: first-party data

Data the team owns because the business produced it.

Sources. Customer transactions, content database, user-generated content, support ticket history, internal product analytics, sales call records, customer feedback databases.

Defensibility. Maximum. Nobody else has the data. A competitor would have to build the same business and accumulate the same usage history to replicate.

Examples. Glassdoor's employee reviews (built by getting employees to submit). Yelp's restaurant ratings (built by getting users to rate). TripAdvisor's traveler reviews (built by getting travelers to write). Reddit's discussion threads (built by getting users to post).

Watchouts. Privacy and terms-of-service compliance. User-generated content used for pSEO needs explicit consent in the original collection terms; retrofitting consent is not legal in most jurisdictions. PII in pSEO pages is a separate liability.

The "moat compounds over time" effect. First-party data sources get stronger as the business runs longer. A 10-year-old review database is more defensible than a 2-year-old one with the same volume because the time-series depth itself becomes valuable.

Pattern 2: licensed datasets

Data acquired through commercial licensing.

Sources. Industry databases (real estate MLS, automotive VIN databases, sports statistics feeds), regulatory data (SEC filings, government statistics), third-party content licenses (medical content, legal precedent).

Defensibility. Medium to high. Defensibility depends on license exclusivity and integration depth. An exclusive license is a moat; a non-exclusive license that anyone can also buy is not.

Examples. Zillow's MLS partnerships (licensed feeds with depth integration). Sportradar customers building stats sites. Bloomberg Terminal customers building financial content. Real estate brokerages with regional MLS access.

Watchouts. License costs scale with usage; the unit economics need to work at scale. License terms typically restrict redistribution, which can complicate pSEO scaling (the data can power the pSEO pages but cannot be exported as a downloadable dataset).

Pattern 3: aggregated public data

Data scraped, cleaned, enriched from public sources.

Sources. Open government data, public web pages, academic research, public APIs.

Defensibility. Low to medium. Anyone can scrape the same sources; the defensibility comes from the cleaning and enrichment work. If the cleaning is shallow, the defensibility is none.

Examples. Sites built on government statistics (census data, BLS data). Sites built on academic research summaries. Sites built on public company filings (EDGAR data plus enrichment).

Watchouts. Legality is jurisdictional and often gray. robots.txt compliance, terms-of-service review, copyright considerations, anti-circumvention rules in some jurisdictions. The legal review is mandatory, not optional, even when the data is "public."

The "scraped Wikipedia plus AI rewrite" anti-pattern. The lowest-effort form of this category. The data is not really enriched (AI rewrite of public encyclopedia entries adds no defensible value). The pSEO sets built on this pattern are the ones that get penalized first when algorithm updates run.

Pattern 4: expert-curated content

Data produced by hired experts who populate the dataset by hand.

Sources. Expert-written reviews, expert-curated lists, professionally-tested products, professionally-evaluated services, professional translations.

Defensibility. High. The defensibility is in the curation cost. A competitor would have to hire and pay the same experts for the same time to replicate.

Examples. Wirecutter's product testing (experts test products in lab conditions). Consumer Reports' product reviews. Edmunds' car reviews. Specialty publications with paid expert contributors.

Watchouts. Slow to build. The set scales at the speed of expert capacity, not at the speed of automated generation. Budget reflects the headcount, not the engineering effort.

The combination pattern. Expert-curated content often combines with structured data (the expert reviews a car; the dataset captures the expert's score plus structured specifications) to produce pages with both narrative depth and queryable structure.

Pattern 5: synthesized data

Data produced by combining multiple sources into a unique view.

Sources. Multi-source pipelines that produce derived analyses unavailable from any single source.

Defensibility. Medium to high. Defensibility comes from the synthesis logic and the ongoing pipeline maintenance.

Examples. "Neighborhoods times schools times prices" combining three datasets into a comparison view. "Companies times salaries times employee reviews" combining three sources into a candidate-decision view. Aggregator pages that show "best X for Y use case" combining multiple product databases with use-case classification.

Watchouts. The synthesis logic is the moat, not the underlying sources. Changes to source schemas break the pipelines. The pSEO program inherits the operational fragility of multi-source pipelines.

The defensibility test

For each candidate data source, walk this question: would a competitor be able to replicate this source within 6 months at reasonable cost?

Yes, easily. No moat. Pursue editorial content instead, or invest in expert curation to build a moat.
Yes, with effort. Partial moat. The first-mover advantage matters; ship before competitors.
No, requires major investment. Real moat. pSEO compounds.
No, requires assets the competitor cannot acquire. Strongest moat. The pSEO program becomes a long-term competitive advantage.

Combining patterns

The strongest pSEO programs combine multiple patterns.

First-party data plus licensed data (Glassdoor: user reviews plus salary licenses)
Licensed data plus expert curation (Wirecutter: licensed product databases plus expert testing)
First-party data plus synthesized data (Yelp: user ratings synthesized with location data and external attributes)

Single-pattern programs are simpler to ship but easier to replicate. Multi-pattern programs are harder to build and harder to copy.

Supporting file: references/internal-linking-at-scale.md

Internal linking at scale

Hub-and-spoke, sibling linking, anchor text variation, orphan prevention.

The internal-link graph is half the program; the data is the other half. A well-linked pSEO set distributes ranking signal across all pages and compounds. A poorly-linked set has hub pages ranking and child pages orphaned.

Hub-and-spoke architecture

The standard pSEO link topology.

Hub pages. Parent-level pages that aggregate the children. "Homes for sale in Denver" is a hub for the neighborhoods; "Software engineer salaries" is a hub for the company-specific salary pages; "Hotels in [city]" is a hub for individual hotel pages.

Hub-level discipline.

Hub pages are linked from main site navigation, not just from sitemaps. Crawlers reach hubs first and traverse to children from there.
Hub pages link to all children in the category. The hub's body or a paginated listing exposes the full set.
Hub pages are not just link aggregators; they have their own content (category overview, comparison tables, top-of-category aggregates) that earns ranking on its own.

Spoke pages. The individual records. Each spoke links up to the hub and laterally to siblings.

Sibling linking

Each page links to 5 to 15 related sibling pages.

The pattern. The sibling-link section of the template renders 5 to 15 related records computed from cross-record fields in the schema. Most-similar-by-attribute, similar-price-range, similar-features, geographic neighbors.

Why sibling linking matters. Without it, the link graph is a star (hub to spokes only). PageRank concentrates at the hub; spokes get minimal flow. With sibling linking, the graph is dense; PageRank distributes across the set.

Bidirectional linking. Sibling links go both directions. If A links to B as a sibling, B should link to A. Asymmetric sibling linking creates ranking dead ends.

Avoiding the "everyone links to everyone" trap. Every page linking to every other page is a complete graph; anchor text relevance dilutes; the link graph reads as algorithmic rather than semantically meaningful. The 5 to 15 sibling-link cap keeps each page's outbound graph navigable and signal-dense.

Reverse-direction (bottom-up) linking

Spoke pages link UP to hub.

The first-200-words pattern. The spoke page's introduction includes a contextual link up to the hub: "This page covers [specific record]. For the broader [category] overview, see [hub page]."

The closing pattern. The spoke page's closing includes a link back to the hub or to the next-most-relevant sibling, giving readers a navigation path back to broader content.

Why bottom-up matters. Without it, the hub does not compound. The spokes inherit traffic from their long-tail queries; without bottom-up links, that traffic does not flow back to lift the hub.

Anchor text variation

Avoid every page using the same anchor text.

The principle. Anchor text is the signal that tells search engines what the linked-to page is about. Identical anchor text across thousands of links to the same page reads as manipulation; varied anchor text reads as natural authority.

Variation patterns for pSEO.

Record-name variation. "View [neighborhood name]" / "[neighborhood name] homes for sale" / "Browse [neighborhood name] listings" / "[neighborhood name] guide" used across different siblings linking to the same record.
Descriptive variation. Anchor text that describes the linked page's distinctive attribute. "Affordable [neighborhood]" / "Top-rated [neighborhood]" / "Family-friendly [neighborhood]" computed from the target record's attributes.
Context-driven variation. The anchor text shifts based on what the linking page is about. A page about prices uses price-relevant anchor text; a page about schools uses school-relevant anchor text.

Anti-pattern. Every sibling link uses "[Record name]" as the anchor. Easy to ship at scale, signals manipulation, dilutes the page's anchor profile.

Crawl-friendly architecture

Hub pages are linked from main navigation. Child pages are reachable via hub or via segmented sitemaps. No orphan child pages.

Sitemap segmentation. A pSEO set with 50,000 child pages does not put all 50,000 in a single sitemap. Segment by category, by recency, by data freshness. Crawlers process segmented sitemaps more reliably.

Sitemap-only access is not enough. A child page only reachable via sitemap, with no other page linking to it, is a partial orphan. Crawlers may visit it; the page will struggle to compound ranking signal because no in-page link votes for it.

The orphan check. Pages with zero inbound internal links besides the sitemap are orphans. Audit quarterly; surface in QC. The fix: add the page to the hub's listing, add it to sibling sets it should belong to, expose it through breadcrumb navigation.

The PageRank flow principle

Internal linking is what makes pSEO sets compound.

The pattern that compounds. Hub linked from main nav (high PageRank concentration). Hub links to all children (PageRank distributes). Children link laterally to siblings (PageRank circulates within the set). Children link back up to hub (PageRank reinforces).

The pattern that does not compound. Hub linked from main nav. Hub links to children. Children do not link to siblings, do not link back to hub. PageRank flows hub-to-child but does not circulate; child pages slowly accumulate independent ranking signal but never compound.

The auditable signal. Average internal-links-in per page. The set's average should be 8 to 20 inbound internal links per page. Below 5, the set is under-linked and orphans dominate. Above 30, the set is link-dense and anchor signal dilutes.

Linking inventory

Maintain an inventory of every internal link in the pSEO set.

Inventory format. A queryable dataset (typically a database table or analytics schema) tracking source page, target page, anchor text, link slot (breadcrumb / hub / sibling / related-record / related-content), link direction, last-validated date.

Why inventory matters.

Quarterly audits run queries against the inventory: orphan check, sibling symmetry check, anchor diversity check, broken-link check.
Template changes that affect linking (slot adjustments, anchor pattern changes) can be analyzed against the inventory before shipping.
Pruning decisions reference the inventory: "if we noindex these 200 pages, what siblings lose links and need their slots refilled?"

The "no inventory" failure. Without inventory, audits become "crawl the site each time," which is slow and produces inconsistent results. The inventory turns audit into a query operation.

When linking architecture is broken

Symptoms:

Hub pages rank, child pages do not (under-linked spokes; add sibling linking)
Specific category cluster does not rank as well as siblings (the category's internal links are sparse; investigate)
Crawl rate plateaus while page count grows (link graph cannot absorb new pages; sitemap and link slots need restructuring)
Algorithm update hits child pages disproportionately (children read as orphans without hub-and-spoke reinforcement)

The fix is rarely "more pages." The fix is usually "better link graph through the existing pages." Internal linking is the structural multiplier.

Supporting file: references/quality-control-at-scale.md

Quality control at scale

Sampling strategy, automated checks, manual review checklist, failure thresholds, cohort tracking. The discipline that distinguishes durable pSEO from penalty-bait.

Auditing all 100,000 pages individually is infeasible. Quality control at scale is sampling discipline plus automated checks plus failure thresholds plus cohort tracking. Without it, pSEO sets degrade silently until algorithm updates expose the rot.

Sampling strategy

Random sample 50 to 200 pages per audit cycle, balanced across data shape.

Stratified sampling. Not "the latest 50 pages" or "the top-traffic 50 pages." A stratified sample exposes problems specific to particular data shapes.

Stratification dimensions:

Sparse vs dense data. Sample some records with minimum-required fields; sample some with most-fields-populated.
Recent vs old. Sample some pages generated in the last 30 days; sample some generated 12+ months ago.
Popular vs niche categories. Sample some pages from high-traffic parent categories; sample some from low-traffic ones.
Different cohort versions. If the template has shipped revisions, sample some pages from each cohort.

Sample size by set size.

Set under 1,000 pages: sample 50 pages per cycle.
Set 1,000 to 10,000 pages: sample 100 pages per cycle.
Set 10,000 to 100,000 pages: sample 150 pages per cycle.
Set 100,000+ pages: sample 200 pages per cycle.

Cycle frequency. Monthly for active sets (new pages generating, data refreshing). Quarterly for stable sets (mature programs in maintenance mode).

Automated checks

Run on every page on a cadence; surface failures as a queue.

Heading-structure check. Validates H1 exists once, H2s are in order, no orphan H3s, no H2-H3-H4 cascades that nobody scrolls.

Schema-validity check. Validates JSON-LD against the page's intended schema type; flags missing required fields, type mismatches, malformed structured data.

Internal-link-count check. Flags pages with fewer than 10 internal links (under-linked) or more than 50 (link-dense, anchor-signal-diluting).

Word-count threshold check. Flags pages below the template's minimum (typically 300 to 500 words depending on category). Pages below the threshold either need data backfill or should sit as drafts.

Duplicate-content check. Hash similarity across the set; flags pages with >80% content overlap with another page in the set. Common cause: comparison pages where X-vs-Y duplicates Y-vs-X without canonicalization.

Broken-link check. Crawl outbound and internal links; flag 404s and 5xx responses. Ages quickly without the check; cluster pieces that linked to deleted records become orphan-link generators.

Schema-population-rate check. For each optional schema field, the percentage of pages that populate it. Flag fields with population rates below 50%; these usually need either to be required, dropped, or backfilled.

Manual review checklist

For sampled pages, the human review covers what automation misses.

Above-the-fold answer quality. Read the first 200 words. Does it answer the user's likely query? Is the language specific to this record or templated boilerplate?

Distinctive vs templated. Compare the page to two siblings. Could you tell them apart on substance, not just on the names? If they read identically, the template lacks variable density or the data is too sparse to differentiate.

Citation-readiness. Would an AI engine cite this page for the user's query? Specifically: is there a self-contained answer paragraph, are statistics with sources present, is FAQPage or Article schema marked correctly?

User-intent satisfaction. If a real user landed on this page from the target SERP, would they stay or bounce? Bounce-shaped pages are the failure mode; staying-shaped pages are the goal.

Off-brand or off-tone signals. Does the page read consistently with the brand voice? Templated pSEO tends to drift toward generic neutral voice; the brand voice should still be present.

Failure thresholds

If more than 5% of sampled pages fail the manual review, halt new generation and fix the template or data before scaling further.

The 5% threshold. Empirical. Programs that hold under 5% sample failure tend to maintain quality at scale; programs that drift above 5% tend to compound the failure into algorithm-update territory.

What "halt" means. New page generation stops. The template or data fix is shipped. The next sample audit confirms the fix improved the failure rate before generation resumes.

Why halt instead of "fix as you go." Continuing to generate while quality degrades produces more pages that need to be fixed retroactively. Halting prevents the problem from compounding.

The threshold is not negotiable. "Just ship the next batch and we'll fix later" is the failure mode. The pattern produces pSEO sets that look fine at month 6 and get penalized at month 18.

Cohort tracking

Pages generated in one period rank differently from pages generated in another? That signals a template change or data quality drift; investigate.

Cohort cuts. Pages from a given month, pages from a given template version, pages from a given data-source version. Track ranking, click-through rate, citation count (from AEO measurement), and engagement metrics by cohort.

Drift signals.

Cohort A pages rank top 10; cohort B pages rank position 30. Template or data changed between cohorts; identify the change.
Cohort A pages get cited; cohort B pages do not. Template's above-the-fold answer changed shape; cohort B may have lost the citation pattern.
Cohort A pages have stable engagement; cohort B pages have decaying engagement. Cohort B may have a data freshness problem.

Why cohorts matter. Aggregate metrics hide problems. The set's overall rank looks fine if 80% of pages are stable and 20% are decaying. Cohort tracking surfaces the decaying 20% specifically; aggregate tracking misses it.

Team budget

A 10,000-page pSEO set requires roughly 0.5 to 1.0 FTE of ongoing quality control discipline. A 100,000-page set requires 2 to 4 FTE.

Where the headcount goes.

Sample audit cycles (monthly to quarterly)
Automated check failure queue triage
Manual review of sampled pages
Template or data fixes when failures surface
Cohort tracking analysis and investigation
Refresh cycle execution (volatile-field refresh, template-version migration)

The "we'll get to QC later" failure. Programs that ship without QC headcount budgeted typically degrade within 6 to 12 months. The set looks fine on launch day; the data drifts, the template ships untracked changes, the cohort gap widens, and by month 12 the algorithm update finds the rot.

The discipline. Budget the QC headcount before generating the first page. If the budget cannot absorb 0.5+ FTE for ongoing QC, the program's scope is too large; reduce scope until QC fits.

When QC reveals the program is broken

Sometimes the QC discipline reveals that the underlying program is wrong, not just that individual pages need fixes. Signals:

30%+ of sampled pages fail the manual review (data is too thin to support the template)
Failures cluster around a specific category (the dataset has a hole in that category; pSEO is generating pages from missing data)
Cohort decay is universal (the underlying competitive dynamics have shifted; the program's value proposition is decaying)

The right response is not "fix individual pages." The right response is to revisit the program's design: data depth, template scope, cohort coverage. Sometimes the answer is to prune the program back to its strong segments and walk away from the weak ones. The sunk cost is real but smaller than the cost of continuing to generate filler.

Supporting file: references/refresh-at-scale.md

Refresh at scale

Data refresh cadence, template versioning, cohort migration, pruning lifecycle.

pSEO sets decay if not maintained. Refresh discipline is built into the program at design time; retrofitting refresh on a 50,000-page set that was not designed for it costs more than building it from the start.

Data refresh cadence

Match the refresh cadence to the data's volatility and the query's freshness reward.

Volatile fields. Daily to weekly refresh. Real estate listings, current prices, current availability, recent reviews, current ratings. The data feed updates daily; the pages update daily; the search and AI surfaces see fresh data.

Slow-changing fields. Quarterly refresh. Population statistics, business categories, attribute classifications, neighborhood demographics. The data updates seasonally or annually; the refresh cycle aligns.

Static fields. No refresh required. Geographic coordinates, founding years, fixed attributes. Set at record creation; tracked in the schema's update-tag system.

Mixed-cadence pages. Most pSEO pages are mixed: some volatile fields, some slow-changing, some static. The refresh pipeline updates each field on its own cadence; the page renders the latest data on each request (or rebuilds when fields change).

The "refresh cadence wasn't designed in" failure. A program ships with annual refresh as the plan. Six months in, the volatile fields are stale (prices moved, listings expired). The fix is expensive: retrofit a daily pipeline for fields that should have had one from launch.

Template version migration

When the template improves, all existing pages need migration.

Why templates ship revisions. AEO patterns evolve, SERP intent shifts, schema requirements update, brand voice tightens. Templates from 18 months ago may need significant updates to compete in the current search and AI environment.

Cohort-by-cohort migration. Migrate one cohort at a time, monitor, then migrate the next. The cohort might be a category, a generation period, a data-density tier. The cohort approach surfaces problems specific to particular page shapes before they spread across the entire set.

Big-bang migration. Migrate all pages at once. Higher risk; if the new template has a regression, the entire set degrades simultaneously. Sometimes the right call when the migration is small or the team can roll back fast; usually the wrong call for large changes.

Migration monitoring. Each cohort post-migration is monitored for 30 days minimum: ranking changes, citation count changes, click-through rate changes, engagement metric changes. Negative trends pause the migration and surface the regression before it propagates.

Rollback discipline. The template migration ships with a rollback path. If a cohort's metrics degrade post-migration, the cohort rolls back to the previous template while the regression is investigated. Without rollback discipline, a bad migration produces permanent damage.

Cohort migration patterns

Three common patterns.

Category-based cohort migration. Migrate one parent category at a time. Real estate: migrate Denver pages first, monitor 30 days, then migrate Seattle. The advantage: category-level metrics are clean; investigation is scoped.

Generation-period cohort migration. Migrate the oldest cohort first (pages generated in year 1), then the next, then the next. The advantage: oldest pages have the most accumulated decay; migrating them first improves the set's average quality fastest.

Data-density cohort migration. Migrate the dense-data pages first (most fields populated), then the medium, then the sparse. The advantage: dense pages have the most upside from template improvements; sparse pages may need data backfill before template migration earns gains.

The right pattern depends on the migration's intent. AEO-focused migrations often prefer dense-data first. Algorithm-update recovery migrations often prefer category-based. Maintenance migrations often prefer generation-period.

Pruning lifecycle

Pages generated 2+ years ago that have not earned traffic should be evaluated for noindex or removal.

The 24-month checkpoint. Standard cutoff. A page that has been indexed for 24+ months and has earned zero impressions in Search Console is dead weight. Pruning options: noindex, 410, or 301 redirect to a more-relevant alternative.

Earlier pruning for some categories. Time-sensitive pages (annual "best of [year]" pages, event-specific pages, deal-specific pages) prune earlier. A "best of 2024" page generated in 2024 should be archived or pruned by mid-2026; the freshness signal has decayed.

Later pruning for stable categories. Some categories support evergreen pages that earn traffic for decades. Geographic pages (neighborhoods, cities), historical reference pages, foundational definitional pages. The 24-month checkpoint is too aggressive for these; review case-by-case.

Pruning is hygiene, not failure. Pruning a page that did not earn traffic is not abandoning the program; it is removing dead weight that drags the set's quality signal down. The set is healthier with 40,000 traffic-earning pages than with the same 40,000 plus 60,000 dead pages.

Set-level refresh

Occasionally the entire set's template needs a refresh.

Triggers for set-level refresh.

AEO patterns shifted significantly (the entire set needs better above-the-fold answers, FAQPage schema, or source citations)
The dataset's underlying source changed schema (the new data exposes fields the old template did not render)
User expectations evolved (the category's accepted page shape shifted; the set's pages now read as dated)
An algorithm update affected the set disproportionately (the set's design needs to adapt to the new ranking signals)

Set-level refresh is a 6-month project. Plan accordingly. The work includes template redesign, cohort-by-cohort migration, post-migration monitoring, and pruning of pages that the new template cannot improve. Underestimating the duration is the most common mistake.

The "do not refresh and let the set decay" anti-pattern. Some teams treat the initial pSEO build as ship-and-forget. The set ranks for 12 to 18 months, then declines as competitors with refreshed sets pass it. The decline accelerates when an algorithm update finds the set's accumulated drift. Refresh is part of the program's ongoing cost; teams that do not budget for it should not start the program.

Refresh budget

The ongoing refresh cost in headcount.

Volatile-field refresh. Mostly automated (data pipelines pull new data into the schema). 0.1 to 0.5 FTE for pipeline maintenance and exception handling.

Slow-changing-field refresh. Quarterly cycles. 0.2 to 0.5 FTE during cycles; lower between cycles.

Template version migration. Project-based when migrations ship. 1 to 3 FTE for the duration of the migration; varies by set size and migration scope.

Pruning lifecycle. Quarterly review of dead pages. 0.1 to 0.3 FTE.

Total ongoing refresh budget. A 10,000-page set: roughly 0.5 FTE steady state plus migration projects when they ship. A 100,000-page set: 1 to 2 FTE steady state plus larger migration projects.

The refresh budget is in addition to the QC budget. Programs that under-budget either degrade; programs that budget both produce durable traffic for years.

Supporting file: references/schema-design-patterns.md

Schema design patterns

Field count, computed fields, cross-record fields, update tags, schema-as-product. The data shape that drives the template.

The schema design here is the methodology layer: what shape the data takes, what fields earn their keep, what derivations add depth. Specific framework type signatures, ORM bindings, and database column choices are stack-specific implementation that varies by team.

Field count signals depth

5 fields per record is thin. 15 to 20 is competent. 30+ is deep.

Why field count matters. Field count determines what the template can render at depth versus what falls back to filler. A record with 5 fields can produce a 200-word page; a record with 30 fields can produce a 1,500-word page that reads as substantive across multiple sections.

The "thin schema" failure mode. Teams design with 5 to 10 fields, ship, find pages reading as thin, then try to bolt on additional fields after the fact. Bolt-on fields rarely populate consistently across the existing dataset; the result is a half-thin set with a thin tail and a thicker head.

The "too-many-fields" trap. 50+ fields per record where most are sparsely populated. The schema looks deep on paper but most fields are empty for most records. The template either renders empty sections (looks broken) or hides them (back to thin pages). Better to design 25 fields with 90% population than 50 fields with 30% population.

Required vs optional fields

Which fields must populate for a page to ship; templates need graceful degradation for optional gaps.

Required field discipline. Define a minimum field-count threshold below which a record does not get a public page. The threshold ships in the schema validation; pages that fail validation sit as drafts until their data populates.

Optional field handling. Each optional field has a render rule: if populated, render this section; if empty, hide this section or substitute a computed default. The render rules are part of the template, not afterthoughts.

The discipline. A page with 25 of 30 optional fields populated is fine. A page with 3 of 30 should not ship; it produces filler content that drags the entire set's quality signal down.

Computed fields

Derived from source data. Computed fields are the pSEO equivalent of the writer adding analysis: the data does the analysis once, every page benefits.

Common computed-field patterns.

Aggregations. "Average price per square foot" computed from listing data; "median rating" computed from review data.
Derived classifications. "Price tier" computed from price percentiles; "freshness tier" computed from data age.
Comparisons. "Price vs neighborhood average" computed from the record's price and the parent category's average; "rating vs category average."
Trends. "Price trend over 12 months" computed from time-series source data; "review-volume trend" from review-date stamps.
Rankings. "Top 10 percent by [field]" computed across the set; "ranked by [field] within [category]."

Why computed fields earn their keep. Each computed field adds a section to the template without requiring more source-data collection. The pipeline does the work; the template renders the result. This is how 15-field source data produces 30-field rendered pages.

Cross-record fields

Fields that reference OTHER records in the set. Enable internal linking and comparison without manual curation.

Common cross-record patterns.

Most similar records. "5 most similar neighborhoods" computed by attribute distance.
Parent and child references. "Parent category" and "list of child records" computed from the hierarchy.
Sibling-comparison aggregates. "Average price across sibling neighborhoods" computed across the parent's children.
Recommended-related. "Users who viewed X also viewed Y" computed from analytics data (when first-party analytics is available).

How they power linking. The sibling-link slot in the template renders from the "most similar records" cross-record field. Without this field, sibling linking becomes manual curation at scale, which is infeasible.

Update frequency tags

Which fields are static (geographic features, founding date) versus which need refresh tracking (current pricing, availability, current statistics).

Tag categories.

Static. Set at record creation; rarely changes (geographic coordinates, neighborhood name, founding year).
Slow-changing. Updates quarterly to annually (population statistics, business categories, attribute classifications).
Volatile. Updates daily to weekly (current price, current availability, current rating, recent reviews).
Real-time. Updates within minutes (live availability, dynamic pricing). Only relevant when the underlying data feed supports it.

Why tagging matters. Without tags, refresh becomes "audit everything every cycle," which does not scale. With tags, refresh becomes "refresh volatile fields daily, slow-changing fields quarterly, static fields never," which scales.

Schema-as-product principle

The schema that drives pSEO IS the product surface. Treat it with the same rigor as a database schema for a customer-facing application.

Schema versioning. Major schema changes (renaming required fields, restructuring nested objects, changing field types) bump a version. Minor changes (adding optional fields, adding computed fields) do not. All schema changes are reviewed; breaking changes require migration plans.

Schema documentation. Every field has a description, a source (where the data comes from), an update tag, a population rate (what percentage of records have this field), and example values. Documentation lives alongside the schema; it is not a separate doc that drifts.

Schema review. Before adding fields or changing field types, the schema change goes through review with stakeholders who depend on the schema (template authors, QC reviewers, analytics consumers). Schema changes affect downstream rendering; review catches breakage before it ships.

Schema testing. Validation rules ship as automated tests. Required fields, type constraints, value-range constraints, cross-field consistency checks. The tests run on every record in the dataset on a cadence; failures surface in the QC queue.

When the schema is wrong

The schema is wrong when:

Required-field threshold produces too few publishable pages (relax the threshold or fix the data pipeline)
Required-field threshold produces too many shallow pages (raise the threshold; let thin records sit as drafts)
Optional fields are sparsely populated, dragging the average page quality down (drop them and refocus on dense fields)
Computed fields are not actually used by the template (cut them; reduce schema bloat)
Cross-record fields produce poor sibling matches (revise the similarity algorithm; the sibling-link section is doing real work for users)
Update tags are wrong (refresh cadence is missing or over-shooting; recalibrate)

The schema is iterated, not designed once. The "schema-as-product" principle makes that iteration safe by enforcing review and migration discipline; without it, every schema change risks breaking the template.

Methodology-level choices that stay in the public skill

Field-count thresholds, computed-field patterns, cross-record patterns, update-tag categories, the schema-as-product principle.

Implementation choices that stay internal

The specific schema language (TypeScript type definitions, dbt YAML, Sanity schema config, Prisma schema, etc.). The specific ORM or query layer. The specific validation framework. The specific deployment pipeline for schema migrations. These vary by stack.

Supporting file: references/template-design-patterns.md

Template design patterns

Variable density, above-the-fold answer, heading hierarchy, schema integration, link slots.

The template is the structure that data fills. Templates are designed at the methodology level here; specific framework implementations (rendering, slot composition, build-time generation versus on-demand rendering) are stack-specific and belong in internal team documentation.

Above-the-fold answer

The first 200 words of the rendered page answer the user's specific query.

Why. Search engines and AI engines both extract the top of the page disproportionately. Featured snippets pull from the first answer-shaped paragraph. AI engines extract the first 200 words as the canonical citation. The reader who lands on the page from a SERP decides within 5 seconds whether to stay; the answer needs to be visible.

The pattern. Lead with the structured answer to the specific query: the price, the rating, the count, the comparison, the location, the recommendation. Follow with supporting details that justify or expand the answer. The opening is not a marketing introduction; it is the answer paragraph.

Anti-pattern. "Welcome to our [page type] page. Below you will find information about [topic]." This intro reads as filler to crawlers and humans. Cut it; lead with the answer.

Variable density

The template accommodates records with sparse fields and dense records gracefully.

Sparse-record handling. Some records will have fewer fields populated. The template needs fallback patterns: hide sections that depend on missing fields, substitute computed defaults, surface "limited data available" rather than rendering empty headings.

Dense-record handling. Some records will have many fields. The template needs progressive disclosure: collapse less-essential sections behind expandable headings, paginate long lists, prioritize the most-queried fields above the fold.

The shape principle. Two pages from the same template can differ significantly in length and depth based on data density without either looking broken. A page with 20% of optional fields populated should still feel competent; a page with 95% should not feel overstuffed.

Heading hierarchy reflects data

H2s and H3s map to data sections, not to template decoration.

The pattern. The H2 set is the same across all pages in the template, but the content under each H2 reflects each page's specific data. "Overview," "Details," "Comparisons," "Related" might be the H2 set; what populates each varies per page.

Snippet-bait paragraphs at H2 level. Each H2 has a 40 to 60 word answer paragraph immediately following it that summarizes that section's specific content. AI engines often quote these as multi-paragraph citations.

Anti-pattern. Every page has a different H2 set because the template branches on data. The inconsistency confuses crawlers; the heading structure should be predictable across the set.

Schema markup as part of template

Structured data renders machine-readable signals at scale.

The principle. Pick the schema type that matches the page's content (Product, Article, LocalBusiness, FAQPage, BreadcrumbList, etc.). Embed the schema in the template; populate from the same data that renders the visible page. The schema is generated, not hand-written; the template ensures every page has it.

Validation discipline. Run schema validation as an automated check on every generated page. Schema errors produce silent failures in search and AI surfaces; the validation catches them before publish.

Schema field coverage. Populate every relevant schema field, not just the required ones. Optional schema fields (aggregateRating, additionalProperty, areaServed, etc.) signal depth at scale even when individual fields are not visibly rendered.

Internal linking placeholders

The template includes link slots for related-record cross-references, parent-category links, and sibling-record links.

Standard slot patterns.

Breadcrumb slot. Path from home to current record. 3 to 4 levels typical.
Parent-category slot. Link up to the hub page for the record's category.
Sibling slot. 5 to 15 related sibling records. Computed from cross-record fields in the schema.
Related-record slot. 3 to 5 records related across categories (different parent, similar attributes).
Related-content slot. Editorial content related to the record (blog posts, guides, comparison editorials).

Total internal links per page. 15 to 30 typical for a well-linked pSEO page. Below 10, the page is under-linked; above 50, the page reads as link-dense and dilutes anchor signal.

Distinctive value per page

Each generated page must offer something the user could not get by going up to the parent or sideways to a sibling.

The test. Generate three sample pages from the template using different records. Read all three. Can you tell them apart on substance, not just on the names? If the pages are interchangeable in everything but identifiers, the template is not generating distinct value.

The fix. Surface the distinctive fields prominently. The fields that vary most across the set are the ones that justify the page's existence; those should be in the above-the-fold answer and in the H2 structure, not buried as "additional details."

Quality bar: the random-sample test

The template's quality bar. A randomly sampled page from the set, viewed in isolation, should answer the user's likely query competently.

The test sequence.

Pick 5 random records from the dataset.
Render them through the template.
Read each page as if you arrived from a search results page.
Score each page on three dimensions: does it answer the query, is the depth competitive with editorial content for the same query, would you trust this page as a source.

If any of the 5 fails, the template needs work before scaling. The 5-page sample is the minimum viable QC; the cohort tracking discipline scales it across the program's lifetime.

Methodology-level design choices that stay in the public skill

The principles above. Field-count heuristics, slot patterns, hierarchy choices, validation discipline, sample-test discipline.

Implementation choices that stay internal

The framework rendering choice (build-time generation, server rendering, hybrid), the specific component composition pattern, the specific data-fetching layer, the deployment topology, the cache-invalidation strategy. These vary by stack and team and should not be prescribed at the methodology level.

Supporting file: references/when-pseo-works-decision.md

When pSEO works decision

The five-criterion framework for deciding whether programmatic SEO is the right answer, with worked examples across business types.

The default answer is no. Most teams asking "should we do pSEO?" should hear "probably not." pSEO works only when all five criteria are met; failing any one is a hard signal to pursue editorial content or paid acquisition instead.

The five criteria

1. Real underlying data

A genuine structured data source with depth. 10+ fields per record, ideally 20+. First-party data, licensed datasets, expert-curated content, or synthesized multi-source data. Not scraped Wikipedia plus AI rewrite.

The test. Could a competent reader extract genuine value from a single page in the set without reading any other page? If yes, the data is real. If no, the page is filler dressed as pSEO.

2. Long-tail query volume justifies the effort

The queries the program targets have meaningful aggregate volume. Individual queries can be small (10 to 100 monthly searches each) as long as the aggregate across the set is large.

The test. Pull the top 20 candidate queries from keyword research. Sum their volumes. If the aggregate is below 5,000 monthly searches, pSEO probably does not justify the build. If above 50,000, the volume case is strong.

The illusion to watch for. Long-tail keywords that look reasonable in keyword tools but are not actually searched by humans. Permutation keywords (every adjective times every noun) often have keyword-tool volume because the tools generate the data; the queries themselves are dead.

3. User intent is queryable

The user's question can be answered through structured data presented well. Not through narrative explanation, judgment, or analysis the data cannot supply.

Queryable intent examples. "Homes for sale in [neighborhood]" answered by listing data. "Software engineer salary at [company]" answered by salary data. "Restaurants near [landmark]" answered by location and rating data.

Non-queryable intent examples. "Should I buy a house in [neighborhood]" requires personal financial judgment. "Why is Y better than X" requires editorial argumentation. "How do I choose [thing]" requires guidance.

If the intent requires narrative, choose editorial. If the intent requires data presented well, choose pSEO.

4. Update cadence aligns with query volatility

Real estate listings update daily; the data feed updates daily; pSEO refresh aligns with the volatility. "Best [thing] for [year]" pages get stale annually; the refresh cadence is annual.

The test. Match the data's update frequency to the query's volatility. If the data is static (geographic features, founding dates) and the queries are stable, low maintenance. If the data shifts daily and the queries reward freshness, daily refresh.

The trap. Underestimating refresh effort at design time. A team designs for "annual refresh" because that feels reasonable, ships 50,000 pages, and discovers the refresh requires 2 FTE for 6 weeks every year. The cadence was real; the resourcing was not.

5. Quality control is operationally feasible

Headcount is budgeted to sample-audit the set, fix failures, and maintain quality. Not aspirationally; in actual hours allocated.

The rule of thumb. A 10,000-page set requires roughly 0.5 to 1.0 FTE of ongoing quality control. A 100,000-page set requires 2 to 4 FTE. If the budget cannot absorb the QC headcount, the program will degrade within 12 months of launch.

Worked examples

Example 1: real estate listings (yes)

A regional brokerage considering pSEO for "homes for sale in [neighborhood]" pages.

Real underlying data: yes. MLS feeds with 30+ fields per listing.
Long-tail volume: yes. Each neighborhood query has 50 to 500 monthly searches; aggregate across 200 neighborhoods is significant.
Queryable intent: yes. Buyers want listings.
Update cadence: data updates hourly; pSEO refresh aligns daily; manageable.
QC feasible: yes; the brokerage already has data ops headcount.

Decision: yes. This is the canonical pSEO use case.

Example 2: SaaS comparison pages (maybe)

A B2B SaaS considering "X vs Y" pages for every competitor combination.

Real underlying data: judgment call. If the comparison data is licensed (G2 reviews, feature databases) or first-party (the team's actual evaluation), yes. If the data is "scraped competitor websites plus AI summary," no.
Long-tail volume: yes for major competitors; thin for niche ones.
Queryable intent: yes for "X vs Y," but readers often want narrative judgment ("which is better for my use case") that data alone cannot supply.
Update cadence: feature databases drift; quarterly refresh required.
QC feasible: depends on team size.

Decision: maybe, leaning yes if the team commits to combining structured comparison data with brief editorial analysis per page. Pure-data comparison pages tend to underperform pages that include the analytical layer.

Example 3: AI-generated city guides (no)

A travel content site considering "things to do in [city]" pSEO across 5,000 cities.

Real underlying data: no. The plan is "AI-generate the content from public sources." Anyone can replicate.
Long-tail volume: yes for major cities; thin for small ones.
Queryable intent: yes, but the queries reward editorial depth (curation, recommendations, taste).
Update cadence: events change weekly; the AI-generated approach cannot match.
QC feasible: no; "AI-generate 5,000 pages" is the plan because QC was not budgeted.

Decision: no. This is the pattern that produces penalty-bait. Either invest in real expert-curated data or pursue editorial content for the highest-volume cities only.

Example 4: enterprise B2B pricing pages (no)

An enterprise B2B SaaS considering "pricing for [industry] companies" pSEO across 50 industries.

Real underlying data: no. Pricing for enterprise SaaS is typically negotiated; there is no structured data feed to render.
Long-tail volume: yes for some industries.
Queryable intent: no. Buyers want a sales conversation, not a price table.
Update cadence: not relevant.
QC feasible: not relevant.

Decision: no. The intent is not queryable. Editorial content explaining the buying process plus a sales-led conversion path is the right approach, not pSEO.

When two of five criteria fail, walk away

If two or more criteria fail, walk away from the pSEO idea. The temptation is to start anyway and "improve as you go," but pSEO programs that launch with weak foundations rarely recover. The data depth, the QC budget, and the refresh cadence are designed in or they are missing forever.

If exactly one criterion fails, see whether a smaller scope resolves the failure. "5,000 pages across all cities" failing on data depth might become "500 pages across major cities with expert-curated depth" that succeeds on all five criteria.

Common questions

How do I install Programmatic SEO in Cursor, Claude Code, or Codex?

Run npx skills add rampstackco/claude-skills --skill programmatic-seo in the project where you want it, then ask your agent for the skill by name. The --skill flag installs only Programmatic SEO, not every skill in the repository.

Where does Programmatic SEO come from and what license is it under?

Programmatic SEO comes from the rampstackco/claude-skills repository on GitHub. That repository has 750 GitHub stars. The skill is published under the MIT license.

Prefer plain text? Read the Programmatic SEO guide as markdown.