Frontmatter Guard Skill
Convention: see
conventions/quality.md(viaget_skill conventions/quality) for citation rules; this skill is structural validation, not citation auditing.
Contract
This skill guarantees:
- Every brain page is scanned against the eight canonical frontmatter validation classes
- Mechanical errors (nested quotes, missing closing
---, null bytes, slug mismatch) are auto-repairable on demand — every repair is apage_put, so the pre-fix content survives as a prior version (page_versions/page_revertis the undo) - Validation aligns with
run_doctor's health surface — one source of truth for what "malformed" means - Reports per source (the brain indexes multiple sources; the read-only note corpus is one of them); never silently audits the wrong root
Why This Exists
Brain pages pile up over months. Agents write them with malformed frontmatter:
- Missing closing
---(entity detector bugs) - Unstructured YAML in meeting pages (ingestion bugs)
- Slug mismatches (path renames not propagated)
- Null bytes (binary corruption from copy-paste accidents)
- Nested double quotes in titles (
title: "Phil "Nick" Last")
Without a guard, these accumulate silently until indexing chokes or search returns garbage. The guard makes the failure visible at audit time and trivially fixable.
Validation classes
| Code | Meaning | Auto-fixable? |
|---|---|---|
MISSING_OPEN |
Page body doesn't start with --- |
No (needs human) |
MISSING_CLOSE |
No closing --- before first heading |
Yes |
YAML_PARSE |
YAML failed to parse | Sometimes (depends on cause) |
SLUG_MISMATCH |
Frontmatter slug: differs from path-derived slug |
Yes (removes the field) |
NULL_BYTES |
Binary corruption (\x00) |
Yes |
NESTED_QUOTES |
title: "outer "inner" outer" shape |
Yes |
NON_STRING_FIELD |
title/type/slug is an unquoted non-string scalar (e.g. title: 123, slug: 2024-06-01) |
No (quote the value) |
EMPTY_FRONTMATTER |
Open + close present but nothing between | No (needs human) |
Phases
Phase 1: Audit
Run a read-only scan. Start from the doctor's health surface, then narrow:
run_doctor # or from the shell: memrain doctor --json
sources_list # which sources are registered
source_health # per-source ingest/index state
Report:
- Per-source counts grouped by error code
- Sample of up to 20 affected pages per source (pull candidates via
page_listand inspect suspicious ones withpage_get) - Total count
- Scan timestamp
Parse the doctor output and the per-page inspection to decide next steps — never assume a brain is clean.
Phase 2: Validate one page
Validate a single page or prefix without a full sweep:
page_get <slug> # read the raw page
page_list <prefix> # enumerate a directory's pages
Check the page's frontmatter against the eight classes above. Clean = no codes fired; report any that did.
Phase 3: Fix
When issues are found, repair the page and write it back:
page_put <slug> <repaired content>
Every page_put records a new version — the pre-fix content is one
page_versions call away, and page_revert restores it. That version
history is the safety contract; there are no loose backup files to manage.
Preview before applying in batch: state exactly which pages will be modified and what each fix does, then confirm.
Read-only source caveat: pages indexed from the read-only note corpus
(the memory source) cannot be repaired with page_put — fix the
underlying note on disk, then reindex it (memrain reindex or the index
tool) so the corrected frontmatter lands.
Phase 4: Write-time prevention (optional)
There is no commit hook to install — the brain is DB-canonical, and the
guard runs at write time in your own workflow instead: validate the
frontmatter you are ABOUT to page_put against the eight classes before
sending it. For the read-only note corpus, run the Phase 1 audit on a
schedule (a systemd timer on the host, or your harness's scheduler) so
drift in the source files is caught at the next sweep.
Trigger words
When the user says any of these, route here:
- "validate frontmatter"
- "check frontmatter"
- "fix frontmatter"
- "frontmatter audit"
- "brain lint"
Output rules
- Always run the Phase 1 audit first; never assume a brain is clean.
- Surface counts to the user in plain language; do not dump raw JSON.
- For fix operations: state how many pages will be modified BEFORE writing, then confirm.
SLUG_MISMATCHfixes remove the frontmatterslug:field — the brain derives slug from path. Mention this when the user's title is intentionally renamed.- Never auto-fix
MISSING_OPENorEMPTY_FRONTMATTERwithout explicit user input — these usually mean a human author started a page and didn't finish.
Chains with
run_doctor— the doctor's integrity checks report the same class of problems as the Phase 1 audit.skills/maintain— broader brain health audit; chain after this skill if other classes of issue are suspected.skills/eiirpPhase 6 — the post-work verification pass expects frontmatter to be clean before it signs off.
Output Format
Audit summary (terse, agent-friendly):
Frontmatter audit — 17 issue(s) across 1 source(s)
[memory] read-only note corpus
17 issue(s)
MISSING_CLOSE: 8
NESTED_QUOTES: 5
NULL_BYTES: 4
sample:
people/jane — MISSING_CLOSE
companies/acme — NESTED_QUOTES
(+ 12 more)
Fix: repair DB-canonical pages via page_put; for [memory] fix the
source notes, then reindex.
Structured envelope (when reporting for a downstream skill to parse):
{
"ok": false,
"total": 17,
"errors_by_code": { "MISSING_CLOSE": 8, "NESTED_QUOTES": 5, "NULL_BYTES": 4 },
"per_source": [
{
"source_id": "memory",
"total": 17,
"errors_by_code": { "MISSING_CLOSE": 8, "NESTED_QUOTES": 5, "NULL_BYTES": 4 },
"sample": [{ "slug": "people/jane", "codes": ["MISSING_CLOSE"] }]
}
],
"scanned_at": "2026-04-25T22:30:00.000Z"
}
Single-page validation returns a similar envelope keyed on per-page results instead of per-source.
Prevention — Writing Valid Frontmatter
This is the most important section. Fixing broken frontmatter is good. Not writing broken frontmatter in the first place is better.
YAML arrays (the historical #1 error source)
# Correct: single-quoted YAML flow (canonical form)
tags: ['yc', 'w2025', 'ai']
# Correct: unquoted scalars (fine when values have no special chars)
tags: [yc, w2025, ai]
# Correct: block style
tags:
- yc
- w2025
# Tolerated but non-canonical: JSON-style double quotes
tags: ["yc", "w2025"]
# Broken: mixed JSON objects and strings (invalid YAML)
tags: [{"name": "sports"}, "posterous"]
Why this used to break: a naive validator counts unescaped " characters and flags any line with 3+. A flow sequence like tags: ["yc", "w2025"] has 4 unescaped " by design — it's valid YAML, but the dumb counter flags it anyway; one long-running brain accumulated nearly 7,000 such false positives in a single audit. The right check parses suspicious values with a real YAML parser before flagging, so JSON-style arrays never trigger NESTED_QUOTES.
Why you should still write the canonical form: repairs and inferred frontmatter both emit single-quoted YAML for tags: / aliases:. Writing the canonical form in new content keeps pages stylistically consistent and makes repair diffs empty.
The classic LLM trap: code like tags: [${items.map(t => JSON.stringify(t)).join(', ')}] produces tags: ["yc", "w2025"]. Use single quotes with an apostrophe fallback: tags: [${items.map(t => t.includes("'") ? JSON.stringify(t) : "'" + t + "'").join(', ')}]. Or use a YAML library that knows how to emit canonical YAML.
Quoted scalars
# Correct: single quotes for values with special chars
title: 'My "Quoted" Title'
# Correct: double quotes when value has apostrophes
title: "Men's Fashion Guide"
# Broken: double quotes wrapping inner double quotes
title: "My "Quoted" Title"
When to quote at all
- Unquoted is fine for simple values:
type: person,batch: w2025 - Quote when the value contains
: " ' # [ ] { } | > & * ! ? ,or starts with@ - Single quotes are the default safe choice
- Double quotes only when the value itself contains apostrophes
Anti-Patterns
Don't auto-fix MISSING_OPEN or EMPTY_FRONTMATTER without user input. These usually mean a human author started a page and didn't finish — silently inserting --- markers around an unfinished draft is wrong.
Don't repair pages just to "make doctor green" without reading the audit first. SLUG_MISMATCH cases are surfaced for manual review specifically because the brain derives the slug from path. A mismatch usually means the user renamed a page intentionally; auto-removing the slug field is the right outcome only when you've confirmed the rename was deliberate.
Don't skip the version history. Every repair goes through page_put so page_versions retains the pre-fix content. If the user wants to review what changed after a batch fix, walk the versions with them — never repair through a side channel that bypasses versioning.
Don't audit a source that isn't registered. If sources_list doesn't show the root you're worried about, don't paper over it with a manual path-walk; the right fix is to register/ingest the source properly, then audit.
Don't promise write-time blocking for the read-only note corpus. Those files are authored outside the brain; the guard catches their problems at audit/reindex time, not at write time. If the user wants earlier feedback there, schedule the audit sweep more frequently.