antigravity-claudekit/skills/ck-orchestration/references/documentation-management.md

Documentation Management Protocol

Maintain project documentation in ./docs after significant changes. Documentation is a living artifact — update it as part of every feature delivery, not as an afterthought.

When to Update Docs

Trigger	Documents to Update
Feature implementation complete	codebase-summary.md, system-architecture.md, development-roadmap.md, project-changelog.md
Bug fix merged	project-changelog.md
Architecture decision made	system-architecture.md, codebase-summary.md
Security update	project-changelog.md, system-architecture.md
Breaking change	project-changelog.md, code-standards.md
Phase status change	development-roadmap.md
New code patterns established	code-standards.md

Documents Maintained

./docs/
├── codebase-summary.md       — Project structure, key files, module overview
├── system-architecture.md    — Architecture decisions, component interactions, data flow
├── code-standards.md         — Coding conventions, patterns, anti-patterns
├── development-roadmap.md    — Phases, milestones, progress tracking
├── project-changelog.md      — Chronological record of significant changes
├── design-guidelines.md      — UI/UX design system, tokens, patterns (frontend projects)
└── deployment-guide.md       — Deployment procedures, environment config

Update Protocol

Before Updating

1. Read current state of the document to understand existing content
2. Identify what changed and how it affects each document
3. Check cross-references between documents for consistency

During Updates

• Maintain version consistency (dates, version numbers)
• Use consistent formatting with the rest of the document
• Add entries chronologically (newest at top for changelogs)
• Keep summaries concise — docs are reference material, not tutorials

After Updating

• Verify links and cross-references are accurate
• Ensure dates match actual implementation dates
• Confirm progress percentages reflect reality

Codebase Summary Freshness

./docs/codebase-summary.md has a 2-day staleness threshold:

• If the file is less than 2 days old: read it as-is for project context
• If the file is more than 2 days old or doesn't exist: regenerate using repomix command, then update the file

# Regenerate codebase summary
repomix
# Then summarize repomix-output.xml into docs/codebase-summary.md

Changelog Entry Format

## [YYYY-MM-DD] Feature/Fix Title

### Added
- New capability or feature

### Changed
- Modified behavior with before/after context

### Fixed
- Bug description and impact

### Security
- Security improvement or vulnerability addressed

### Breaking Changes
- What broke, migration path

Roadmap Update Format

## Phase N: Phase Name — [Status: pending/in-progress/complete]

**Progress:** X%
**Target:** YYYY-MM-DD
**Actual:** YYYY-MM-DD (if complete)

### Milestones
- [x] Completed milestone
- [ ] Pending milestone

### Notes
Any relevant context about blockers or decisions

Finalize Step Integration

Documentation updates are part of the mandatory Finalize step in ck-cook:

1. Update plan/phase status to complete
2. Update ./docs if changes warrant it ← this step
3. Ask user if they want to commit via ck-git

Never skip the docs update step. Even a one-line changelog entry is better than no record.

Anti-Patterns

• Docs as afterthought: Updating docs days after implementation → inaccurate timestamps and forgotten context
• Over-documenting: Giant walls of text no one reads → keep entries concise and scannable
• Stale summaries: Using a 2-week-old codebase-summary.md for project context → regenerate it
• Missing breaking changes: Forgetting to document API breaks → surprises for future developers