types/: Seiten-Type-Spec-Anleitungsprosa in stackeigene guidance-Datei ausgelagert (schliesst #104)
Files changed: - AGENTS.md - CHANGES.md - VERSION - docs/ownership-and-templates.md - instructions/migrations/6.0.0-type-guidance-split.md - instructions/setup-instance.md - tools/CONTRACT.md - tools/chemenu/commands/dist_cmd.py - tools/chemenu/commands/types_cmd.py - tools/chemenu/tests/test_dist_cmd.py - tools/chemenu/tests/test_dist_upgrade.py - tools/chemenu/tests/test_type_resolver.py - tools/chemenu/tests/test_types_cmd.py - tools/chemenu/type_resolver.py - tools/chemenu/types_core.py - types/comparison.guidance.md - types/comparison.md - types/concept.guidance.md - types/concept.md - types/entity.guidance.md - types/entity.md - types/source.guidance.md - types/source.md - types/type-guidance.md - types/type-guidance.schema.yaml - types/type-spec.md
This commit is contained in:
@@ -0,0 +1,63 @@
|
||||
---
|
||||
type: types/type-guidance.md
|
||||
name: source
|
||||
description: When to write a source page instead of a neighboring type, and how to write a conforming one - capture-field, provenance and not-extracted rules that hold regardless of which source_type values this instance chose
|
||||
---
|
||||
|
||||
# Source Guidance
|
||||
|
||||
`source` is the type for pages that summarize and catalogue ingested raw material. Source pages
|
||||
are the bridge between the `raw/` layer (immutable source files) and the `kb/` layer (compiled
|
||||
knowledge). One source page stands for **one logical source**, which may span several raw files.
|
||||
|
||||
## When to use
|
||||
|
||||
- Summarizing a single external article, document or specification
|
||||
- Recording several related notes or meeting records as one source
|
||||
- Documenting an ingested PDF, manual or other document
|
||||
- Capturing information about an image or a diagram
|
||||
|
||||
## When NOT to use
|
||||
|
||||
- For compiled knowledge (use `entity` or `concept`)
|
||||
- For comparative analyses (use `comparison`)
|
||||
- For original wiki content not derived from raw material
|
||||
|
||||
## Authoring guidance
|
||||
|
||||
- `source_type` has **no default** - `wikitool new source` refuses without an explicit value. Where the category is unclear, set `unclassified` rather than guessing; that is a visible catalog slot with an advisory `lint` finding, not a dumping ground. What separates `analysis` from `document`, and which area holds which value, is a call this instance's own collection contract makes - see `kb/sources/COLLECTION.md`
|
||||
- `raw_files` lists every raw file this source covers (one source page per logical source, not per file)
|
||||
- `fidelity` and `authority` are **capture fields** (`capture_fields:` on this type): recorded at the drop point and not freely changeable afterwards. `wikitool raw accept --fidelity <value> --authority <value>` refuses without both; without `--page` it instead prints the ready-made `new source --set fidelity=... --set authority=...` line, which `new source` in turn refuses without both values. `wikitool touch --set fidelity=<value>` only writes while the field is absent - where a value already stands, it refuses and points at `raw accept --replaces` as the one correction path (a corrected capture is a new edition, not an edit). `unknown` is backfill-only: only `wikitool touch` may write it, never `raw accept` or `new source` - the same construction as `source_language` uses for pages that predate this rule. What the values mean and how they differ: [raw/CONTRACT.md](../raw/CONTRACT.md#getting-a-file-in-incoming)
|
||||
- For external articles, always set `source_url` to the origin URL
|
||||
- Set `source_language` to the raw material's language, not the page's
|
||||
- The page is written in the KB language, whatever language the source is in; verbatim passages are quoted in the original (`kb/CONVENTIONS.md` § "Language")
|
||||
- Summarize the key claims in the summary section
|
||||
- Put anything actionable in the action items section
|
||||
- Put deliberate omissions in the not-extracted section - see below
|
||||
- Link the entities and concepts mentioned under related entities/concepts
|
||||
|
||||
## Not Extracted
|
||||
|
||||
The decision that material should *not* be taken over cannot be reconstructed: nothing in the
|
||||
repository can re-derive it, and `sources coverage` only knows whether a raw file is claimed by
|
||||
some source page - never whether anyone decided about its contents. Left unwritten, the same
|
||||
source is renegotiated on every later pass.
|
||||
|
||||
- Record every deliberate omission with a **reason**, not just a filename.
|
||||
- Mandatory where the ingest ran through `instructions/ingest-large-tree.md` - on both axes: for
|
||||
a tree ingest the section records what was not taken from the tree; for a thematically broad
|
||||
single source, which named subjects got no page of their own, and why. Optional for a single
|
||||
small file - but an empty section still beats a missing one.
|
||||
- Belongs on the source page, not in `kb/log.md`: it is a statement about *this* source, and the
|
||||
log is chronological rather than per-source.
|
||||
|
||||
---
|
||||
|
||||
Relevant Notes:
|
||||
|
||||
- Source pages are the authoritative catalogue of what raw material has been ingested
|
||||
- **One raw file, one owner.** A raw file appears in exactly one `raw_files:` - that page is responsible for keeping it summarized. Any number of pages may **cite** it via `[^cite-id]`; a citation is reuse, `raw_files:` is a maintenance responsibility. With two claimants it is undefined which page has to be brought up to date when the raw file changes - and then both rot quietly
|
||||
- Source pages make knowledge traceable back to the original raw material
|
||||
- `raw_files:` holds concrete existing file paths, never directories
|
||||
- A `raw_files:` list beyond roughly 15 entries indicates the cut was too coarse - the source should have been split into several source pages via `instructions/ingest-large-tree.md`
|
||||
- `entities:` plus `concepts:` beyond roughly 20 entries is the counterpart on the other axis: not cut too little, but compiled too much at once. Such a source is not split - a raw file has one owner - it needed the extract pass from `instructions/ingest-large-tree.md` § "A broad source is not cut", so that not every named subject gets a page
|
||||
Reference in New Issue
Block a user