type: runbook
status: active
timestamp: 2026-06-20
tags: [runbook, okf, knowledge, self-update, workflow]

Add a new decision to the knowledge bundle

Capture decisions as knowledge before session ends

Add a new decision to the knowledge bundle

Every architectural, naming, or stack decision the user makes in chat must land as a concept file in knowledge/ in the same conversation. This is the self-update rule made operational.

Steps

Pick the directory. Decide which knowledge/<area>/ the concept belongs in. Most live in decisions/, but cross-cutting constraints go in rules/, services in services/, terms in glossary/, and so on. See the directory layout in ../_okf.md.
Pick a kebab-case slug. Match the family pattern: <short-noun-phrase>.md. Examples: oriz-kit-package-name.md, jsonl-as-canonical-store.md, razorpay-as-primary-billing.md. The path becomes the stable identity.

Write the file with full frontmatter. Use this template:

---
type: decision   # or rule, service, glossary, etc.
title: "<human-readable title>"
description: "<one-line summary used by agents during retrieval>"
tags: [<topic>, <topic>]
timestamp: <today, ISO-8601>
format_version: okf-v0.1
status: active
related:
  - <slug>
  - <slug>
---

# <human-readable title>

## Context
<what prompted the decision — what was being weighed>

## Decision
<the locked choice, in one or two sentences>

## Why
<the reasoning, in 30-80 lines of body>

## See also
- <!-- TODO: broken link, was [<related>](../../<area>/<related>.md) -->

Append to knowledge/log.md. One line, dated, pointing at the new file:
```
- 2026-06-20 — `decisions/<slug>.md` — <one-line summary>
```
Update the relevant index.md. If the new file should be listed in <area>/index.md, add it there in the appropriate section so future agents find it via the index.

Commit on main. Conventional commit:

git add knowledge/
git commit -m "docs(knowledge): <one-line summary>"

Don’t push without say-so per

When the new decision supersedes an older one

Don’t delete the old file. Set status: superseded and superseded_by: <new slug> on the old one, and supersedes: <old slug> on the new one. The bundle is a living wiki — outdated concepts are preserved as history.