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 |
|
||||
|
||||
Reference in New Issue
Block a user