NotAlterra/skills/documentation/SKILL.md

Documentation

When to update each documentation file in the project.

Hierarchy

File	Purpose	When to update
src/*	Doc comments on every function	Every change to the function
CHANGELOG.md	What changed, version, date	Every commit
GOVERNANCE.md	Roadmap, release process, checklist	When process or plans change
KNOWN_ISSUES.md	Bugs and limitations users might encounter	When a new issue surfaces or is resolved
DECISIONS.md	Rationale behind architecture choices	When a significant decision is made
_release.md	What's new in the current release	Every release
README.md	User-facing features, build instructions	When features or setup change
CI workflow file	Pipeline configuration	When pipeline logic changes

Doc Comment Standards

• Every public function must have a doc comment
• Each comment explains what the function does, why it exists, and what edge cases it handles
• No "Internal helper" or "see module-level docs" placeholders
• Language-standard doc format (e.g. /// in Rust, /// in C#, /** */ in JS)

Changelog Format

## [v0.x.y] — YYYY-MM-DD

### Added
- New features

### Fixed
- Bug fixes

### Changed
- Behavior changes, refactors

### Removed
- Features removed

### Notes
- Operational notes (git resets, CI issues, etc.)

Release Notes

• Contains only the current version's changes — no history from older versions
• Replaced entirely for each new release, not appended