archive

Files (1)

• SKILL.md

SKILL.md (first lines)

# Living documentation

Always in sync with code. Current ground truth only — atemporal, no history, no plans.

- `README.md` — for users: what it is, who for, how to use
- `docs/tech-spec.md` — for developers/agents: current system state (core backbone, ≤300 lines)
- `docs/specs/<topic>.md` — modular subsystem/protocol details; referenced by path
- `docs/ROADMAP.md` — direction (≥3 milestones or long-term)
- `CHANGELOG.md` — version history (`ship` maintains)
- `docs/decisions/` — architectural rationale (`context / choice / ruled-out`), append-only

## Living doc North Star

> **Standard**: Zero history, maximum truth density, instant scannability.
> - **The Razor**: Past rationale belongs in `docs/decisions/` or `CHANGELOG.md`; `docs/tech-spec.md` holds exclusively active ground truth.

1. **Atemporal**: Describes exclusively current ground truth. No version/milestone headers, changelog deltas, or supersession notes. Mutate in-place.
2. **Modular (Progressive disclosure)**: Bulky subsystem specs (>15 lines, schemas, complex state machines) live in `docs/specs/<topic>.md`, referenced by a one-line declaration in `tech-spec.md`.
3. **Structured & concise**: Atomic declarations (≤25 words per sentence). Multi-attribute contracts use structured bulleted lists or tables; no dense text blocks.

## tech-spec format

Declarations only.

```
purpose:      <what problem this solves — one sentence>
user:         <who uses this>
use-case:     <key scenarios, one line each>
architecture: <structural shape — one line, or see docs/architecture.md>
stack:        <language, runtime, frameworks, key deps>
entry:        <where execution starts>
contract:     <public APIs / interfaces that must not break — stability set; full surface by doc-coverage>
flow:         <name>: <trigger> → <steps> → <output>
              (complex — branching/async/multi-actor: one-line summary here, diagram in docs/specs/<flow>.md)
invariant:    <what must always hold>
constraint:   <limits, warnings from code>
convention:   <naming, file structure, test patterns, lint/format/typecheck tools, error-handling, security baseline>
milestone:    <current milestone> (see docs/ROADMAP.md)
```

# Archive

If `topology=multi-module` (triage announcement or coordinator spec/plan declaration), read `../references/multi-module.md`. Merge each module's artifacts in its own repository first. Then merge shared contracts and integration facts in the coordinator, record the revision set, and archive it last. Keep module-local facts in module repos.

`<gate>` Before proceeding: (1) verify `tdd`/`subagents` have completed all tasks listed in the plan; (2) user has approved shipping/archiving this change (ship disposition or an explicit archive go-ahead). `</gate>`

1. **Merge** staging spec into living doc:
   - Integrate in-place into existing declarations; overwrite modified contracts rather than appending new sections.
   - Subsystem details >15 lines go to `docs/specs/<topic>.md`.
   - Maintain concise, structured formatting (lists/tables, no text walls).

2. **Roadmap** (if spec contains `## Roadmap`): update roadmap independently; do not duplicate into tech-spec.

3. **Decisions** (if spec or working notes contain a knowledge artifact — protocol spec, RE findings, architectural rationale): save to `docs/decisions/YYYY-MM-DD-<topic>.md` as `context / choice / ruled-out`.

`<gate>` Before deleting staging spec/plan, verify Living Doc North Star: (1) Atemporal (zero history/dates/supersessions)? (2) Truth-dense (binding facts only)? (3) Modular (subsystems >15 lines in docs/specs/)? (4) User approved merged living-doc. `</gate>`

4. **Delete** `docs/staging/specs/YYYY-MM-DD-<topic>.md` — content absorbed; Git has the history.
5. **Delete** `docs/staging/plans/YYYY-MM-DD-<topic>.md` — plans don't belong on `main`.

From ouonet/praxis, MIT.

More from ouonet/praxis