tsunami28/MindNova / .claude/skills/governance-check-graph
governance-check-graph
VerifiedValidate documentation and graph integrity across the repo: the AI-SDLC artifact graph (every artifact declaring a `story:` has a valid work-item key, a known phase, and `relates:` links that resolve) AND the documentation wiki (no orphan pages, no broken relative links, indexes in sync), and documentation house-style (no em-dash characters). Use when the user says "check the artifact graph", "validate the artifact links", "lint the docs", "are the doc links broken", "check the wiki", "check for em-dashes", before opening a PR that touches docs or graph artifacts, or as the governance-check-graph step. It runs the same scripts the CI gates run, so local results match the pipeline. Do NOT use to create or fix artifacts, tickets, links, or docs (that is elaboration-upsert-user-story / governance-enrich-ticket / governance-author-adr / create-upsert-documentation).
Check graph and docs-wiki integrity
Owned by the Lead persona (link integrity). Invoked as /governance-check-graph.
Validate that the repo's links are intact and its docs follow house-style - the artifact graph, the documentation wiki, and the no-em-dash rule - and explain any failures. This is the local face of the CI gates: it invokes the same shared scripts, so a clean local run means a clean pipeline run.
The conventions enforced are in docs/ai-sdlc/artifact-graph.md (the traceability graph) and
docs/ai-sdlc/docs-wiki.md (the documentation wiki). Read those for the schemas and rules.
Run it
Run the repository scripts (cross-tool: Claude Code, Copilot CLI, or a plain shell):
pwsh MindNova/toolsCheck-ArtifactGraph.ps1 # traceability graph
pwsh MindNova/toolsCheck-DocsWiki.ps1 # docs wiki: orphans + broken relative links
pwsh MindNova/toolsBuild-DocsIndex.ps1 -Check # docs wiki: index in sync with the pages
pwsh MindNova/toolsCheck-DocEmDashes.ps1 # docs house-style: no em-dash (U+2014)
Pass -RepoRoot <path> if you are not at the repository root. These are the same scripts wired (or,
for the docs-wiki checks, planned) into MindNova/pipelines/Common/code-analysis-pipeline.yml, so do
not reimplement the checks here; run them and interpret the output. To clear index drift, run
Build-DocsIndex.ps1 without -Check to regenerate the indexes.
What it checks
Artifact graph (Check-ArtifactGraph.ps1) - for every artifact under docs/, docs-functional/,
or specs/ that declares story: in front-matter:
storyis a valid work-item key (e.g.MN-42).phaseis present and one ofdiscovery | elaboration | create | mature | governance.- Each
relates.*repo path resolves to a file; each URL is well-formed. Artifacts withoutstory:front-matter are ignored (adoption is incremental).
Docs wiki (Check-DocsWiki.ps1 + Build-DocsIndex.ps1 -Check) - over docs/ and docs-functional/:
4. No orphan pages (every page is listed in its layer index or linked by another page; index.md,
README.md, and templates are exempt).
5. No broken relative markdown links (links shown inside code spans or fences are ignored).
6. The committed index.md files match what the generator would emit (no drift).
Docs house-style (Check-DocEmDashes.ps1) - over AGENTS.md, docs/, and docs-functional/:
7. No em-dash (U+2014) characters; the house style uses ' - ', commas, colons, or parentheses.
On failure
The scripts print file : reason per violation. Fix per the relevant convention:
- Artifact graph (
docs/ai-sdlc/artifact-graph.md): a validstory:key, a knownphase:, andrelates:paths that exist; if a relation points at something not yet in the repo, add it or correct the path. - Docs wiki (
docs/ai-sdlc/docs-wiki.md): repoint or create the target of a broken link; add an orphan page to its index or link it; for index drift, regenerate withBuild-DocsIndex.ps1. - Docs house-style: replace each flagged em-dash (the script prints
file:line) with ' - ', a comma, a colon, or parentheses.
Guardrails
- Read-only. This validates; it does not edit artifacts or create links. Fixing is a separate step.
- Keep the rule in the script (the shared source of truth), not duplicated in this skill, so the local check and the CI gate never diverge.
Next steps
- On a clean result, no further action.
- On a failure, fix with the owning skill and re-run: unresolved
relates:links ->/governance-enrich-ticket; a missing ADR backlink ->/governance-author-adr; a malformedstory:orphase:-> correct the artifact's front-matter; a broken doc link, orphan page, or index drift ->/create-upsert-documentation(regenerate the index and fix or repoint the links); an em-dash -> replace it with ' - ', a comma, a colon, or parentheses.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |