# Context OS Principles

The Context OS is long-term memory for product work.

It is not a documentation framework, knowledge base, wiki, or status-report archive. Its job is to preserve the durable context needed to make good product decisions over time.

## Purpose

The Context OS should help humans and AI workflows:

- recover project context quickly
- understand why decisions were made
- avoid repeating the same discussions
- distinguish current truth from historical notes
- carry product knowledge across meetings, sessions, and tools

If a file does not help with those jobs, it probably should not exist yet.

## Session Initialization Protocol

At the start of a new AI session, read context in this order:

1. `context/CONTEXT_PRINCIPLES.md`
2. `context/RULES.md`
3. `context/COMMUNICATION_GUIDELINES.md`
4. `context/00_START_HERE.md`
5. `context/NOW.md`
6. Relevant canonical files for the current task
7. Historical records only if additional evidence is required
8. `.context/working-context.md` as temporary task context

Communication guidelines are part of the project context and should be applied automatically whenever client-facing communication is requested.

Do not rely on historical records when they contradict canonical memory. If canonical files are ambiguous, ask instead of assuming.

## Canonical Memory vs Historical Records

Canonical memory is the current source of truth.

It belongs in:

- `context/project/` for stable project-level context
- `context/product/` for product-level context
- `context/product/features/` for feature-owned context
- `context/decisions/` for durable decisions
- `context/NOW.md` for the short current working snapshot
- `context/GLOSSARY.md` for shared language

Historical records are evidence of what happened.

They belong in:

- `context/meetings/` for meeting notes
- `context/explorations/` for research, brainstorming, critiques, and AI-assisted thinking
- `context/inbox/` for raw capture that has not been processed yet

Historical records may explain how context changed. They should not become the place people must read to know the current truth.

## Information Flow

Information should move through the system in stages:

1. Capture raw material quickly.
2. Extract durable conclusions.
3. Promote those conclusions into canonical memory.
4. Link back to supporting history when useful.
5. Update `context/NOW.md` if the current working state changed.

Do not skip promotion. A meeting note or exploration is not finished just because it was written down.

## Meetings, Explorations, Decisions, and Product Context

Meetings are immutable historical records.

Do not rewrite old meeting notes to match the current state. If a meeting produces a durable outcome, create or update the relevant canonical file.

Explorations are working history.

They can be messy, speculative, contradictory, and useful. Their job is to preserve reasoning, alternatives, and discarded paths. When an exploration produces a conclusion, promote the conclusion elsewhere.

Decisions are durable commitments.

A meaningful decision should live in `context/decisions/`, even if it originated in a meeting, exploration, chat, pull request, or AI session. The decision record should name the owner, status, context, decision, consequences, and supporting links.

Product documentation is current product memory.

Product and feature files should describe what is currently believed, intended, required, or unresolved. They should link to decisions and historical records only when the history matters.

## When to Create a New Document

Create a new document only when one of these is true:

- the topic has a clear owner or lifecycle
- the existing file is becoming hard to scan
- the information will be updated independently
- the distinction prevents duplicated truth
- a durable decision needs its own record
- a feature needs its own home

Otherwise, update an existing file.

Default to fewer files. More structure can be added later when the project earns it.

## Temporary Working Context

The `.context/` directory is non-canonical.

Use it for:

- generated context packs
- AI skill inputs
- summaries assembled for a specific task
- temporary analysis
- local workflow scratch files

Rules for `.context/`:

- it may be regenerated at any time
- it must link back to canonical files when possible
- it must not contain the only copy of durable knowledge
- AI workflows may consume it, but should verify against `context/`
- generated files should be ignored by Git unless intentionally kept as a template

`context/` is memory. `.context/` is working material.

## What Should Never Happen

Never treat meeting notes as current truth.

Never bury decisions inside transcripts, chats, explorations, or implementation notes.

Never create a new file because a template exists.

Never duplicate durable facts across multiple canonical files.

Never let `.context/` become the source of truth.

Never rewrite uncertainty as certainty.

Never make the system depend on a specific AI model, editor, vendor, or automation script.

Never optimize for completeness at the cost of daily maintainability.

## Maintenance Biases

Small and current beats large and stale.

Links beat copied paragraphs.

Promotion beats summarization.

Clear ownership beats broad categorization.

Open questions beat hidden assumptions.

Manual maintainability beats clever automation.

## Assumptions to Challenge

Do not assume every product area needs a document. Empty structure creates maintenance debt.

Do not assume every meeting needs a polished summary. Some meetings only need raw notes plus one promoted decision.

Do not assume AI-generated summaries are reliable memory. They are inputs for review, not canonical truth.

Do not assume one source of truth means no summaries. Short orientation summaries are useful when they point back to canonical files.

Do not assume the system should grow automatically. Growth should follow repeated use, not imagined future needs.