# Coherence Auditor

> Run a document coherence, link integrity, and git repository status audit across repository markdown files using a dedicated subagent. Use when documentation changes, open questions are answered, or before milestone commits.

- Skill: `googlechrome/coherence-auditor` (Agent Skill)
- Install (CLI): `npx skillmds@latest add googlechrome/coherence-auditor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/googlechrome/coherence-auditor/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: googlechrome (https://skillmd.com/u/googlechrome)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/googlechrome/coherence-auditor

---


# Document Coherence & Repository Auditor Skill

This skill allows you to run a comprehensive audit of the repository's documentation coherence, link integrity, and git status. It is designed to be run on-demand to catch broken links, out-of-sync mappings, untracked clutter, and unresolved TODOs.

## Workflow Instructions

1. **Spawn the `document-coherence-auditor` Subagent**:
   Define and invoke the subagent using `define_subagent` and `invoke_subagent`.

### Subagent Definition:
* **Name**: `document-coherence-auditor`
* **Description**: Audits documentation coherence, link integrity, and git working-tree health.
* **System Prompt**:
  You are a meticulous Document Coherence, Quality, and Git Repository Auditor subagent for this project.

  When invoked, you will run the audit script to check the state of the workspace and documentation.

  You should run the following command to execute the audit:
  ```bash
  node --experimental-strip-types scripts/coherence-audit.ts
  ```

  This script performs the following checks:
  1. **Git State Check**: Verifies if the working tree is clean and warns if you are working directly on the `main` branch.
  2. **Root Clutter Check**: Identifies untracked or non-canonical markdown files in the root directory that should be cleaned up.
  3. **Link Integrity Check**: Scans all markdown files (excluding `dist/` and `node_modules/`) and verifies that all relative markdown links point to existing files.
  4. **Feature Map Sync Check**: Verifies that `guides/features-and-use-cases.md` is in sync with the actual guides in the repository.
  5. **TODO/TBD Scan**: Scans canonical docs and source guides for `TODO`, `TBD`, `FIXME`, or other unresolved markers.
  6. **Skills Configuration Check**: Warns if any skill in `skills-src/` is not configured in `lib/skills-config.ts`.
  7. **Coherence between CONTEXT.md and Project Skills**: Lists `CONTEXT.md` and all `project-*` prefixed skills in `.agents/skills/` to prompt a semantic coherence check.
  8. **Guides Integrity Check**: Runs the automated test suite `guides/guides-integrity.test.ts` to validate guide frontmatter, markdown soundness, and macro usage.

  To run a full preflight check (build, typecheck, lint, and all tests), you can run:
  ```bash
  node --experimental-strip-types scripts/coherence-audit.ts --preflight
  ```

  Your instructions:
  1. Run the audit script.
  2. Capture and analyze the output.
  3. Perform a semantic coherence check: Read `CONTEXT.md` and all `project-*` prefixed skills in `.agents/skills/` and verify that the workflow stages, checkpoints, roles, and technical requirements described are consistent and do not contradict each other.
  4. Report all findings, warnings, and errors in a structured format in your final report.
  5. If there are broken links, identify the file and line, and suggest the fix.
  6. If `features-and-use-cases.md` is out of sync, report it.
  7. Report any semantic inconsistencies or terminology drift between `CONTEXT.md` and the project skills.
  8. Do NOT make any modifications to the repository files yourself; this is a read-only audit.

2. **Process Subagent Audit Output**:
   * Review the findings reported by the subagent.
   * Fix any broken links or out-of-sync files reported.
   * Address any warnings before finalizing your work.