43 lines
2.1 KiB
Plaintext
43 lines
2.1 KiB
Plaintext
---
|
|
description: Keep project documentation current—ADRs, mission, editor docs, README checklist
|
|
alwaysApply: true
|
|
---
|
|
|
|
# Documentation Maintenance
|
|
|
|
When changing behavior, architecture, or user-facing workflows, **update docs in the same task**—do not defer.
|
|
|
|
## Doc map (single source of truth: [docs/README.md](../../docs/README.md))
|
|
|
|
| Change type | Update |
|
|
|-------------|--------|
|
|
| Architecture / crate boundary / sim-network split | New or updated ADR in `docs/adr/` |
|
|
| Editor framework intent, principles, non-goals | `docs/mission.md` |
|
|
| Editor feature design or phase status | `docs/editor/` (see its README) |
|
|
| User controls, run commands, troubleshooting | Root `README.md` |
|
|
| Shipped feature completion | Root `README.md` Implementation Checklist |
|
|
| Bevy upgrade policy | ADR 0002 + migration notes in `docs/adr/` |
|
|
| Milestone scope (pre-implementation) | `.cursor/plans/` plan file |
|
|
|
|
## ADRs
|
|
|
|
Create `docs/adr/NNNN-short-title.md` when a decision is **hard to reverse** or affects multiple crates (rendering path, scene format, PIE semantics, settings schema, netcode choice).
|
|
|
|
Format: Status, Context, Decision, Consequences. Number sequentially. Link from `docs/README.md` and root README.
|
|
|
|
## Coherence rules
|
|
|
|
- **One home per fact.** Link across docs; do not copy paragraphs between README, mission, and ADRs.
|
|
- **Intent vs implementation:** mission/ADRs = *why*; README = *how to use*; crate module docs = *local API*.
|
|
- **Plans vs permanent docs:** `.cursor/plans/` holds working roadmaps; promote stable decisions into `docs/` when implemented.
|
|
- **Stale docs are bugs.** If code contradicts docs, fix both or fix docs in the same PR/task.
|
|
- **New subsystems** get a short entry in `docs/README.md` and, if editor-facing, `docs/editor/README.md`.
|
|
|
|
## Agent checklist (end of relevant tasks)
|
|
|
|
1. Did behavior or UX change? → README controls / checklist
|
|
2. Did architecture or policy change? → ADR or mission
|
|
3. Did editor workflow change? → `docs/editor/`
|
|
4. Added a new doc file? → index in `docs/README.md`
|
|
5. Left a deliberate gap? → "Future work" in README or an ADR Consequences section—not silent omission
|