design-programmatic-template

# Design Programmatic Template This skill produces the template + data spec for a green-lit programmatic build. Output is the handoff document engineering + content + design teams build against. The skill is opinionated about a few things: every page needs substantive unique content per slot (templates that are mostly boilerplate produce thin pages); index-control rules are non-negotiable (publish only when data threshold is met); internal-link orchestration is part of the template (hub-and-spoke + peer linking), not an afterthought; schema is per-template, not per-page. ## When to use this skill - The user has a green-lit programmatic build (from `plan-programmatic-seo`) and is ready to spec the template. - Engineering is ready to build and needs the template + data spec. - Content team is ready to populate and needs the field-by-field spec. - The team is iterating on an existing programmatic template and needs the redesign spec. ## When NOT to use this skill - Programmatic viability hasn't been evaluated — run `plan-programmatic-seo` first. - The user wants to brief a single editorial piece — use `generate-content-brief`. - The user wants the template *code* — that's engineering's job; this produces the spec. - The user wants to design a single pillar / blog post — use `design-pillar-page` / `generate-content-brief`. ## Inputs required 1. **Business context and SEO foundation** — read `businesses/<slug>/business_context.md` and, for SEO-specific work, `businesses/<slug>/seo_foundation.md`. Resolve `<slug>` by listing `businesses/`: if exactly one folder exists, use it; if multiple, ask which business; if none, recommend running `business-context` first. If SEO foundation is missing, recommend running `seo-foundation` before producing output. Critical fields: products/services, customer, and brand voice from `business_context.md`. 2. **Programmatic evaluation** — read `businesses/<slug>/programmatic/<use-case-slug>-evaluation.md` (output of `plan-programmatic-seo`). Required. Confirms the build is green-lit. 3. **Cluster map** — read `businesses/<slug>/clusters/cluster-map.md`. Programmatic pages often anchor to a topic cluster. 4. **Archetype** — confirmed from the evaluation (glossary, comparison, location, listing, "for [persona]"). 5. **Data sample** — strongly preferred. 3-5 example entries with the data the user has available. If unavailable, ask what fields exist; the spec is harder to design without sample data. 6. **Existing schema patterns** — if the brand has an existing schema strategy (per `plan-schema-strategy`), build on it. 7. **CMS / tech stack** — optional but useful. Affects template implementation patterns. If evaluation document or archetype is missing, ask. The template is anchored to a specific approved build. ## Process 1. **Confirm the archetype** and load archetype-specific conventions. - **Glossary:** entry per term; hub at `/[type]/`; sections: definition, mechanism, uses, related entries, related products. - **Comparison:** entry per pair; URL pattern `/compare/[a]-vs-[b]`; sections: side-by-side table, deep-dive per item, recommendation, related comparisons. - **Location:** entry per location; URL pattern `/[service]/[location]`; sections: service description, local context, location-specific data, related locations. - **Listing / database:** index page with filters; entry per item; URL pattern `/[type]/[slug]`. - **For [persona]:** entry per persona; URL pattern `/for/[persona]`; sections: persona description, recommendations, social proof, related personas. 2. **Design the URL pattern.** Lowercase, hyphen-separated, no year stamps, no UTM-style query parameters. URL is the most stable element of the template; design carefully. 3. **Build the page section spec.** What sections does every page have? For each section: required vs. optional, content requirements, length range, data slots, fallback behaviour when data is missing. 4. **Define the data schema.** Field-by-field. For each field: - Name + type (string / number / boolean / array / structured object). - Required or optional. - Validation rules (length, format, allowed values). - Source (own database, manually curated, third-party API). - Maintainer (team / role). 5. **Set index-control rules.** What constitutes "enough data to publish"? Typically: 80%+ of required fields populated, all required fields meeting minimum-content thresholds, no banned-content flags. 6. **Plan schema markup.** Per-template schema: - Glossary entries: Article + DefinedTerm (where supported) + FAQPage. - Comparison pages: Article + ItemList (the comparison) + Product (per item) + FAQPage. - Location pages: LocalBusiness (if appropriate) + Article + FAQPage. - Listing pages: ItemList + Article. 7. **Plan internal linking.** - **Hub:** index page (`/[type]/`) lists all entries. The hub is the highest-equity page; should rank for the head term. - **Spoke (each entry):** links back to hub; links to 3-5 related entries; links to 2-3 related products / cluster posts. - **Peer linking:** entries link to topically-related peers (related ingredients, related comparisons, etc.). - **Cluster-bridge linking:** programmatic entries link to cluster pillar / blog spokes where contextually relevant. 8. **Plan XML sitemap segmentation.** Dedicated sitemap for the programmatic template (e.g. `sitemap-ingredients.xml`). Helps GSC analysis at the cohort level. 9. **Plan analytics.** Page-template-level events. Cohort-level dashboards (all pages in this template) for ranking, traffic, engagement, indexing. 10. **Define acceptance criteria.** Per-page criteria + cohort-level criteria. 11. **Plan Phase 1 production.** First-batch population (30-50 entries). Editorial review. Quality gates before launch. 12. **Plan ongoing operations.** Data maintenance cadence. Quality monitoring (cohort-level). Quarterly reviews. 13. **Write the spec.** Output is a structured Markdown doc covering all of the above. ## Output format ```markdown # Programmatic Template Spec — [Use case] **Use case:** [from evaluation] **Archetype:** [glossary / comparison / location / listing / "for [persona]"] **Phase 1 page count:** [n] **Spec date:** [date] **Engineering owner:** [name / TBD] **Data owner:** [name / role] ## URL pattern - **Index (hub):** `/[type]/` - **Entry:** `/[type]/[slug]` - **Slug rules:** lowercase, hyphen-separated, no special characters, no year stamps. - **Examples:** `/ingredients/zinc-oxide`, `/ingredients/niacinamide`, `/ingredients/hyaluronic-acid`. ## Page section spec ### Section 1 — Hero - **H1:** [pattern, e.g. `What is {{ingredient.name}}?`] - **Subtitle:** [pattern, e.g. `{{ingredient.summary_short}}`] - **Required:** `name`, `summary_short`. - **Length range:** [n words]. - **Fallback:** if data missing, page should be `noindex`ed. ### Section 2 — Mechanism / Definition - **Heading:** [pattern, e.g. `How {{ingredient.name}} works`] - **Body content:** [pattern] - **Required:** `mechanism_explanation` (200-400 words). - **Optional:** `mechanism_diagram_url` (illustration). - **Length range:** [n words]. - **Fallback:** if `mechanism_explanation` is < 150 words, page is below threshold → `noindex`. ### Section 3 — [Section name] - **Heading:** [...] - **Required:** [...] - **Optional:** [...] - ... [Repeat for each section in the template — typically 6-10 sections per page] ### Section N — FAQ - **Heading:** "Frequently asked questions about {{name}}" - **Body:** 3-6 question / answer pairs. - **Required:** at least 3 Q&A pairs. - **Schema:** populates FAQPage schema. ### Section N+1 — Related entries - **Heading:** "Related [archetype]" - **Body:** 3-5 cards linking to related entries (peer linking). - **Required:** at least 3 related entries. - **Selection logic:** rule-based (same category, similar mechanism, etc.) or curated. ### Section N+2 — Related products / blog - **Heading:** "Find this in our products" / "Read more" - **Body:** 2-3 product cards + 1-2 cluster blog links. - **Required:** at least 1 link, but not blocking — leave empty if no good match. ## Data schema | Field | Type | Required | Source | Maintainer | Validation | |-------|------|----------|--------|------------|------------| | `name` | string | ✅ | manual | content | 2-50 chars | | `slug` | string | ✅ | derived | system | lowercase-hyphenated | | `summary_short` | string | ✅ | manual | content | 80-160 chars | | `mechanism_explanation` | text (markdown) | ✅ | manual + dermatologist review | content + reviewer | 150-400 words | | `regulatory_status` | enum | ✅ | manual | content | one of: FDA-approved, EU-approved, multi-region, restricted | | `our_percentage` | number (or null) | optional | own database | product | 0-100, % | | `our_products` | array of product IDs | optional | own database | system (sync) | 0-10 entries | | `tolerance_three_skin_tones` | structured (object) | optional | own testing | product testing | structured fields | | `dermatologist_note` | text | optional + reviewed | dermatologist | reviewer | up to 200 words | | `related_ingredients` | array of slugs | ✅ | manual | content | 3-5 entries | | `faqs` | array of {question, answer} | ✅ | manual | content | 3-6 pairs | | `last_reviewed` | date | ✅ (system) | system | system | ISO-8601 | | `last_reviewed_by` | string | ✅ for credibility-sensitive | manual | reviewer | name + credentials | ## Index-control rules A page **publishes** (status: indexable) only if all of the following are true: - All ✅ required fields are populated. - `mechanism_explanation` is ≥ 150 words. - `faqs` has ≥ 3 Q&A pairs. - `related_ingredients` has ≥ 3 entries. - For credibility-sensitive content: `dermatologist_note` is populated and `last_reviewed_by` is set. If any condition fails: - Page is generated but `noindex,follow` (still findable via internal links, not indexed). - Page is excluded from XML sitemap. - Daily report flags the page for content team to populate / review. ## Schema markup Per-template schema implementation: ### Article - `@type`: "Article" - `headline`: `{{name}}` - `datePublished`: `{{first_published}}` - `dateModified`: `{{last_reviewed}}` - `author`: `{{last_reviewed_by}}` (or default brand author) - `image`: hero image URL - `mainEntityOfPage`: page URL ### FAQPage - Populated from `faqs` array. - One `Question` + `acceptedAnswer` per Q&A. ### DefinedTerm (where supported) - `@type`: "DefinedTerm" - `name`: `{{name}}` - `description`: `{{summary_short}}` ### BreadcrumbList - Home → [Type Index] → [Entry] ### Reference - See [generate-schema-markup](../../technical/generate-schema-markup/SKILL.md) for implementation. ## Internal linking strategy ### Hub linking - `/[type]/` (index) lists all published entries with thumbnail + summary. - Hub is linked from main nav and footer. - Each entry links back to hub in breadcrumb. ### Peer linking - Each entry links to 3-5 related entries (selected by category match + manual curation). - Anchor pattern: entry name + descriptive context. ### Cluster bridging - Each entry links to relevant cluster pillar (where applicable). - Each entry links to 1-2 sibling blog posts in the cluster. - Cluster pillar links to relevant entries in body content. ### Product bridging - Each entry with `our_products` populated displays product cards with link to PDP. - Anchor pattern: product name (not generic "shop now"). ## XML sitemap segmentation - Dedicated sitemap: `sitemap-[type].xml`. - Updated on every entry publish / unpublish. - Submitted to GSC. - Referenced from sitemap index (`sitemap.xml`). ## Analytics instrumentation - **Page-template-level events:** page view, scroll depth, internal-link clicks, product-card clicks, FAQ expand. - **Cohort dashboards:** all pages in the template — average ranking, total traffic, average engagement, indexing rate. - **GSC analysis:** filter by URL prefix `/ingredients/` (or template path) for cohort GSC queries. - **Quality metrics:** % of pages publishing vs. `noindex`ed; % of pages with all required fields; data freshness (last reviewed > 12 months). ## Acceptance criteria ### Per-page - [ ] Page publishes only if index-control rules pass. - [ ] All required fields populated. - [ ] `mechanism_explanation` ≥ 150 words. - [ ] FAQ has ≥ 3 Q&A pairs. - [ ] Related-entries section has ≥ 3 entries. - [ ] Schema (Article + FAQPage + BreadcrumbList) deployed and validates in Rich Results Test. - [ ] Page LCP ≤ 2.5s, INP ≤ 200ms. - [ ] No broken internal links. ### Cohort (Phase 1, 30 pages) - [ ] At least 25 of 30 entries pass index-control and are indexable. - [ ] All 30 entries have dermatologist review for credibility-sensitive fields. - [ ] Hub page (`/[type]/`) is linked from main nav. - [ ] Sitemap `sitemap-[type].xml` is submitted to GSC. - [ ] Cohort dashboard is set up in analytics. - [ ] At month 4 post-launch: average ranking is at position 25 or better; cohort traffic is on track for 12-month target. ## Phase 1 production plan ### Engineering (weeks 1-4) - [ ] Template implementation (HTML / CMS / static-gen). - [ ] Data schema in CMS or database. - [ ] Index-control logic. - [ ] Schema markup.