docs-health

Documentation Health Check

Audit custom element manifests for documentation completeness and quality using cem health.

Workflow

Phase 1: Run Health Analysis

Run cem health with JSON output to get structured scoring data:

cem health --format json

To filter to specific components or modules:

# Single component
cem health --format json --component my-button

# Specific modules
cem health --format json --module src/components/button.js

The JSON output has this structure:

{
  "modules": [
    {
      "path": "src/components/button.js",
      "score": 18,
      "maxScore": 20,
      "declarations": [
        {
          "tagName": "my-button",
          "name": "MyButton",
          "score": 18,
          "maxScore": 20,
          "categories": [
            {
              "id": "description",
              "category": "Description",
              "points": 5,
              "maxPoints": 5,
              "status": "pass",
              "findings": [...]
            },
            {
              "id": "attributes",
              "category": "Attribute Documentation",
              "points": 3,
              "maxPoints": 5,
              "status": "warn",
              "findings": [
                {
                  "check": "attribute 'variant' has description",
                  "points": 1,
                  "max": 1
                },
                {
                  "check": "attribute 'size' has description",
                  "points": 0,
                  "max": 1,
                  "message": "Add a description for attribute 'size'"
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "overallScore": 18,
  "overallMax": 20,
  "recommendations": [
    "my-button: Add a description for attribute 'size' (Attribute Documentation, +1 pts)"
  ]
}

Phase 2: Interpret Results

The health categories scored by cem health are:

Category	What it checks
description	Element has a description and summary
attributes	Every attribute has a description, type, and default
slots	Every slot has a description
css	CSS custom properties, parts, and states have descriptions
events	Every event has a description and type
demos	Element has demo links

Status values:

• pass (>=80%): Well documented
• warn (40-79%): Has gaps
• fail (<40%): Major gaps

Phase 3: Report

Present the results in a readable format. Use the JSON data to build:

## Documentation Health Report

### Summary
- Components audited: X
- Overall score: X/Y (Z%)
- Components passing: X
- Components needing attention: X

### Per-Component Scores

| Component | Score | Description | Attrs | Slots | Events | CSS | Demos |
|-----------|-------|-------------|-------|-------|--------|-----|-------|
| `<my-button>` | 90% | pass | pass | pass | warn | pass | fail |

### Findings

#### `<my-button>` (18/20, 90%)
- **Attribute Documentation** (warn): Add a description for attribute 'size'
- **Demos** (fail): No demo links found

### Top Recommendations
[List the recommendations from the JSON output — these are already
sorted by point impact]

Phase 4: Deeper Investigation (Optional)

If the user wants more detail on specific gaps, read the element's MCP resources:

cem://element/{tagName}
cem://element/{tagName}/attributes
cem://element/{tagName}/slots

This provides the full manifest data so you can show exactly what's missing and suggest what to document.

Phase 5: Suggesting Fixes

When reporting gaps, show the user how to fix them.

!cat ${CLAUDE_SKILL_DIR}/html-comment-syntax.md

Guidelines

• Use cem health as the source of truth: Don't reinvent the scoring — it already checks descriptions, types, defaults, etc.
• Surface recommendations first: The recommendations array is sorted by impact — present those prominently
• Suggest, don't fabricate: Flag gaps for the element author to fill, don't invent descriptions
• Flag inconsistencies: If some elements score 100% and others score 30%, highlight the gap
• Use --component for focused audits: When the user asks about a specific element, filter to avoid noise