assess-docs-code-alignment

Skill: Assess Docs Code Alignment

Purpose

Detect whether code changes have corresponding documentation updates, and output an actionable documentation supplement checklist.

---

Core Objective

Primary objective: Infer the documentation that needs updating from the code diff, and report uncovered gaps.

Success criteria：

1. ✅ Code diff scope parsed
2. ✅ Code regions mapped to documentation regions
3. ✅ missing/partial/covered alignment results output
4. ✅ Actionable supplement recommendations produced
5. ✅ Written to docs/calibration/code-doc-alignment.md

---

Scope Boundaries

This skill is responsible for: Alignment analysis between code changes and documentation changes. This skill is not responsible for: Documentation standards assessment (assess-docs), link graph (assess-docs-links）、SSOT（assess-docs-ssot）。

---

Use Cases

• Documentation gate before PR merge
• Code change review before release

---

Behavior

Phase 0: Norms Resolution (new in v1.1)

Implemented per specs/artifact-contract.md §8 Runtime Norms Resolution Protocol §8.2 / §8.3 / §8.5: read project norms; if code-doc-alignment artifact_type's path_patternis declared, use the project value; otherwise fall through to the skill default (docs/calibration/code-doc-alignment.md). This skill is afixed-path governance output, using only the path_pattern override mechanism.

Phase 1: Code-Documentation Alignment Assessment

1. Get diff:git diff <base>...HEAD --name-status --diff-filter=MAD
2. Categorize code change regions
3. Infer "documentation that should be updated" based on mapping rules
4. Compare documentation changes in the current branch
5. Output findings and recommendations

---

Input & Output

Input

• base or diff range
• docs root path (optional)
• Region mapping rules (optional)

Output

• docs/calibration/code-doc-alignment.md

---

Restrictions

• Do not modify code or documentation files
• Only output assessments and recommendations

---

Self-Check

• diff parsed
• gap list and recommendations produced
• single alignment report written

---

Examples

• src/api/auth.py modified but docs/architecture/api.md not updated -> high

---

Appendix: Output Contract

This skill produces a Code-Doc Alignment Report:

Element	Format	Required fields	Path pattern
Report body	Markdown	front-matter; sections: Summary / Alignment Gaps / Recommended Documentation Updates	docs/calibration/code-doc-alignment.md
Gap entries	List items	id / category（api_drift / config_drift / behavior_drift / removed_feature）/ code_location / doc_location / evidence / suggested_update	"Alignment Gaps" section
Machine-readable block	YAML fenced yaml alignment_gaps:	gaps[] each item contains id/category/severity/code_ref/doc_ref	End of report