# 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

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

## Changelog Entry Format

```markdown
## [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

```markdown
## 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