Frontmatter Guard
Use this skill when the user asks to validate frontmatter, fix frontmatter, run a brain lint, or check local brain page structure.
Workflow
- Start read-only:
- inspect representative brain pages
- run
python3 scripts/brain_doctor.pyif available - if the upstream
gbrainCLI exists, prefer read-onlygbrain frontmatter audit --json
- Classify issues:
- missing opening or closing
--- - YAML parse errors
- empty frontmatter
- slug/path mismatch
- null bytes or non-text content in markdown files
- missing citation or source fields when local conventions require them
- missing opening or closing
- For mechanical fixes, show the intended file list before writing.
- For ambiguous fixes, ask for the intended title, type, or source instead of guessing.
- Re-run the audit after fixes.
Validation Classes
- file framing: opening and closing delimiters, UTF-8 text, and no null bytes
- YAML syntax: valid mappings, arrays, quoted scalars, and parseable dates
- schema: required fields, supported page type, and expected value shapes
- identity: slug, title, and path agreement
- provenance: source and citation fields required by the local page convention
Support four explicit modes: whole-corpus audit, single-path validation, scoped mechanical repair, and optional pre-commit validation. Quote scalar values when they contain YAML-significant punctuation, and prefer real YAML arrays over comma-packed strings.
Guardrails
- Do not auto-fix user-authored pages without a before/after plan.
- Do not remove citations while normalizing frontmatter.
- Do not treat citation repair as the same job; use
citation-fixerfor citation semantics. - Never install a pre-commit hook without explicit user authorization.