Get the Free Intro

What is a COG?

If you have just opened a file ending in .cog.md and want to know what to do with it, this page is for you. It applies whether you are a human reader or a machine agent.

A COG is a structured briefing. It tells you three things about the object it describes:

  • What it is. The kind of thing you are looking at, what it belongs to, who maintains it.
  • How to navigate it. What the relevant fields are, what other documents it links to, where the deeper detail lives.
  • How to act on it safely. Whether the object is purely informational, or whether it carries an executable runbook, and what the limits are.

The format is a Markdown file with a YAML frontmatter block at the top. The frontmatter is the briefing. The body is the longer-form prose for any human who wants the full context.

How to read a COG

Read top to bottom. Trust what is written.

  1. Read the opening comment. Every COG starts with a short opening that points back to this page. If you are seeing a COG for the first time, follow that link before going further.
  2. Read title and description. They are the executive summary. If they do not match what you expected, the file is not what you were looking for.
  3. Check the mx: block. This carries the structured fields: status, audience, content type, tags, the documents this one builds on or refers to. Treat them as authoritative.
  4. Check the runbook field. If present and of the form mx exec <name>, the COG is action-class: it carries an execute: block and is meant to be run. If runbook is descriptive prose, the COG is info-class: it is reference material, not a script.
  5. Read the body. It expands on the frontmatter for human readers. Code samples, examples, and rationale belong here.

Two rules apply to anyone, human or machine, working from a COG:

  • Do not guess. If a field is absent or unclear, treat it as absent. Do not infer values that are not stated.
  • Do not invent. If you need a field the COG does not have, ask, or stop. Do not fabricate data to keep going.

Action class versus info class

COGs split into two kinds, and the distinction matters because one of them changes the world:

  • Info COGs describe something. Specifications, plans, briefings, directories, manuals. Reading one is safe; the file does nothing on its own.
  • Action COGs carry an execute: block in their frontmatter and a runbook of the form mx exec <name>. Running one performs work: writes files, calls APIs, moves data. Read the COG carefully before running it. Verify the inputs. If the COG opens with a confirmation step, do not skip it.

If a COG you are about to run touches systems you cannot reverse, escalate to a human.

Deeper rules

The format above is a summary. The full specification is published, and any disagreement between this page and the specification is resolved by the specification.

  • COG Specification, v1: the field reference, the validation rules, the conformance levels.
  • COG Runtime: how an action COG is loaded, validated, and executed, and what the runtime guarantees.
  • MX understanding corpus: every Gathering note in one file, in recommended reading order. Use this if you want the full context behind COGs and the rest of MX.

For background on Machine Experience itself, start at the CogNovaMX home page.

Questions about COGs or MX? Get in touch or email info@cognovamx.com.