Hub Page Excellence — Design Spec

Date: 2026-05-14 Status: Brainstorm output, ready for implementation plan Owner: Survipedia content fleet (lead: webmaster + author) Collaborator model: Codex (gpt-5.5 via mcp__codex__codex MCP) as independent per-lens critic

Goal

Bring the homepage (docs/index.md) and the Water hub (docs/water/index.md) to "consumer-critical" excellence across four lenses — reader clarity, authority signal, SEO, and conversion to deeper reading — and codify what excellence means into a reusable standard (STANDARDS.md § Hub Pages) so the remaining 11 Foundation hubs can be retrofitted to the same bar in follow-up loops.

These 13 pages (homepage + 12 Foundation hubs) carry the majority of consumer entry traffic. They are the storefront. They must hold up under hostile reading and Google scrutiny equally.

Non-goals

New content pages (sprint freeze 2026-05-06 → 2026-06-15 permits hub rewrites but not new pages)
Rewriting child pages reached from the hubs — out of scope this session
Visual asset regeneration unless a rubric item forces it
Changing the 12-Foundation taxonomy, the Essentials/Infrastructure/Fieldcraft tier framing, the Field Note admonition pattern, or the hub-hero image rule (Q4 sacred cows)

Constraints

Constraint	Source
Calm, practical, empowering tone — no fearmongering	Operating Constitution rule 6
Life-safety claims need Tier 1 sources	Operating Constitution rule 2
Tier framework + Field Note + voice preserved	Q4 sacred cow
Hub Page Hero Image Rule (no text, regenerate if violated)	CLAUDE.md
Sprint freeze on new pages until 2026-06-15	SPRINT-2026-05.md
Hub retrofit work is OTHER tier — runs after TAG-AUDIT / CANON-PROMOTE / CANON-stub	SPRINT-2026-05.md priority ladder
All governance-file edits log to AUDIT_LOG.md	Operating Constitution rule 5

Decisions baked in

Scope: Home + Water this session as pilot; template codified after; 11 remaining hubs retrofitted post-sprint via BACKLOG.
Excellence lens (all four matter): reader clarity, authority/completeness, SEO, conversion. Rubric covers all four; no single lens is sacrificed.
Codex role: Independent critic per lens — three round-trips minimum (rubric completeness, per-page critique x2, standards enforceability). Codex never has conversation memory; every prompt is self-contained.
Template artifact: New section appended to STANDARDS.md (§ Hub Pages). Not a separate root file.
Sacred cows: voice + Field Note + Essentials/Infrastructure/Fieldcraft tier structure preserved. Hero image + onramp tabs + scenario tabs are open to challenge by the rubric.
Disagreement resolution: Webmaster arbitrates when Codex and the local draft disagree; reasoning logged in the per-page edit plan; final disposition visible in the commit body.
Rubric expansion guard: If Codex's Phase 1 critique proposes 5+ new rubric items, accept only items that close a clear coverage gap; reject stylistic preferences.

Architecture — Three-phase workflow

Phase 1: Rubric anchor
  └─ Draft RUBRIC.v1 → Codex round 1 (completeness) → reconcile → RUBRIC.v2

Phase 2: Per-page edit pass (home, then water)
  └─ For each page:
     1. Score against RUBRIC.v2 → draft edit plan
     2. Codex round 2 (independent per-lens critique of page + plan)
     3. Reconcile critique → final edit plan
     4. Implement edits

Phase 3: Codify
  └─ Promote RUBRIC.v2 → STANDARDS.md § Hub Pages (with concrete examples)
     → Codex round 3 (enforceability check)
     → reconcile → publish
     → Queue 11 HUB-RETROFIT POST-SPRINT BACKLOG tasks

Total Codex round-trips: 4 happy-path (Phase 1: 1, Phase 2: 2 — one per page, Phase 3: 1), up to 6 with reconciliation cycles.

The rubric — RUBRIC.v1 (22 items, 4 lenses)

This is the draft to send to Codex in Phase 1. Final version is RUBRIC.v2 after Codex round 1.

Lens 1 — Reader clarity (R1–R6)

R1 First 80 words establish topic + stakes, no jargon
R2 "What to do next" entry point reachable in mobile first viewport
R3 H2 sections answer reader questions, not topic taxonomies
R4 ≥1 Field Note admonition with topic-specific practical wisdom (sacred cow per Q4)
R5 Concrete numbers (gallons, $, days, lb/kg) appear before abstract framing
R6 No insider term without immediate gloss

Lens 2 — Authority / completeness (A1–A5)

A1 All foundation child pages linked (no orphans in the directory)
A2 ≥1 citation, source ref, or named institution per major claim cluster
A3 Multi-setting breadth (urban / suburban / rural OR emergency / short-term / permanent)
A4 Tier-1 / life-safety claims weighted and warned per SOURCES.md
A5 Depth signal — measurements, decision criteria, named methods — not just descriptions

Lens 3 — SEO (S1–S5)

S1 H1 matches title; description ≤160 chars and answers query intent
S2 H2/H3 hierarchy reflects real subtopic clusters (passage-ranking lens)
S3 ≥8 outgoing internal links to child pages
S4 ≥1 schema-eligible element (FAQ / HowTo / ItemList) embedded
S5 Featured-snippet candidate — complete <50-word answer to the obvious query near top

Lens 4 — Conversion (C1–C6)

C1 ≥2 explicit "start here" CTAs above the fold or in first 2 sections
C2 Audience-segmented entry paths (new / intermediate / advanced OR scenario tabs)
C3 Every child-page link carries a one-line "why click" — no bare links in lists
C4 Closing section ends with a single next action, not a summary
C5 Cross-links to ≥3 other Foundations (system-connection signal)
C6 At least one "you can do this today" action with a time estimate

Codex interaction protocol

Each mcp__codex__codex call is fully self-contained. Codex has no conversation memory between calls.

Phase 1 prompt — rubric completeness

You are an independent reviewer for an encyclopedia hub-page rubric.

Below is the draft rubric for "what makes a category hub page excellent."
Critique it for COMPLETENESS across 4 lenses (reader clarity, authority,
SEO, conversion). Don't refine wording — flag missing dimensions,
redundancies, and lens-coverage gaps.

Return:
1. Per-lens coverage assessment (Solid / Has gaps / Over-stuffed)
2. Missing items, one per line
3. Redundant items, one per line

[paste RUBRIC.v1]

Phase 2 prompt — per-page critique (one call per page)

Independent critic mode. You have NOT seen prior analysis. Critique fresh.

You will receive:
1. The hub-page excellence rubric (22 items, 4 lenses)
2. The current page content (markdown)
3. The proposed edit plan

For EACH of the 4 lenses, return:
- Worst flaw in the CURRENT page on this lens (cite line numbers)
- Worst flaw in the EDIT PLAN on this lens
- One concrete suggestion the plan is missing

Be harsh and specific. No diplomatic hedging.

[rubric] [current page] [my edit plan]

Phase 3 prompt — standards enforceability

Review the proposed STANDARDS.md § Hub Pages section for clarity and
enforceability. Could an author + editor pair use this to ship a new hub
page without ambiguity? Flag any criteria that are subjective, untestable,
or open to interpretation.

Return:
1. Enforceable items (list)
2. Ambiguous items + suggested rewording
3. Missing enforcement detail (e.g., how to measure "depth signal")

[proposed STANDARDS.md section]

Logging

Each Codex call appends one LOG.md entry:

YYYY-MM-DD HH:MM | codex-mcp | hub-excellence:phase-N | <subject> | ~Nk tokens

Per-page edit-plan format

Drafted before each page edit; lives in the conversation and is summarized into the commit body. Not committed as a separate file.

# Edit plan: docs/{path}/index.md
## Rubric scorecard (current state, 22 items)
  R1 pass | R2 fail (reason) | R3 partial (reason) | ... | C6 pass
## Edits — Lens 1 (clarity)
  - [E1] scope: section
        current: "..."
        proposed: "..."
        rationale: closes R3 gap (H2 was "The three layers" — topic taxonomy)
  ...
## Edits — Lens 2 (authority)
## Edits — Lens 3 (SEO)
## Edits — Lens 4 (conversion)
## Codex reconciliation
  - [Codex flag #1: "intro buries the stakes"] accept; redraft first paragraph
  - [Codex flag #2: "drop SODIS, it's niche"] reject; SODIS earns its placement because...
  - [Codex flag #3: "add FAQ schema"] modify; add as ItemList instead because...
## Final implementation summary (high-level diff)

STANDARDS.md § Hub Pages (Phase 3 deliverable)

The new section appended to STANDARDS.md contains:

Preamble — what a hub page is, why it matters (consumer-critical, drives the majority of Foundation entry traffic), which pages it applies to (homepage + 12 Foundation hubs).
The 22-item rubric, each item paired with:
One concrete pass example drawn from the rewritten home or water hub
One concrete fail example drawn from the pre-rewrite version
Anti-patterns — bare link lists, generic encyclopedia intros, missing "today" action, taxonomy-as-H2, etc.
Editor checklist — score all 22 items; document waived items with rationale.
Hard-fail items (publisher blocks the commit):
A4 (life-safety treatment)
R4 (Field Note present)
S1 (description length ≤160 chars)
Soft-fail items — editor flags, does not block.
Retrofit protocol — how to apply this standard to existing hubs (one page per [M] BACKLOG task; CANON-PROMOTE work takes priority during the sprint).

State-file integration

File	Change
`LOG.md`	One entry per Codex round, per page-edit dispatch, per STANDARDS.md update
`MEMORY-CONTENT.md`	Append lesson on what made home/water excellent (per-lens insights worth keeping)
`MEMORY-STANDARDS.md`	Append pointer to STANDARDS.md § Hub Pages with one-line summary
`AUDIT_LOG.md`	Governance-file edit rationale (STANDARDS.md additions) per Operating Constitution rule 5
`BACKLOG.md`	11 `HUB-RETROFIT: POST-SPRINT:` tasks (one per remaining hub), each `[M]` 4pt, RICE-scored on traffic
`JOURNAL.md`	Brainstorm + execution narrative (reflector)

Reflector closes the loop before publisher commits. Publisher runs mkdocs build --strict, then git add -A && commit && push in one shot.

Verification gates (before publisher commit)

All 22 rubric items scored on both pages; hard-fails resolved; soft-fails documented with rationale.
Every Codex critique item has a recorded disposition (accept / reject / modify with reason).
mkdocs build --strict passes (link integrity, schema, front matter).
New STANDARDS.md § Hub Pages section reads cleanly to a cold reader (one self-review pass).
LOG.md, MEMORY-CONTENT.md, MEMORY-STANDARDS.md, AUDIT_LOG.md, BACKLOG.md all updated in the same commit as the page edits.
Hub heroes (home, water) still present and text-free — Hub Page Hero Image Rule preserved.

Risks and mitigations

Risk	Mitigation
Codex critique drifts into stylistic preference (low-signal)	Phase 1 prompt explicitly excludes wording refinement; Phase 2 prompt asks for worst flaw not all flaws
Rubric balloons past 22 items, becomes unenforceable	Expansion guard: accept Phase 1 additions only if they close clear coverage gaps; reject style additions
Edits break voice/tone (Operating Constitution rule 6)	Sacred cow constraint in design; webmaster reads final draft for tone before commit
Sprint freeze conflict	Hubs are existing pages; rewrites are permitted. Retrofit tasks are tagged POST-SPRINT and deferred
Hub Hero text-leak after any image regen	Hero rule check in verification gate; image-gen agent owns regeneration with text-free prompt
Disagreement deadlock (me vs Codex)	Webmaster arbitrates; reasoning logged; visible in commit body

Success criteria

The session is complete when:

docs/index.md and docs/water/index.md both score 22/22 on RUBRIC.v2 (or with documented waivers).
STANDARDS.md § Hub Pages exists, validated by Codex round 3 for enforceability.
Four Codex round-trips logged in LOG.md with token estimates (more if reconciliation cycles fire).
Eleven HUB-RETROFIT POST-SPRINT tasks queued in BACKLOG.md.
One commit lands on main with all state-file updates included.

Out of scope this session

Editing child pages reached from the hubs
Visual asset regeneration unless a rubric item forces it
Executing the 11-hub retrofit (queued for post-sprint)
Building automated rubric-scoring tooling (manual editor pass for now)

Next step

Invoke superpowers:writing-plans to break this design into an executable implementation plan with review checkpoints.