Project knowledge
Project knowledge
Knowledge lives in docs/: small, dense, linked, tagged markdown files.
Follow in every change.
QA → QA.md at the project root (and in each subproject).
Before claiming done:
1. Run the tier your change requires (see its selection table).
2. Compare the result against that tier's expect: collected count, skips, warnings, duration.
3. Run the relevant oracles. On diff vs main, explain every difference.
4. End with a QA report: what ran, how it compares to expect, oracles, what wasn't run and why.
These don't count as evidence: reasoning, tests you weakened, mocks of the unit under test,
new skips, "output exists". If you move a baseline on purpose, update expect in the same commit.
You may add oracles as status: proposed. Only a human confirms them.
Writing: docs/style.md. Read it before writing any doc. Summary: dense, no filler,
diagrams and schemas over prose.
Current state → docs/architecture.md.
How the system is now: components, data flow, boundaries, invariants.
It's a living doc: keep it true. No history in it.
Decisions → docs/adr/NNNN-slug.md.
ADRs record changes from the architecture baseline onward. Write one when choosing
between real alternatives, adding a dependency, or changing a public interface or
data shape. Accepting an ADR means updating architecture.md in the same change.
Never rewrite an accepted ADR. Supersede it and link both ways.
Papercuts → docs/papercuts/slug.md.
Anything that slowed you or the human down: a confusing error, a flaky step,
a missing script, a misleading doc. Log it when you hit it. Fix inline only if trivial.
Small files. One concept per file, ~<150 lines. Split rather than grow. Link related files relatively. A file nothing links to is a smell.
Frontmatter on every doc:
---
title: Invoice computation
tags: [billing, domain]
code: [src/pkg/billing.py::compute_invoice, src/pkg/io/]
---
Tags only from docs/tags.md. If none fits, add one there in the same change.
Freshness. Docs point at code via code:, never the reverse.
If you change or move anything listed in some doc's code:, update that doc in the same commit.
Before a task: find docs whose tags/code touch the area, and read their open papercuts.