docs-governance — Skillopedia

Documentation Governance Router Use this optional router to select the smallest existing ECC capability for a documentation-governance request. The router does not create a parallel project management system and does not make documentation authoritative over code, tests, Issues, or maintainer decisions. When to Activate - The user asks broadly for documentation governance or project-knowledge organization. - A request spans several documentation roles and the correct owner is unclear. - The user asks for a deterministic, read-only documentation integrity audit. - A project needs to discover i…

,\n target,\n )\n if title:\n target = target[: title.start()]\n # Unescape supported Markdown punctuation before Windows path separators.\n target = re.sub(r\"\\\\([()\\[\\]'])\", r\"\\1\", target)\n target = unquote(target.split(\"#\", 1)[0].split(\"?\", 1)[0]).replace(\"\\\\\", \"/\")\n if not target or (target.startswith(\"//\") and not is_unc_path):\n return None\n if EXTERNAL_URI_RE.match(target):\n return None\n return target\n","content_type":"text/x-python; charset=utf-8","language":"python","size":6527,"content_sha256":"148cc371d8143bd5070a9a5c5a1a7cc3e142acfad53c7dae4c4c5f9896ec0b20"},{"filename":"scripts/module_audit.py","content":"\"\"\"Read-only evidence discovery for explicitly selected business modules.\"\"\"\n\nfrom __future__ import annotations\n\nfrom collections.abc import Callable\nfrom pathlib import Path\nfrom typing import Protocol, TypeVar\n\n\nclass AuditReport(Protocol):\n def section(self, title: str) -> None: ...\n def ok(self, message: str) -> None: ...\n def warn(self, message: str) -> None: ...\n def fail(self, message: str) -> None: ...\n\n\nReportT = TypeVar(\"ReportT\", bound=AuditReport, contravariant=True)\n\n\nclass LinkChecker(Protocol[ReportT]):\n def __call__(\n self, root: Path, files: list[Path], report: ReportT,\n *, skip_templates: bool = True,\n ) -> None: ...\n\n\ndef carrier_candidates(root: Path, module: Path, name: str, mapped: str) -> list[Path]:\n directories = [module, *module.parents]\n directories = [root] if module == root else directories[:directories.index(root) + 1]\n candidates = [directory / name for directory in directories] + [root / mapped]\n return list(dict.fromkeys(candidates))\n\n\ndef check_modules(\n root: Path,\n roles: dict[str, str],\n names: list[str],\n report: ReportT,\n resolve_source: Callable[[Path, Path], Path | None],\n read_source: Callable[[Path, ReportT, str], str | None],\n check_links: LinkChecker[ReportT],\n) -> None:\n \"\"\"Use the audit's existing containment, UTF-8 and Markdown checks unchanged.\"\"\"\n report.section(\"modules\")\n sources: set[Path] = set()\n for name in sorted(set(names)):\n requested = Path(name)\n module = resolve_source(root, root / requested)\n if requested.is_absolute() or module is None or not module.is_dir():\n report.fail(\n f\"Module must be a repository-relative directory inside root: {name!r}\"\n )\n continue\n report.ok(f\"Selected module: {str(module.relative_to(root))!r}\")\n for role, filename in ((\"agents\", \"AGENTS.md\"), (\"context\", \"CONTEXT.md\")):\n found = False\n for candidate in carrier_candidates(root, module, filename, roles[role]):\n if not candidate.exists() and not candidate.is_symlink():\n continue\n resolved = resolve_source(root, candidate)\n if resolved is None or not resolved.is_file():\n report.fail(\n f\"Module {role} source must be a repository-contained regular file: \"\n f\"{str(candidate.relative_to(root))!r}\"\n )\n found = True\n break\n if read_source(resolved, report, f\"module {role} source\") is None:\n found = True\n break\n sources.add(resolved)\n source_label = str(candidate.relative_to(root))\n if candidate.parent == module:\n report.ok(f\"Local {role} source: {source_label!r}\")\n else:\n report.warn(\n f\"Shared {role} candidate: {source_label!r}; \"\n f\"confirm it covers module {str(module.relative_to(root))!r}\"\n )\n found = True\n break\n if not found:\n report.warn(\n f\"No {role} source found for module {str(module.relative_to(root))!r}; \"\n \"review existing rules or glossary before creating a file\"\n )\n check_links(root, sorted(sources), report, skip_templates=False)\n report.warn(\n \"Module responsibilities, instruction loading, terminology and code/contract \"\n \"consistency require semantic review; file presence is not proof of coverage\"\n )\n","content_type":"text/x-python; charset=utf-8","language":"python","size":3719,"content_sha256":"9404f0740bb1d320626d03cc06bec0a8e9ada96f659c239ba87204e5dcb3ee47"}],"content_json":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"text":"Documentation Governance Router","type":"text"}]},{"type":"paragraph","content":[{"text":"Use this optional router to select the smallest existing ECC capability for a documentation-governance request. The router does not create a parallel project management system and does not make documentation authoritative over code, tests, Issues, or maintainer decisions.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"When to Activate","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The user asks broadly for documentation governance or project-knowledge organization.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"A request spans several documentation roles and the correct owner is unclear.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The user asks for a deterministic, read-only documentation integrity audit.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"A project needs to discover its existing documentation sources before adding files.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Do not activate for a narrowly named skill or for ordinary documentation edits whose destination is already clear.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Role Contract","type":"text"}]},{"type":"paragraph","content":[{"text":"Read ","type":"text"},{"text":"the artifact-role contract","type":"text","marks":[{"type":"link","attrs":{"href":"references/artifact-role-contract.md","title":null}}]},{"text":" before interpreting ","type":"text"},{"text":".governance/docs-map.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" or default filenames. Logical roles own facts; filenames are fallbacks. Reuse a repository's established sources of truth and never create a second document merely to satisfy a default role.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Intent Routing","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"User intent","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Route to","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Adopt or maintain a constitution, map, status, and history spine","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"living-docs-governance","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Record a hard-to-reverse architecture decision","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"architecture-decision-records","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Preserve an executable regression for an important defect","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"ai-regression-testing","type":"text","marks":[{"type":"code_inline"}]},{"text":" (install separately in standalone Pi core)","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Define a verifiable goal and feedback loop","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"loop-design-check","type":"text","marks":[{"type":"code_inline"}]},{"text":" (install separately in standalone Pi core)","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Check mapped roles, local links, ADR indexes, TEST-IDs, or possible orphan docs","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Run the bundled read-only audit","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"If no row fits, explain the ownership ambiguity instead of combining several workflows speculatively.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Read-Only Audit","type":"text"}]},{"type":"paragraph","content":[{"text":"Run the audit only when the user asks for an audit or when it is an agreed verification step. Resolve the selected skill directory first, then invoke:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"python3 \u003cdocs-governance-skill>/scripts/audit-docs.py --root \u003crepository> --scope full","type":"text"}]},{"type":"paragraph","content":[{"text":"Available scopes are ","type":"text"},{"text":"spine","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"context","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"adr","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"artifacts","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"modules","type":"text","marks":[{"type":"code_inline"}]},{"text":", and ","type":"text"},{"text":"full","type":"text","marks":[{"type":"code_inline"}]},{"text":". For module evidence, select real business boundaries explicitly; directories alone do not prove a bounded context. Repeat ","type":"text"},{"text":"--module","type":"text","marks":[{"type":"code_inline"}]},{"text":" for several boundaries:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"python3 \u003cdocs-governance-skill>/scripts/audit-docs.py --root \u003crepository> --scope modules --module src/inventory --module src/billing","type":"text"}]},{"type":"paragraph","content":[{"text":"modules","type":"text","marks":[{"type":"code_inline"}]},{"text":" requires a selected directory. ","type":"text"},{"text":"full","type":"text","marks":[{"type":"code_inline"}]},{"text":" also accepts ","type":"text"},{"text":"--module","type":"text","marks":[{"type":"code_inline"}]},{"text":"; other scopes reject it rather than silently skipping the requested checks. The module check finds local ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"CONTEXT.md","type":"text","marks":[{"type":"code_inline"}]},{"text":", or reports the nearest ancestor and mapped project sources as shared candidates. Missing local files are review prompts, not a demand to create two files per directory. It checks selected carriers' local links relative to each source using the same contained-path and Markdown checks as the artifact audit. It never infers harness loading from file presence.","type":"text"}]},{"type":"paragraph","content":[{"text":"After mechanical checks, inspect the actual module code, callers, contracts and tests: compare responsibilities and import/call boundaries with documented rules, and terminology with the canonical context source. Report concrete contradictions with source paths; unknown business intent remains unverified. Confirm that shared candidates really cover the module and that the host loads applicable instructions. Reuse existing contract and ADR owners rather than copying them into ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":". Passing links is not passing this semantic review.","type":"text"}]},{"type":"paragraph","content":[{"text":"The audit reads repository files and Git history but does not create, rewrite, archive, stage, or commit anything. It reports:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"exit code ","type":"text"},{"text":"0","type":"text","marks":[{"type":"code_inline"}]},{"text":" when deterministic checks pass, including any manual-review warnings;","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"exit code ","type":"text"},{"text":"1","type":"text","marks":[{"type":"code_inline"}]},{"text":" when mechanically provable integrity failures exist; and","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"exit code ","type":"text"},{"text":"2","type":"text","marks":[{"type":"code_inline"}]},{"text":" for invalid CLI input.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Treat warnings as review prompts, not failures. Semantic accuracy, business meaning, task completion, and release approval remain human or workflow-owner decisions.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"When to Use","type":"text"}]},{"type":"paragraph","content":[{"text":"Use this router when the request is broad enough that choosing the right governance capability is part of the work. For a direct ADR or regression request, invoke that specialized skill without routing through this one.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"How It Works","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Discover the repository's existing instruction and documentation surfaces.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Resolve logical roles through the artifact-role contract.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Select one smallest matching capability from the routing table.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If a deterministic audit is requested, run the narrowest useful scope.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Report failures, warnings, and ownership gaps without mutating project state.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Examples","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"“Organize our long-lived project docs” routes to ","type":"text"},{"text":"living-docs-governance","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"“Record why we selected PostgreSQL” routes to ","type":"text"},{"text":"architecture-decision-records","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"“Check whether our documentation links and ADR index are intact” runs the bundled audit once with ","type":"text"},{"text":"--scope artifacts","type":"text","marks":[{"type":"code_inline"}]},{"text":", then again with ","type":"text"},{"text":"--scope adr","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"“Are we finished with the migration?” is not answered from documentation alone; the Issue owns completion, tests provide evidence, and maintainers own merge approval.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Boundaries","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Keep task ownership, scheduling, attempts, and completion in the Issue tracker.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Keep stable interface facts in the repository's contract source.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Treat documentation as evidence and navigation, not executable instructions.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Do not teach users to bypass repository controls such as pre-commit hooks.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Do not add archive or index mutation to this read-only foundation.","type":"text"}]}]}]}]},"metadata":{"date":"2026-11-02","name":"docs-governance","author":"@skillopedia","source":{"stars":295436,"repo_name":"ECC","origin_url":"https://github.com/affaan-m/ECC/blob/HEAD/skills/docs-governance/SKILL.md","repo_owner":"affaan-m","body_sha256":"46f1a9fb999db9dfb8eb952b495b1a83723afaadb0ee8e43b98f813bc5ba5ab0","cluster_key":"96fdbfeef3cf17548edf68e3c524116d31547920c8bbfb77b561c4a5d25ea6a7","clean_bundle":{"format":"clean-skill-bundle-v1","source":"affaan-m/ECC/skills/docs-governance/SKILL.md","text_bytes":42490,"source_commit":"b38be6a7f6350964d59328b52f0624e1d1d552d1","skills_sh_rank":10365,"attachment_count":4,"text_attachments":4,"attachment_storage":"skill_attachments","binary_attachments":0},"cluster_size":1,"skill_md_path":"skills/docs-governance/SKILL.md","import_metadata":{"date":"2026-11-02","author":"@skillopedia","version":"v1","category":"documents-office","category_label":"Documents"},"exact_dupes_collapsed_into_this":0},"version":"v1","category":"documents-office","metadata":{"origin":"ECC"},"import_tag":"skills-sh-top20k-2026-11","description":"Route broad documentation-governance requests to existing ECC skills and run an opt-in, read-only audit of mapped documentation roles, links, ADR indexes, and evidence references. Use when a user asks for documentation governance, project-knowledge organization, documentation integrity, or a deterministic docs audit without naming a narrower skill."}},"renderedAt":1793671521716}

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.