fix: align H1 headings with frontmatter title convention by waynesun09 · Pull Request #36 · fullsend-ai/experiments

waynesun09 · 2026-07-02T20:55:34Z

Summary

Update all 21 experiment H1 headings to match their frontmatter title: field
The numbering convention (PR feat: add experiment numbering and metadata conventions #35) set frontmatter titles to NNNN. Title format but left H1 headings with old inconsistent formats (Experiment 002:, PoC FullSend, ADR 0022, etc.)
The fullsend docs site sidebar extracts H1 for directory-based entries (fullsend-ai/fullsend#2969), so mismatched H1s cause wrong sidebar titles

Test plan

Verify no remaining frontmatter/H1 mismatches: for d in 0*/; do fm=$(grep -m1 "^title:" "$d/README.md" | sed 's/^title:\s*//' | tr -d '"'); h1=$(grep -m1 "^# " "$d/README.md" | sed 's/^# //'); [ "$fm" != "$h1" ] && echo "MISMATCH: $d"; done
Pre-commit hooks pass (lint-experiment-numbers, lint-experiment-frontmatter, lint-experiment-index)
After merging and bumping the submodule in fullsend, sidebar titles display correctly

The experiment numbering convention (PR #35) set frontmatter titles to the `NNNN. Title` format but left H1 headings with their old inconsistent formats (e.g. "Experiment 002:", "PoC FullSend", "ADR 0022"). This causes the fullsend docs site sidebar to display wrong titles since it falls back to H1 when rendering directory entries. Update all 21 experiment H1 headings to match their frontmatter title field exactly. Assisted-by: Claude (fix) Signed-off-by: Wayne Sun <gsun@redhat.com>

fullsend-ai-review · 2026-07-02T20:56:17Z

🤖 Review · ⚠️ Cancelled · Started 8:56 PM UTC · Ended 8:57 PM UTC
Commit: 0a95cac · View workflow run →

qodo-code-review · 2026-07-02T20:56:35Z

PR Summary by Qodo

Align experiment H1 headings with frontmatter titles

🐞 Bug fix 📝 Documentation 🕐 10-20 Minutes

AI Description

• Update 21 experiment docs so the H1 exactly matches frontmatter title:.
• Fix docs-site sidebar titles that fall back to H1 for directory entries.
• Normalize legacy heading formats ("Experiment 002:", "PoC", "ADR") to NNNN. Title.

Diagram

graph TD
  A["Experiment markdown files"] --> B(["Docs site renderer"]) --> C{"H1 matches frontmatter title?"}
  C -->|"Yes"| D["Correct sidebar label"]
  C -->|"No"| E["Wrong sidebar label"]
  subgraph Legend
    direction LR
    _file["Document"] ~~~ _proc(["Process"]) ~~~ _dec{"Decision"}
  end

High-Level Assessment

The following are alternative approaches to this PR:

1. Update the docs site to prefer frontmatter title for directory entries

➕ Eliminates reliance on H1 as a fallback source of truth
➕ Prevents future sidebar regressions even if authors change headings
➖ Requires changes in the consuming docs site repo and its release process
➖ May not be possible if the renderer cannot access frontmatter for directory nodes

2. Add/strengthen a lint rule enforcing `title:` == H1

➕ Prevents drift from reappearing
➕ Keeps the convention explicit and automatically enforced in CI/pre-commit
➖ Doesn't fix existing mismatches by itself
➖ Adds maintenance cost to lint tooling and contributor workflow

Recommendation: The PR’s approach is the fastest and least invasive fix for the current regression: make the H1 match the established frontmatter NNNN. Title convention everywhere. As a follow-up, consider adding/confirming an automated lint check for title:/H1 equality to prevent future drift; updating the docs site to always prefer frontmatter is attractive but belongs in the consumer repo and may not be feasible depending on its renderer.

Files changed (21) +21 / -21

Documentation (21) +21 / -21

0001-agent-outage-fire-drill.mdAlign H1 heading with frontmatter title +1/-1

Align H1 heading with frontmatter title
• Replaces the legacy H1 format ("Experiment 003: …") with the normalized numbered title matching the frontmatter 'title:' field.
0001-agent-outage-fire-drill.md