> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whyfile.dev/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> whyfile post-processes a graphify code graph. Before running `whyfile`, create the graph with `graphify update .` (writes graphify-out/graph.json) — running whyfile without it exits 2. Check readiness with `whyfile --doctor --json`. The explain / list-intent / why query commands are read-only, LLM-free, and free. For the full agent runbook and JSON/exit-code contract, see the 'Driving whyfile from an agent' page (/guide/agents).

# What is whyfile?

> Every codebase remembers what it does and forgets why. whyfile recovers the why from what you've already written, and won't make it up. Get a real answer on your own repo in two minutes.

You've hit this bug. There's a strange `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.

```bash theme={null}
whyfile why "why do we retry payments only twice"
# → [constraint] Idempotency key expires at 3 attempts. The processor dedupes on a
#   key we mint per-order; a 3rd retry outlives it and can double-charge.
#   Grounded in: docs/adr/0012-payments.md · governs: src/billing/retry.py
```

No wiki, no tribal knowledge. That came straight out of your own repo.

## 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](mcp-server.md) call away), writes new decisions back as it makes them
([`capture`](team-collaboration.md)), and runs into [the gate](gates.md) 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 and `Why:`/`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](attested-intent.md)
* **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.

The part that makes this trustworthy rather than confident-sounding fiction: every unit is tagged
either `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.

<Card title="Fastest possible win — 30 seconds, no new docs" href="/guide/attested-intent" horizontal>
  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.
</Card>

## The mental model

whyfile sits on top of a [graphify](https://github.com/safishamsi/graphify) knowledge graph of your
code and adds an **intent layer**:

1. **The base graph** is graphify's AST view of your source: the *what*.
2. **The intent layer** is what whyfile adds. It pulls `decision`, `mechanism`, `constraint`, and
   `tradeoff` units 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*.

```mermaid theme={null}
flowchart LR
    D["docs/*.md<br/>+ # why: comments<br/>+ commit trailers"] --> A
    G["your code<br/>(graph.json)"] --> B
    A["extract<br/>the why"] --> B["anchor it<br/>to the code"]
    B --> Q["ask it anything:<br/>whyfile why / explain"]
```

## Quickstart

```bash theme={null}
# 1. Install (uses your Claude Pro/Max subscription by default — no API key).
pip install whyfile

# 2. Build the base code graph (no LLM). This creates graphify-out/graph.json.
graphify update .

# 3. Enrich: extract intent from docs/, comments, and commits; anchor it to the graph.
whyfile --graph graphify-out/graph.json --docs docs/ --passes A,B,C

# 4. Ask your repo why — read-only, LLM-free, free of charge.
whyfile why "why does this module exist"
```

<Note>
  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](agents.md).
</Note>

## Start small, grow only if it pays off

Nothing here is all-or-nothing. Each rung stands on its own, so stop wherever the value runs out:

| Effort          | What you do                                    | What you get                                                                      |
| --------------- | ---------------------------------------------- | --------------------------------------------------------------------------------- |
| **Zero**        | Run whyfile on your repo as-is                 | Ask *why* and get grounded answers from your existing docs, comments, and commits |
| **One line**    | Add a `# why:` comment above a gnarly function | A trusted, queryable node, so the reasoning finally lives next to the code        |
| **One command** | `whyfile capture` a decision as you make it    | The *why* recorded while you still remember it, when it's cheapest to capture     |
| **Team**        | Turn on the [gate](gates.md) in CI             | A PR that silently breaks a recorded constraint doesn't merge                     |

## Where to go next

| If you want to…                         | Read                                                                      |
| --------------------------------------- | ------------------------------------------------------------------------- |
| Get a trusted result with zero new docs | [Attested intent](attested-intent.md)                                     |
| Get it installed and pick a backend     | [Installation](installation.md)                                           |
| Understand the extraction passes        | [How it works](how-it-works.md)                                           |
| Point a coding agent at it              | [Driving whyfile from an agent](agents.md)                                |
| Ask the intent layer questions          | [Querying](querying.md)                                                   |
| Know what a run costs                   | [Caching, resume, and cost](caching-and-cost.md)                          |
| Wire it into a team's PR/CI flow        | [Team collaboration](team-collaboration.md)                               |
| Make intent block a merge               | [Gates](gates.md)                                                         |
| See it used on a real codebase          | [Dogfooding case study](../case-studies/dogfooding-pipeline-hardening.md) |