32 lines
1.4 KiB
Markdown
32 lines
1.4 KiB
Markdown
## Documentation Voice
|
|
|
|
Use terse, normative statements. Avoid "the user wants", "currently", "now", "fixed", "regressed", "recently". State what the system **does**, not what happened.
|
|
|
|
## Bullet Budget
|
|
|
|
At most 120 lines per file. Nearly empty or empty files are honest.
|
|
|
|
## Single-Home Rule
|
|
|
|
- `architecture.md`: structural/runtime decisions (component boundaries, chosen abstractions, protocol/storage direction, explicit "X over Y" with reason).
|
|
- `product.md`: behavior, UX, defaults, scope, naming/terminology, workflow decisions.
|
|
- `style.md`: visual/aesthetic language, presentation/typography conventions, prose/voice rules.
|
|
|
|
## Concreteness Test
|
|
|
|
Every bullet must change a fresh agent's behavior. "Provide configurable, reference-compatible interactions" is delete-tier. "Status bar: powerline segments, solid right edge, inward-facing left triangle, no bold, elapsed time ≤3 chars" is keep-tier.
|
|
|
|
## Exclusions
|
|
|
|
- Project docs digest (already documented).
|
|
- Global user taste not a project decision.
|
|
- Current-task state (bugs in flight, progress, plans, TODOs, "for now").
|
|
- File paths, line numbers, function/type names, commit/issue ids (product component vocabulary allowed).
|
|
|
|
## Friction Markers
|
|
|
|
A terse marker like "(recurrently regressed)" MAY close a bullet where it strengthens the instruction; keep rare.
|
|
|
|
## Grouping
|
|
|
|
Group bullets under short `##` domain sections. One line per bullet where possible. |