plan-kb git:20260816.bc70711A

Immutable. This exact content is served forever at /api/v1/blob/fee9e534df0c52b8.

---
name: plan-kb
description: Create or evolve a durable Markdown plan inside a hraness/kb vault. Use when a user asks for an implementation plan, proposal, RFC, migration plan, execution audit, phased checklist, or an update to an existing plan's decisions, progress, review findings, verification evidence, or final result.
---

# Write a durable plan

Keep the plan useful before, during, and after execution. It is the coordination
record, not a disposable answer or a duplicate task tracker.

## Find the plan's owner

1. Resolve `<vault>` to the directory containing its authored or managed
   `index.md` front door, then
   set the shell-local `KB_ROOT` to that path (`KB_ROOT=kb` from a typical
   repository root, or `KB_ROOT=.` from inside the vault). Read the vault's
   `AGENTS.md` and the nearest guide under `<vault>/plans/`. Pass that resolved
   root to every command; do not assume the starting directory is the vault.
2. When the plan owns a repository path, resolve the repository root as
   `KB_REPO` and load that path's current memory before a whole-vault search:

```sh
kb context "<repository-path>" --root "$KB_ROOT" --repo "$KB_REPO"
```

Use `--kind file` or `--kind directory` when an absent future path cannot be
classified from the filesystem. Read the inherited guides first, then the
applicable maintained knowledge, active plans, dated research, reports, and
separate historical-plan group.

3. Search existing plans before creating one:

```sh
kb list --root "$KB_ROOT" --where type=plan --sort area --json
kb search "the intended outcome" --root "$KB_ROOT" --json
```

If `kb` is not installed, do not let retrieval tooling block the plan: use
`rg` or the available file search over `<vault>/plans/`, titles, aliases, and relevant
terms. If the directory is not an initialized hraness/kb vault, follow the
repository's existing planning convention instead of initializing one without
being asked. Semantic search writes only a derived local cache; when that cache
location is not writable, use exact search or point `XDG_CACHE_HOME` at a
writable cache directory.

4. Update an existing plan when it already owns the outcome. Create a new file
   only for independently executable work.
5. Use `<vault>/plans/<descriptive-kebab-name>.md` unless the local guide already groups
   plans by area. Do not reorganize older plans merely to impose a new tree.

## Write from evidence

Read [the plan structure reference](references/structure.md), then tailor it to
the work. Preserve these invariants:

- State one concrete outcome and the current status.
- Record what is known, what is assumed, and what remains to discover.
- Separate in-scope work from non-goals.
- Put constraints and decisions before the steps they shape.
- Make dependencies and ordering visible.
- Give each acceptance claim a verification method.
- Include rollback or recovery when a change can leave durable state behind.

Turn a missing implementation detail into an ordered discovery gate when the
outcome and authorization are already clear and the decision can be made from
in-scope evidence. Stop and request direction when the unknown would change the
intended outcome, expand authority or external coordination, or choose between
materially different products.

Use small frontmatter. Start with `type: plan`, a descriptive title and
one-sentence description, a kebab-case `area`, and one of `proposed`,
`accepted`, `in-progress`, `blocked`, `completed`, `superseded`, or `cancelled`.
When the plan owns work in a code repository, add `repository_scopes` with the
few exact canonical repository-relative files or directories it explains. Use
no globs. A future path is valid; update an active plan deliberately when code
moves instead of relying on inferred Git renames. Add aliases or tags only when
they help humans or structured queries.

## Grow the same file during execution

- Change status when reality changes, not in anticipation.
- Check off completed work without deleting the original intent.
- Incorporate decisions, review findings, deviations, and command or test
  evidence where a future reader can understand their consequence.
- When blocked, name the exact missing condition and the safe work already
  completed.
- When a plan becomes `completed`, `superseded`, or `cancelled`, write a
  non-empty `## Result` and `## Durable memory`. State what shipped or why work
  stopped in Result. In Durable memory, link each reusable conclusion to the
  maintained note, guide, documentation, or checked code contract that now owns
  it. When nothing warrants promotion, say so explicitly and give the reason.
  Retain the terminal plan as history.
- Do not create separate progress, review, or completion files for the same
  plan.

## Connect and verify

Add wikilinks or typed relationships only where the prose and evidence explain
a useful connection. Review the changed plan for reusable concepts before
refreshing:

```sh
kb percolate "<plan-note-id>" --root "$KB_ROOT" --limit 25 --json
kb refresh --root "$KB_ROOT"
kb check --root "$KB_ROOT"
```

Run those commands when the plan lives in an initialized hraness/kb vault. In a
repository-native planning directory, use that repository's own validation
instead. Review broken links first, then inspect orphan and mention advisories
in context. Promote only concepts likely to be reused, and ground every typed
relationship in the plan's prose. An independently useful plan may legitimately
remain an orphan in a new or sparse vault. Record that disposition mentally or
in the task handoff; do not manufacture links or relations merely to improve
graph counts.

In an authored-catalog vault, refresh leaves the front door unchanged and `kb
catalog --root "$KB_ROOT"` renders an exhaustive disposable inventory. In a
managed vault, independent edit lanes use `kb check --root "$KB_ROOT"
--no-catalog`; the integrating lane performs the single catalog refresh.