Documentation Update Workflow

Streamline documentation updates when code changes are made. This skill helps identify what documentation needs updating and guides you through the process.

When to Use

Use this skill after:

• Adding new TUI keybindings
• Adding new CLI commands or flags
• Adding new config options
• Changing default behavior
• Adding new features or integrations
• Modifying user-facing functionality

Workflow

Step 1: Identify Changes

Analyze recent commits or current changes to identify documentation-impacting changes:

# Check uncommitted changes
git diff

# Check recent commits
git log -5 --oneline
git show <commit-sha>

# Check specific files
git diff HEAD~1 internal/tui/model.go

Look for:

• New keybindings in TUI code
• New commands in CLI code
• New config fields
• Changed default values
• New features or integrations

Step 2: Find Relevant Documentation

Documentation files to check:

Search commands:

# Find documentation files
find . -name "*.md" -not -path "./agent-deck/*" | head -20

# Search for specific content
grep -r "keybindings" README.md docs/
grep -r "Default keybindings" README.md

Step 3: Update Documentation

README.md Sections to Update

Default Keybindings (around line 311):

**Default keybindings:**

- `:` - Open command palette (when user commands configured)
- `v` - Toggle preview sidebar (shows tmux pane output)
- `r` - Recycle session
- `d` - Delete session
...

TUI Features (around line 303):

**Features:**

- Tree view of sessions grouped by repository
- Real-time terminal status monitoring (with tmux integration)
- Preview sidebar showing live tmux pane output (`v` to toggle)
...

Configuration Options (around line 238): Add new config fields to the table with type, default, and description.

CLI Reference (starting line 288): Add new commands or flags with descriptions and examples.

Recipe Updates

Update docs/recipes/tmux-integration.md when:

• Adding tmux-specific keybindings
• Changing tmux integration behavior
• Adding new status indicators

Step 4: Verify Updates

Check that documentation is accurate and complete:

# Search for old keybinding references
grep -r "old-key" README.md docs/

# Verify all new features are documented
grep -r "new-feature" README.md

# Check for consistency
grep -rn "keybindings" README.md

Step 5: Commit

Commit documentation changes separately from code changes:

git add README.md docs/
git commit -m "docs: describe what was updated

Detailed description of changes."

Examples

Example 1: New TUI Keybinding

Change: Added v key to toggle preview sidebar

Documentation Updates:

1. README.md line ~315: Add v key to keybindings list
2. README.md line ~305: Add preview feature to features list
3. Verify no other mentions of keybindings need updating

Commit:

git add README.md
git commit -m "docs: add preview sidebar to TUI features and keybindings

Document the new 'v' key for toggling the tmux pane preview sidebar
in the default keybindings list and TUI features section."

Example 2: New Config Option

Change: Added tui.preview_enabled config option

Documentation Updates:

1. README.md Configuration Options table: Add new row with type, default, description
2. README.md Config example: Add to YAML example if commonly used
3. Check if any recipes should mention it

Example 3: New CLI Command

Change: Added hive preview command

Documentation Updates:

1. README.md CLI Reference: Add new section with command description
2. Add flag table if command has flags
3. Add usage examples
4. Update command list in Quick Start if relevant

Checklist

Use this checklist for every documentation update:

• Identified all code changes that impact users
• Found all relevant documentation files
• Updated README.md keybindings (if applicable)
• Updated README.md features list (if applicable)
• Updated README.md config options (if applicable)
• Updated README.md CLI reference (if applicable)
• Updated recipes (if applicable)
• Searched for old references to changed behavior
• Verified accuracy of all updates
• Committed with clear message

Tips

Be Proactive:

• Update docs in the same PR as code changes when possible
• Review documentation as part of code review

Be Thorough:

• Search for all mentions of changed behavior
• Update examples to match new behavior
• Check both inline docs and separate files

Be Clear:

• Use consistent terminology
• Provide examples for complex features
• Document the “why” not just the “what”

Keep Organized:

• Separate doc commits from code commits when updating after the fact
• Use descriptive commit messages
• Link docs commits to related code commits