Wed Field Hub Drilldown Pages

---
name: wed-field-hub-drilldown-pages
description: Build worldenergydata drill-down pages (field hub, well timelines, insight/norm pages) with the proven validate-first playbook, the fractal IA grammar, honesty rules, and the exact wed CI gotchas.
version: 1.0.0
tags: [worldenergydata, pages, lifecycle, drill-down, insights, benchmarking, ci-gotchas]
---

# worldenergydata field-hub drill-down pages — grammar + build playbook

Use this for ANY page work in the wed field-hub family: lifecycle posters, well timelines,
insight front-doors, phase-norm/benchmark pages, atlas/browse, asset drill-downs.
Source epics: wed#754 (fractal IA), wed#764 (engineering↔asset circle), wed#774 (insight family).
Live site: https://vamseeachanta.github.io/worldenergydata/

## IA grammar (non-negotiable contract)

1. **Fractal spine:** the same "stage-gate timeline + you-are-here + deep-dive" grammar recurs at
   every zoom level — Region ▸ Play ▸ Field ▸ Well ▸ Stage. New pages reuse the grammar, never
   invent a new one per page.
2. **Both-altitudes insight contract** (#754 comment issuecomment-4881675172): every life-cycle
   insight ships at TWO altitudes — (a) a standalone indexable front-door page (traffic magnet,
   own URL, specific title) AND (b) a per-well/per-field stage deep-dive card. Same data, two zooms.
3. **Unique live links:** every capability/insight gets its OWN purpose-built page — N distinct
   pages = N front doors. Never fold into a shared "dashboards" section.
4. **Comprehensiveness bar:** thesis + a number ("4.4× vessel shortfall, $375M–$1B/yr"), not
   descriptive stats.
5. **Drill-down CTAs:** poster/hub pages gain deep-dive links only when the target exists
   (generator globs for the artifact — e.g. `wells/<id>_*_well.html` — never hardcode).

## Honesty rules (these have killed 2 pitched theses — load-bearing)

- **Validate numbers BEFORE building.** Scratchpad probe / curated spec first; delegate the build
  only with acceptance targets. Verify the built artifact independently — not the agent's report.
- **Cite-or-null:** for web-sourced facts, 1 agent per item, refuse to borrow values across fields
  (em-dash the cell instead). Curate the spec yourself before build.
- **Honest density badges:** RICH / SAMPLE / ROADMAP per data reality (freshness-scorecard).
  Thin populations → explicit "insufficient (n=X)" badge, never a fabricated norm.
- **Like-for-like bases:** never compare native V30 rig-days against calendar-day proxies; tag
  every metric with its basis and compute deltas only within one basis (wed#848 rule).
- **Curated over raw:** play-level D&C stats come from the curated FDAS_V30 xlsx (drop the blank +
  TOTALS trailer rows — filter on LEASE_NAME notna), NOT raw WAR extraction (wed#846: raw overshoots
  published figures).

## Key data sources (verified 2026-07-06)

| Source | What it gives |
|---|---|
| `docs/modules/bsee/analysis/production/FDAS_V30/drilling_and_completion_days.xlsx` | LT play population, native rig-days (SPUD/TD dates, DRILLING_DAYS, COMPLETION_DAYS, TVD, mud wt) |
| `reports/lower_tertiary/lt_well_benchmark_lower_tertiary_2010_latest.csv` | 56 wells, field-crosswalked: api12, days, first_oil, cum_oil, uptime, interventions, decline |
| `data/modules/bsee/current/wells/well_data.csv` | 57k GoM boreholes: SPUD/TD dates (calendar proxy only), BOTM_FLD_NAME_CD, BOREHOLE_STAT_CD (PA/TA), TVD |
| `reports/lower_tertiary/lifecycle/_facts.json` | list of 10 field dicts (id, play, gates, reservoir, provenance) |
| `config/fields.yml` | #755 canonical crosswalk id ⇄ name ⇄ BSEE block/lease ⇄ surfaces flags |

Join trick: benchmark `api12` ↔ well_data `API_WELL_NUMBER` → discover a field's
`BOTM_FLD_NAME_CD` codes → pull the field's full well population.

## Build pipeline conventions

- Generator scripts live in `scripts/lower_tertiary/` (or `scripts/field_atlas/` etc.); each new
  publish family needs a `build_*` domain entry in `scripts/build_pages.py` AND (if new paths)
  `config/repo_structure.yml` allowlist rows.
- **build_pages renames on publish** (underscore→hyphen, path flatten) → author cross-page hrefs
  for the PUBLIC layout, then link-check the published tree.
- Templates: `reports/lower_tertiary/lifecycle/lifecycle_template.html` (field posters, stage
  cards + engtrack lane) and `lifecycle/wells/well_lifecycle_template.html` (dual-scale well
  timeline: rig-day construction band + calendar-year production band).
- Additive lanes that share a template/`__init__.py` → ONE integration PR (squash-merge breaks
  stacked PRs). After merge, GREP the unique markup on origin/main — bundled commits get lost in
  merge races (#767 lost in #788; re-landed #803).

## wed CI gotchas (every PR)

1. **Lint = THREE steps** on `src/ tests/`: mirror ALL of `uvx black@25.9.0`, `uvx isort@6.0.1`,
   `uvx flake8@7.3.0` (flake8 runs on `src/` only — modules under `packages/*/src/` are NOT
   flake8-gated; put lint-gated modules in `src/worldenergydata/`). black-only is not enough.
   Re-verify pins against `.github/workflows/ci.yml` before pushing (versions drift).
2. "Validate PR Title": conventional type required (`polish:` FAILS) and subject after
   `type(scope):` ≤ 80 chars.
3. Tests via `./.venv/bin/python -m pytest` (plain python3 is sandbox-blocked; uv broken in wed).
4. Branch protection: 11 checks + up-to-date; main churns → `gh pr merge <N> --auto --squash
   --delete-branch` + self-healing `gh pr update-branch` on BEHIND.
5. Agent can verify but NOT self-merge; hand the human the exact merge command.
6. NEVER blind `git stash pop` (pre-existing stale stashes corrupt worktrees); `git stash list`
   first. Single-lane worktree off fresh origin/main for template-touching work.

## Related
- Plan precedent: `docs/plans/2026-07-06-issue-wed-848-phase-norm-layer.md` (phase-norm layer)
- Open family: wed#848 (norms), wed#849 (per-well economics), wed#850 (nav spine), #756/#757 (hub/econ)
- Memory: `project_wed_field_hub_ia_epic`, `feedback_unique_live_links_traffic_credibility`