ai-docs-source-quality-impl

name	ai-docs-source-quality-impl
description	Implement source-level quality improvements for component and hook docs generated by apps/ai-docs.

AI Docs Source Quality — Implementation Skill

Use this skill to implement documentation quality improvements at generation source, not by patching generated markdown files.

Required Principles

• Keep generated artifacts deterministic.
• Preserve backward compatibility for MCP responses where possible.
• Prefer additive fields before breaking schema changes.

Implementation Modules

1) Component doc generation uplift

• File: apps/ai-docs/src/internal/buildComponentDocArtifacts.ts
• Improve generated markdown template:
  • Add Description section from entity.jsDoc when available.
  • Add Default column to props table using defaultValue.
  • Normalize empty values to — rather than blank cells.
  • Add structured sections (Usage notes, optional Caveats) using rule-based text.

2) Hook metadata enrichment

• File: apps/ai-docs/src/internal/extractSymbols.ts
• Add derived fields for hooks:
  • deprecated: boolean
  • deprecationMessage?: string
  • Optional source tag inferred from source path (e.g. /deprecated/).
• Keep existing fields intact (params, returns, jsDoc).

3) Quality metrics emission

• File: apps/ai-docs/src/generate.ts
• Emit quality stats into manifest/report:
  • component description coverage
  • prop description coverage
  • hook jsDoc coverage
  • deprecated hook tagging rate

4) Quality gate validation

• File: apps/ai-docs/src/validate.ts
• Add threshold checks with strict-mode toggle:
  • fail when configured minimum coverage is not reached.

Suggested Order

1. Template uplift
2. Hook enrichment
3. Metrics output
4. Validate gates

Checklist

• Generated component docs now include richer sections/fields
• Hook output exposes explicit deprecation signals
• Manifest/report includes measurable quality stats
• Validation can block low-quality generations in strict mode