Doc Maintainer Skill

Purpose

Maintain documentation that is concise, accurate, scannable, and perfectly aligned with project standards.

Activation Triggers

Proactive Activation

• New features, packages, or significant code changes without documentation updates
• Documentation files appear outdated or inconsistent with current code
• Documentation exceeds recommended length limits (README.md > 150 lines)
• Public functions/types lack required doc comments (Go projects)
• Documentation quality issues detected during code review

Manual Activation

• User requests documentation creation/update
• User asks to verify documentation completeness
• Before committing documentation changes

Core Documentation Domains

1. Project Documentation (README.md, CLAUDE.md, SETUP.md)
2. Code Documentation (inline comments, doc comments)
3. Documentation Quality Assurance (consistency, accuracy, conciseness)

Fundamental Principles (from ~/.claude/CLAUDE.md)

README.md Standards

• Conciseness: Target 150 lines maximum
• Scannable structure: Clear sections with meaningful headings
• No temporal information: Describe current state only, not history
• No manual metrics: Use CI badges instead of hardcoded numbers
• Avoid redundancy: Don't duplicate information available in code/CI

Essential Sections:

• Project overview
• Technology stack (concise)
• Development environment setup
• Project structure
• Key features (current state only)
• Development commands
• License information
• Reference links

Prohibited Content:

• Detailed technology stack explanations
• Excessive project structure diagrams
• Information about unused platforms
• Change history (use Git instead)
• Verbose explanations of self-evident information

CLAUDE.md Standards

• Prescriptive tone: Use "should" not "has been done"
• Generality: Describe ideal state, not current project-specific status
• Separation of concerns: Development guidelines in CLAUDE.md, usage in README.md
• Normative descriptions: Focus on what should be, not what is

Code Documentation Standards

For Go Projects

• Public functions/types: MUST have doc comments starting with function/type name
• Comment style: Clear, concise, describing what and why (not how)
• Error messages: Lowercase start, no punctuation
• Current state: Describe present behavior, not past changes

For TypeScript/React Projects

• JSDoc for public APIs: Especially for library-like modules
• Complex logic: Explain non-obvious patterns
• Type annotations: Let TypeScript types self-document when possible
• Avoid obvious comments: Don't explain what code clearly shows

Documentation Workflow

Phase 1: Analyze Context

1. Review existing patterns

   • Check project-specific CLAUDE.md
   • Identify target audience
   • Understand documentation conventions

2. Assess current state

   • Read existing documentation
   • Identify gaps or inconsistencies
   • Check for outdated information

Phase 2: Verify Compliance

1. Length limits

   • README.md: ≤ 150 lines
   • CLAUDE.md: Focus on principles, not exhaustive details

2. Content quality

   • Remove temporal/historical information
   • Replace hardcoded metrics with CI badges
   • Eliminate redundant information

3. Markdown quality

   • Run mcp__ide__getDiagnostics to check errors
   • Follow markdownlint rules (~/.markdownlint.jsonc)

Phase 3: Structure Optimization

1. Organize logically

   • Most important information first
   • Clear, scannable headings
   • Appropriate formatting (code blocks, lists, emphasis)

2. Internal consistency

   • Validate internal links
   • Ensure consistent terminology
   • Maintain uniform style

Phase 4: Quality Assurance

1. Accuracy verification

   • Ensure documentation matches current codebase
   • Test code examples
   • Validate all references

2. Consistency check

   • Compare with project conventions
   • Verify alignment with CLAUDE.md standards
   • Check language consistency

Code Documentation Validation

Coverage Check

• Go: Verify all exported functions/types have doc comments
• TypeScript: Check public API documentation completeness
• Identify missing documentation for complex logic

Quality Assessment

• Comments explain "why" not "what" (code shows what)
• Descriptions are clear and concise
• Technical terms used accurately
• Examples provided where helpful

Maintenance Flags

• Identify outdated comments that don't match current code
• Flag TODO/FIXME comments that should be addressed
• Detect redundant comments that add no value

Output Format

When providing recommendations:

1. Specific issues: List exact problems with file/line references
2. Suggested improvements: Provide concrete, actionable changes
3. Rationale: Explain why changes align with project standards
4. Priority: Indicate severity (critical, important, nice-to-have)
5. Examples: Show before/after where helpful

Integration with Other Skills

• code-reviewer: Flag documentation issues during code review
• git-commit-assistant: Ensure documentation is updated before commit
• knowledge-manager: Record documentation patterns and best practices

Maintenance

Update this Skill when:

• Documentation standards evolve
• New documentation types are introduced
• Team feedback suggests improvements
• New projects require different conventions