Frontmatter Is Navigation, Not Decoration
I gave Claude access to my personal workspace. Hundreds of markdown files — product specs, meeting notes, project trackers, stakeholder threads. Everything I use to manage products across multiple work contexts, all with structured YAML frontmatter.
It still got everything wrong.
Not because the information wasn’t there. The problem was how Claude looked for it.
How It Breaks
The obvious ones are fine. Say you have a note called “Meridian” in your project folder — a codename for a platform initiative. The AI reads the filename and writes three paragraphs about GPS coordinate systems and navigation protocols. You catch it immediately.
The dangerous failures look like correct answers. You ask for the launch date of a feature. The project spec has a milestone table: “Beta: March 15. Launch: April 23.” Clean, authoritative-looking data. The AI reports April 23. But the actual launch date moved to late May — a partner timeline shifted, and the sync from last Tuesday documented the slip. You forgot to update the spec because the decision lived in the meeting notes. The AI read the spec, found a confident-looking date, and stopped. You nearly send it to a stakeholder before checking.
The worst failure is when the AI attributes a decision from one project to another. You ask for the status of a feature. The AI tells you it’s been pushed to next quarter — cites the reason, names the blocker, gives you the revised timeline. Everything you’d need to update a stakeholder. You go to verify before sending. That decision was about a different project. Both appeared in the same week’s meeting notes, both were behind schedule, discussed in the same breath. The AI pulled the delay from one and applied it to the other. Your feature wasn’t delayed. But the answer had enough specificity that you almost didn’t check.
That’s the one that costs you. Not the obvious mistakes. The ones that look right and survive a quick skim.
Frontmatter as a Map
The default behavior is to treat each file as a standalone document. Read it, extract an answer, move on. But when I open a feature spec, I instinctively check: what’s the parent project? What meetings discussed this? Who pushed back? The answers aren’t in the spec — they’re in the notes it links to, and the notes that link to it. Some of those connections are explicit (the spec links to its parent project). Others are implicit (meeting notes that mention the spec, but the spec doesn’t mention them).
The YAML properties you already have are the fix. They’re navigation instructions — you just haven’t told the AI to use them that way.
A typical feature note in my workspace looks like this:
---
type: Feature
parent: Meridian
context: Client Work
status: In Development
---Every property is a traversal instruction. parent: alone tells Claude where this feature sits in a hierarchy — and that hierarchy leads to project context, collaborator notes, and meeting history. None of this helps if the AI treats it as decoration.
I added four lines to my Claude Code rules:
When a file is mentioned, opened, or relevant:
Read it first — never respond about a document without reading it
Follow frontmatter links — traverse
parent:,context:to understand hierarchyCheck related folders — Documents/ contains specs, analysis, drafts
Use what’s documented — if the answer exists in the workspace, find it
That’s the entire traversal ruleset. Four instructions. The week after I added them, I asked Claude the kind of question that had been burning me: the status of a feature with a stale spec. Instead of reporting the old date, it read the feature note, followed parent: to the project, found a meeting note from three days earlier documenting the schedule change, and gave me the updated timeline with the reason it slipped. Same workspace, same files, same question. Different behavior because the AI knew to follow the link instead of stopping at the first file.
(Previous post covered the enforcement and memory layers that sit underneath this. Traversal rules tell the AI how to navigate. Those other layers make sure it actually does.)
The pattern works with any system where files have structured metadata — Obsidian, Cursor, VS Code, anything with YAML headers and folder structure.
The Backward Problem
Following links forward is one hop. Feature spec links to parent project — go read it. Most people stop here, and it already makes a noticeable difference.
The harder problem runs the other direction. “What’s the current status of the Meridian project?” The answer isn’t in the project note. Project notes are slow-moving artifacts — a milestone table that’s accurate maybe twice a month, a status field that reflects last quarter’s reality. The current status lives in the meeting notes, weekly summaries, and message threads that reference the project. For one initiative I manage, that’s 30+ files. None of them are linked from the project note.
Forward traversal follows explicit connections. Backward traversal requires the AI to search for every file that references a given note and synthesize the result. It’s the difference between reading a Wikipedia article and finding every article that cites it.
Without traversal rules, most AI setups can’t even attempt this. The AI reads the project note, finds a stale status field, and reports it as current. The instruction that changed this for me was simple: “When asked about the current state of a project, search for all files that reference it and synthesize recent activity.” One line. The AI finds last Tuesday’s meeting where the timeline shifted, Thursday’s thread where the engineering lead flagged a blocker, and this morning’s daily note where you logged a workaround. Three files the project note knows nothing about — but they’re the ones with the answer.
File access is a filing cabinet. Traversal behavior is how you actually think through your files when someone asks you a question. You pull the thread. You check what referenced what. You reconstruct the current state from fragments.
Your files already encode how you think. The AI just needs to be told to follow them.