# Audit

Source: https://flow-next.dev/skills/audit/

Review .flow/memory/ against the current codebase - Keep / Update / Consolidate / Replace / Delete / Harden per entry.

`/flow-next:audit` is the agent-native staleness review for the `.flow/memory/` store.

Flow-Next runs fully without this. The memory tree is on by default and nearly free; the audit sweep is the part with a price - a pass over every entry, judged against the current codebase. Run it once entries have had time to go stale, typically after a refactor that invalidates prior art. See [Running Lean](https://flow-next.dev/understand/what-each-layer-costs/).

Memory entries decay. A bug note logged six months ago might reference a renamed file, a deleted function, or a codepath that no longer exists. Without periodic review, `memory-scout` ends up surfacing outdated advice.

The host agent walks `.flow/memory/`, reads each entry, verifies references against the current codebase via Read / Grep / Glob / git, and decides per entry.

## The six outcomes

| Outcome     | When                                                                                                                                                                               |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Keep        | Entry is still accurate and useful.                                                                                                                                                |
| Update      | Core point holds; references or wording need a refresh - or the entry is fine and hard to find, and its retrieval surface gets repaired.                                           |
| Consolidate | Multiple entries cover the same ground; merge them.                                                                                                                                |
| Replace     | Conclusion has changed; write a successor, mark the old one superseded.                                                                                                            |
| Delete      | Code is gone AND the problem domain is gone. Rare.                                                                                                                                 |
| Harden      | The lesson keeps recurring and is mechanizable: graduate it into an enforced gate (lint rule, CI step, or CLAUDE.md/AGENTS.md rule) and demote the entry to a pointer at the gate. |

Delete is reserved for unambiguous cases. When in doubt, the audit prefers Replace or Consolidate so the prior context is preserved.

Harden (added in 3.4.5) is the graduation path: a lesson your agent keeps re-learning should stop riding the context window and become a gate. The audit verifies the gate actually fires before demoting the entry - the file stays on disk with `hardened_into` pointing at the gate, so provenance survives, and `flowctl memory mark-fresh` un-graduates it if the gate is ever removed. Harden never applies unattended: in autofix, pilot, or Ralph runs it only reports candidates, because lint configs, CI workflows, and instruction files are shared repo infrastructure.

Update carries a **retrieval fix** (added in 4.13.0) for the lesson Harden cannot take. When an entry keeps recurring but states a rule no lint or CI step can check, the audit asks whether the entry is hard to find rather than wrong, and repairs its `title`, `tags`, `module`, and `applies_when` - moving a misfiled entry into the category the lesson belongs to, since a category-scoped search never reaches an entry filed somewhere else. The retrieval rationale never rewrites the entry’s body; plain reference drift in the same entry is still repaired on its own evidence, in the same Update. A nameable defect in the retrieval surface is required, so an already-findable entry falls through to the ordinary drift check. The report counts retrieval fixes inside Updated.

## What gets walked

* All categorized entries under `.flow/memory/bug/` and `.flow/memory/knowledge/`.
* `decisions/` entries get a calibrated judging question: does the constraint that motivated this choice still hold?
* `GLOSSARY.md` terms are scanned for code usage; zero-hit terms get a `<!-- stale: ... -->` marker.

Legacy flat files (`pitfalls.md`, `conventions.md`, `decisions.md` at the memory root) are skipped with a pointer to `/flow-next:memory-migrate`.

## Invocation

| Mode                     | Behavior                                                                                                                                                 |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Interactive (default)    | Ask one question at a time on ambiguous classifications. Batch obvious Keeps and Updates. Confirm Consolidate / Replace / Delete / Harden one at a time. |
| Autofix (`mode:autofix`) | No user questions. Apply safe actions directly. Ambiguous cases are marked stale, not deleted. Harden candidates are reported only, never applied.       |

A scope hint after the mode token narrows the audit to a concept, category, module, or path.

## Decision entries supersede

`knowledge/decisions/` entries persist on disk even when superseded. Replace means writing a new entry and marking the old one `decision_status: superseded` with a `superseded_by:` pointer - never `git rm`. Decision history is the audit trail.

## Where it stops

* Not a way to mass-rename code from a glossary finding. The audit reports file:line locations and stops there.
* Not a substitute for thoughtful curation when adding memory. Bad entries are still bad after an audit.

## Worked example

```plaintext
/flow-next:audit src/auth
```

```text
Scope: module src/auth - 6 memory entries matched
  keep    bug/runtime-errors/token-refresh-race          (still reproduces at src/auth/refresh.ts:88)
  keep    knowledge/patterns/session-store-convention     (convention still followed)
  update  knowledge/decisions/cookie-vs-header-auth       (decision text references moved file; path fixed)
  delete  bug/build-errors/legacy-esbuild-flag            (flag removed in the build revamp; entry obsolete)
Applied: 4 kept, 1 updated, 1 deleted.
```

Every verdict names its evidence in the current codebase - an entry is never kept just because it exists.

* Scope the audit (a concept, category, module, or path after the command) - a scoped pass is minutes, a whole-memory pass on an old repo is not.
* Run it after a refactor that moves or renames files: path-anchored entries go stale silently, and stale memory misleads every future scout.
* In unattended runs, `mode:autofix` never guesses on ambiguity - ambiguous entries are marked stale for a human pass instead of deleted.

## Dynamic usage

Recipes that compose with audit in the [cookbook](https://flow-next.dev/guides/cookbook/):

* [Evidence-first](https://flow-next.dev/guides/cookbook/#evidence-first) - memory hygiene keeps the evidence trail trustworthy for the skills that read it.
* [Autonomy dial](https://flow-next.dev/guides/cookbook/#autonomy-dial) - schedule `mode:autofix` audits between loop runs so long-lived repos self-clean.

## Next step

After running, review the report and re-run `memory-scout`-using skills with the updated store:

```bash
/flow-next:plan <spec-id>   # plans now ground on fresh memory
```