MonoMind project-context

Docs · The records

Three files, each answering one question.

The moment after install is where adoption is usually lost: you have three Markdown files and no feel for them. This page is a tour of what goes in each, what stays out, and how each one changes over time — with real entries, not a schema.

  • NOW.md
  • DECISIONS.md
  • LEARNINGS.md
01 what a stock install lands

Thirteen files, three of which you will ever edit

A core install adds one readable directory, the protocol that maintains it, and the wiring that delivers the protocol into a session. The three records at the top are the whole point; everything below them exists so agents keep the records honest.

your-project/ 13 files 
your-project/
├── AGENTS.md                        ← managed block added, or refreshed in an existing file
├── project-context/
│   ├── NOW.md
│   ├── DECISIONS.md
│   ├── LEARNINGS.md
│   ├── SKILL.md                     ← the operating protocol, readable in place
│   ├── README.md
│   └── .project-context.json
├── .agents/skills/project-context/
│   ├── SKILL.md                     ← same protocol text; the two can never disagree
│   ├── agents/openai.yaml
│   └── scripts/
│       ├── context_triggers.py
│       ├── context_index.py
│       └── context_doctor.py
└── .claude/skills/project-context/
    └── SKILL.md                     ← pointer so Claude Code discovers the skill

core profile · zero runtime dependencies · stdlib Python 3.10+

The full profile adds decisions/, designs/, incidents/, and tasks/ subfolders with templates, for projects that need the complete evidence structure. The three records stay the same either way.

02 NOW.md

What is true now, what is active, and what happens next?

The first thing the next person or agent reads. It holds exactly the state a stranger would need to act — nothing that git history already knows.

project-context/NOW.md real example

Current Project State

Last reviewed: 2026-08-26

Snapshot

Area Current state Evidence
Evidence scope The report uses public studies published through 2025-12-31. D-001

Active work

Initiative Status Next action
Findings synthesis in-progress Resolve three claims that lack page-level citations. L-001

Blockers

None.

from the shipped example — a research report, not code

not a changelog

Git already records what changed and when. NOW.md records what a next contributor would act on: what is in flight, what is blocked, and the next concrete step. If a line only describes the past, it belongs in a commit message.

How it changes over time

It is replaced, not appended to. When work lands, stale state is removed once its durable result is linked, and Last reviewed is set to today. The file stays around a screenful forever; its history lives in version control.

a good entry

Active work

Findings synthesis: in-progress

Next: resolve three claims that lack page-level citations. L-001

State a stranger could act on: what is in flight, and the next concrete step, with a pointer at the evidence.

a bad entry

Updates

14:20 fixed typos in the intro

15:05 reran the bibliography export

16:40 more edits, see commit log

A changelog of edits. Git already knows all of this, and none of it says what happens next.

03 DECISIONS.md

Which accepted choices constrain future work, and why?

The choices already made and the reasoning behind them, so later work builds on them instead of quietly undoing them. Every entry has a stable ID other records can point at.

project-context/DECISIONS.md real example

D-001: Set an evidence cutoff

Status: accepted

Date: 2026-08-05

Decision: Include public studies published on or before 2025-12-31.

Rationale: Keep the review reproducible while the first report is drafted.

Consequences: Newer evidence is logged for the next review rather than silently added.

Evidence: docs/research-protocol.md@8c41f2e

ID · status · date · statement · rationale · consequences · evidence

not a design doc

The registry holds the constraint and the reason, and points at the design. The full architecture, the rejected alternatives, the diagrams — those live in a design document the entry links to. An entry a future contributor may freely change is not a decision at all; leave implementation details out.

How it changes over time

Decisions are superseded, not deleted. Reversing or narrowing one means a new entry with a supersession link; the old entry keeps its ID, its status becomes superseded, and it remains readable as historical evidence. History is corrected through status, never rewritten.

a good entry

D-001: Set an evidence cutoff

Decision: include public studies published on or before 2025-12-31.

Rationale: keep the review reproducible while the first report is drafted.

The constraint and the reason. Anyone can now tell whether new work violates it — and whether the reason still holds.

a bad entry

D-002: Report generator architecture

The generator runs three passes. Pass one tokenises the corpus into…

(forty more lines of design)

A design doc pasted into the registry. Record the constraint, give the reason, and link the design instead.

04 LEARNINGS.md

Which verified lessons should future collaborators reuse?

What was tried and what it actually taught you — kept separate from what everyone merely believes to be true. An entry earns its place by being reusable and verified; evidence is required.

project-context/LEARNINGS.md real example

L-001: Capture claim-level provenance

Status: accepted

Scope: evidence synthesis and collaborative editing

Learning: A bibliography entry alone does not show which source supports a specific claim.

Action: Record a page, section, table, or dataset locator for every material claim.

Evidence: Editorial review found three claims that could not be traced from the bibliography alone.

verified once, reused by every later session

not a diary

Not a log of what a session did, and not a place for hunches. An entry earns its place by being reusable beyond the task that produced it and verified by evidence — an observed result, a reproduced failure, a review finding. If nobody verified it, it is a belief, and beliefs do not go in the registry.

How it changes over time

An entry stands while its evidence holds. When the cited material changes — the doctor flags this as drift — the lesson is re-verified, then re-anchored to the current state or superseded. Like decisions, learnings are never silently rewritten.

a good entry

L-001: Capture claim-level provenance

Learning: a bibliography entry alone does not show which source supports a claim.

Evidence: editorial review found three claims that could not be traced.

Verified by a real finding, and reusable on every future claim — not just the three that triggered it.

a bad entry

L-002: Long day on the export bug

Spent most of Tuesday chasing the export bug. Frustrating.

Might be the encoding? Will look again tomorrow.

A diary entry: no evidence, nothing verified, nothing the next person can reuse.

05 evidence anchors

Pinning a citation to a point in history

Decisions and learnings cite evidence. When that evidence lives in the repository, the citation can be pinned to the exact commit it was verified at — so a later session can tell whether the justification still holds.

docs/research-protocol.md@8c41f2e

The anchor form is path/to/file@commit — a repository-root-relative path at the commit where the evidence was verified. It goes on an Evidence: line inside the entry it supports.

drift

The doctor verifies every anchor. evidence-drift warns when the cited path has changed since the pinned commit — the justification may no longer hold; re-verify, then re-anchor or supersede. evidence-unverifiable warns when the commit is unknown. Anchors are optional and Git-gated: warnings only, never errors.

06 next

Now make it a habit

You know what the three files hold. The next page is the day-2 ritual: what agents read before work, what triggers a durable record, and the five things worth having written down by the end of week one.

next Operate — the session loop back Docs — getting started

Clarity comes with context.