torben
c64479fe02
Files changed: - AGENTS.md - CHANGES.md - ENVIRONMENT.md.template - SOUL.md - SOUL.md.template - USER.md.template - VERSION - docs/ownership-and-templates.md - docs/version-model.md - instructions/CONTRACT.md - instructions/dev/doc-pull-through.md - instructions/dev/stack-close/SKILL.md - instructions/dev/stack-dev/SKILL.md - instructions/dev/version-parts.md - instructions/setup-instance.md - kb/CONVENTIONS.md - kb/CONVENTIONS.md.template - kb/concepts/COLLECTION.md - kb/sources/COLLECTION.md - tools/CONTRACT.md - tools/chemenu/commands/types_cmd.py - tools/chemenu/commands/version_cmd.py - tools/chemenu/tests/test_toc.py - tools/chemenu/tests/test_version_cmd.py - tools/chemenu/toc.py - tools/chemenu/version.py - types/comparison.md - types/concept.md - types/entity.md - types/lint-report.md - types/source.md
116 lines
5.8 KiB
Markdown
116 lines
5.8 KiB
Markdown
---
|
|
profile: concepts
|
|
outbound:
|
|
concepts: [extends, grounds, rests-on, enables, precondition, exemplifies, abstracted-from, contrasts, compares-with, contradicts, addresses, alternative-to, composition, part-of, supersedes, derived-from, adapted-from, see-also]
|
|
entities: [operationalized-from, mechanism, procedure, applies-when, operates-on, invokes, exemplifies, alternative-to, see-also]
|
|
sources: [evidenced-by, derived-from, adapted-from, defined-in, see-also]
|
|
comparisons: [compares-with, see-also]
|
|
required_by_stack: false
|
|
---
|
|
|
|
# kb/concepts/ - Collection Contract
|
|
|
|
Ideas rather than things: architectures, patterns, protocols, workflows, recurring problems,
|
|
and the decisions taken about them. A concept explains *how* or *why*, where an entity page
|
|
records *what*.
|
|
|
|
**Quality goal:** explanatory sufficiency - the page should answer *why it is done this way*
|
|
without the reader having to open the entity pages that use it. If the explanation only makes
|
|
sense once you already know the system, it is on the wrong page.
|
|
|
|
Inherits [kb/CONTRACT.md](../CONTRACT.md) for the rules the stack enforces - linking mechanics,
|
|
provenance, citation, the confidence machinery - and
|
|
[kb/CONVENTIONS.md](../CONVENTIONS.md) for what this instance decided: language, naming forms,
|
|
tone, relationship labels, the confidence rubric. Neither is restated here.
|
|
|
|
<!-- wikitool:toc -->
|
|
## Contents
|
|
|
|
- [Types offered](#types-offered)
|
|
- [Decisions](#decisions)
|
|
- [Authorised labels](#authorised-labels)
|
|
- [Outbound linking](#outbound-linking)
|
|
- [What does not belong here](#what-does-not-belong-here)
|
|
<!-- /wikitool:toc -->
|
|
|
|
## Types offered
|
|
|
|
`concept` (`tools/wikitool types describe concept`). The `concept_type:` field
|
|
picks the area:
|
|
|
|
| Area | Holds |
|
|
|------|-------|
|
|
| `architectures/` | Shape and structure: how a system is cut up, and why the cuts fall where they do |
|
|
| `patterns/` | Reusable solution shapes that hold across more than one subject |
|
|
| `protocols/` | Communication protocols and standards, named in their usual spelling |
|
|
| `workflows/` | Procedures and processes that recur across projects |
|
|
| `decisions/` | Architectural and design decisions (see below) |
|
|
| `problems/` | Recurring problems and the approaches taken to them |
|
|
|
|
These are areas, not collections: they inherit this contract and carry no
|
|
`COLLECTION.md` of their own.
|
|
|
|
Nobody assigns them by hand — the mapping is the `layout:` in
|
|
`types/concept.md`, and `wikitool new` puts a new page straight there. A page
|
|
sitting anywhere else is reported by `wikitool lint` as *misplaced*;
|
|
`wikitool move --page "<title>"` moves it to its computed location.
|
|
|
|
The split is not a matter of taste but what makes the catalog's shard threshold
|
|
effective at all: `index rebuild` splits **per area**, and a collection without
|
|
areas never splits — with 80 pages in a single table the threshold was a dead
|
|
value here. None of the six areas is currently above it, so none gets a shard of
|
|
its own; when one grows into it, that happens without anyone acting.
|
|
|
|
## Decisions
|
|
|
|
An architectural decision is an ordinary concept page with `concept_type: decision`
|
|
(`tools/wikitool types describe concept`) - not a separate format, and not a separate location.
|
|
There is no `adr-NNN-`-prefixed filename and no dedicated directory: naming follows
|
|
[kb/CONVENTIONS.md § Naming](../CONVENTIONS.md#naming) like every other concept, and the page
|
|
lives in `kb/concepts/` like every other concept.
|
|
|
|
The body is organic prose under this collection's usual sections, not a fixed template. What it
|
|
still has to carry: what was decided, what forced the decision, what it costs (not only what it
|
|
buys), and a link to every entity the decision affects. A `**Status:**` line is optional - most
|
|
decision pages in this instance carry none, because the page's own prose already says whether the
|
|
decision stands.
|
|
|
|
A decision superseded by a later one is never deleted or rewritten. The new page declares
|
|
`supersedes` pointing at it; the old one needs no edge back, because its inbound view renders the
|
|
replacement.
|
|
|
|
`concept_type: decision` is also the one subtype [kb/CONTRACT.md](../CONTRACT.md)'s confidence
|
|
machinery treats differently: `confidence decay` skips it structurally, because elapsed time does
|
|
not falsify a decision - only a later decision superseding it does.
|
|
|
|
## Authorised labels
|
|
|
|
The `outbound:` block above is what `wikitool lint` and `xref add` check: which labels a page in
|
|
this collection may use, per destination. The catalogue they are drawn from - and what each one
|
|
asserts - is [instructions/link-taxonomy.md](../../instructions/link-taxonomy.md), which binds
|
|
nothing on its own.
|
|
|
|
The widest authorisation in this instance, because argumentation is what concept pages do. Note that the operational labels are absent: a concept does not `depend-on` anything - the entity implementing it does.
|
|
|
|
`addresses` is the one that pairs with this collection's own subtypes: a `concept_type: decision`
|
|
or a mechanism pointing at the `concept_type: problem` it answers. Without it, the collection can
|
|
declare a problem and never say what was done about it. `alternative-to` is self-dual and written
|
|
once per pair - see [instructions/link-taxonomy.md](../../instructions/link-taxonomy.md).
|
|
|
|
Adding a label here is a deliberate contract change, not a way around a refusal.
|
|
|
|
## Outbound linking
|
|
|
|
A concept links to every entity that implements or uses it. A concept with no inbound entity
|
|
link is usually either premature or misfiled - `wikitool lint` reports it as an orphan.
|
|
|
|
Where two concepts compete, do not argue the comparison inside either page; create a page in
|
|
`kb/comparisons/` and link both to it.
|
|
|
|
## What does not belong here
|
|
|
|
- A concrete, pointable thing - that is an entity.
|
|
- A head-to-head evaluation of alternatives - that is a comparison.
|
|
- Generic textbook explanation with no connection to anything in this wiki. If no entity here
|
|
uses it, the page is not earning its keep.
|