oleh/astrolabe
1
0
Fork 0
mirror of https://github.com/olehomelchenko/astrolabe.git synced 2026-08-08 02:02:33 +00:00
Code Issues Packages Projects Releases Wiki Activity

Docs: record the spec-follows-code regime across the working docs

Browse Source
This commit is contained in:
Oleh Omelchenko
2026-07-02 22:33:05 +03:00
parent e42a535726
commit fb4b42a1a7
13 changed files with 76 additions and 59 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude/skills/doc-update/SKILL.md
+17 -16
View File
@@ -30,9 +30,10 @@ For documentation organization, see **[CLAUDE.md](../../../CLAUDE.md)** and the
## The three documentation layers (know which one a gap belongs to)
- **`docs/spec/`** — the _what_: behavioral contract (what the app does, acceptance points).
This is a **contract**. Only change it when product behavior genuinely changes, and do so
deliberately — never as a casual "fill a doc gap" edit. A how-detail does NOT belong here.
- **`docs/spec/`** — the _what_: behavioral record (what the app does, acceptance points).
The code leads; the spec is kept rewritten to match what shipped. If the session added or
changed user-facing behavior, name the spec section that describes it — or write it — as
part of this pass. A how-detail does NOT belong here.
- **`docs/architecture/`** — the _how_: the patterns behind each layer (state, persistence,
modals, routing, rendering, inference, relationships). Most navigation maps and decision
rules land here.
@@ -59,19 +60,19 @@ not do Y"). If you can't state it concisely, it may be too implementation-specif
Map each gap to the right document:
| Gap type | Target document |
| ------------------------------------------------- | ----------------------------------------------------------------------------- |
| Product behavior, capabilities, acceptance points | `docs/spec/` (the relevant 00–10 section) — **contract; change deliberately** |
| State / Zustand stores | `docs/architecture/01-state-and-stores.md` |
| Persistence, IndexedDB, localStorage, migrations | `docs/architecture/02-persistence.md` |
| Modals, dialog lifecycle | `docs/architecture/03-modal-system.md` |
| URL routing, keyboard/events | `docs/architecture/04-routing-and-events.md` |
| Rendering, theming, vega-embed, preview | `docs/architecture/05-rendering-theming-preview.md` |
| Type inference, dataset profiling | `docs/architecture/06-type-inference.md` |
| Names, snippet↔dataset links, rename propagation | `docs/architecture/07-naming-and-relationships.md` |
| Milestone scope, build order | `docs/IMPLEMENTATION-PLAN.md` |
| Project philosophy / identity | `SOUL.md` |
| Onboarding, conventions, stack | `AGENTS.md` / `CLAUDE.md` |
| Gap type | Target document |
| ------------------------------------------------- | --------------------------------------------------------------------------------- |
| Product behavior, capabilities, acceptance points | `docs/spec/` (the relevant 00–10 section) — **record; keep it matching the code** |
| State / Zustand stores | `docs/architecture/01-state-and-stores.md` |
| Persistence, IndexedDB, localStorage, migrations | `docs/architecture/02-persistence.md` |
| Modals, dialog lifecycle | `docs/architecture/03-modal-system.md` |
| URL routing, keyboard/events | `docs/architecture/04-routing-and-events.md` |
| Rendering, theming, vega-embed, preview | `docs/architecture/05-rendering-theming-preview.md` |
| Type inference, dataset profiling | `docs/architecture/06-type-inference.md` |
| Names, snippet↔dataset links, rename propagation | `docs/architecture/07-naming-and-relationships.md` |
| Milestone scope, build order | `docs/IMPLEMENTATION-PLAN.md` |
| Project philosophy / identity | `SOUL.md` |
| Onboarding, conventions, stack | `AGENTS.md` / `CLAUDE.md` |
If a gap fits no existing document, consider a new section in the closest one; prefer
extending over creating. A brand-new architecture topic can become `docs/architecture/08-*.md`