When to use this workflow
Use the context principles to distinguish current product knowledge from the history that produced it. A useful context system lets a teammate find the approved decision, its rationale, and the sources behind it. A folder containing every transcript without status or ownership does not provide that distinction.
A worked example
For an invitation feature, keep the customer discussion as a source, the alternatives as an exploration, and the approved scope as a decision. Link the feature brief to the current decision and the relevant components. If bulk invitations were deferred, make that explicit so a future agent does not implement an earlier suggestion as current scope.
Decisions and common mistakes
Test the structure by asking a fresh session to identify the user, approved behavior, constraints, and open questions with source references. If it cites an outdated exploration, repair the routing or status labels before generating more work. Retrieval errors can produce convincing but incorrect designs.
What to hand off
Assign owners for active decisions and update current context when work ships. Preserve history with clear superseded notices rather than silently erasing the reason for a change. The full principles document below is a starting point to adapt to the team’s actual responsibilities.
Put the resource to work
1. Start with one concrete task
Bring: Current product decisions, repository structure, and the people responsible for maintaining context.
First task: Adapt the principles into a small project context document with owners and links to source decisions.
Choose one component, screen, or team workflow to improve. Gather the existing decisions and write down the question you want this resource to help answer.
2. Open the source material
Download Context Principles Markdown ↗
Add the file to your project’s context folder, then adapt it to the actual repository and team responsibilities. The full text is included below.
3. Apply it with your project context
Follow the material in sequence and replace examples with your own product context. Record decisions as you go so another teammate can understand why the result changed.
4. Review the result
Check that another teammate can find current decisions and distinguish them from outdated notes.
Compare the output with the task’s acceptance criteria. Check factual claims, unsupported assumptions, and any changes to the interface. For code or design changes, review real states and behavior before treating the result as finished.
5. Keep what works
Save approved outputs with their source and ownership. Note which instructions helped, where the result needed correction, and what must be checked next time. Use the workflow below to connect this task to its next step.
Follow the related step-by-step field guide ↗
Completion checklist
- The inputs and intended result are explicit.
- Required files and tools are available in the chosen host.
- The result has been reviewed against the actual task.
- Limitations and follow-up checks are recorded.
The Context Principles document
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:
context/CONTEXT_PRINCIPLES.mdcontext/RULES.mdcontext/COMMUNICATION_GUIDELINES.mdcontext/00_START_HERE.mdcontext/NOW.md- Relevant canonical files for the current task
- Historical records only if additional evidence is required
.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 contextcontext/product/ for product-level contextcontext/product/features/ for feature-owned contextcontext/decisions/ for durable decisionscontext/NOW.md for the short current working snapshotcontext/GLOSSARY.md for shared language
Historical records are evidence of what happened.
They belong in:
context/meetings/ for meeting notescontext/explorations/ for research, brainstorming, critiques, and AI-assisted thinkingcontext/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:
- Capture raw material quickly.
- Extract durable conclusions.
- Promote those conclusions into canonical memory.
- Link back to supporting history when useful.
- 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.
