mirror of
https://github.com/olehomelchenko/astrolabe.git
synced 2026-08-08 02:02:33 +00:00
Docs: record the spec-follows-code regime across the working docs
This commit is contained in:
@@ -37,8 +37,11 @@ Review all changes in scope. If changes span multiple patterns below, apply all
|
||||
3. **Fix directly; don't ask first.** When you find an issue covered by these instructions,
|
||||
fix it in place rather than reporting it and waiting. Ask the user only when the fix is
|
||||
genuinely ambiguous or several valid approaches exist with real trade-offs. When guidelines
|
||||
conflict, prefer in this order: **SOUL.md philosophy > `docs/spec/` behavioral contract >
|
||||
`docs/architecture/` patterns > local cleanup**. These instructions are not strictly
|
||||
conflict, prefer in this order: **SOUL.md philosophy > `docs/spec/` behavioral record >
|
||||
`docs/architecture/` patterns > local cleanup**. (The spec is descriptive — the code
|
||||
leads. A spec/code mismatch is fixed by updating the stale spec section, not by
|
||||
reverting the code; only flag the code when it contradicts recorded _rationale_, not
|
||||
merely an unrewritten section.) These instructions are not strictly
|
||||
prohibitive — if a guideline has a valid reason to be bypassed, mention it in the summary.
|
||||
|
||||
### Code Quality
|
||||
@@ -178,12 +181,15 @@ role`) or the rule it demonstrates. - **Positional sub-section cross-refs.** Cit
|
||||
(whole-spec drag/simplify) — never re-inlining the model/parse/writeBack prologue. The
|
||||
family has grown by copy-paste twice (eng-council; arch 08).
|
||||
|
||||
17. **Spec tracks the surfaces it mandates** (`docs/spec/`): a diff that **removes, moves, or
|
||||
renames a user-facing surface** — where a message, control, or affordance lives — updates the
|
||||
`docs/spec/` section describing it, not only the `docs/architecture/` pattern doc. The spec is
|
||||
the behavioral contract; an arch-doc-only update leaves it describing a surface that no longer
|
||||
exists. An arch-only update once left spec §03E mandating an editor-pane error message after it
|
||||
had moved to the preview (eng-council).
|
||||
17. **Spec tracks the surfaces it describes** (`docs/spec/`): a diff that **adds, removes,
|
||||
moves, or renames a user-facing surface** — a feature, message, control, or affordance —
|
||||
updates the `docs/spec/` section describing it (adding a section for new behavior), not
|
||||
only the `docs/architecture/` pattern doc. The spec is the behavioral record and the code
|
||||
leads; an arch-doc-only update leaves the spec describing a product that no longer exists.
|
||||
An arch-only update once left spec §03E mandating an editor-pane error message after it had
|
||||
moved to the preview (eng-council); a run of feature commits (2026-06-25 → 06-30: the
|
||||
/learn/ section, the composition wireframe, editor scaffolds) once landed with zero spec
|
||||
coverage (eng-council, 2026-07).
|
||||
|
||||
### Output
|
||||
|
||||
@@ -206,7 +212,7 @@ role`) or the rule it demonstrates. - **Positional sub-section cross-refs.** Cit
|
||||
|
||||
Update relevant docs if the feature is significant:
|
||||
|
||||
- **`docs/spec/`** — if product behavior changed (this is a contract; change deliberately).
|
||||
- **`docs/spec/`** — if product behavior changed (descriptive record; update it to match what shipped — see #17).
|
||||
- **`docs/architecture/`** — if a new pattern, navigation map, or decision rule emerged.
|
||||
- **`docs/IMPLEMENTATION-PLAN.md`** — mark milestone progress.
|
||||
Use the `/doc-update` skill for session-discovered gaps. The list is not exclusive.
|
||||
@@ -226,7 +232,7 @@ If `package.json` changed:
|
||||
### Alignment Check
|
||||
|
||||
- **SOUL.md** — philosophy (must not violate without good reason).
|
||||
- **`docs/spec/`** — behavioral contract.
|
||||
- **`docs/spec/`** — behavioral record.
|
||||
- **`docs/architecture/`** — the relevant pattern doc.
|
||||
|
||||
---
|
||||
@@ -245,7 +251,7 @@ Usually not required unless the bug revealed incorrect docs, or the fix changes
|
||||
|
||||
### Alignment Check
|
||||
|
||||
- **SOUL.md** philosophy; **`docs/spec/`** behavioral contract; **`docs/architecture/`** patterns.
|
||||
- **SOUL.md** philosophy; **`docs/spec/`** behavioral record; **`docs/architecture/`** patterns.
|
||||
|
||||
---
|
||||
|
||||
@@ -286,10 +292,10 @@ Update JSDoc/inline comments if signatures or behavior changed.
|
||||
|
||||
## Reference Documents
|
||||
|
||||
| Document | Purpose |
|
||||
| ------------------------------------------------------------------- | ----------------------------------------- |
|
||||
| [SOUL.md](../../../SOUL.md) | Project philosophy and core values |
|
||||
| [AGENTS.md](../../../AGENTS.md) | AI onboarding and project context |
|
||||
| [docs/spec/](../../../docs/spec/) | Behavioral contract — _what_ the app does |
|
||||
| [docs/architecture/](../../../docs/architecture/00-overview.md) | Architecture playbook — _how_ it's built |
|
||||
| [docs/IMPLEMENTATION-PLAN.md](../../../docs/IMPLEMENTATION-PLAN.md) | Milestone sequence and scope |
|
||||
| Document | Purpose |
|
||||
| ------------------------------------------------------------------- | ---------------------------------------- |
|
||||
| [SOUL.md](../../../SOUL.md) | Project philosophy and core values |
|
||||
| [AGENTS.md](../../../AGENTS.md) | AI onboarding and project context |
|
||||
| [docs/spec/](../../../docs/spec/) | Behavioral record — _what_ the app does |
|
||||
| [docs/architecture/](../../../docs/architecture/00-overview.md) | Architecture playbook — _how_ it's built |
|
||||
| [docs/IMPLEMENTATION-PLAN.md](../../../docs/IMPLEMENTATION-PLAN.md) | Milestone sequence and scope |
|
||||
|
||||
@@ -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`
|
||||
|
||||
Reference in New Issue
Block a user