SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsassess-docs

assess-docs

Writing & research

View repository

Updated 10-16 06:50

About this skill

Skill: Document Assessment (Assess Docs)

Purpose

Assess the core governance state of documentation in a single run: whether it complies with norms, whether evidence is sufficient to support planning, and how gaps should be minimally filled.

Core Objective

Primary Objective: Output an actionable documentation assessment report that clearly identifies compliance issues, layer readiness, and minimal remediation actions.

Success Criteria(all must be satisfied):

  1. ✅ Project norms parsed (docs/ARTIFACT_NORMS.md or default contract)
  2. ✅ Path/naming/front-matter compliance checks completed with findings provided
  3. ✅ Layer readiness scoring completed (strong/weak/missing)
  4. ✅ Gap priorities and minimal remediation plan produced
  5. ✅ Written to a single report docs/calibration/doc-assessment.md

Acceptance Test: Can the team, based solely on the report, clearly determine "what to fix first, what to fill in next, and who handles it"?

Scope Boundaries

This skill is responsible for：

  • Norms compliance checks (path, naming, front-matter)
  • Documentation layer evidence inventory and readiness scoring
  • Gap prioritization and minimal remediation plan

This skill is not responsible for：

  • Norms creation/update (use define-docs-norms）
  • Code-documentation alignment analysis (use assess-docs-code-alignment）
  • Link graph health analysis (use assess-docs-links）
  • SSOT intent conflict audit (use assess-docs-ssot）
  • Repository structure restructuring (use tidy-repo）

Handoff Point: After the core assessment report is complete, hand off to the corresponding split skill for specialized assessment based on the issue type.

Use Cases

  • Documentation readiness check before milestones
  • Quickly determine evidence completeness before planning
  • Documentation debt inventory and prioritization

Behavior

Phase 0: Norms Resolution + Scope Resolution (v4.1 update)

According to specs/artifact-contract.md §8 Runtime Norms Resolution Protocol , implement the path_pattern resolution for this skill's output (doc-assessment) + simultaneously parse the project norms being assessed as the assessment baseline:

  1. Resolve the docs root path
  2. Read project norms in the discovery order per §8.2 (prefer .ai-cortex/artifact-norms.yaml, then docs/ARTIFACT_NORMS.md); if neither exists, fall back to specs/artifact-contract.md default
  3. Read the doc-assessment for the artifact_type path_pattern in the project norms to determine the output path of this assessment report (default docs/calibration/doc-assessment.md); this skill produces fixed-path governance output
  4. Establish the target layer mapping (mission/vision/requirements/architecture/roadmap/backlog, etc.) for assessment in subsequent phases

Phase 1: Compliance Verification

  1. Scan Markdown within docs
  2. Validate path, naming, front-matter
  3. Form findings (location/category/severity/title/description/recommendation)

Phase 2: Layer Evidence Inventory

  1. Count document coverage by layer
  2. Determine evidence freshness and usability
  3. Mark each layer's status (strong/weak/missing)

Phase 3: Readiness Scoring

  1. Calculate layer scores and overall readiness (high/medium/low)
  2. Mark critical blocking layers

Phase 4: Minimal Remediation Plan

  1. Prioritize gaps by impact and effort
  2. Form a minimal action set (sequence, responsibility suggestions, target path)

Phase 5: Report Persistence

  1. Write docs/calibration/doc-assessment.md
  2. Output "core issues + recommended next-step skill routing"

Input & Output

Input

  • docs scope (default repository docs/）
  • optional layer mapping
  • optional target readiness level (medium|high）

Output

  • docs/calibration/doc-assessment.md
  • findings + readiness + minimum fill plan

Restrictions

Hard Boundaries

  • Do not perform repository structure write operations
  • Do not create or update docs/ARTIFACT_NORMS.md
  • Do not perform code diff, links graph, or SSOT deep audit

Skill Boundaries

Do not do these (other skills are responsible)：

  • Specification persistence:define-docs-norms
  • Code alignment:assess-docs-code-alignment
  • Links graph:assess-docs-links
  • SSOT audit:assess-docs-ssot

Self-Check

  • Specification source resolved (project specification or default contract)
  • Complete compliance findings output
  • Layer readiness scoring completed
  • Minimal remediation plan produced
  • Only the core assessment report is generated, with no specialized extension report

Examples

Example 1: Standard Core Assessment

  • Input: existing docs
  • Output:doc-assessment.md(including compliance + readiness + remediation plan)

Example 2: Low-Readiness Project

  • Input: only partial roadmap/backlog documents
  • Output: readiness=low, the primary action is to complete key layer documents

Appendix: Output Contract

This skill produces a document health assessment report:

Element Format Required Fields Path Pattern
Report Body Markdown front-matter (artifact_type=assessment / lifecycle=snapshot); sections: specification compliance / layered readiness scoring / minimal remediation plan docs/calibration/doc-assessment.md
Specification Compliance List items rule_id / artifact_path / status（pass/fail/n-a）/ evidence "Specification Compliance" section
Layered Readiness Table layer / score（0-3）/ missing_artifacts / next_action "Layered Readiness Scoring" section
Minimal Remediation Plan List items artifact_path / proposed_skill / priority / rationale "Minimal Remediation Plan" section