documentation-sync

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:

1. Identify Impact: Which docs need updates?
2. Update Content: Follow scenario-specific patterns
3. Cross-Reference: Ensure links remain valid
4. Validate Examples: Test all code samples
5. 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