Codex Review: Page Action Block Standard

Review date: 2026-05-16 Reviewer: Codex (gpt-5.5 via mcp__codex__codex) Reviewed files: docs/superpowers/specs/2026-05-16-page-action-block-design.md, STANDARDS.md § 11, docs/water/storage.md, docs/medical/wounds.md

1. Enforceability gaps

The standard is directionally enforceable as a structural block, but the current 14-item rubric mixes three enforcement classes without labeling them cleanly: publisher-checkable mechanics, editor-checkable semantics, and expert/fact-checker judgments. § 11 handles this better by defining terms such as "life-safety claim," "named institution," and "weighted/warned."

Operationally checkable items: B3, F3, F5, and parts of V1 are strong binaries. B1/B2 are mostly checkable, but "immediately after H1 + intro paragraph" at lines 43 and 123 is ambiguous on pages with an educational disclaimer, prerequisite block, hero image, or opening warning. medical/wounds.md currently has H1, intro, then !!! warning "Educational use only" and a "Before you start" block before the first H2. The spec does not say whether the Action Block comes before the disclaimer, after it, or replaces the prerequisite block.

Field-quality items are not yet binary enough. F1 can reject banned verbs, but it cannot verify that the chosen action is actually the highest-value first action. F2 can check allowed tier words, but not whether cost actually gates the page. F4 can check obvious brand names only if there is a brand denylist; otherwise terms like Coban, Steri-Strips, Telfa, NOCO, and WaterBOB will be handled inconsistently. R1/R2 are editorial judgments. R3 is mechanically checkable if Foundation boundaries can be inferred from link paths. R4 is only checkable if "links to a specific inline admonition" means an actual markdown anchor or explicit reference, not the current example's plain text "See danger admonition below."

"Do this first" is falsifiable only if the spec defines a failure test. Lines 58 and 129 require "action verb + concrete object + time estimate" and ban three vague verbs. That catches "learn water storage," but not weak actions like "Review your options (10 min)," "Assess readiness (15 min)," or "Prepare supplies (20 min)." On procedural/life-safety pages this can mislead. For medical/wounds.md, "Assemble a wound kit (15 min)" is valid but wrong as the first action for acute wound care; "Control active bleeding, then irrigate with clean water or saline (5-10 min)" is falsifiable against the visible procedure.

The proposed page_action_block_check.py is necessary but insufficient. It can catch missing blocks, literal labels, rough placement, and Page meta drift. It cannot validate the eight required fields unless it parses field names; cannot determine mobile fit; cannot validate source hierarchy against actual citations; cannot know whether links are author-curated; and cannot judge safety/legal completeness or skill level correctness. The script description also says yaml.safe_load while requiring stdlib-only at line 170. PyYAML is not stdlib. Either implement a tiny front-matter parser for scalar keys or drop "stdlib-only."

The skill-level scale is usable as a display field, but it does not stand up across all 12 Foundations without definitions. "Expert+licensed" conflates complexity with legal authorization. Electrical work may be intermediate to understand but licensed to perform. Food preservation may be beginner for jam and high-consequence for pressure canning. Firearms/security topics depend on legal training, range proficiency, and jurisdiction. Medical topics split between layperson emergency care and clinician-only care. Add criteria: beginner = no prior practice and low irreversible harm; intermediate = practice required; advanced = failure can injure or destroy property; expert+licensed = license, permit, or supervised training required.

2. Field definition ambiguity

Do this first. Lines 19, 58, and 129 need a "single highest-value next action" rule. For operational pages, use the smallest action that materially improves readiness today. For procedural pages, use the first safe action in the procedure, including prerequisites such as "control bleeding first." Ban more generic verbs: review, assess, prepare, plan, consider, understand, learn, familiarize, explore, improve.

Time required. Line 59 does not define active work, elapsed waiting time, procurement time, skill acquisition time, or recurring maintenance. The water example mixes active setup and recurring rotation. Recommended format: Active: X; elapsed/wait: Y if applicable; recurrence: Z. If learning curve matters, name it as practice time.

Cost range. Lines 60 and 130 match STYLEGUIDE, which is good. The bright-line for dollar amounts should mirror STYLEGUIDE: use approximate USD only when the reader must choose between materially different paths and tier language cannot distinguish them. Water storage can use tiers by scale; batteries may need approximate ranges only if the page asks the reader to choose between small UPS, portable power station, and whole-home system.

Skill level. Line 61 needs definitions and examples per Foundation. It also needs a rule for pages with multiple sub-tasks. water/storage.md is beginner for jugs but advanced/professional for buried cisterns. Allow formats like "Beginner baseline; advanced/pro for cistern installation."

Tools needed. Line 62 says physical tools/items, but examples include consumables and infrastructure: tap water, labels, containers. Either split tools/supplies/infrastructure or rename the field "Tools/supplies needed." Brand-name enforcement needs a generic-name exception or replacement rule: "self-adherent wrap" instead of Coban; "closure strips" instead of Steri-Strips.

Safety warnings. Line 63 says "See danger admonition below" or "(none)," but the sample pages mostly use !!! warning, not !!! danger. Define the bright line: use (none) only if the page contains no warning/danger admonition and no life-safety claim under § 11 A4-style logic. If the page has warning/danger content, point to the most important same-page warning by title.

Legal/regional caveats. Line 64 says "Cite jurisdiction layers" but gives no granularity. Include federal/national rules when universally relevant; state/province variation when legality materially changes; county/city/HOA only for land use, structures, weapons, water rights, animals, fire, sanitation, or radio transmission. For medical pages, this may be scope-of-practice or prescription status, not geography.

Page meta. Lines 65 and 133 conflict: the table says "depth: X · criticality: Y" while the example shows operational · life-safety. Pick one literal format. I recommend depth: operational · criticality: high.

Last reviewed. Line 86 is clear if derived from date_modified. The validator should check it, or it becomes another manual drift point.

Source hierarchy. Lines 87 and 137 say "top 2 Tier 1 sources actually cited." Neither sample page has a formal source list. medical/wounds.md mentions American College of Surgeons and USDA without links. Define precedence: choose sources supporting the highest-risk claims; prefer government/standards/medical institutions; prefer sources cited near claims; exclude minor background sources.

Next 3 links. Lines 88, 138, and 139 need a routing rule. "Next" should mean most likely next action after completing this page, not merely related reading. Each rationale should imply "go here if..." Cross-Foundation routing is good, but allow a documented waiver when honest next actions are intra-Foundation.

3. Mobile rendering edge cases

The top block will not fit the stated budget. The worked example at lines 72-79 has eight source lines, but several exceed 80 characters and will wrap on a 393px viewport. Material admonitions add icon/title chrome and padding; usable text width is closer to 300-330px. At typical body type, that is roughly 35-45 characters per visual line. The example's eight logical lines likely render as 12-16 visual lines plus title, exceeding one screen once H1 and intro are included.

Stacking !!! info "Action block" immediately before a !!! warning or !!! danger block risks alert fatigue. medical/wounds.md would become H1, intro, Action Block, educational warning, prerequisite block, then H2. The pilot should screenshot pages where a warning appears before the first H2 and decide whether medical disclaimers precede the Action Block.

Print compatibility at lines 114 and 235 is under-specified. The reportlab pipeline needs explicit checks for admonition title, nested numbered/bulleted lists, link rendering, and page breaks. The bottom block's nested lists are exactly the structure most likely to degrade in PDF extraction.

4. Schema concerns

"No JSON-LD for the block" is defensible, but the boundary should be explicit. Existing standards already require schema_json on procedural pages, and medical/wounds.md already has FAQPage plus HowTo schema. Duplicating "Do this first" into HowTo JSON-LD risks mismatch unless the visible procedure and schema step are updated too.

Recommended rule: the Action Block does not create separate schema. If the page already has HowTo schema, Do this first must be consistent with the first visible HowTo step and schema step. For operational pages like water storage, forcing HowTo schema may create artificial steps.

ItemList for "Next 3 links" is not worth it in v1. These are navigational links, not a ranked list of products or steps. If search-snippet eligibility matters, improve existing FAQ/HowTo coverage where natural.

Surfacing criticality: life-safety creates a trust/legal concern. "Page meta: operational · life-safety" may be interpreted as a warranty or official safety classification. Safer wording: "Safety stakes: life-safety topic" or "Review level: life-safety page; verify against current local/professional guidance." For medical pages, pair it with the educational-use warning.

5. Structural problems vs. § 11

No direct contradiction with § 11 for pure hub pages: lines 38 and 165 correctly exclude hubs. The unresolved edge is a hub/spine hybrid. Define "spine page" mechanically: content child page under docs/{foundation}/ excluding index.md, guides, about pages, specs, and generated pages. If a child page functions as a mini-hub, § 13 should still apply unless formally promoted to index.md.

Lens naming is structurally consistent but semantically noisy. § 11 uses R/A/S/C; § 13 uses B/F/R/V. Reusing R for Routing makes "R3" ambiguous unless always qualified as "§ 13 R3." Consider N for Navigation.

§ 13 also lacks § 11's "Known v1.1 work" discipline. Add a post-pilot refinement queue: mobile line budget, skill taxonomy, source-selection disputes, schema consistency, and field-count reduction.

6. Hard-fail scope

Life-safety-first gating is reasonable, but too narrow for the block's purpose. water/storage.md is criticality: high, not life-safety, yet it is the spec's primary example and one of the highest-impact pilot pages. If high-criticality pages only warn for 30 days, the canonical example class can drift.

depth: procedural should hard-fail for block presence once the pilot is complete, regardless of criticality. Procedural pages are where readers are most likely to act immediately.

Recommended gating:

• Pilot/WARN: all five pilot pages.
• Codification + 7 days: hard-fail criticality: life-safety and all pilot pages.
• Codification + 30 days: hard-fail criticality: high and depth: procedural.
• Opportunistic: criticality: standard non-procedural pages outside the 36-page spine.

B2 should also become hard-fail for required pages. A top block without bottom source/routing answers action questions but not trust or next-step questions.

7. Recommendation

Hard blockers before § 13 codifies:

• Fix the stdlib/PyYAML contradiction in validator design.
• Resolve Page meta literal format.
• Define placement when a page has an opening educational warning, prerequisite block, hero, or first-H2 disclaimer.
• Replace the mobile budget with a rendered screenshot requirement or reduce top-block fields.
• Define Safety warnings as warning/danger with actual same-page anchor/reference mechanics.

Soft improvements before pilot:

• Rename "Tools needed" to "Tools/supplies needed" or define tool/consumable/infrastructure boundaries.
• Add skill-level definitions and Foundation-specific examples.
• Add source-selection precedence for pages with many Tier-1 sources.
• Allow Next 3 links cross-Foundation waiver.
• Decide whether legal/regional caveats belongs in the bottom block.
• Add screenshot/PDF verification, especially for medical/wounds.md.

Open questions for the author:

• Should medical/life-safety pages show the educational-use warning before or after the Action Block?
• Should the top block be capped at six fields, moving legal caveats and page meta to bottom?
• Should Last reviewed and Page meta be auto-derived to eliminate drift?
• What is the generic-name policy for common trademarked medical/material terms?
• Is the field intended for urgent incident use, pre-incident preparation, or both?

Overall verdict: NEEDS-REVISION.

The concept is ready for a five-page pilot after tightening, but not ready to codify as STANDARDS § 13. The major issues are enforceability and rendering details that will produce inconsistent retrofits across 36 pages if left open.