audit-docs

Skill: Document Governance Audit (Audit Docs)

Purpose

Integrate the current state of document governance in a read-only manner, output a unified audit report and action roadmap, without performing structural changes or persisting standards.

Core Objective

Primary Objective: Produce a directly executable governance audit report (issues, priorities, routing), rather than directly modifying the repository.

Success Criteria(all must be satisfied):

✅ Read-only assessment orchestration corresponding to the completed mode
✅ Core findings and risk priorities have been summarized
✅ Clear next-step skill routing has been output
✅ A single unified report has been generated docs/calibration/audit-docs.md
✅ No write operations such as organizing, migrating, or persisting standards have been performed

Acceptance Test: Can the team decide "which skills to invoke next" based solely on the report, without worrying about the repository being implicitly modified?

Scope Boundaries

This skill is responsible for：

Orchestrating read-only assessment skills by mode
Aggregating scores, risks, and action priorities
Generating a unified governance report

This skill is not responsible for：

Creating or updating standards files (define-docs-norms）
Repository organization or file migration (tidy-repo）
Automatically accepting and applying any modifications

Handoff Point: After the report is completed, leave it to the user to choose whether to execute creation/organization-type skills.

Use Cases

New project governance baseline check
Pre-release governance audit
Documentation gate before PR merge
Periodic governance health check

Behavior

Stage 0: Norms Resolution (new in v2.1)

Implemented per specs/artifact-contract.md §8 Runtime Norms Resolution Protocol §8.2 / §8.3 / §8.5: if the project norms declare audit-docs for artifact_type path_pattern, use the project value; otherwise fall through to the skill default (docs/calibration/audit-docs.md). This skill is afixed-path governance output(orchestrator role), and only uses the path_pattern override mechanism; the dependent sub-skills each execute their own Stage 0.

Mode Definition

quick: only assess-docs(core assessment)
full：assess-docs + assess-docs-links + assess-docs-ssot
code-review：assess-docs + assess-docs-code-alignment

Execution Steps

Pre-check: git repository accessible, docs path readable
Norms check: if docs/ARTIFACT_NORMS.mdis missing, only record the risk and route discover-docs-norms/define-docs-norms
Execute read-only assessment skills by mode and collect outputs
Aggregate scores (structure, readiness, links, SSOT, code alignment)
Generate docs/calibration/audit-docs.md

Input & Output

Input

Project path (default CWD)
Mode:quick|full|code-review
Optional code-diff(for code-review）

Output

docs/calibration/audit-docs.md
Referenced downstream reports (by mode):
- docs/calibration/doc-assessment.md
- docs/calibration/doc-link-health.md
- docs/calibration/ssot-integrity-audit.md
- docs/calibration/code-doc-alignment.md

Restrictions

Hard Boundaries

Do not execute tidy-repo --apply or equivalent rewrite operations
Do not execute define-docs-norms persistence
Do not automatically accept norms derivation results

Skill Boundaries

Do not do these (other skills are responsible)：

Norms discovery:discover-docs-norms
Norms persistence:define-docs-norms
Repository cleanup:tidy-repo

Self-Check

Mode-to-orchestration mapping is correct
Downstream report conclusions have been aggregated
Priority roadmap has been output
No structural/specification writes were triggered
Audit report has been persisted to disk

Examples

Example 1: full audit

Execute:assess-docs + assess-docs-links + assess-docs-ssot
Output:audit-docs.md + routing suggestions

Example 2: code-review audit

Execute:assess-docs + assess-docs-code-alignment
Output: PR-focused documentation gate suggestions

Appendix: Output Contract

This skill is a read-only audit aggregator that produces a unified report:

Element	Format	Required Fields	Path Pattern
Report body	Markdown	front-matter; sections: Executive Summary / Sub-audit Aggregation (assess-docs / assess-docs-links / assess-docs-ssot / assess-docs-code-alignment) / Priority Actions / Skill Routing	docs/calibration/audit-docs.md
Priority Actions	Table	rank / issue / target_artifact / recommended_skill / rationale	"Priority Actions" section
Skill Routing	List items	skill_id / invocation_hint / scope / expected_output_artifact	"Skill Routing" section
Machine-readable block	YAML fenced `yaml audit_summary:`	counts, top_actions[] each item contains rank/skill/artifact	End of report