Skip to content

Draft — not approved. A working draft by UASK. It may change without notice.

Knowledge item

This template is not tied to a playbook stage.

Download knowledge-item.md — the source, as in the repository.

How to use

The template's own instructions:

Template of a knowledge item. Use it when adding a new item under content/: copy it to content/<part>/<domain>/<slug>.md, replace every value and delete this comment. The schema schemas/knowledge-item.schema.json and tools/validate_content.py decide what is valid.

Fields

Front-matter fields and sections of the document the template creates. A section marked Optional in the template may be deleted from a copy; every other field and section stays (tools/check_artifacts.py checks this for the kinds it knows).

Field or sectionWhereRequired
idfront matterrequired
titlefront matterrequired
kindfront matterrequired
domainfront matterrequired
descriptionfront matterrequired
versionfront matterrequired
statusfront matterrequired
applies_tofront matterrequired
extendsfront matterrequired
sourcesfront matterrequired
standardsfront matterrequired
requiresfront matterrequired
relatedfront matterrequired
templatesfront matterrequired
skillsfront matterrequired
last_reviewedfront matterrequired
review_everyfront matterrequired
supersedesfront matterrequired
superseded_byfront matterrequired
Summarysectionrequired
Rulessectionrequired
Guidancesectionrequired
Explanationsectionrequired
Examplessectionrequired
Sourcessectionrequired

Example

A filled-in copy for an invented product, templates/examples/knowledge-item.md, in the Hub repository.It shows the level of detail to aim for, not text to reuse.

example-knowledge-item.md
---
id: arch.example-rule-set
title: Keep a decision record for every hard-to-reverse choice
kind: practice
domain: architecture
description: Example of a filled knowledge item, showing the front matter, the rule ids and the sections of a practice.
version: 0.1.0
status: draft
applies_to: [core]
extends: ~
sources:
- title: Architectural Decision Records
url: https://adr.github.io/
license: CC0-1.0
accessed: 2026-03-01
standards: []
requires: []
related: []
templates: [templates/adr.md]
skills: []
last_reviewed: 2026-03-01
review_every: 12
supersedes: ~
superseded_by: ~
---
## Summary
A hard-to-reverse choice is written down once, with its reasons, so that nobody has to guess later why it was made. This
example item shows how a rule, its guidance and its sources fit together.
## Rules
- **R1.** A choice that is costly to reverse MUST have a decision record before the work that depends on it starts.
- **R2.** A decision record SHOULD name at least two options, one of them "keep the current approach".
## Guidance
Write the record when the choice is made, not afterwards. A short record is enough; the options and the reason matter most.
Small, easily reversed choices do not need one.
## Explanation
Without a record, reasons are lost when people leave, and the same debate is held again. Recording the options also exposes
choices that were made by default.
## Examples
Good: "Store notes as plain files in Git" lists three options and the measured reason for the choice.
Bad: "We use a database" with no options and no reason.
## Sources
- [Architectural Decision Records](https://adr.github.io/) — CC0-1.0, the idea and the formats. Accessed 2026-03-01.

Completion checks

A copy is complete when:

  • every required field and section above is present, in the same order, and no bracketed placeholder is left;
  • the owner has approved it, where the playbook asks for approval. Only the owner sets approved.

Source

templates/knowledge-item.md, as in the repository. Placeholders are in square brackets; comments carry the instructions.

knowledge-item.md
---
id: domain.slug # <domain prefix>.<slug>, unique, never reused (prefixes: schemas/knowledge-item.schema.json)
title: Title in sentence case
kind: standard # standard | practice | checklist | concept | tutorial | term | playbook
domain: architecture # SWEBOK v4 knowledge area
description: One sentence (20–300 characters) for search, SEO and agent discovery.
version: 0.1.0 # item SemVer: MAJOR new/stricter MUST, MINOR new item or SHOULD, PATCH wording
status: draft # draft | review | approved | published | deprecated
applies_to: [core] # core, or profile names
extends: ~ # profile items only: the core item id they specialise
sources: # at least one for standard, practice, checklist
- title: Name of the primary source
url: https://example.org/spec
license: CC-BY-4.0 # SPDX id; LicenseRef-All-Rights-Reserved if none; BY-SA only in content/adapted/
accessed: 2026-01-01
standards: [] # external standards by name, reference only
requires: [] # item ids to understand or apply first
related: [] # item ids
templates: [] # paths such as templates/adr.md
skills: [] # skill names in skills/
last_reviewed: 2026-01-01
review_every: 12 # months
supersedes: ~
superseded_by: ~ # required when status is deprecated
---
<!-- Template of a knowledge item. Use it when adding a new item under content/: copy it to content/<part>/<domain>/<slug>.md, replace every
value and delete this comment. The schema schemas/knowledge-item.schema.json and tools/validate_content.py decide what is valid. -->
## Summary
Two to four sentences: what this is and why it matters.
## Rules
- **R1.** One testable rule with an RFC 2119 keyword (MUST, MUST NOT, SHOULD, SHOULD NOT, MAY).
- **R2.** Rule ids are stable: never renumber; retire a rule by marking it "(removed in 2.0.0)".
## Guidance
Recommendations, trade-offs and when not to apply the rules. No upper-case keywords here.
## Explanation
Why the rules exist; background and history.
## Examples
A short good example and a short bad one.
## Sources
- [Name of the primary source](https://example.org/spec) — licence, what was used. Accessed 2026-01-01.