Part of the OBSERVER skill package

Field reference — OBSERVER Format 0.1

Every field of every file. R = required, r = recommended, o = optional. Section numbers point into the OBSERVER Format specification, which is the authority and is available to download from the standard's website.

Conventions that apply everywhere: keys are lowercase snake_case (§4.2); dates are ISO 8601 and timestamps carry an explicit offset (§4.3); identities are <producer>/<version>, human:<id> or process:<id> (§4.4); unknown keys are legal and a consumer must not reject them, so your own extra keys are welcome (§4.2).

Every .md file

Field		Notes
`type`	R	OBSERVER Index, OBSERVER Log, OBSERVER Valence, OBSERVER Perception, OBSERVER Entry, and OBSERVER Reference for any .md file under `references/` (§4.1). This is what makes the folder a valid OKF bundle too.
`navigation.layer`	R	"1 of 4", "1.1 (history of layer 1)", "2 of 4", "3 of 4", entry, reference. Comes immediately after type.
`navigation.entry`	R	Always `1.0_INDEX.md`.
`navigation.up`	R	Except in `1.0_INDEX.md` and entry files. `references/*.md` use up: `1.0_INDEX.md`.
`navigation.down`	R	Except in the lowest layer present and in `1.1_LOG.md`, which has up: `1.0_INDEX.md` and no down. Entry files use down: `1.0_INDEX.md`; `references/*.md` have no down. When raw data is referenced or withheld, `3.0_PERCEPTION.md` is the lowest layer and has no down. Every file entry, up or down names must exist, written relative to the folder root.
`navigation.note`	R	One or two sentences describing where the reader is. Descriptive, never imperative — many harnesses treat imperative text in files as suspect (§3.4). In `3.0_PERCEPTION.md` it must also contain the raw data reading notice when raw data is included; when it is referenced or withheld, the note should say the raw data is not in the folder and point to `raw_data` in `1.0_INDEX.md`.

Mistake to avoid: writing note: "YOU MUST READ 1.0_INDEX.md FIRST". It reads as prompt injection and gets ignored or stripped. Write "Layer 3 of 4. The contract is in 1.0_INDEX.md."

1.0_INDEX.md (§5)

Identity and scope

Field		Notes
`observer_version`	R	"0.1". Quote it; unquoted it is a float.
`observer_id`	R	Stable across reports. The folder name may change; this may not.
`title`	R	Display name.
`purpose`	R	One or two sentences naming the subject, the period and the question answered. An agent decides relevance from this.
`report_date`	R	The date the report describes, not the date it was built.
`cadence`	r	one-off, daily, weekly, monthly, …
`transparency`	R	open if every formula is disclosed and data is included or referenced; `declared_opacity` if any formula is proprietary or data is withheld (§11.4).
`runtime`	r	`{language, version, dependencies}`. Required in practice if any formula imports anything.
`generated`	r	`{by: <actor>, at: <datetime>}`. Follows OKF: at is when the build actually ran, with an explicit UTC offset. Capture it once per build and use the same value in every file.
`verified`	o	[`{by, at}`] when a person or process confirmed the report.
`stale_after`	o	When a consumer should warn.
`sources`	o	Where the data came from (OKF §5.1).
`complexity`	r	See below.

raw_data (§5.4)

Field		Notes
`files[].path`	R	Path in the folder, or a URI when availability: referenced.
`files[].format`	R	csv, json, jsonl, parquet, …
`files[].rows`	R	Row count; feeds the reading notice.
`files[].key`	R	Columns that uniquely identify a row. Every `verify.rows` selector uses these.
`files[].columns`	R	[`{name, type, description}`]. Especially important when data is withheld — a reader with access must be able to resolve your verify fields.
`availability`	R	included \| referenced \| withheld (§10.3).
`withheld_reason`	R when withheld	Licensing, privacy, confidentiality.
`reading_notice`	R unless withheld	The §3.4.4 text with the real row and column counts (the URI in place of the file name when referenced). For a `4.0_RAW_DATA/` directory, the first sentence describes the directory (see the end of this file).
`sources`	o	Per-file provenance.

metrics[] (§5.2)

Field		Notes
`metric`	R	The name used by every observation object.
`description`	R	What the value means, with units.
`formula`	R	Python, or a proprietary statement. Must match the `trust.formula` of every object for this metric exactly, as text (compared once the YAML is read, so indentation within the file may differ). An open formula must parse as Python and should define a function named after the metric (§4.5).
`disclosure`	R	open \| proprietary. Always stated; there is no default.
`utility`	R	Why the metric is here: the decision it informs.
`citation`	o; R when proprietary	The producer's choice for an open formula: trust and verify carry the scrutiny, and a citation adds credibility where readers may not know the method — an industry report using Shannon entropy might cite Shannon (1948), Bell System Technical Journal 27(3). May also be original. For a proprietary formula it is required, as proprietary, citable as "`<name>`" (§11.3).
`inputs`	R	The raw columns or upstream metrics the formula reads. Every formula argument should map to one of them (`revenue_t` and `revenue_t_minus_1` both map to revenue).

valence (§5.3)

Field		Notes
`relative_obs[].id`	R	Referenced by every observation object.
`relative_obs[].name`	R	Human label.
`relative_obs[].comparison`	R	`cross_sectional` \| temporal \| benchmark \| other.
`relative_obs[].population`	R	What the value is compared against, precisely enough to rebuild. For history: the window length, gap handling and minimum count, with every row the window reaches kept in 4.0_RAW_DATA (§7.4).
`relative_obs[].formula`	R	Python, or a proprietary statement.
`relative_obs[].disclosure`	R	open \| proprietary. Always stated.
`relative_obs[].citation`	o; R when proprietary	As for metrics, e.g. "Standard score (z-score), sample standard deviation".
`relative_value.description`	R	Including whether direction is kept or discarded.
`relative_value.formula`	R	Takes the relative observations, returns one number.
`relative_value.disclosure`	R	open \| proprietary. Always stated.
`elevation.rule`	R	Text or expression. A reader must be able to apply it by hand.
`elevation.order`	R	descending \| ascending.
`elevation.max_objects`	o	Optional cap on `2.0_VALENCE.md`. The format sets no floor or ceiling on how many objects are elevated; if you declare a cap, `2.0_VALENCE.md` frontmatter must carry `max_objects` and `elevated_count` (§8).

complexity (§13)

complexity:
  raw:        { n: <rows in 4.0_RAW_DATA>, p: <columns> }
  compute:    { n: <instances computed over>, p: <input columns + metrics + rel_obs + relative_value> }
  perception: { n: <objects in 3.0_PERCEPTION.md>, p: <metrics + rel_obs + relative_value> }
  valence:    { n: <objects in 2.0_VALENCE.md>, p: <rel_obs that promoted them> }

The gap between compute and perception tells a reader how much computation stands behind the reported values.

1.1_LOG.md (§6)

Date headings ## YYYY-MM-DD, newest first. Entries lead with **Report**, **Data**, **Contract**, **Correction** or **Initialization**. Every change to a formula, relative observation, relative value or elevation rule requires a **Contract** entry. A one-off report may hold a single entry.

Observation objects (§7) — both 2.0_VALENCE.md and 3.0_PERCEPTION.md

One ## heading holding the id, then one fenced YAML block (§7.1).

Field		Notes
`id`	R	`<metric>/<subject>/<report_date>`; drop subject when there is only one. Never positional. Unique within its file.
`metric`	R	Declared in `1.0_INDEX.md`.
`subject`	r	The entity described. Omit when the metric has one subject.
`report_date`	R	The date the value describes.
`value`	R	Number or string.
`unit`	R	Spell it out: percent, percentage points, USD, minutes. For a unitless value, say what it is: count, ratio, label.
`observations[]`	R	One entry per declared relative observation: `{rel_ob, value, note}`. Extra keys (window, n, mean, std, percentile) are legal and make the comparison checkable.
`relative_value`	R	The contract's relative value. null when it cannot be computed — never 0. Null objects sort last.
`elevated`	R in perception	Follows from the elevation rule.
`rank`	R in valence	1 = highest. Objects with a null `relative_value` rank last.
`perception_ref`	R in valence	The id of the matching perception object.
`trust.disclosure`	R	open \| proprietary.
`trust.formula`	R when open	Echoes `1.0_INDEX.md` exactly.
`trust.statement`	R when proprietary	How the method may be cited.
`trust.track_record`	o	Historical hit rate of elevated values — the substitute for an inspectable formula (§11.3).
`trust.resource`	o	Path to a longer implementation shipped in the folder.
`verify.source`	R	The file declared in `raw_data.files` that the value was computed from. In a `4.0_RAW_DATA/` directory, the file's path within it (`4.0_RAW_DATA/transactions.csv`) — the only place a reader learns which table an object used.
`verify.rows`	R	Selector on the key columns: a value, a list, or `{from, to}`.
`verify.columns`	R	Every column the formula read, from every file it read.
`verify.args`	R when the mapping is not evident	`{<argument>`: `{column, source, rows}`} for every argument of the formula. Required when any argument is not named after a column in `verify.columns`, when `verify.rows` selects more than one row, or when the formula reads more than one file. source defaults to `verify.source`; name another declared file for a joined table. Each rows selects on its own file's key columns, narrowing `verify.rows` on shared keys (omitted shared keys are inherited); several matching rows pass a list ordered by the key.
`verify.notes`	o, but R in substance	Any missing, imputed, excluded or corrected input, and how it was handled. A value computed around a gap with no note is not conformant (§7.4).

2.0_VALENCE.md frontmatter (§8)

observer_id (R), report_date (R), elevation_rule (R, echoing the contract), object_count (R, may be 0), generated (r), and, when the contract declares elevation.max_objects, max_objects (R, echoing the contract) and elevated_count (R, objects in 3.0_PERCEPTION.md with elevated: true). object_count then equals the smaller of the two, and the list was truncated exactly when elevated_count exceeds object_count. object_count: 0 is valid and meaningful: nothing met the threshold.

3.0_PERCEPTION.md frontmatter (§9)

observer_id (R), report_date (R), object_count (r), generated (r). Every declared metric needs at least one object here; every object needs elevated; order objects in a single list by relative_value descending, across all metrics, nulls last.

Entry files (§3.4.3)

README.md and AGENTS.md byte-identical, type: OBSERVER Entry, a navigation block with layer: entry, entry: 1.0_INDEX.md, down: 1.0_INDEX.md and no up, a statement that they are identical copies, a link to the OBSERVER Format specification, the reading order, and the raw data reading notice. CLAUDE.md may be a third identical copy; the statement then names all three.

The raw data reading notice (§3.4.4), verbatim

4.0_RAW_DATA.<ext>: <rows> rows × <columns> columns. Trust verification with select columns and rows only. Full data set only intended for full reading when verification of values reported in 2.0_VALENCE.md and/or 3.0_PERCEPTION.md is explicitly requested by the user or programmatically mandated by the assigned workflow.

When the raw data is included it must appear in raw_data.reading_notice, in the navigation.note of 3.0_PERCEPTION.md, and in the entry files. When it is referenced, it appears only in raw_data.reading_notice, naming the URI; when it is withheld, raw_data.withheld_reason takes its place. Generate it once, from the table's real shape, and insert it wherever it is required.

For a 4.0_RAW_DATA/ directory of several files, the first sentence describes the directory, and each object's verify.source identifies its table:

4.0_RAW_DATA/: <files> files; each object's verify.source names the file it was computed from, and raw_data.files gives each file's rows and columns. Trust verification with select columns and rows only. [...]

references/*.md (§3.1)

Any .md file under references/ carries type: OBSERVER Reference and a navigation block: layer: reference, entry: 1.0_INDEX.md, up: 1.0_INDEX.md, no down, and a note saying what the file supports. Code files there (.py or other) carry no frontmatter.