docgraph-drift-audit

DocGraph Drift Audit

Invocation — Claude Code: Skill("docgraph-drift-audit") | OpenCode / Codex: use triggers above.

Scans all indexed .md files and reports how well they conform to DocGraph conventions. Run after bulk content changes, after adding new docs, or when graph queries return unexpected results.

Execution

• Model: Haiku (scan) or Sonnet (fix suggestions)
• Effort: Low-Medium
• Advisor: Not required

---

Step 1: Get index state

docgraph_status

Record file count, node count, edge count, unresolved refs count. If unresolved refs > 5% of total edges, expect widespread broken-link findings below.

Locate the database and verify sqlite3 is available:

DB=$(find . -name "docgraph.db" -path "*/.docgraph/*" | head -1)
echo "DB: $DB"
command -v sqlite3 >/dev/null 2>&1 || echo "WARNING: sqlite3 not found — install with: brew install sqlite (macOS) or apt install sqlite3 (Linux). Steps 2a–2e require it."

---

Step 2: Scan drift categories

2a. No frontmatter

sqlite3 "$DB" "SELECT path FROM files WHERE has_frontmatter = 0 ORDER BY path"

PASS if count = 0 for ADR/plan/governance docs. Priority: HIGH for structured docs. LOW for README/changelog.

2b. No outgoing links — isolated docs

sqlite3 "$DB" "
  SELECT f.path FROM files f
  WHERE NOT EXISTS (
    SELECT 1 FROM nodes n
    JOIN edges e ON e.source = n.id
    WHERE n.file_path = f.path
      AND e.kind IN ('references','wikilinks_to','related_to')
  )
  ORDER BY f.path"

PASS if key docs have at least one outgoing link. Priority: HIGH if doc should relate to others. LOW for standalone entries.

2c. Broken links — unresolved refs

sqlite3 "$DB" "
  SELECT reference_text, reference_kind, COUNT(*) as cnt
  FROM unresolved_refs
  GROUP BY reference_text, reference_kind
  ORDER BY cnt DESC LIMIT 20"

PASS if count = 0. Broken links are graph bugs — HIGH priority always.

2d. No headings

sqlite3 "$DB" "
  SELECT f.path FROM files f
  LEFT JOIN nodes n ON n.file_path = f.path AND n.kind = 'heading'
  WHERE n.id IS NULL ORDER BY f.path"