Audit: Phase 7b Content Patterns

audit-phase7b-content-patterns Doc

active benchmark

Project

Audit: Phase 7b Content Patterns

Content audit of all 256 notes in pal-e-docs, cataloging every HTML element and pattern the Phase 7b parser must handle. Captured 2026-03-07 by Dottie.

Corpus Summary

Metric	Value
Total notes	256
Note types present	11: plan (38), todo (38), phase (34), doc (9), sop (13), convention (10), project-page (11), template (9), agent (5), skill (5), issue (1), plus 85 untyped
Notes with headings	229 (89%)
Notes with no headings	27 (11%)

HTML Elements Found

Element	Prevalence	Parser Block Type	Notes
<code><h2></code>	~180 notes	<code>heading</code>	Used as note title echo AND as section dividers. See "Redundant h2" section below.
<code><h3></code>	~220 notes	<code>heading</code>	Primary section heading. Most common heading level.
<code><h4></code>	~40 notes	<code>heading</code>	Sub-subsections. Plans and phase notes use these for deliverable sub-items.
<code><p></code>	~256 notes	<code>paragraph</code>	Universal. Contains inline <code><strong></code>, <code><em></code>, <code><code></code>, <code><a></code>.
<code><ul></code>	239 notes (93%)	<code>list</code>	Unordered lists. Most common structural element after paragraphs.
<code><ol></code>	~60 notes	<code>list</code>	Ordered lists. SOPs, workflows, debugging stories.
<code><table></code>	118 notes (46%)	<code>table</code>	All use <code><tr><th></code> for headers, never <code><thead></code>/<code><tbody></code>. See table edge cases below.
<code><pre><code></code>	72 notes (28%)	<code>code</code>	Code blocks. No language hints (no <code>class="language-*"</code>). Plain text content.
<code><pre class="mermaid"></code>	37 notes (14%)	<code>mermaid</code>	Mermaid diagrams. Whitespace-sensitive. No nested <code><code></code> wrapper.
<code><code></code> (inline)	~240 notes	within <code>paragraph</code>	Inline code for slugs, commands, variable names. NOT a standalone block.
<code><strong></code>	~230 notes	within <code>paragraph</code>	Bold emphasis. Inline element within paragraphs and list items.
<code><em></code>	~30 notes	within <code>paragraph</code>	Italic emphasis. Less common than strong.
<code><a href="..."></code>	~15 notes	within <code>paragraph</code>	External links. Mostly in project-page repo tables and concept docs.

Redundant h2 Title Pattern

Many notes start with <h2>Note Title</h2> that exactly matches the title field. This is the html-style-guide standard pattern, but it means the title is stored twice (in the title column and in the HTML content).

Pattern	Estimated Count	Examples
h2 matches title exactly	~120 notes (47%)	<code>plan-skill-enforcement-gap</code>, <code>template-sprint-item</code>, <code>skill-sprint-sync</code>, all plan stubs
h2 present but differs from title	~60 notes (23%)	<code>deployment-lessons</code> (title: "Deployment Lessons Learned", h2: "Hard Shutdown Survival...")
No h2, starts with h3	~50 notes (20%)	<code>bug-grafana-crashloop</code>, <code>bug-cnpg-webhook-drift-wal-timeout</code>, <code>concept-argocd-ghost-override</code>
No headings at all	27 notes (11%)	<code>phase-postgres-1-tf-modularize</code> (single paragraph)

Parser implication: The parser should not assume the first element is an h2 matching the title. It must handle all four patterns. The compiler should decide whether to emit the redundant h2 or suppress it (since base.html already renders the title as h1).

Content Before First Heading

Some notes have paragraph content before any heading element. This is common in phase notes and newer doc notes.

Pattern	Count	Examples
Starts with <code><p></code> before any heading	~45 notes	<code>phase-postgres-7b-parser-compiler</code> (5 paragraphs before first h3), <code>phase-postgres-1-tf-modularize</code> (only content is a paragraph)
Starts with <code><h2></code>	~120 notes	Standard html-style-guide pattern
Starts with <code><h3></code>	~65 notes	Bug/issue notes, concept docs
Starts with <code><h2></code> then <code><p></code> then <code><h3></code>	~25 notes	Standard pattern with intro paragraph

Parser implication: Content before the first heading must become standalone blocks (not orphaned). The flat-block model handles this naturally -- paragraphs before the first heading are just paragraph blocks with no preceding heading block.

Table Edge Cases

Pattern	Prevalence	Example
Standard: first row is <code><th></code>, rest are <code><td></code>	~110 notes	Most tables follow this
<code>colspan</code> attribute on cells	~5 notes	<code>project-pal-e-docs</code> roadmap table uses <code>colspan="3"</code> for section headers
No <code><thead></code>/<code><tbody></code>	All 118 notes	Consistent: flat <code><tr></code> rows only. Parser can assume first row with <code><th></code> = header.
Bold text in cells (<code><strong></code>)	~40 notes	<code>benchmark-phase7-block-baseline</code> uses bold for key values
Code in cells (<code><code></code>)	~80 notes	Slug references, command names in table cells
Links in cells (<code><a></code>)	~10 notes	Project pages with repo URLs

List Edge Cases

Pattern	Prevalence	Example
Flat list items	~230 notes	Standard pattern
Nested lists (<code><ul></code> inside <code><li></code>)	~25 notes	<code>skill-sprint-sync</code> (sub-steps within numbered items)
Checklist pattern (<code>[x]</code> / <code>[ ]</code>)	~15 notes	<code>bug-grafana-crashloop</code> acceptance criteria
Rich content in items (<code><strong></code> + text)	~150 notes	Definition-list style: <code><strong>Term:</strong> description</code>
Code blocks inside list items	~5 notes	SOPs with inline commands in steps

Code Block Edge Cases

Pattern	Prevalence	Example
<code><pre><code>...</code></pre></code>	72 notes	Standard pattern. No language class attributes.
<code><pre class="mermaid"></code> (no <code><code></code>)	37 notes	Mermaid diagrams use <code><pre></code> directly, not nested <code><code></code>.
Language hints	0 notes	No notes use <code>class="language-python"</code> or similar. All code blocks are plain text.
HTML entities in code	~20 notes	Code blocks containing <code>&lt;</code>, <code>&gt;</code>, <code>&amp;</code> for HTML examples.

Parser implication: Distinguish <pre class="mermaid"> (mermaid block) from <pre><code> (code block). The class attribute on <pre> is the discriminator.

Mermaid-Specific Patterns

Always <pre class="mermaid">, never <pre><code class="mermaid">
Whitespace inside the <pre> is significant -- diagram definitions are multi-line, indentation matters
Diagram types found: graph TD, graph LR, flowchart TD, sequenceDiagram
37 notes total, concentrated in project-pages (11) and architecture docs

Inline Element Patterns

These are NOT standalone blocks but appear inside paragraphs, list items, and table cells:

Element	Context	Parser Handling
<code><strong></code>	Everywhere: paragraphs, lists, tables	Preserve as inline HTML within block content
<code><em></code>	Paragraphs, occasional list items	Preserve as inline HTML within block content
<code><code></code> (inline)	Everywhere. Slugs, commands, variables.	Preserve as inline HTML. Auto-linked by frontend.
<code><a href></code>	Project pages, repo tables, some docs	Preserve as inline HTML within block content

Inconsistencies Found

Issue	Count	Impact
Multiple <code><h2></code> in one note (not title echo)	~5 notes	<code>deployment-lessons</code> uses h2 for each lesson section. Parser must handle multiple h2s, not just one at the top.
h2 title echo inconsistent with <code>title</code> field	~3 notes	<code>project-pal-e-docs</code> has h2 "pal-e-docs" but title is "Project: pal-e-docs". Parser cannot assume h2 == title.
HTML entities in titles	1 note	<code>plan-2026-02-28-agent-skill-frontmatter</code> has <code>&amp;</code> in title field. Parser must handle entity-encoded content.
Badge classes in note content	0 notes	Badge classes (<code>.badge-github</code>, etc.) are used only by Jinja2 templates, not in note <code>html_content</code>.
Inline <code>style</code> attributes	0 notes	No notes violate the html-style-guide prohibition on inline styles.
<code><div></code> elements	0 notes	No notes use divs. Clean semantic HTML throughout.

Elements NOT Found (Parser Can Skip)

<h1> -- never used in note content (rendered by base.html from title)
<h5>, <h6> -- never used
<img> -- never used (mermaid replaces diagrams)
<div> -- never used
<span> -- never used in note content
<blockquote> -- never used
<hr> -- never used
<dl>/<dt>/<dd> -- never used (definition-style lists use <strong> in <li> instead)

Summary for Parser Implementation

The parser must handle exactly these top-level elements:

<h2>, <h3>, <h4> -- heading blocks (3 levels)
<p> -- paragraph blocks (with inline HTML preserved)
<ul>, <ol> -- list blocks (with nested sub-lists possible)
<table> -- table blocks (th-first-row convention, colspan possible)
<pre><code> -- code blocks (no language hints)
<pre class="mermaid"> -- mermaid blocks (whitespace-sensitive)

That is the complete set. No other top-level elements exist in the corpus. Inline elements (<strong>, <em>, <code>, <a>) appear only inside the above block elements and should be preserved as raw HTML in block content.

benchmark-phase7-block-baseline -- quantitative baseline (sizes, distributions)
phase-postgres-7b-parser-compiler -- the phase this audit supports
html-style-guide -- the authoring convention (what SHOULD be used)

Audit: Phase 7b Content Patterns