Documentation Consistency Skill

This skill ensures project documentation accurately reflects the current implementation.

When to Use This Skill

• After implementing a new feature
• After fixing a bug that changes behavior
• Before creating a release
• When adding or modifying configuration options
• When adding or modifying keyboard shortcuts
• When updating architecture or patterns
• When reviewing documentation quality

Documentation Update Workflow

1. Identify Changed Components

After code changes, determine which documentation needs updates:

| Change Type | Documents to Update | |-------------|---------------------| | New feature | README.md, CHANGELOG.md | | Bug fix | CHANGELOG.md | | Config change | README.md (Configuration), CHANGELOG.md | | Shortcut change | README.md (Keyboard Shortcuts), CHANGELOG.md | | Architecture change | CLAUDE.md, possibly domain CLAUDE.md files | | WebView change | src/webview/CLAUDE.md, CLAUDE.md | | Test pattern change | src/test/CLAUDE.md |

2. Update Documentation in Order

1. CHANGELOG.md - Always update first

   • Add entry under [Unreleased] section
   • Use correct section (Added/Changed/Fixed/etc.)
   • Include issue/PR number if applicable

2. README.md - If user-visible changes

   • Features table if new feature
   • Configuration section if settings changed
   • Keyboard Shortcuts if bindings changed

3. CLAUDE.md - If development process affected

   • Commands section if new npm scripts
   • Architecture section if patterns changed
   • Guidelines if best practices updated

4. Domain-specific docs - If specialized area changed

   • src/webview/CLAUDE.md for WebView changes
   • src/test/CLAUDE.md for testing changes

3. Verify Consistency

Run verification checks from references/verification-checklist.md:

# Version check
node -p "require('./package.json').version"

# Commands check
node -p "require('./package.json').contributes.commands.map(c => c.command).join('\n')"

# Config check
node -p "Object.keys(require('./package.json').contributes.configuration.properties).join('\n')"

Pre-Release Documentation Checklist

Before each release, verify:

• [ ] CHANGELOG.md has entry for new version with correct date
• [ ] All new features documented in README.md
• [ ] All changed configurations documented correctly
• [ ] All keyboard shortcuts documented with correct platforms
• [ ] Version numbers consistent across files
• [ ] No TODO items left in documentation
• [ ] Links are working

Quick Reference Commands

Check Undocumented Commands

node -e "
const pkg = require('./package.json');
const fs = require('fs');
const readme = fs.readFileSync('README.md', 'utf8');
pkg.contributes.commands.forEach(cmd => {
  const shortName = cmd.command.replace('secondaryTerminal.', '');
  if (!readme.includes(shortName)) {
    console.log('Undocumented:', cmd.command);
  }
});
"

Check Undocumented Configs

node -e "
const pkg = require('./package.json');
const fs = require('fs');
const readme = fs.readFileSync('README.md', 'utf8');
Object.keys(pkg.contributes.configuration.properties).forEach(key => {
  if (!readme.includes(key)) {
    console.log('Undocumented config:', key);
  }
});
"

Check CHANGELOG Version

VERSION=$(node -p "require('./package.json').version")
grep -q "## \[$VERSION\]" CHANGELOG.md && echo "Version documented" || echo "Version missing in CHANGELOG"

Document Structures

README.md Structure

# Product Name
[Badges]
**Description**
[Hero Image]
## Quick Start
## Key Features
## Keyboard Shortcuts
## Command Palette
## Configuration
## Architecture
## Performance
## Troubleshooting
## Development
## Known Limitations
## Privacy
## Contributing
## Links
## License

CHANGELOG.md Entry Format

## [X.Y.Z] - YYYY-MM-DD

### Added
- **Feature Name**: Description (#issue-number)

### Fixed
- **Bug Name**: Fix description (#issue-number)
  - Technical detail if helpful

### Changed
- **Component Name**: What changed

CLAUDE.md Structure

## Development Flow
## Essential Development Commands
## Architecture Overview
## Development Guidelines
## Known Issues & Workarounds
## Performance Optimization
## Testing Strategy
## Emergency Response

Reference Files

For detailed information, read the following reference files:

| Reference | Use When | |-----------|----------| | references/documentation-structure.md | Understanding project documentation layout | | references/verification-checklist.md | Running consistency checks | | references/writing-guidelines.md | Writing or improving documentation |

Common Issues and Solutions

Issue: Feature in code but not documented

Solution:

1. Add feature description to README.md Key Features table
2. Add CHANGELOG.md entry under appropriate section
3. If architecture changed, update CLAUDE.md

Issue: Configuration default changed

Solution:

1. Update README.md Configuration section
2. Add CHANGELOG.md entry under Changed
3. Verify package.json description matches

Issue: Keyboard shortcut modified

Solution:

1. Update README.md Keyboard Shortcuts table
2. Include both Mac and Win/Linux bindings
3. Add CHANGELOG.md entry

Issue: Japanese docs out of sync

Solution:

1. Compare README.md with docs/README_ja.md
2. Update Japanese version with new content
3. Consider whether domain CLAUDE.md files should be translated

Writing Style Quick Reference

• Concise: Users skim documentation
• Accurate: Match current implementation exactly
• User-centric: Focus on "how to use" not "how it works"
• Consistent: Follow existing patterns in each file
• Actionable: Include commands and examples