verify-docs

Verify that documentation claims in @markuplint/types are accurate by cross-referencing them against official web standards (WHATWG, W3C, RFC, CSS, SVG) and the actual source code implementation.

Input

$ARGUMENTS specifies the target: a package name (e.g., @markuplint/types) or a specific documentation file path. If omitted, defaults to all docs/*.md files in packages/@markuplint/types/.

Phase 1: Discovery

Read all target documentation files and extract every claim that references an external specification. Look for:

• •Specification URLs (e.g., https://html.spec.whatwg.org/..., https://www.w3.org/TR/...)
• •ABNF grammar blocks
• •RFC numbers (e.g., RFC 5646, BCP 47)
• •Specific numeric claims (e.g., "46 names", "8 reserved names")
• •Regex patterns claimed to match a spec definition
• •CSS value definition syntax references
• •Statements like "Implements the X spec" or "according to Y specification"

Collect each claim as a structured item:

{ file, line, claim, specDomain, specURL }

Phase 2: Categorize

Group extracted claims by specification domain:

Phase 3: Parallel Verification

For each domain group, launch a parallel agent using the Task tool with subagent_type: "general-purpose". Each agent:

1. •Searches the official specification using WebSearch to find the authoritative definition
2. •Compares the documentation claim against the spec definition
3. •Reads the corresponding source code to confirm the implementation matches
4. •Assigns a verdict to each claim:
   • •PASS — Documentation accurately describes the spec and matches the implementation
   • •FAIL — Documentation is inaccurate (wrong number, incorrect grammar, misleading description)
   • •WARN — Documentation is technically correct but potentially misleading or incomplete

Each agent returns its results as a structured list:

| # | File:Line | Claim | Spec Source | Verdict | Notes |

Phase 4: Report

Collect results from all parallel agents and produce a consolidated PASS/FAIL table:

## Verification Report

| #   | Domain | File:Line         | Claim Summary           | Verdict | Notes                                    |
| --- | ------ | ----------------- | ----------------------- | ------- | ---------------------------------------- |
| 1   | WHATWG | validators.md:214 | 46 autofill field names | FAIL    | Code has 44                              |
| 2   | W3C    | validators.md:315 | ABNF grammar            | WARN    | allow-list optionality differs from spec |
| ... | ...    | ...               | ...                     | ...     | ...                                      |

**Summary:** X PASS / Y FAIL / Z WARN out of N total claims

Phase 5: Correction Plan

For every FAIL item, produce a concrete correction instruction:

### Correction 1: [Brief description]

- **File:** `path/to/file.md`
- **Line:** 214
- **Current:** `(46 names)`
- **Corrected:** `(44 names)`
- **Reason:** Source code `check-autocomplete.ts` contains 44 entries in `autofillFieldNames` array

For WARN items, produce an advisory note with a suggested improvement (not mandatory).

Rules

1. •Source code is the source of truth for implementation behavior. If the docs say "implements X" but the code does something slightly different, the docs should be corrected to accurately describe what the code does.
2. •Specification is the source of truth for what the standard defines. If the code intentionally deviates from the spec, the docs should note the deviation explicitly.
3. •Code bugs are a separate category. If the code itself doesn't match the spec, flag it as a code issue (not a documentation issue) and note it separately.
4. •Numeric claims must be exact. Count arrays, enum values, and lists in the source code to verify numbers stated in documentation.
5. •ABNF and regex patterns must be character-for-character accurate when presented as quotes from a specification.
6. •Use WebSearch for spec verification. Always fetch the latest version of the referenced specification — do not rely on cached knowledge.