This directory records how sim-use is built and why. Each numbered folder holds one topic: the plan or investigation that came before the work, and the decisions and results that came after it. Humans and agents read it to answer "why is it built this way?" without a search through git history.
sim-use uses AI-docs-driven development: a substantial change starts with a
record here, and a decision is written down when it is made. The rules are in
the write-ai-docs skill (.agents/skills/write-ai-docs/SKILL.md).
docs/ai/NNN-<slug>/
000-plan.md # before the work: background, goals, approach, alternatives
# (000-investigation.md when the work starts as a root-cause hunt,
# 000-design.md for a backfilled or design-only record)
001-action.md # after the work: what shipped, PRs, deviations from the plan
002-<topic>.md # amendments: follow-up work, review rounds, corrections
# (a design or investigation record that already holds its outcome
# has no action log; its amendments start at 001)
<name>.md # no number = living document (guide, runbook, contract), kept current
- Numbers are three digits, in the order the topics started, and are never reused.
- A numbered file records what was true when it was written. When a later finding makes it wrong, add a dated note at the top or in Amendments that says what changed and where. Do not silently rewrite history.
- A file without a number is a living document. Update it in place when the behavior it describes changes.
README.md,AGENTS.mdandskills/sim-use/describe current behavior for users and agents. History and decisions go here.
On 2026-10-14 the entries were numbered by the date their topic started.
002, 003, 004, 006 and 009 were first written as
docs/ai/xxxx-<slug>/README.md. 008 combines the former docs/linux.md
(now linux-guide.md) with a design
record backfilled from #141 and #147. 001, 005, 007 and the amendment
002/001 were backfilled on the same day from pull requests, issues, the code
and CHANGELOG.md; each backfilled file says so at the top.