# Validate Docs

> Validates code comment quality and TODO/FIXME formatting

- Skill: `ww-w-ai/validate-docs` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add ww-w-ai/validate-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ww-w-ai/validate-docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: ww-w-ai (https://skillmd.com/u/ww-w-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ww-w-ai/validate-docs

---


# validate-docs -- Code Documentation Quality Validation

Corresponding rule: `docs/specs/documentation.md`

## Input -- Dynamic Target Resolution

Resolve the target directory in the following order:
1. CLAUDE.md "Project Structure" section -- extract source code directories
2. If CLAUDE.md is absent or has no structure: Glob source files (`**/*.{ts,tsx,js,jsx,py,java,go,rs}`) -- use the top-level directory containing matches
3. If no source files exist: report status as SHALLOW with reason

Default exclusions: node_modules/, .git/, dist/, build/, coverage/
Skill-specific exclusions: `*.generated.*`, `*.g.dart`, `*.freezed.dart` (auto-generated code)

### Mandatory output: Target resolution result

Output the following before proceeding to validation. Do not proceed until resolved.

| Step | Result |
|------|--------|
| CLAUDE.md check | found/not found |
| Resolved directories | {list or "none"} |
| Source files found | {count} |
| Resolution method | CLAUDE.md / Glob fallback / SHALLOW |

## Execution logic

1. **Validate TODO/FIXME formatting**
   - Grep for the `TODO` or `FIXME` keywords
   - Valid format: `TODO(@assignee, YYYY-MM): description` or `FIXME(@assignee, YYYY-MM): description`
   - Warn when the `(@` + `, ` + 4-digit year pattern is absent
   - TODOs/FIXMEs without an assignee/deadline cannot be tracked and risk permanent neglect

2. **Validate HACK removal conditions**
   - Grep for the `HACK` keyword
   - Warn when no removal condition or date (`YYYY`, `vN`, `#issue-number`) is present
   - A HACK without a removal condition causes temporary code to become permanent

3. **Prefix usage report**
   - Prefix list: `WHY`, `CONSTRAINT`, `DEPENDS`, `SECURITY`, `PERF`, `MIGRATION`
   - Grep the usage count of each prefix
   - Generate a prefix usage ratio report (informational only, no PASS/FAIL verdict)

4. **Detect self-evident comments** (low confidence)
   - Detection patterns: `// declare variable`, `// increment i`, `// call function`, `// return`, `// loop`, `// declare`
   - Patterns where the comment restates what the code already expresses
   - High false-positive rate, so marked as "suspected items" only (not FAIL)

### Mandatory output: Findings verification matrix

Output the following matrix before generating the final report. Do not proceed until every category has been checked.

| Category | Status | Items Checked | Pass | Warn | Fail | Evidence |
|----------|:------:|:-------------:|:----:|:----:|:----:|----------|
| TODO/FIXME format | ? | ? | ? | ? | ? | {tools, files, patterns} |
| HACK conditions | ? | ? | ? | ? | ? | {tools, files, patterns} |
| Prefix usage | ? | ? | - | - | - | {tools, files, patterns} |
| Self-evident comments | ? | ? | - | - | - | {tools, files, patterns} |

Status values: PASS (verified clean), NOT_APPLICABLE (no source files found), SKIPPED (plugin issue), SHALLOW (target resolution failed)

### Pre-output checklist (required before final output)

Verify every item before drafting the report. If any item is unchecked, go back and complete it.

- [ ] Every validation category has a Status value assigned (no empty Status cells)
- [ ] Every category whose Status != SKIPPED has an Evidence value
- [ ] Every WARN item includes a file path and line number
- [ ] Report language matches the user's conversation language

### Schema compliance check (required before persisting to .ww-w-ai/standards/)

Verify the JSON output before writing to `.ww-w-ai/standards/validate-docs/`:
- [ ] All "required" fields in schema.json are present and non-empty
- [ ] findings[] array includes every detected item
- [ ] summary aggregates match the actual number of findings

## Output

Produce the validation report in the user's conversation language.

Output the validation results in the following format:

```
Documentation Quality Report
==================================================

### TODO/FIXME format

| File:line | Type | Description |
|-----------|:----:|-------------|
| src/auth.ts:42 | WARN | TODO without assignee/deadline: `// TODO: fix later` |
| src/order.ts:15 | PASS | `// TODO(@kim, 2026-06): implement pagination` |
| src/payment.ts:88 | WARN | FIXME without assignee: `// FIXME: intermittent timeout` |

### HACK removal conditions

| File:line | Type | Description |
|-----------|:----:|-------------|
| src/legacy.ts:23 | WARN | HACK without removal condition: `// HACK: don't touch` |

### Prefix usage summary

| Prefix | Count |
|--------|:-----:|
| WHY | 5 |
| CONSTRAINT | 3 |
| DEPENDS | 2 |
| SECURITY | 1 |
| PERF | 0 |
| MIGRATION | 0 |

### Suspected items (self-evident comments)

| File:line | Content |
|-----------|---------|
| src/utils.ts:10 | `// declare the variable` |
| src/calc.ts:25 | `// increment i by 1` |

> Suspected items have a high false-positive rate. Check the context to decide whether the comment is truly unnecessary.

--------------------------------------------------
Total: 3 warnings | 2 suspected items
```

## Output persistence

After generating the documentation quality report, persist results to `.ww-w-ai/standards/validate-docs/`:

1. Create the `.ww-w-ai/standards/validate-docs/` directory if it does not exist
2. Write `latest.json` -- structured result following `templates/schema.json`
3. Write `latest.md` -- human-readable report following `templates/report.template.md`
4. Archive to `history/` -- copy latest.json to `.ww-w-ai/standards/validate-docs/history/{timestamp}.json`

`latest.md` is produced in the user's conversation language. JSON field names remain in English regardless of language.
The JSON output enables machine-parseable history tracking and cross-run comparison.
The history/ directory preserves prior runs for trend analysis.

## Permission rationale

- **Write**: restricted to `.ww-w-ai/standards/` output persistence. No modification of project source.
- **Bash**: restricted to read-only git/system queries. No file modification.

## Notes

- This skill is read-only. It does not modify or add comments.
- Self-evident comment detection is based on string pattern matching and has a high false-positive rate. Results are marked as "suspected items" only and the final judgment is the user's.
- Auto-generated code (`*.generated.*`, etc.) is excluded from the search scope.
- The prefix usage summary is informational; a low usage ratio does not lead to a FAIL verdict.
- English-only detection patterns are used. In non-English projects, detection accuracy (especially for self-evident comment detection) may vary.

## Spec references

Detailed verification criteria, evidence tables, examples:
- Corresponding rule spec: `../../docs/specs/documentation.md`
- Evidence index: `../../docs/evidence/evidence-registry.md`