What counts as a 'stated state'?

Any declared status, state description, or phase in the documents that should reflect reality.

Which document should be authoritative?

Assign authorship per concept (e.g., ADRs or design decisions) and prefer the document that originally defines the concept.

How do you resolve a finding?

Specify the inconsistency, name exact locations, designate authoritative source, and propose a concrete edit with precise wording and location.

coherence

npx machina-cli add skill rana/yogananda-skills/coherence --openclaw

Files (1)

SKILL.md

2.1 KB

Read all project markdown documents (CLAUDE.md, CONTEXT.md, DESIGN.md, DECISIONS.md, ROADMAP.md, and any others present) to ground in the project's actual state.

Coherence Audit

Systematically check:

Cross-reference integrity — Every identifier (ADR-NNN, DES-NNN, Phase N, or whatever conventions the project uses) referenced in one document exists in its canonical location. No dangling references. No stale identifiers.
Stated vs actual state — "Current state" sections match what's actually implemented. Phase statuses agree across documents. Counts (ADR count, phase count) are accurate.
Consistent terminology — The same concept uses the same term everywhere. No synonym drift.
Bidirectional links — If Document A references Document B section X, does B's section X make sense in that context? Are there references that should exist but don't?
Narrative coherence — Do the documents tell a unified story? Or have they drifted into contradictions through incremental edits?

Focus area: $ARGUMENTS

For every finding, state:

What the inconsistency is (with exact locations in both documents)
Which document should be considered authoritative
The specific edit to resolve it

Present findings as an action list. No changes to files — document only.

Output Management

Hard constraints:

Segment output into groups of up to 8 findings, ordered by severity of inconsistency.
Write each segment incrementally. Do not accumulate a single large response.
After completing each segment, continue immediately to the next. Do not wait for user input.
Continue until ALL findings are reported. State the total count when complete.
If the analysis surface is too large to complete in one session, state what was covered and what remains.

What questions would I benefit from asking?

What am I not asking?

Source

git clone https://github.com/rana/yogananda-skills/blob/main/skills/coherence/SKILL.mdView on GitHub

Overview

Coherence auditing ensures all project documents tell a consistent story. It validates cross-reference integrity, matches stated vs actual state, maintains consistent terminology, and checks bidirectional links and narrative alignment. This helps prevent drift after edits or changes.

How This Skill Works

The skill scans project markdowns (CLAUDE.md, CONTEXT.md, DESIGN.md, DECISIONS.md, ROADMAP.md, and related files), then verifies identifiers exist in canonical locations, confirms states align with implementation, checks terminology consistency, and evaluates bidirectional references. It outputs action items with authoritative sources and suggested edits.

When to Use It

After major project document changes to verify no drift
When onboarding new team members who need a coherent document baseline
When a new identifier (ADR-NNN, DES-NNN, etc.) is introduced or renamed
When reports or milestones indicate inconsistencies across documents
During periodic governance audits to ensure narrative coherence

Quick Start

Step 1: Gather CLAUDE.md, CONTEXT.md, DESIGN.md, DECISIONS.md, ROADMAP.md and related docs
Step 2: Run a coherence check (manual checklist or tool) to validate references, states, terminology, and bidirectional links
Step 3: Record action items with exact locations, assign owners, and propose edits

Best Practices

Designate authoritative sources for each concept (e.g., ADRs define decisions, ROADMAP reflects progress)
Maintain a central glossary and ensure all terms map to the same definitions
Enforce consistent identifier patterns and avoid synonyms
Require bidirectional links: references must have valid targets and contexts
Document findings as action items with exact locations and proposed edits

Example Use Cases

Example 1: ADR-NNN referenced in DESIGN.md but missing in DECISIONS.md
Example 2: Phase 2 status differs between ROADMAP.md and CONTEXT.md
Example 3: Terminology drift where 'prototype' and 'beta' are used inconsistently
Example 4: A bidirectional reference from CLAUDE.md to CONTEXT.md points to a non-existent section
Example 5: Narrative inconsistency where the project goal described in CONTEXT.md conflicts with the roadmap

Frequently Asked Questions

Add this skill to your agents