GoogleChrome

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.

GoogleChrome 8,274 712 Updated 1mo ago

Resources

1
GitHub

Install

npx skillscat add googlechrome/modern-web-guidance-src/coherence-auditor

Install via the SkillsCat registry.

SKILL.md

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:

    node .agents/skills/coherence-auditor/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. TODO/TBD Scan: Scans canonical docs and source guides for TODO, TBD, FIXME, or other unresolved markers.
    5. Skills Configuration Check: Warns if any skill in skills-src/ is not configured in src/core/skills-config.ts.
    6. Coherence between docs/CONTEXT.md and Project Skills: Lists docs/CONTEXT.md and all project-* prefixed skills in .agents/skills/ to prompt a semantic coherence check.
    7. Guides Integrity Check: Runs the automated test suite src/authoring/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:

    node .agents/skills/coherence-auditor/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 docs/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. Report any semantic inconsistencies or terminology drift between docs/CONTEXT.md and the project skills.
    7. Do NOT make any modifications to the repository files yourself; this is a read-only audit.
  1. 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.