agentleFS
jhutchison0jhutchison0/tacsop/.claude/skills/maintaining-the-common-operating-picture/SKILL.md

maintaining-the-common-operating-picture

Skill0 starsChanged 26 days agoApache-2.0View on GitHub

House rule for how a repo knows its own state. Two ideas and eight kernel rules, with the vocabulary (measurement, estimate, projection, horizon, surprise, gap) defined once. Mark every line as a measurement or an estimate; place every line by how it moves. Use when writing or reading any statement about what is true now, before measuring something that may already be measured, when designing a probe or a status report, and when deciding where a fact lives.

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 4 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Before measuring anything, to check whether the picture already holds it

    line 32
  2. Distinctive:

    Never report clean: Every declared quantity renders checked, with its fields, or unchecked, with a reason and no value, in one shape.

    line 86
  3. Distinctive:

    For a statement you are about to write or read: Ask which horizon it belongs to.

    line 108
  4. Distinctive:

    Every estimate names a replacing observation that is never collected, so rule 4 holds on paper and nothing ever moves.

    line 142

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Maintaining the Common Operating Picture

A statement about a repo's own state goes stale the moment it is written, and a stale sentence reads exactly like a fresh one. This skill is how a repo keeps a picture of itself that a reader, human or agent, can trust at a glance: what was measured, when, by what, how it is expected to have moved since, and what nobody can see yet. The product is a common operating picture: one display over the data every reader shares, never a paragraph somebody maintains.

It counters two failures, and they are symmetric. An estimate used where a measurement was needed: a plan said three hosts were unswept, the sweep was done, and a day went to arguing a gate already met. A measurement made where one already existed: one quantity measured four times in a day with no reference run, so four numbers competed and none was the holding.

Scope, stated once. verifying-claims governs a claim about what this turn changed; this skill governs standing facts this turn did not touch, and where they live. shift-left-testing governs how code is tested; this skill governs how the repo's state is known.

Philosophy: Mark where every line came from; place every line by how it moves.

When to Use

  • Writing or reading any statement about what is true now: a host, a count, a schedule, a coverage figure, a version, a branch
  • Before measuring anything, to check whether the picture already holds it
  • Designing a probe, a status document, a status command, or the session-start summary
  • Deciding where a fact lives: config, a plan, a task list, a record, or a generated report
  • Reviewing a plan whose gate states a measurement instead of naming a command

Vocabulary

Defined once, here and in DOCTRINE.md. A document that uses one of these words for something else is wrong, not the glossary.

TermMeansNever means
assessmentthe process: monitor, evaluate, recommenda line in the picture
measurementa line a collector produced at a time, carrying subject, universe and shapea number without those fields
estimatea line produced by judgment or projection, carrying a range and a basisa point
projectionthe estimate the picture derives from the last measurement and the quantity's motiona measurement
horizonthe age at which a projection no longer serves the decision at handa fixed cadence
surprisea measurement outside its projection, or an absence at the scheduled timean error
gapa known unknown, with the collector that would close it and the decision it blocksa to-do
collectorwhatever produces measurements: a command, a probe, a test run, a listinga person's recollection
universewhat a collector enumerates; it is structurally blind to everything outsidethe whole system
picturethe rendered join of every module, generated, never hand-editeda status paragraph

The Kernel

Eight rules. The ambient copy lives in CLAUDE.md.

  1. The rendered picture is never hand-edited; its inputs may be. It is one display over the data every reader shares. A paragraph someone maintains is an estimate wearing a measurement's clothes.
  2. Every line is a measurement or an estimate, and an input or an outcome, and says which. A measurement carries its value, time, collector, the identity of what was measured, the universe searched, and its shape: exact, a bound with its direction, or an interval. An estimate carries a range, never a bare point, its basis, and the observation that would prove it wrong.
  3. Every quantity declares how it moves and what would be a surprise. Constant until a change event, drifting in a known direction, or scheduled. The picture shows the last measurement, its age, and the projection from the two, and flags a surprise. A measurement past its horizon stays a measurement, marked stale, never relabelled an estimate.
  4. Supersede in place, never overwrite. The old line keeps its place with a status mark and a pointer to what replaced it. Tests count unmarked lines only, so a superseded line cannot satisfy a never-empty rule.
  5. Gaps are listed, each naming its collector and the decision it blocks, and the list is never empty. An empty gap list is a finding about the staff, not evidence the system is clean. An estimate no collector could falsify is a gap, not an estimate.
  6. Read the picture before you measure or assert state. Re-measure when the projection's uncertainty exceeds what the decision needs, when the subject or the universe changed, or when a measurement surprised the projection; never for comfort. Two measurements that disagree with subject and universe named are a change event: record both, name the cause.
  7. One horizon per line, not per document. Current operations are measured by command. The running estimate is maintained. Plans are intent, and a plan's gate names the command that evaluates it. A record (a session doc, a review, an issue log) keeps every horizon and is never rewritten.
  8. Never report clean. Every declared quantity renders checked, with its fields, or unchecked, with a reason and no value, in one shape. A picture with no observations says so in its header. A row of zeros is the most reassuring rendering of the least informative fact.

The two ideas behind the eight

Provenance (rules 2, 3, 4, 8): a line says where it came from, when, by what, over what universe, how it is expected to have moved, and what replaced it. A reader never has to parse prose to know whether a number was measured or guessed, or how old it is.

Placement by motion (rules 1 and 7, and the layout in ADOPTION.md): a fact lives with things that age at its rate. A measured fact lives in a generated report with a time on it. An estimate lives in a maintained document with a basis and a replacing observation. Intent lives in a plan. History lives in a record. A document that mixes them ages at the rate of its fastest line, and its slowest line then reads as stale or its fastest reads as current.

Rules 5 and 6 are what a reader does with the picture: name what it cannot show, and consult it before adding to it.

Procedure

For a statement you are about to write or read. Ask which horizon it belongs to. If a reader would act on it today, it is a measurement or an estimate and must carry the fields in rule 2; if it is history, it is prose and stays where it is. Then ask whether the picture already holds it (rule 6). If it does and nothing in rule 6 has fired, cite the holding with its age. If it does not, measure, and the measurement enters the picture through its module.

For a probe. Declare its universe in its own docstring, and the one thing it is structurally blind to. It reads; it never writes into the universe of any probe, including its own. Its output takes the two-shape contract of rule 8: checked with every field, or unchecked with a reason and no value key, same punctuation either way, so a test can assert the absence by name. Ship it with a gap-register row (rule 5) and a test that fails when the probe disappears or the row does.

For a quantity entering the picture. Declare in config, not in code: its motion (constant, drifting, scheduled), its horizon per decision that reads it, and its surprise condition. The renderer compares age to horizon and prints the verdict beside the age.

For a plan. A gate is a predicate in one of three forms, in order of preference: executable (the command and the output that satisfies it), observable (the artifact and the property, when no command exists), or blocked (nothing can evaluate it; name the instrument that would have to exist, which is a gap by rule 5). A measurement inside a gate is a defect: it started ageing the moment the plan was written.

For the session-start summary. It is the picture's human view. Each line is tagged with its horizon, and each measured line carries its age and its verdict. A line the renderer could not produce renders unchecked with the blocker, never blank and never copied from the previous session.

What makes this skill decorative

Each of these has been observed in a repo that had the rules on paper.

  • The mark exists but nobody reads it: agents copy the line and drop the mark.
  • Marks are applied by the author after the fact, to a line already acted on.
  • Every estimate names a replacing observation that is never collected, so rule 4 holds on paper and nothing ever moves.
  • The gap list is padded with trivia to stay non-empty. Rule 5's two required fields are the defence: a gap with no collector and no blocked decision is not a gap.
  • The picture renders but no command reads it; the reporting commands stay sources.
  • The skill's own EXAMPLES.md is the only place the marks appear.

Success criterion

OPEN. The shape is traversing-the-knowledge-base's five-session bet, and the window opens when the first repo renders a picture through this skill; the numbers are set then, not now. The candidate measures:

  • M1 uptake: at least 3 of 5 session docs carry a COP: line naming the picture command run, the newest measurement's age, and the count of unchecked or stale lines.
  • M2 integrity: the join test stays green and each run's result is recorded: a picture with no observations renders no clean line; the gap list is non-empty with both fields; every estimate names a replacing observation.
  • M3 value: at least one case where the picture prevented either failure in the opening paragraph, verified at window close by someone other than the line's author.

The outcome matrix and the human decision each cell triggers are copied from that skill once the window opens. No cell triggers automatically.

Sidecar Files

  • DOCTRINE.md: the terms, their doctrinal sources, the three horizons, the convoy example that fixes the decay model, and what this skill is not.
  • EXAMPLES.md: the cases that earned each rule, with the specifics removed.
  • ADOPTION.md: where things live, the degenerate cases (one box, fresh clone, no observations), the commands and documents a repo rewrites, the first slice, and the measurement requirements for agents.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.