---
description: Documentation, changelog, and development log update rules
alwaysApply: true
---

# Documentation Rules

After every meaningful code change, update the relevant documentation. Do not let code and documentation drift apart.

Always consider whether these files need updates:
- `changelog.md`
- `docs/dev-log.md`
- `docs/protocol.md`
- `docs/architecture.md`
- `docs/setup.md`
- `docs/testing.md`

## Changelog vs Dev Log

Use both files, but for different purposes:

| File | Purpose | When to update |
|------|---------|----------------|
| `changelog.md` | Complete record of every change | After **every** code edit, addition, removal, fix, or documentation update |
| `docs/dev-log.md` | Milestones, testing, discoveries, next steps | After feature milestones or meaningful development sessions |

**Changelog** — log every change under `[Unreleased]` using [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) categories. Include what was added, changed, deprecated, removed, fixed, or security-related. Mention affected files or areas when helpful. Do **not** include testing results, test plans, verification notes, known issues, or next steps.

**Dev log** — keep the existing milestone format for broader feature work, technical discoveries, and testing.

## Changelog Format

Follow [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/).

- Keep an `## [Unreleased]` section at the top for all in-progress changes.
- When cutting a release, move `[Unreleased]` entries into a new `## [X.Y.Z] - YYYY-MM-DD` section (ISO 8601 date), then clear `[Unreleased]`.
- Newest versions come first, directly under the file preamble.
- Omit empty change-type sections.
- One bullet per change; keep entries concise and factual.

Use these change types (only when applicable):

| Type | Use for |
|------|---------|
| `Added` | New features, files, fields, or capabilities |
| `Changed` | Changes to existing functionality |
| `Deprecated` | Soon-to-be removed features |
| `Removed` | Removed features or files |
| `Fixed` | Bug fixes |
| `Security` | Vulnerability fixes |

Example:

```md
## [Unreleased]

### Added
- New packet field `exampleField` in transform sync.

### Fixed
- Guard null actor pointer before proxy movement update.

## [0.1.0] - 2026-06-23

### Added
- Initial world-state sync MVP.
```

## Dev Log Format

At minimum, after every milestone or feature change, update `docs/dev-log.md` with:
- Date
- Summary of what changed
- Files modified
- What was tested
- What worked
- Any known issues
- Suggested next steps

Use this dev-log format:

```md
## YYYY-MM-DD - Feature or Milestone Name

### Summary
Briefly explain what changed.

### Files Changed
- `path/to/file`
- `path/to/file`

### Details
- Important technical detail
- Important technical detail

### Testing
- What was tested
- What the expected result was
- What actually happened

### Known Issues
- Issue or `None currently known`

### Next Steps
- Suggested next task
```

If the protocol changes, update `docs/protocol.md`. If the architecture changes, update `docs/architecture.md`. If setup changes, update `docs/setup.md`. If testing workflow changes, update `docs/testing.md`.