# How it compounds

Source: https://flow-next.dev/understand/how-it-compounds/

How review corrections, decisions, and project vocabulary become repository knowledge that the next task, teammate, or coding agent can read.

Flow-Next gets better as you use it. Memory, glossary, decision records, strategy, and the feature map compound as side-effects of the workflow you already run. **There is no manual “compound” / “refresh” / “reindex” ceremony, by design**: improvement that depends on remembering an extra command doesn’t happen.

## The next task starts with what this one learned

A review finds an integration mistake and the fix reaches SHIP. The workflow records the cause, correction, and prevention in project memory. When a later task touches that module, the agent can read the relevant lesson before implementing the next change.

The same continuity applies when you change sessions or coding agents. The next agent reads the spec, current task state, decisions, and relevant lessons from the repository. A team member can inspect those files too.

## The compounding loops

Every self-improving surface has the same lifecycle - seeded once, grown by the skills where new knowledge actually surfaces, read back where it pays, and pruned by the audit sweep:

| Surface                                                    | Seeded by                                                                                                                                 | Grows through                                                                                                                                                                              | Read by                                                                                                                                                          | Pruned by                                                                                                                                                  |
| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Memory** (`.flow/memory/`)                               | Project setup (on by default)                                                                                                             | Worker auto-capture on NEEDS\_WORK → SHIP; `flow --auto` writes the same entries unattended                                                                                                | One `memory search` during planning and at each task’s re-anchor; `why-scout` on a rationale question (bug track)                                                | [`/flow-next:audit`](https://flow-next.dev/skills/audit/) - Keep / Update / Consolidate / Replace / Delete / Harden per entry                              |
| **Glossary** (`GLOSSARY.md`)                               | [`/flow-next:prime`](https://flow-next.dev/skills/prime/) - repo scan, read-back gated                                                    | [`/flow-next:refine`](https://flow-next.dev/skills/refine/) + [`/flow-next:capture`](https://flow-next.dev/skills/capture/) term adds                                                      | Plan scouts, worker re-anchor, review prompts (task-relevant terms only)                                                                                         | [`/flow-next:audit`](https://flow-next.dev/skills/audit/) - staleness + alias creep                                                                        |
| **Decision records** (`.flow/memory/knowledge/decisions/`) | - (accrete from work)                                                                                                                     | [`/flow-next:capture`](https://flow-next.dev/skills/capture/) strategy-override prompts; refine + review cycles                                                                            | The memory search during planning; `why-scout` on a rationale question                                                                                           | [`/flow-next:audit`](https://flow-next.dev/skills/audit/) - supersede-not-delete                                                                           |
| **Strategy** (`STRATEGY.md`)                               | [`/flow-next:strategy`](https://flow-next.dev/skills/strategy/)                                                                           | Drift surfaced read-only by plan / capture / sync - updates stay human-confirmed                                                                                                           | [`/flow-next:prospect`](https://flow-next.dev/skills/prospect/), [plan](https://flow-next.dev/skills/plan/) (`## Strategy Alignment`), refine, capture           | [`/flow-next:strategy`](https://flow-next.dev/skills/strategy/) (the only writer)                                                                          |
| **Feature map** (`.flow/features/`)                        | [`/flow-next:features`](https://flow-next.dev/skills/features/) - seeds when the directory is absent; setup and prime always recommend it | [`/flow-next:work`](https://flow-next.dev/skills/work/) updates the routes its own change altered; readers file drift notes; the maintain pass on the same command re-proves every feature | [`/flow-next:qa`](https://flow-next.dev/skills/qa/), [Drive](https://flow-next.dev/skills/flow-next-drive/), and bug intake - navigation, preconditions, gotchas | [`/flow-next:features`](https://flow-next.dev/skills/features/) maintain when due - `clean` / `changed` / `blocked`, retiring the drift notes it re-proved |

## Memory

A categorized store, on by default (bug and knowledge tracks) that survives context compaction. The write moment is the review loop: when an implementation review goes NEEDS\_WORK → SHIP, work captures the problem, root cause, fix, and prevention as a structured bug-track entry - under [`flow --auto`](https://flow-next.dev/autonomy/pilot/) this happens with nobody watching. Overlap detection merges duplicates at write time, so capture carries no dedup burden.

Reads happen where they pay: [planning](https://flow-next.dev/skills/plan/) and each task’s re-anchor run one `memory search` and pick the entries that apply before touching code. With a [Jev](https://flow-next.dev/guides/jev-judge/) key the hits are reordered, never dropped. [`/flow-next:audit`](https://flow-next.dev/skills/audit/) is the garbage collector - it walks entries against the current codebase and keeps, updates, consolidates, replaces, or deletes each one. It is also the graduation path: a lesson that keeps recurring and is mechanizable can be hardened into an enforced gate, so it stops being context the agent re-reads and starts being a check that fires on its own. A recurring lesson no gate can check gets the other repair: the audit fixes the entry’s title, tags, module, and filing so the search that should have surfaced it does. Migrating an older flat-file store: [`/flow-next:memory-migrate`](https://flow-next.dev/skills/memory-migrate/).

## Glossary

Wrong-meaning-of-a-normal-word errors get built into plans and code - an agent that quietly conflates two project terms produces a correct-looking implementation of the wrong concept. The glossary loop closes that:

* **Seed** - [`/flow-next:prime`](https://flow-next.dev/skills/prime/) bootstraps `GLOSSARY.md` from the repo’s load-bearing nouns, with file-reference evidence and a read-back before anything is written. On an already-populated glossary it reports coverage and never rewrites.
* **Add** - [`/flow-next:refine`](https://flow-next.dev/skills/refine/) and [`/flow-next:capture`](https://flow-next.dev/skills/capture/) offer term adds when genuinely new vocabulary surfaces in conversation, consent-gated at read-back.
* **Read** - plan scouts, the work worker’s re-anchor, and review prompts pull task-relevant terms (budget-capped - never the whole file).
* **Prune** - [`/flow-next:audit`](https://flow-next.dev/skills/audit/) checks every term against the current code as part of its normal sweep.

## Decision records

Load-bearing architectural choices land in `.flow/memory/knowledge/decisions/` at the moment they’re made - for example, [`/flow-next:capture`](https://flow-next.dev/skills/capture/) proposes a decision record when a spec deliberately overrides an active strategy track. Audit treats decisions specially: Replace is supersede-not-delete, so the historical trail of *why* stays intact.

## Strategy

`STRATEGY.md` is read by the skills that need direction - [`/flow-next:prospect`](https://flow-next.dev/skills/prospect/)’s candidate filter, [`/flow-next:plan`](https://flow-next.dev/skills/plan/)’s `## Strategy Alignment` section, refine and capture conflict surfacing - and the same reads keep it honest: drift between the doc and what’s actually being built is flagged read-only, never auto-superseded. The human stays the editor via [`/flow-next:strategy`](https://flow-next.dev/skills/strategy/).

## Feature map

A committed user-POV drive directory (`.flow/features/`, beside `.flow/memory/`) recording how a user reaches each user-facing feature, how an agent drives it, and which traps waste a verification run. It is the layer that stops live verification re-deriving navigation every time: the spec still supplies this run’s acceptance criteria, and live captured evidence remains the only basis for a ship verdict.

* **Seed** - [`/flow-next:features`](https://flow-next.dev/skills/features/) when `.flow/features/` is absent: interview the repo, prove every route with one live drive, write the index plus one four-H2 file per proven feature, each stamped with a `**Last proven:**` date and commit. Nothing undriven lands. Setup and prime recommend this step on every repository.
* **Grow** - [`/flow-next:work`](https://flow-next.dev/skills/work/) updates the map in the same change when that change alters how a user reaches a mapped feature: only the affected files, each new route proven with one live drive. When it cannot prove the route, it files a drift note and leaves the map alone. Besides `/flow-next:features`, work is the only map writer.
* **Read** - [`/flow-next:qa`](https://flow-next.dev/skills/qa/), [Drive](https://flow-next.dev/skills/flow-next-drive/), and bug intake consume it by existence check, with no registration. An absent map leaves them exactly as they are today. A reader that finds a stale route files a `feature-map-drift` note and never edits the map.
* **Prune** - the maintain pass on the same command, run when the map is due: an open drift note, or a feature whose last proof is `features.staleAfterCommits` (default 50) product commits old. It re-proves every feature live, fixes what moved, retires the drift notes whose routes it re-proved, and ends `clean` (no branch, no PR), `changed` (one chore PR of proven corrections), or `blocked` (naming what blocked).

How the three mechanisms fit together, and how to run maintain from a loop: [Keep the feature map current](https://flow-next.dev/guides/keep-feature-map-current/).

Unlike `/flow-next:map`’s local `.clawpatch/` code index, this map is **committed**: its whole value is surviving the session and the machine. Full behavior on the [Features skill page](https://flow-next.dev/skills/features/).

## The no-ceremony principle

Each loop’s write moment is embedded in a step that already happens. Prime runs once per repo. Captures and refine passes happen when specs are born. Reviews happen before merge. Audits run when memory is consulted and found wanting.

The feature map’s full maintain pass is the one step that stays human-invoked, and it is scoped. Everyday upkeep is ambient: work updates the routes its own change moved, and every reader files a drift note when a route no longer matches, during work that already happens. The full pass drives the live app, so it runs when you or a host loop you start invoke it, never from a pipeline stage. You do not have to remember it: `flowctl features status` reports the map due from open drift notes and last-proven age, and flow’s no-argument reading recommends the pass at that moment.

Contrast with workflows that require a manual “compound” or “refresh” pass: those degrade silently the day the operator forgets. Flow-Next’s surfaces degrade toward *pruning* - audit and the feature-map maintain pass remove what’s stale - rather than toward *staleness*, where nothing has been added since the last ceremony.