refine: restructure the bundle to get the most from OKF

When to use it

• When the content is right but the shape may not be: directories grown fat by one additive pass after another, hubs homed by history rather than meaning, a tag layer that never became the second index it could be.
• "Restructure this", "rebalance the bundle", "is the structure right", "get more out of OKF" all route here.
• It is the third authoring boundary, and the one most often confused with the other two. curate keeps the structure sound as it stands; maintain keeps the content true; refine changes where knowledge lives, never what it says.

What the agent does

The frame that governs every move: the directory tree is a lossy projection of the link graph. A tree gives each concept one parent, so it can encode only the single dominant decomposition; every genuinely many-to-many relationship rides links and tags, never a new directory. And cohesion outranks balance, always: a move has semantic cost, so evenness is a tiebreaker and a fatness alarm, never the goal.

1. Orient. okf dirs for the shape and, through its subtree count, where the weight sits; log.md for how the bundle grew; okf stats for the totals. Additive growth optimizes each pass locally and never the whole, and that is the drift this verb corrects.
2. Measure, because the CLI is the evidence. Baseline validate, lint --stale-after, and loose first, since refine assumes a sound bundle and hard errors are curate's job. Then two structural reads: okf tags --by dir, whose count/total makes a tag's locality legible (a tag wholly inside one directory names a domain, one spread across directories names a concern), and okf graph --hubs, which ranks concepts by inbound links and groups those links by source directory, the origin test for every hub.
3. Diagnose, because you are the judgment. The measurements are evidence, never verdicts. A concern never becomes a container: a directory built around a spread tag prunes nothing, so the cross-cut stays a tag. A directory must prune: knowing "it is in there" should eliminate a large, nameable slice. The hub origin test decides moves: an inbound majority from a hub's own directory means leave it, a dominant foreign directory names the better home, and a foreign majority with no dominant source is a shared primitive. A fat directory (roughly 20 to 25 concepts and up) is an alarm, not a rule: it wants heading sections inside its own index.md first, and directory nesting pays only at hundreds of concepts.
4. Propose, never auto-apply. Refine hands back a report plus a frozen execution prompt; the moves happen when you run them, not before. It prefers the free levers (index sections, tags, links, the connective sentence a link lives in) over file moves, and it never rewrites a body, because summarizing or correcting content is maintain's job reached by switching verbs.

Try it

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

Is docs/ structured well? Look at where the weight sits and whether any hubs are homed in the wrong place, and propose what to move.

Pitfalls

• Refine proposes; it does not apply. You get a report and a frozen execution prompt, and the moves land only when you run them. That is deliberate: a structural move has cost, and the call stays yours.
• Cohesion over balance. A fat directory is an alarm, not a mandate to split. Reach for heading sections in its index.md before sub-directories, and nest directories only at hundreds of concepts, where the index headings already form separable groups.
• A concern stays a tag. A cross-cut like "everything async" prunes nothing, so it never earns a directory, however many concepts carry it. The tag layer is the second index; that is where cross-cuts belong.
• Refine is structural; correcting a body is maintain. Refine moves, sections, retags, and relinks. The moment a concept no longer matches reality, that is a maintain job, reached by switching verbs rather than stretching this one.
• Refine assumes a sound bundle. Run validate and lint first; clearing hard errors is curate's job, not this one.