The deep dive · chapter 4 · 7 steps

Notes about your code, kept once

How AIDLC records what it learns about your codebase so the next session asks a question instead of re-reading the same files.

1. 1. The problem — paying twice for the same understanding

   Ask an assistant to change your alert engine and watch what it does first. It opens the alert engine. Then the price feed, because the engine imports it. Then two tests, to work out the intended behaviour. Then it makes a small change.

   Tomorrow, same question, same reading. You paid for that understanding twice, and you'll pay for it again on Thursday. On a codebase of any size, the reading is most of the cost and the change is a rounding error.

   The obvious fix is to write down what was learned. The reason nobody does it is that prose documentation about code goes stale and then actively misleads. So the notes have to be small, structured, attributed to a source file, and cheap enough to update as a matter of habit.

2. 2. Write one, connect it, ask for it back

   Writing something down once

   aidlc — zsh

   $ aidlc knowledge add \
       --id module-alert-engine \
       --type module \
       --name "Alert engine" \
       --description "Evaluates thresholds in src/alerts/." \
       --source src/alerts/engine.ts
   
   Merged module 'module-alert-engine'

   .aidlc/knowledge/entities/module-alert-engine.yaml

   id: module-alert-engine
   type: module
   name: Alert engine
   description: Evaluates thresholds
     in src/alerts/.
   source: src/alerts/engine.ts

   ← backstep 1 of 3next →

   Three commands, and they're the whole surface: record something, record a connection, ask a question.

   Each note carries what it is (module, service, decision, convention, a few more), a description in plain words, and where in the codebase it came from. The source path matters more than it looks: a note that names its origin can be checked, and a note that can't be checked eventually becomes a lie.

3. 3. What's worth writing down

   Not everything. A note that restates what the code obviously says is noise, and noise is what makes people stop reading notes.

   Worth recording:

   • The non-obvious dependency. "Touching the price feed breaks the alert engine's cache assumptions."
   • The decision and its reason. "We poll rather than subscribe because the upstream feed drops connections silently." Six months later nobody remembers the reason, and somebody 'improves' it.
   • The convention. "Every handler validates before hashing." Conventions are invisible to anyone reading one file.
   • The debt, and why it's still there. "This retry loop is wrong under partition; it hasn't mattered because we run single-region."

   Not worth recording: anything you'd get from reading one function. That's what reading a function is for.

4. 4. Your turn

   your turn · Ask instead of re-reading

   You are starting a session on the alert engine. Someone already recorded what it does, last week. Which command finds that out, without reading the code again?

   $ the command that asks
   
   entities:
     - id: module-alert-engine
       type: module
       name: Alert engine
       description: Evaluates thresholds in src/alerts/.
   totalCount: 1

   Which line goes in the blank?

   • aidlc knowledge query "alert engine"
   • aidlc knowledge add --id module-alert-engine
   • aidlc discover

   This exercise needs JavaScript. The transcript above is complete apart from the blank.

5. 5. How it gets read automatically

   You mostly won't run query by hand. At the start of a step, the relevant notes get pulled in for you:

   aidlc knowledge context --scope phase --phase ideation
   

   That returns the notes relevant to the step about to begin, within a token budget. The aidlc-ideation skill runs it before exploring any code, and the instruction is explicit about the order: the notes come first, and you only go read the codebase for what they don't cover.

   There's a check attached, too. Leaving the ideation step requires the notes to contain at least three modules, two dependency connections, and one convention. That threshold is low on purpose — it isn't trying to make the notes complete. It's making sure that a piece of work which explored your codebase leaves something behind, rather than throwing the understanding away when the session ends.

6. 6. The failure mode to watch for

   Notes that nobody trusts are worse than no notes, because they cost a query and then have to be verified anyway.

   Two habits keep them honest. Each note records a confidence and a last-verified date, so a stale one is visible as stale rather than as fact. And when a note turns out to be wrong, correcting it is the same command that created it — add with the same id merges over the top. Fixing a wrong note takes about fifteen seconds, which is the only reason anyone does it.

7. 7. What you can do now

   You can ask what your project already knows about a module before reading it, and you can leave a note behind when you learn something that took effort to work out. On a codebase you'll return to, that's the difference between paying for understanding once and paying every session.

   Next: what all of this costs, and the number that's usually a third too low.