update-project-documentation

name	update-project-documentation
description	Update existing project documentation to maintain parity with source code changes. Analyzes code diffs, identifies documentation gaps, and surgically updates affected documents while preserving structure and style.

Update Project Documentation

Primary Directive

Update existing documentation in the docs/ directory to reflect current source code changes. Perform a delta analysis between the implementation and documentation, then surgically update only the affected sections while preserving the overall document structure, style, and formatting.

Execution Context

This skill is triggered after code changes to ensure documentation stays in sync. It focuses on efficiency — only updating what has changed rather than regenerating entire documents.

Analysis Phase

Step 1: Identify Changed Code

1. Check recent changes using git diff or by examining the files provided
2. If no specific files are indicated, scan all Go source files for modifications
3. Build a list of changed exported types, functions, constants, and configurations
4. Identify new, modified, or removed public APIs

Step 2: Map Changes to Documentation

For each code change, identify which documentation files are affected:

Change Type	Affected Documentation
New exported type/function	Package docs, possibly tools/resources reference
Modified function signature	Package docs, tools reference, examples
New MCP tool	docs/reference/tools/README.md, package docs
New MCP resource	docs/reference/resources.md, package docs
New MCP prompt	docs/reference/prompts.md, package docs
Configuration change	docs/reference/configuration.md
New package	docs/README.md index, new package doc
Architecture change	docs/concepts/architecture.md, diagrams
Build/deploy change	docs/development/development.md, docs/deployment.md
Removed API	All referencing documents

Step 3: Assess Impact

For each affected document:

1. Read the current documentation
2. Compare with the current source code
3. Classify the update as: Minor (parameter change), Moderate (new section), or Major (restructure)
4. Prioritize Critical and High priority documents first

Update Strategy

Principles

• UPD-001: Preserve existing document structure, heading hierarchy, and formatting style
• UPD-002: Use surgical edits — replace only the changed sections, not entire files
• UPD-003: Maintain cross-reference integrity — check all links still work
• UPD-004: Update Mermaid diagrams if component relationships changed
• UPD-005: Update tables (parameters, types, functions) to match source
• UPD-006: Add deprecation notices for removed APIs rather than deleting immediately
• UPD-007: Never introduce TBD/TODO placeholders in updates
• UPD-008: Maintain consistent terminology with the rest of the documentation
• UPD-009: When creating or editing Markdown pipe tables in README.md or docs/, run go run ./cmd/format_md_tables/ and verify with go run ./cmd/format_md_tables/ --check so source tables keep consistent padding and alignment markers

For New APIs

1. Add new entries to the appropriate reference document tables
2. Add new sections following the existing document pattern and style
3. Update the package documentation if the API belongs to an existing package
4. Add cross-references from related documents
5. Update the documentation index if new documents are created

For Modified APIs

1. Update parameter tables with new/changed/removed parameters
2. Update return type documentation if changed
3. Update code examples to reflect the new signature
4. Add migration notes if the change is breaking
5. Update Mermaid diagrams if type relationships changed

For Removed APIs

1. Mark the API as deprecated with a notice and removal version/date
2. Suggest the replacement API if one exists
3. Update cross-references that pointed to the removed API
4. After one release cycle, fully remove the deprecated section

For Configuration Changes

1. Update the environment variables table
2. Update default values and descriptions
3. Add migration instructions if existing users need to change their config
4. Update deployment documentation if the change affects deployment

Parity Verification

After all updates are applied, perform a parity check:

For Each Updated Document

1. Read the updated documentation
2. Compare every documented API, parameter, and type against source code
3. Verify all code examples are syntactically valid
4. Confirm Mermaid diagrams reflect current architecture
5. Check all cross-reference links resolve correctly

Verification Checklist

• All changed exported types/functions are documented correctly
• Parameter tables match current function signatures
• Return types and error handling match implementation
• Code examples compile and reflect current API
• Mermaid diagrams reflect current component relationships
• Cross-reference links are valid
• No TBD/TODO placeholders in updated sections
• Consistent terminology and style with surrounding content
• Deprecation notices added for removed APIs
• Markdown pipe tables in README.md and docs/ were verified with go run ./cmd/format_md_tables/ --check

Output Format

After completing updates, provide a summary:

## Documentation Update Summary

### Documents Updated
| Document | Sections Changed | Change Type |
|----------|-----------------|-------------|
| `docs/reference/tools/README.md` | Added `gitlab_new_tool` section | New API |
| `docs/packages/tools.md` | Updated exported functions table | Modified API |

### Parity Status
- [x] All changes documented
- [x] Examples validated
- [x] Diagrams updated
- [x] Cross-references verified

### Notes
[Any observations, recommendations for follow-up, or areas needing manual review]

Error Handling

• ERR-001: Source file not found — report the expected path and skip
• ERR-002: Documentation file not found — recommend running generate-project-documentation skill first
• ERR-003: Ambiguous change — document both interpretations and flag for manual review
• ERR-004: Breaking change detected — add prominent migration notice with before/after examples
• ERR-005: Diagram rendering failure — provide the Mermaid source and flag for manual validation