Documentation Synchronization Skill

Overview

This skill ensures documentation in the docs/ directory remains synchronized with codebase changes, maintaining accuracy and completeness for both users and developers.

Core Principle

Documentation is part of the definition of done. No code change is complete until the relevant documentation is updated.

When to Use This Skill

Activate this skill when:

API Changes: Adding/modifying REST or GraphQL endpoints
Database Changes: Adding entities, modifying schema
Architecture Changes: Changing design patterns, component structure
Configuration Changes: Adding environment variables, config options
Security Changes: Modifying authentication, authorization
Testing Changes: Adding test strategies, new test types
Performance Changes: Optimizations, benchmarking
Feature Implementation: New user-facing features

Core Documentation Files

API and Integration

| File | Purpose | Update When | | ----------------------- | ------------------------------- | ---------------- | | docs/api-endpoints.md | REST/GraphQL endpoints, schemas | API changes | | docs/user-guide.md | User-facing features | Feature changes | | docs/security.md | Auth, authorization | Security changes |

Architecture and Design

| File | Purpose | Update When | | --------------------------------- | ----------------------- | -------------------- | | docs/design-and-architecture.md | System design, patterns | Architecture changes | | docs/developer-guide.md | Dev patterns, examples | Dev workflow changes | | docs/glossary.md | Domain terminology | New domain concepts |

Operations and Configuration

| File | Purpose | Update When | | -------------------------------- | ------------------- | -------------- | | docs/advanced-configuration.md | Env vars, config | Config changes | | docs/getting-started.md | Setup, installation | Setup changes | | docs/operational.md | Monitoring, logging | Ops changes |

Development

| File | Purpose | Update When | | --------------------- | ------------------------- | ---------------- | | docs/testing.md | Test strategies | Test changes | | docs/performance.md | Benchmarks, optimizations | Performance work | | docs/onboarding.md | New dev onboarding | Process changes |

Versioning

| File | Purpose | Update When | | ----------------------- | ------------ | ------------------- | | docs/versioning.md | Version info | Version bumps | | docs/release-notes.md | Changelog | Significant changes |

Documentation Update Workflow

Quick Reference

For each code change:

Identify Impact: Which docs need updates?
Update Content: Follow scenario-specific patterns
Cross-Reference: Ensure links remain valid
Validate Examples: Test all code samples
Review Checklist: Use pre-commit checklist

Common Update Scenarios

| Change Type | Primary Docs | Commands | Guide | | --------------------- | ------------------------------------------- | ---------------------------- | ----------------------------------------------------------------------------------- | | REST Endpoint | api-endpoints.md | make generate-openapi-spec | api-endpoints.md | | GraphQL Operation | api-endpoints.md | make generate-graphql-spec | api-endpoints.md | | Database Schema | design-and-architecture.md | - | database-and-architecture.md | | Domain Model | design-and-architecture.md, glossary.md | - | database-and-architecture.md | | Configuration | advanced-configuration.md | - | configuration-and-operations.md | | Authentication | security.md, api-endpoints.md | - | configuration-and-operations.md | | Testing | testing.md | - | configuration-and-operations.md | | Performance | performance.md | - | configuration-and-operations.md |

See detailed guides: update-scenarios/ directory

Documentation Quality Standards

Consistency

✅ Follow existing doc structure and formatting
✅ Use terminology from docs/glossary.md
✅ Include code examples with syntax highlighting
✅ Add cross-references to related sections

Completeness

✅ Document all public APIs and endpoints
✅ Include error handling and edge cases
✅ Provide basic and advanced examples
✅ Update version info when needed

Maintenance

✅ Remove outdated information
✅ Update release notes for significant changes
✅ Validate all links and references
✅ Update diagrams if architecture changes

See detailed standards: reference/quality-standards.md

Pre-Commit Checklist

Before committing code with documentation updates:

[ ] Identify Impact: Determine which docs need updates
[ ] Update Content: Apply scenario-specific patterns
[ ] Cross-Reference: Verify all links remain valid
[ ] Test Examples: Run all code examples
[ ] Check Consistency: Verify terminology matches glossary
[ ] Update Specs: Run make generate-openapi-spec or make generate-graphql-spec if needed
[ ] Review Changes: Ensure completeness and accuracy

See complete workflow: reference/workflow-checklist.md

Integration with Development

During Development

Documentation is code:

Update docs in same PR as code changes
Test documentation examples
Validate links and references

During Code Review

Reviewers check:

Documentation accuracy
Completeness of examples
Terminology consistency
Link validity

During CI/CD

Automated checks:

Documentation links validation
Example code syntax checking
Spec generation and validation

Supporting Files

For detailed guides, examples, and standards:

update-scenarios/api-endpoints.md - REST and GraphQL documentation
update-scenarios/database-and-architecture.md - Schema and design docs
update-scenarios/configuration-and-operations.md - Config, security, testing, performance
reference/quality-standards.md - Documentation quality guidelines
reference/workflow-checklist.md - Complete update workflow

Success Criteria

✅ All affected docs updated
✅ Code examples tested and working
✅ Links and references valid
✅ Terminology consistent
✅ Release notes updated
✅ Docs reflect actual code behavior