if in the payment path. git blame pins it on a “fix edge
case” commit from three years ago, written by someone who left two years ago. Is it load-bearing?
Nobody knows. So nobody touches it, and the workaround quietly hardens into architecture.
Your codebase remembers what it does. It forgot why. The decision, the approach you tried
first that didn’t work, the constraint the ugly bit is quietly paying for: none of it got written
down above the code. It lived in a Slack thread, or a design doc nobody reopens, and then it walked
out the door with the person who knew.
whyfile gets it back. It reads the reasoning you already wrote down — your docs, your commit
messages, your # why: comments — and turns it into something you can ask questions of. It’s also
honest about the difference between what it found and what it’s guessing.
Your AI pair-programmer forgot why too, and it won’t admit it
This got sharper the day you started coding with an assistant. A bigger context window doesn’t fix it, and neither does a smarter memory feature, because context and “memory” aren’t a ledger. They’re a scratchpad. They reset between sessions, they drift as they fill, and when pressed they confabulate. Ask an agent why the code is the way it is, hand it nothing to read, and it will give you a confident, plausible, invented answer. That’s the expensive part. With no durable record of the decisions behind the code, every session risks re-arguing something you settled last week, or disappearing down a day-long rabbit hole that one recorded constraint would have closed in a sentence. It burns tokens. It burns time. It burns people out. whyfile is the ledger that was missing: an append-only, queryable record of why, where every entry is grounded to the exact code or sentence it came from. Your agent reads it instead of guessing (one MCP call away), writes new decisions back as it makes them (capture), and runs into the gate if it tries to
quietly break a constraint you set on purpose. It can’t invent an entry, because every entry cites
its source. And where the record is thin, it tells you, instead of papering over the gap.
New to “intent-driven development”? Start here
Don’t let the phrase put you off. It’s plainer than it sounds, and it is not a methodology you have to adopt. Here’s the whole idea. Your code already spells out what it does in a form tools can read; that’s what compilers, linters, and type-checkers work on. The why never got the same treatment. It stays as prose, scattered around, and it rots. Intent-driven development just means letting the why be first-class too: written down once, queryable, and — when you want it — able to fail a pull request that quietly undoes a decision you made on purpose. You can start at zero effort and add discipline only where it earns its keep. Day one needs no new docs (more on that next). Stop at “I can finally ask my repo why,” or take it all the way to “this merge is blocked because it breaks a recorded constraint.” Your call, one step at a time.The best-kept-secret part: you already have the ingredients
This is the bit people don’t expect. whyfile doesn’t make you change how you work before it does anything useful. It starts from what’s already sitting in your repo:- The
# why:comments andWhy:/Decision:trailers you’ve already written turn into trusted intent nodes. No LLM, no cost, queryable straight away. Nearly every repo has a few of these lying around, so you get a real, honest layer on the first run. → Attested intent - Your design docs get read by a short LLM pass that pulls the decisions and constraints out of the prose, each one pinned to the sentence it came from.
authored (a human wrote it) or reconstructed (a model inferred it). A guess never gets to
pose as a decision you made. And when whyfile doesn’t know, it says so. Here, silence is a finding,
not something to paper over.
Fastest possible win — 30 seconds, no new docs
Add one
# why: comment above a function, run whyfile, and query it back as trusted intent. It was
already in your code; whyfile just made it answerable.The mental model
whyfile sits on top of a graphify knowledge graph of your code and adds an intent layer:- The base graph is graphify’s AST view of your source: the what.
- The intent layer is what whyfile adds. It pulls
decision,mechanism,constraint, andtradeoffunits from your prose, comments, and commits, anchors each one to the code it governs, and tags each with how far to trust it. That’s the why.
Quickstart
Step 2 is the one people miss. whyfile post-processes a graphify graph, so
graphify-out/graph.json has to exist before the whyfile run; skip it and you get exit 2.
Driving this from a coding agent? See Driving whyfile from an agent.