doc-consistency

• 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

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

1. README.md - If user-visible changes

- Features table if new feature

- Configuration section if settings changed

- Keyboard Shortcuts if bindings changed

1. CLAUDE.md - If development process affected

- Commands section if new npm scripts

- Architecture section if patterns changed

- Guidelines if best practices updated

1. 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:

```bash

# 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')"

```

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

Check Undocumented Commands

```bash

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

```bash

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

```bash

VERSION=$(node -p "require('./package.json').version")

grep -q "## \[$VERSION\]" CHANGELOG.md && echo "Version documented" || echo "Version missing in CHANGELOG"

```

README.md Structure

```

# Product Name

[Badges]

Description

[Hero Image]

```

CHANGELOG.md Entry Format

```markdown

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

```

```

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 |

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

• 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