agentleFS
ChindanaiNaKubChindanaiNaKub/openthought/.claude/skills/coherence-check/SKILL.md

coherence-check

Skill0 starsChanged 4 months agoMITView on GitHub

Run the coherence checks over the intent graph and answer the judgment queue — find work standing on abandoned premises, plans that were never decomposed, stories that restate their parent, goals whose measure nothing addresses, and artifacts that are active on paper but dead in practice. Use when the user asks what's stale, what's drifted, what to clean up, whether the plan still holds, or after editing anything under intent/.

2 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions2 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 2

    1. lukasrepublic/agentic-foundry★ 1same name
    2. crfldrxyz/AuthorOps-Skills★ 0same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository3 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 3 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    redundant-overlap: do two siblings state the same intent twice?

    line 62
  2. Distinctive:

    Rephrasing is not always copy-paste: If the child added a decision, whether a mechanism, a constraint, or a boundary the parent left open, …

    line 95
  3. Very specific:

    Check the repo before flagging presupposed-capability: Search for the thing first.

    line 99
  4. Distinctive:

    Do not dump the raw output.

    line 105
  5. Distinctive:

    If everything is clear, say so in a line.

    line 113

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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

Coherence checks

Two tiers. Deterministic rules are pure functions over the graph and run instantly. Judgment checks need a reader, which is you, and their answers are cached by content hash so an unchanged pair is never judged twice.

Tier 1: deterministic

coherence check                   # everything, human-readable
coherence check --json            # machine-readable
coherence check --severity warn   # this severity and worse
coherence check --no-judgment     # skip cached verdicts

(Commands assume coherence on PATH; a repo may vendor it at bin/coherence instead. Use whichever exists.)

Exit code 1 means at least one block-severity finding. The thirteen rules:

checkfires when
dead-linka parent: or serves: points at an id that doesn't exist
orphannon-root artifact with no parent, so nothing connects it to the mission
illegal-parentthe level chain is broken (a story hanging off a bet)
duplicate-idtwo files claim the same id
duplicate-singletonmore than one live mission
stale-premiselive work whose ancestor is dropped or done
lifecycle-contradictiondone artifact with live children or unticked criteria
decomposition-gapactive bet/goal/project with no children, a sentence rather than a plan
coverage-gapa user or problem nothing serves
unrealized-commitmentdone story whose code: globs match no files
priority-inversionchild ranked more urgent than its parent
zombieactive for 30+ days without a touch
plan-stalenessparent untouched 60+ days while 2+ descendants moved recently

Recency uses git commit dates when available and file mtime otherwise.

Tier 2: judgment

coherence queue              # unanswered tasks, human-readable
coherence queue --json       # the same as structured tasks
coherence queue --limit 5    # work through them in batches

Each task gives you a hash, a check, the subject artifacts with their paths, and the question. Read the actual files. The task carries ids and titles rather than bodies, and judging from a title is how you produce confident nonsense.

The five judgment checks:

  • contradiction: does the child pull against the parent it descends from? A real conflict in direction, not merely narrower scope.
  • copy-paste: does the child restate the parent instead of decomposing it? Flag only when no new decision was made at this level.
  • redundant-overlap: do two siblings state the same intent twice?
  • orphaned-metric: a goal declares a measure:; does anything below it plausibly move that number?
  • presupposed-capability: does this plan assume something that neither exists in the repo nor is planned anywhere in the graph?

Answer by piping JSON to verdict:

echo '[
  {"hash":"84e60bc89340c6f1","check":"copy-paste","verdict":"clear"},
  {"hash":"aace92facacd818b","check":"orphaned-metric","verdict":"flag",
   "note":"goal-fast-recall measures time-to-reconstruct, but every story under it builds checks and nothing measures the time",
   "fix":"add a story that times three cold branches, or drop the measure"}
]' | coherence verdict

verdict must be clear or flag. Flagged verdicts then show up in coherence check as ordinary findings, with your note as the message and fix as the suggested action. Write those two fields for someone reading them cold in a month, not as a note to yourself.

Judging well

Default to clear. A flag costs the user attention. The value of this system collapses if it cries wolf, and a solo builder will delete a noisy checker within a week. Only flag when you can state the specific conflict in one sentence.

Scope difference is not contradiction. A parent saying "make onboarding fast" and a child saying "cache the session token" are not in conflict. That is decomposition working correctly. Contradiction means the child cannot succeed without the parent being wrong.

Rephrasing is not always copy-paste. If the child added a decision, whether a mechanism, a constraint, or a boundary the parent left open, it decomposed. Flag only when you could delete the child and lose no information.

Check the repo before flagging presupposed-capability. Search for the thing first. An assumption that turns out to be already built is the most annoying possible false positive.

Reporting to the user

Do not dump the raw output. Lead with what is worth acting on:

  • block findings first. These are broken references and orphaned work, and they are always real, because they are mechanical.
  • Then the judgment flags, because those carry actual reasoning.
  • Group zombie and coverage-gap findings. A solo builder with six of them has one decision to make, not six.

If everything is clear, say so in a line. Do not manufacture concern.

Related: intent-graph for authoring, ship-check for the pre-commit gate.

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.