Runtime Configuration (Step 0 — before any processing)
Read these files to configure domain-specific behavior:
-
ops/derivation-manifest.md— vocabulary mapping, platform hints- Use
vocabulary.notesfor the notes folder name - Use
vocabulary.note/vocabulary.note_pluralfor note type references - Use
vocabulary.topic_mapfor MOC references - Use
vocabulary.templatesfor the templates folder path
- Use
-
ops/config.yaml— processing depthprocessing.depth: deep | standard | quick
If these files don't exist, use universal defaults.
Processing depth adaptation:
| Depth | Validation Behavior |
|---|---|
| deep | Full schema validation. All checks enabled including composability analysis and cross-reference verification |
| standard | Full validation — all checks enabled |
| quick | Basic schema validation only — required fields, YAML validity, enum values |
EXECUTE NOW
Target: $ARGUMENTS
Parse immediately:
- If target contains a note name: validate that specific note
- If target contains
--handoff: output RALPH HANDOFF block at end - If target is "all" or "notes": validate all notes in {DOMAIN:notes}/ directory
- If target is empty: ask which note to validate
Execute these steps:
Step 1: Locate Template
Determine which template applies to the target note:
- Check the note's location — notes in {DOMAIN:notes}/ use the standard note template
- Check the
typefield in frontmatter — specialized types may have dedicated templates - Look for a templates directory (check
ops/templates/or domain-specific path from derivation manifest) - If the template has a
_schemablock, read it — this is the authoritative schema definition
If no template is found, use the default schema checks below.
Step 2: Read Target Note
Read the target note's full YAML frontmatter. Parse:
- All YAML fields and their values
- The body content (for link scanning)
- The footer section (for Topics and Relevant Notes)
Step 3: Run Schema Checks
Run ALL validation checks. Each check produces PASS, WARN, or FAIL.
START NOW.
Schema Checks
Required Fields (FAIL if missing)
| Check | Rule | How to Verify |
|---|---|---|
description | Must exist and be non-empty | Check YAML frontmatter for description: field with non-empty value |
| Topics | Must link to at least one {DOMAIN:topic map} | Check for topics: in YAML or Topics: section in footer. Must contain at least one wiki link |
A missing required field is a hard failure. The note cannot pass validation without these.
Description Quality (WARN if weak)
| Check | Rule | How to Verify |
|---|---|---|
| Length | Should be ~50-200 characters | Count characters in description value |
| New information | Must add context beyond the title | Compare description text against filename/title — if semantically equivalent, WARN |
| No trailing period | Convention: descriptions don't end with periods | Check last character |
| Single sentence | Should be one coherent statement | Check for sentence-ending punctuation mid-description |
How to check "adds new info": Read the title (filename without .md). Read the description. If the description merely restates the title using different words, it fails this check. A good description adds one of:
- Mechanism — how or why the claim works
- Scope — what boundaries the claim has
- Implication — what follows from the claim
- Context — where the claim applies
Examples:
Bad (restates title):
- Title:
vector proximity measures surface overlap not deep connection - Description: "Semantic similarity captures surface-level overlap rather than genuine conceptual relationships"
Good (adds mechanism):
- Title:
vector proximity measures surface overlap not deep connection - Description: "Two notes about the same concept with different vocabulary score high, while genuinely related ideas across domains score low"
YAML Validity (FAIL if broken)
| Check | Rule | How to Verify |
|---|---|---|
| Frontmatter delimiters | Must start with --- on line 1 and close with --- | Read first line and scan for closing delimiter |
| Valid YAML | Must parse without errors | Check for common YAML errors: unquoted colons in values, mismatched quotes, bad indentation |
| No duplicate keys | Each YAML key appears only once | Scan for repeated field names |
| No unknown fields | Fields not in the template schema | Compare against _schema.required and _schema.optional if available — unknown fields get WARN |
Domain-Specific Enum Checks (WARN if invalid)
If the note has fields with enumerated values, check them against the template's _schema.enums block:
| Field | Expected | Severity |
|---|---|---|
type | Values from template enum (e.g., claim, methodology, tension, problem, learning) | WARN |
status | Values from template enum (e.g., preliminary, open, dissolved) | WARN |
classification | Values from template enum (e.g., open, closed) | WARN |
| Custom domain fields | Values from template enum | WARN |
If a field has a value not in the enum list, report the invalid value and list the valid options.
Link Health (WARN per broken link)
| Check | Rule | How to Verify |
|---|---|---|
| Body wiki-links | Each [[link]] should point to an existing file | Extract all [[...]] patterns from body, check each against file tree |
| Topics links | {DOMAIN:topic map} referenced in Topics must exist | Verify each topic wiki link resolves |
| Relevant notes links | Each note in relevant_notes must exist | Verify each wiki link in relevant_notes resolves |
| Backtick exclusion | Wiki links inside backticks are examples, not real links | Skip [[...]] patterns inside single or triple backtick blocks |
How to verify link resolution: For each [[link text]], check if a file named link text.md exists anywhere in the vault. Wiki links resolve by filename, not path.
Relevant Notes Format (WARN if incorrect)
| Check | Rule | Severity |
|---|---|---|
| Format | Array with context: ["[[note]] -- relationship"] | WARN |
| Context phrase present | Each entry should include -- or — followed by relationship description | WARN |
| Relationship type | Standard types: extends, foundation, contradicts, enables, example | INFO |
| No bare links | ["[[note]]"] without context is a bare link — useless for navigation | WARN |
Composability (WARN if fails)
| Check | Rule | How to Verify |
|---|---|---|
| Title test | Can you complete "This note argues that [title]"? | Read the title as a sentence fragment — does it make a claim? |
| Specificity | Is the claim specific enough to disagree with? | Could someone reasonably argue the opposite? |
| Prose fitness | Would since [[title]] read naturally in another note? | Check if the title works as an inline wiki link |
Topic labels vs claims:
- "knowledge management" — topic label, not a claim, FAILS composability
- "knowledge management requires curation not accumulation" — claim, PASSES composability
Batch Mode
When validating all notes (target is "all" or "notes"):
- Discover all .md files in {DOMAIN:notes}/ directory
- Optionally include additional directories (e.g., self/memory/) if they exist
- Run all schema checks on each note
- Produce summary report:
- Total notes checked
- PASS / WARN / FAIL counts
- Top issues grouped by check type
- Notes needing immediate attention (FAIL items)
- Pattern analysis: are certain check types failing systematically?
Batch output format:
## Validation Summary
Checked: N notes
- PASS: M (X%)
- WARN: K (Y%)
- FAIL: J (Z%)
### FAIL Items (immediate attention)
| Note | Check | Detail |
|------|-------|--------|
| [[note]] | description | Missing |
| [[note]] | topics | No topics f