maintain: sync knowledge with reality

When to use it

• The project changed (a rename, a migration, a retired service) and the bundle's content must catch up with reality.
• You learned something durable while consuming the bundle: a fact it lacks, a link it is missing, a concept that no longer matches what shipped.
• Note what maintain is not: a bundle that is structurally messy but factually current wants curate instead.

What the agent does

1. Orient before hunting. okf index maps the whole bundle in one pass (every directory's index body, rollups, and listings), log.md gives the baseline of what changed last, and okf stats shows size and shape. This comes before any grep, because grep cannot find an index entry that is missing: only the map shows what a listing should contain but does not.
2. Find every affected concept. The classic failure is fixing only the obvious one. The agent runs okf search with the changed asset's resource URI, path, and name (it hits frontmatter and bodies and returns ranked concept ids, with grep as the backstop for what search cannot express), and pulls okf graph --json --minimal for the edges, the concepts that link to the ones being touched, without paying for every body. Search and the graph do the finding, so nothing drifts silently.
3. Update. Bodies and timestamps, fixed or added cross-links, new concepts for new assets. Retired assets get a deprecation note rather than silent deletion, so the context that explains them survives.
4. Update every enumeration. A new, renamed, or removed concept changes its directory's index.md listing too, not just the concept file. A dated entry goes into log.md, and the agent re-runs okf index to confirm each listing matches reality.
5. Check. okf validate, then okf lint for the curation drift the change introduced: new orphans, broken citations, dangling index entries. When concepts carry timestamps, --stale-after (for example 90d) goes on the lint, because freshness is off by default.
6. Review loose files. okf loose lists the concepts with no cross-links in or out. This pass is semantic, so the tool only surfaces the set; for each floater the agent judges intent: should it link out (write the sentence that explains the relationship and put the link in it), should something link to it, or is it terminal by design, like a backlog item or a leaf reached only through its index, which is not a defect.
7. Curate the tag vocabulary when the pass touched tags or okf tags shows a long tail of singletons. Reading the grouped views (--by area, --by type), the agent merges twins (two tags riding the exact same concepts), drops group-name echoes (a tag restating an axis the concept already carries), questions each singleton rather than treating a count of 1 as a verdict, and protects the connective tags consumers have already learned.

Before calling the pass done, the agent walks the same closeout gate produce ends with, as the check that none of the steps above was skipped.

Try it

In Claude Code with the okf plugin, run /okf:gem maintain, or ask the skill in plain words:

We renamed the orders table to sales_orders and split checkout out of the storefront service. Update the knowledge bundle to match.

Pitfalls

• Fixing only the obvious concept. The concept named after the changed asset is rarely the only one that mentions it. Let the resource search and the graph find the rest; reading the whole bundle only scales on tiny ones.
• Enumeration drift. Updating the concept but not its directory's index.md leaves a listing that lies. Grep cannot catch this, which is why the playbook re-runs okf index and eyeballs each listing.
• A quiet lint is not a fresh bundle. Staleness reporting is off by default; without --stale-after, lint will not tell you what the change left stale.
• Zero loose files is not the goal. Terminal-by-design leaves are fine, and forcing links onto them adds noise, not knowledge. Loose is a review list, and the judgment is the point.