118 lines
3.9 KiB
Markdown
118 lines
3.9 KiB
Markdown
# 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
|