yukart/project-yukart
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Rewrite reference docs as current state; record the style rule

Browse Source 
Reference, guidelines and plan documents describe what is and what will be.
Retirement stories, resolved-risk narration and against-the-alternative
argument moved out or were cut; reports keep that material.

What survives the cut is the mechanism that can bite again (driving side is a
country-level property) and the condition that would change a decision (a
permanently installed, car-powered panel), both stated generally.

Also removes a duplicated Japan section from a bad edit.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013kj58Jugkic783b8ZrtTVZ
This commit is contained in:
Mikkeli Matlock
2026-09-04 15:23:08 +09:00
parent 102cf38082
commit 574df1471c
4 changed files with 75 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/REPOS.md
+32 -12
View File
@@ -115,10 +115,8 @@ it records the investigation and the dead ends, not just the final commands.
### Scaffolding conventions
No template repository. Template instantiation is fork-at-create, so it could not
reach repos that already exist, and the scaffolding is a handful of markdown files
— lighter than the machinery to manage it. A template earns its place where there
is a real toolchain to carry, which is the ESP32 case above.
Component repos are scaffolded by hand. A template repo is for carrying a real
toolchain, which is the ESP32 case above.
Every component repo carries:
@@ -131,6 +129,33 @@ docs/impl/reports/
docs/BOM.md only where the repo owns hardware
```
### Writing style
Documents describe **what is and what will be**. They are not changelogs — git
holds the sequence.
| Instead of | Write |
|---|---|
| "X was dropped because Y" | what the design **is** |
| "this was a risk, now resolved" | what runs, and the measurements |
| "the earlier decision assumed Z" | the current constraint |
| "X was rejected in favour of Y" | Y, stated as the rule |
⚠ **A sentence justifying a current state by a current reason becomes false when
the reason changes, and nothing announces it** — it stays, confident and
well-written, and reads as fact.
Two things survive the cut, because they stay true when their subject is gone:
- **A mechanism that can bite again.** Not "we picked the wrong extract once", but
"driving side is a country-level property, so a clipped extract routes mirrored".
- **A condition that would change the decision**, stated generally — "a
permanently installed, car-powered panel" rather than a story about a panel that
was considered.
Reports under `impl/reports/` are the exception and the place for all of it: the
investigation, the dead ends, what was measured and found wrong.
### Front matter
Every markdown document carries front matter, with **no exceptions for the hub or
@@ -145,14 +170,9 @@ for any particular repo**. The `type` discriminates:
`status` is one of `active`, `superseded` or `done`.
The extra fields exist for one reason. This document already observes that **plans
go stale and reports do not** — but nothing made staleness visible, so a plan
written months ago looked identical to one written this morning. `status` and
`updated` fix that; `date` on a report records the moment it describes, which is
the whole value of a report.
A `type` with one possible value would be decoration. This one has four and they
are worth grepping for.
`status` and `updated` make a plan's staleness visible — plans go stale and
reports do not, and without them a plan from months ago reads identically to one
written this morning. `date` on a report records the moment it describes.
## Naming