← knowledge.oriz.in

Keep knowledge fresh — read first, write current truth, delete obsoletes

rule rulesknowledgeokfself-updatefamilycurrent-truth

Keep knowledge fresh

The rule

The OKF knowledge bundle at knowledge/ is the family's persistent memory. Every chat session, every agent, every subagent reads from it before acting, writes to it whenever a decision lands, and prunes it whenever a prior decision is obsolete.

Knowledge files read as CURRENT TRUTH SNAPSHOTS, not as journey logs. A reader landing on any file sees what IS today, not how we got here. Git commit history is the durable record of "how."

Four obligations on every session:

1. Read first

Before suggesting any architectural or naming change, read:

If knowledge already locks the answer, DO NOT ask the user — surface the locked answer and proceed.

2. Write every chat decision

When the user makes a decision in chat (MCQ answer, free-text choice, override), the decision lands in knowledge SAME TURN:

Per rules/agent/self-update-rule.md. The chat is ephemeral; knowledge is durable.

3. Delete obsoletes same-day

When a decision is superseded, delete the old file outright. The git commit history preserves what was there. Banner-superseded stubs are forbidden — they pollute knowledge with stale references.

When a single section inside a file is obsoleted, rewrite the section in place to state the new truth. Delete the prior version in the same commit.

Per rules/interaction/user-prefers-deletion-over-archive.md.

4. Current truth only — no historical logs

Every concept file reads as a snapshot of what IS today.

Forbidden in knowledge prose:

Permitted:

When you change a decision, rewrite the section in place. When you supersede a file entirely, delete it. Apply both to new content and retroactively when touching any existing file.

How to apply per session

START
+-- Read knowledge/index.md
+-- Read knowledge/log.md (last 10 entries)
+-- For each user request:
¦   +-- Identify which knowledge area applies
¦   +-- Read the relevant decision/rule files
¦   +-- If answer is locked ? use it
¦   +-- If not ? ask user MCQ, then write decision to knowledge
¦   +-- If reversal ? delete obsolete + write new
+-- At session end (or every 10 turns):
¦   +-- Sweep for orphaned references to deleted files
¦   +-- Commit + push knowledge changes
END

Required reading on first turn of every session

Every agent's first action in a session is:

  1. Read C:/D/oriz/knowledge/index.md
  2. Read C:/D/oriz/knowledge/decisions/index.md
  3. Read C:/D/oriz/knowledge/rules/index.md
  4. Read C:/D/oriz/knowledge/log.md (most recent 20 entries)

Without these reads, the agent cannot know what's already decided. Acting without reading first violates this rule.

When NOT to apply

Everything else triggers the read-write-prune cycle.

What goes WHERE

Type Goes in Example
Locked architectural / stack / naming choice decisions/<topic>/<slug>.md branding/naming-policy-v5.md
Non-negotiable family-wide constraint rules/<slug>.md rules/no-card-on-file.md
Service pick with alternatives + swap cost services/<category>/<service>.md services/business/auth/firebase-spark.md
Step-by-step actionable sequence runbooks/<slug>.md runbooks/workflow/scaffold-a-new-site.md
Family-specific term definition glossary/<letter>/<term>.md glossary/o-r/oriz-kit.md
Per-app scoped concept inside the app submodule at <app-path>/knowledge/<slug>.md see
Time-stamped history log.md (append-only)

Cross-refs