DOCS · CORE CONCEPTS
The learning loop
Why the loop closes on merge, what an as-built spec is, and how the twentieth spec ends up better grounded than the first.
Most AI tooling is flat: session twenty is exactly as informed as session one. specd is shaped the other way — every delivered spec becomes retrievable context for the next one.
What happens on merge
Merging is the only event that matters. Closing a pull request without merging changes nothing, on purpose.
| What was merged | What specd does |
|---|---|
| The setup branch from Ground | Records adoption and indexes knowledge/. |
A spec/<id>-<slug> branch | Marks the spec delivered and re-indexes. |
Anything touching knowledge/ on the default branch | Re-indexes. |
| A pull request that was closed, not merged | Nothing. |
The as-built spec
The last task of every spec is to file its as-built record into knowledge/specs/<id>-<slug>.md. Two properties matter:
- It is written by specd, not by the model
- A verbatim copy of what was approved. If the model omits the task, specd appends the record itself — so the loop cannot quietly stop closing.
- It is a historical record
- Never rewritten. If reality diverged from the approved design, that is appended as a "Deviations" section — because the useful artifact is what was decided and what actually happened, not a tidied version of either.
Why it compounds
The as-built specs are indexed like every other document, so the next draft retrieves them. In practice that changes what the agent has to guess about:
- Spec 1 is drafted against whatever grounding found. Expect several
UNVERIFIEDclaims — the corpus is thin. - Spec 5 retrieves four delivered specs. Patterns you established are now citable, so the agent proposes them instead of inventing alternatives.
- Spec 20 is drafted against nineteen decisions that were actually shipped, plus the ADRs and corrections that accumulated along the way. The
UNVERIFIEDcount is now a signal about genuinely new territory, not about a cold start.
What keeps it honest
- The index refresh is atomic and shrink-guarded — a run that would gut the index is refused, and a run that drops edges from documents it never touched is rolled back.
- Freshness and coupling are recomputed from git, so a document that stopped moving with the code it describes starts saying so.
- Nothing is re-derived by a model at index time, so the corpus cannot drift by being re-summarised.
The mechanics of the refresh are in Architecture; what the index does with the corpus afterwards is in The retrieval engine.