kollabor 0.4.9__py3-none-any.whl → 0.4.15__py3-none-any.whl

agents/technical-writer/changelog-management.md

@@ -0,0 +1,1181 @@
+<!-- Changelog Management skill - maintain version history and release notes -->
+
+changelog management mode: KEEP A CHANGELOG DISCIPLINE
+
+when this skill is active, you follow Keep a Changelog standards.
+this is a comprehensive guide to maintaining project changelogs.
+
+
+PHASE 0: CHANGELOG CONTEXT DISCOVERY
+
+before creating or updating ANY changelog, understand the project's versioning.
+
+
+check for existing changelog
+
+  <terminal>ls -la | grep -i change</terminal>
+  <terminal>cat CHANGELOG.md 2>/dev/null || cat CHANGELOG 2>/dev/null || cat CHANGES.md 2>/dev/null || echo "no existing changelog"</terminal>
+
+if changelog exists, analyze:
+  - format being used (keep a changelog, custom, etc.)
+  - version numbering scheme
+  - categorization of changes
+  - release date format
+  - unreleased section handling
+
+
+check version history
+
+  <terminal>git tag --list | sort -V | tail -20</terminal>
+  <terminal>git log --oneline --decorate | head -30</terminal>
+
+identify:
+  - current version
+  - version tags in use
+  - release frequency
+  - version scheme (semver, calver, custom)
+
+
+check project type and versioning
+
+  <terminal>cat pyproject.toml 2>/dev/null | grep -A5 "version\|project"</terminal>
+  <terminal>cat package.json 2>/dev/null | grep version</terminal>
+  <terminal>cat Cargo.toml 2>/dev/null | grep version</terminal>
+
+determine:
+  - where version is stored
+  - if using semantic versioning
+  - if there's an automatic version bump system
+
+
+check commit message patterns
+
+  <terminal>git log --oneline | head -50</terminal>
+
+analyze:
+  - are commits following conventional commits?
+  - is there a pattern (feat:, fix:, docs:, etc.)?
+  - are issues referenced in commits?
+  - are commit scopes used?
+
+
+check for release tooling
+
+  <terminal>cat .github/workflows/*.yml 2>/dev/null | grep -i release</terminal>
+  <terminal>cat pyproject.toml 2>/dev/null | grep -A10 "commitizen\|release"</terminal>
+
+identify:
+  - automated release tools (release-please, semantic-release, etc.)
+  - changelog generation tools
+  - version bump automation
+
+
+PHASE 1: UNDERSTANDING KEEP A CHANGELOG
+
+
+the standard format
+
+Keep a Changelog is the de facto standard for changelogs.
+url: https://keepachangelog.com
+
+core principles:
+
+  [1] humans care about what changed, not when
+      versions over dates as the primary organizer
+
+  [2] categorize changes by type
+      added, changed, deprecated, removed, fixed, security
+
+  [3] list changes per version
+      grouped by category under each version
+
+  [4] link to actual commits
+      provide traceability
+
+
+changelog structure
+
+  # Changelog
+
+  All notable changes to this project will be documented in this file.
+
+  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+  [Unreleased]
+
+  ## [1.0.0] - 2024-01-15
+
+  ### Added
+  - New feature that users will care about
+
+  ### Changed
+  - Something that worked differently now
+
+  ### Deprecated
+  - Feature that will be removed in future
+
+  ### Removed
+  - Feature that was deprecated and now removed
+
+  ### Fixed
+  - Bug fix for something
+
+  ### Security
+  - Security vulnerability fix
+
+
+category definitions
+
+  Added
+    new features
+    new capabilities
+    new integrations
+    new configuration options
+
+  Changed
+    behavior changes in existing features
+    modified functionality
+    updated defaults
+    performance improvements
+
+  Deprecated
+    features marked for future removal
+    features that will change incompatibly
+
+  Removed
+    features removed from the project
+    deprecated features that reached end of life
+
+  Fixed
+    bug fixes
+    regression fixes
+    crash fixes
+
+  Security
+    vulnerability fixes
+    security hardening
+    dependency updates for security
+
+
+PHASE 2: SEMANTIC VERSIONING
+
+
+semver basics
+
+semantic versioning: MAJOR.MINOR.PATCH
+
+  MAJOR
+    incompatible API changes
+    examples:
+      - remove a public function
+      - change function signature
+      - modify behavior contract
+
+  MINOR
+    backwards-compatible functionality
+    examples:
+      - add new public function
+      - add new optional parameter
+      - add new feature flag
+
+  PATCH
+    backwards-compatible bug fixes
+    examples:
+      - fix crash condition
+      - fix incorrect output
+      - fix edge case handling
+
+
+version bumping rules
+
+  [1.0.0] -> [1.0.1]
+    patch release
+    fixed a bug
+
+  [1.0.1] -> [1.1.0]
+    minor release
+    added a feature
+
+  [1.1.0] -> [2.0.0]
+    major release
+    breaking change
+
+  pre-release versions:
+    [1.0.0-alpha], [1.0.0-alpha.1], [1.0.0-beta], [1.0.0-rc.1]
+
+
+development versions
+
+during development, use pre-release identifiers:
+
+  - alpha
+    internal testing, not feature complete
+    [1.0.0-alpha]
+
+  - beta
+    feature complete, public testing
+    [1.0.0-beta]
+
+  - rc (release candidate)
+    testing for bugs, no new features
+    [1.0.0-rc.1]
+
+  ordering: alpha < beta < rc < final
+
+
+PHASE 3: CONVENTIONAL COMMITS
+
+
+commit message format
+
+conventional commits work hand-in-hand with changelogs:
+
+  <type>[optional scope]: <description>
+
+  [optional body]
+
+  [optional footer(s)]
+
+types:
+  feat:     new feature
+  fix:      bug fix
+  docs:     documentation only
+  style:    formatting, no code change
+  refactor: code change without feature/fix
+  perf:     performance improvement
+  test:     adding or updating tests
+  chore:    maintenance tasks
+  ci:       CI/CD changes
+  build:    build system changes
+  revert:   revert a previous commit
+
+
+examples:
+
+  feat: add plugin system
+  feat(api): add streaming endpoint
+  fix: correct memory leak in parser
+  fix(auth): resolve token expiry issue
+  docs: update installation guide
+  chore: upgrade dependencies
+  perf: reduce database query time
+  ci: add github actions workflow
+
+
+breaking changes
+
+mark breaking changes in commit:
+
+  feat!: redesign user interface
+
+or with body:
+
+  feat(api): remove deprecated endpoint
+
+  BREAKING CHANGE: endpoint /v1/users no longer exists
+
+
+scope usage
+
+scope categorizes changes by module/area:
+
+  feat(auth): add oauth2 support
+  fix(database): resolve connection pool issue
+  docs(readme): update quick start
+  refactor(ui): extract component library
+
+common scopes:
+  - core, api, cli, ui
+  - auth, database, storage
+  - readme, contributing, guide
+
+
+PHASE 4: CREATING A NEW CHANGELOG
+
+
+initial changelog setup
+
+  <create>
+  <file>CHANGELOG.md</file>
+  <content>
+  # Changelog
+
+  All notable changes to this project will be documented in this file.
+
+  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+  [Unreleased]
+
+  ## [0.1.0] - YYYY-MM-DD
+
+  ### Added
+  - Initial release
+  </content>
+  </create>
+
+
+migrating from no changelog
+
+if you have existing releases without a changelog:
+
+  [1] list all git tags
+      <terminal>git tag --list | sort -V</terminal>
+
+  [2] for each significant release, analyze commits:
+      <terminal>git log --pretty=format:"%h %s" <prev-tag>..<tag></terminal>
+
+  [3] create changelog entries retroactively
+      focus on user-facing changes only
+
+  [4] use approximate dates from tags:
+      <terminal>git log -1 --format=%ai <tag></terminal>
+
+
+migrating from custom format
+
+if you have an existing changelog in non-standard format:
+
+  [1] preserve the history
+      don't delete existing entries
+
+  [2] create a new section following keep a changelog
+      start with [Unreleased]
+
+  [3] gradually migrate old entries
+      if time permits, reformat historical entries
+
+  [4] note the format change
+      add note explaining the switch
+
+
+PHASE 5: THE UNRELEASED SECTION
+
+
+purpose of unreleased
+
+collect changes that haven't been released yet:
+
+  [Unreleased]
+
+  ### Added
+  - New feature in progress
+
+  ### Changed
+  - Modified existing feature
+
+  ### Fixed
+  - Bug that was fixed but not released
+
+
+working with unreleased
+
+as you make changes, add them to [Unreleased]:
+
+  commit: feat(api): add streaming endpoint
+
+  immediately add to CHANGELOG.md:
+
+  [Unreleased]
+
+  ### Added
+  - Streaming endpoint for real-time responses
+
+
+releasing from unreleased
+
+when releasing:
+
+  [1] create version header
+      move unreleased items to new version
+
+  [2] add release date
+      use ISO format (YYYY-MM-DD)
+
+  [3] create new unreleased section
+      empty placeholder for next release
+
+  [4] create git tag
+      <terminal>git tag -a v1.2.0 -m "Release v1.2.0"</terminal>
+
+
+PHASE 6: WRITING EFFECTIVE CHANGE ENTRIES
+
+
+entry writing guidelines
+
+  [1] write for users, not developers
+      explain the impact, not the implementation
+
+  [2] be specific but concise
+      what changed and why it matters
+
+  [3] use active voice
+      "Added feature" not "Feature was added"
+
+  [4] group related changes
+      list multiple related items as sub-bullets
+
+
+good vs bad entries
+
+  bad:
+    - Fixed bug in parser
+
+  good:
+    - Fixed parser crash when handling nested comments
+
+  bad:
+    - Performance improvements
+
+  good:
+    - Reduced startup time by 40% through lazy loading
+
+  bad:
+    - Changed API
+
+  good:
+    - Changed authentication to require API key in header
+
+
+migration entries
+
+for breaking changes, provide migration path:
+
+  ### Changed
+
+  - Authentication header now requires Bearer token
+    Migration: Update requests to include `Authorization: Bearer <token>`
+    instead of `X-API-Key: <key>`
+
+  - Database schema for users now requires email field
+    Migration: Run `python migrations/add_user_email.py` before upgrading
+
+
+scope prefixes
+
+use scope prefixes for clarity:
+
+  - (auth) Added OAuth2 support
+  - (cli) New --verbose flag for debugging
+  - (docs) Updated API reference
+
+scopes help users find relevant changes quickly.
+
+
+PHASE 7: LINKING CHANGELOG TO COMMITS
+
+
+commit linking strategies
+
+provide traceability from changelog to code:
+
+  ### Added
+  - New plugin system (abc1234)
+
+or with issue:
+
+  ### Added
+  - New plugin system (#123)
+
+or with both:
+
+  ### Added
+  - New plugin system (abc1234, closes #123)
+
+
+automatic linking
+
+github/gitlab auto-link patterns:
+
+  #123 links to issue 123
+  abc1234 links to commit abc1234
+  @username links to user
+
+use these in changelog entries:
+
+
+  ### Fixed
+  - Memory leak in connection pool (@devuser, #456)
+
+
+link format in versions
+
+at the bottom, add version links:
+
+  [Unreleased]: https://github.com/user/repo/compare/v1.0.0...HEAD
+  [1.0.0]: https://github.com/user/repo/compare/v0.9.0...v1.0.0
+  [0.9.0]: https://github.com/user/repo/releases/tag/v0.9.0
+
+allows clicking version to see diff.
+
+
+PHASE 8: HANDLING DIFFERENT CHANGE TYPES
+
+
+added entries
+
+feature additions:
+
+  ### Added
+  - Plugin system for extensibility
+  - Support for OpenAI and Anthropic APIs
+  - Configuration file validation
+  - (cli) --version flag to display current version
+  - (docs) Plugin development guide
+
+
+changed entries
+
+behavior modifications:
+
+  ### Changed
+  - Default timeout increased from 30s to 60s
+  - Error messages now include troubleshooting hints
+  - (api) Response format includes metadata field
+  - (ui) Status indicators use color by default
+
+
+deprecated entries
+
+features being phased out:
+
+  ### Deprecated
+  - Old API endpoint /v1/chat (use /v2/chat instead)
+  - --legacy flag (will be removed in 2.0.0)
+  - Python 3.10 support (migrate to 3.11+)
+
+
+removed entries
+
+deleted features:
+
+  ### Removed
+  - Support for Python 3.9 (end of life)
+  - Deprecated REST API v1
+  - Old configuration file format
+
+
+fixed entries
+
+bug fixes:
+
+  ### Fixed
+  - Crash when handling empty response from API
+  - Memory leak in long-running sessions
+  - (auth) Token refresh now happens correctly
+  - (cli) Input not being saved in pipe mode
+
+
+security entries
+
+vulnerability fixes:
+
+  ### Security
+  - Updated dependency to fix CVE-2024-12345
+  - API keys now excluded from debug logs
+  - Added input validation for file operations
+
+
+PHASE 9: RELEASE NOTES VS CHANGELOG
+
+
+changelog vs release notes
+
+changelog:
+  - comprehensive record of all changes
+  - developer-focused
+  - updated continuously
+  - includes all commit types
+
+release notes:
+  - highlights for end users
+  - marketing-friendly
+  - crafted for each release
+  - focuses on features and fixes
+
+
+generating release notes from changelog
+
+for a GitHub release, extract:
+
+  [1] headline features from Added
+  [2] important fixes from Fixed
+  [3] migration notes from Changed/Removed
+  [4] security issues from Security
+
+example release notes:
+
+  What's New in v1.2.0
+
+  Features:
+  - Plugin system for extending functionality
+  - Support for multiple LLM providers
+
+  Fixes:
+  - Fixed crash when handling empty responses
+  - Resolved memory leak in long sessions
+
+  Upgrade Notes:
+  - If using the old REST API, migrate to v2 before upgrading
+  - Update configuration files to new format
+
+  Security:
+  - Updated dependency for CVE-2024-12345
+
+
+PHASE 10: AUTOMATED CHANGELOG TOOLS
+
+
+commitizen / cz-cli
+
+standardized commit messages with automatic changelog:
+
+  <terminal>npm install -g commitizen cz-conventional-changelog</terminal>
+  <terminal>echo '{ "path": "cz-conventional-changelog" }' > ~/.czrc</terminal>
+
+use:
+  <terminal>git cz</terminal>
+
+prompts for:
+  - type (feat, fix, docs, etc.)
+  - scope
+  - description
+  - body
+  - breaking changes
+
+
+standard-version
+
+automated versioning and changelog:
+
+  <terminal>npm install -g standard-version</terminal>
+
+run before release:
+  <terminal>standard-version</terminal>
+
+automatically:
+  - bumps version in package.json
+  - updates CHANGELOG.md from commits
+  - commits the changes
+  - tags the release
+
+
+release-please
+
+github action for automated releases:
+
+  .github/workflows/release-please.yml:
+    name: Release Please
+
+    on:
+      push:
+        branches: [main]
+
+    permissions:
+      contents: write
+
+    jobs:
+      release-please:
+        runs-on: ubuntu-latest
+        steps:
+          - uses: googleapis/release-please-action@v3
+
+          with:
+            release-type: python
+            package-name: kollabor
+
+
+semantic-release
+
+fully automated releases:
+
+  <terminal>npm install -D semantic-release</terminal>
+
+  .releaserc.json:
+    {
+      "branches": ["main"],
+      "plugins": [
+        "@semantic-release/commit-analyzer",
+        "@semantic-release/release-notes-generator",
+        "@semantic-release/changelog",
+        "@semantic-release/npm",
+        "@semantic-release/git",
+        "@semantic-release/github"
+      ]
+    }
+
+analyzes commits to determine version bump automatically.
+
+
+PHASE 11: CHANGELOG FOR DIFFERENT PROJECT TYPES
+
+
+library changelog
+
+focus on API changes:
+
+  # Changelog
+
+  ## [2.0.0] - 2024-01-15
+
+  ### Added
+  - async variants of all core functions
+  - type hints for public API
+
+  ### Changed
+  - (api) parse() now returns Result object instead of raising
+  - minimum Python version increased to 3.11
+
+  ### Deprecated
+  - parse() with raise_exception=False (use parse_safe())
+
+  ### Removed
+  - Python 3.10 support
+  - legacy Config class (use ConfigBuilder)
+
+  ### Fixed
+  - type hints corrected for generic types
+
+
+application changelog
+
+focus on features and fixes:
+
+  # Changelog
+
+  ## [1.5.0] - 2024-01-15
+
+  ### Added
+  - Dark mode theme
+  - Export conversations as markdown
+  - Keyboard shortcuts for common actions
+
+  ### Changed
+  - Improved startup performance
+  - Redesigned settings interface
+
+  ### Fixed
+  - Fixed crash when loading large conversations
+  - Corrected scrolling behavior in chat view
+
+
+cli tool changelog
+
+focus on commands and options:
+
+  # Changelog
+
+  ## [2.0.0] - 2024-01-15
+
+  ### Added
+  - --watch flag for continuous monitoring
+  - --format option for json output
+
+  ### Changed
+  - default verbosity level (use -v for more output)
+  - --output flag now accepts directory paths
+
+  ### Removed
+  - --legacy flag (use --compat instead)
+
+  ### Fixed
+  - pipe mode now handles binary data correctly
+
+
+PHASE 12: CHANGELOG IN THE RELEASE PROCESS
+
+
+pre-release checklist
+
+before cutting a release:
+
+  [ ] review unreleased section
+  [ ] categorize all uncategorized items
+  [ ] verify all entries are user-facing
+  [ ] add migration notes for breaking changes
+  [ ] link to relevant issues/commits
+  [ ] set version number based on semver
+  [ ] add release date
+
+
+release workflow
+
+  [1] prepare the changelog
+      create version section from unreleased
+
+  [2] create release notes
+      craft user-friendly summary
+
+  [3] update version file
+      <terminal># edit version in appropriate file</terminal>
+
+  [4] commit the changelog
+      <terminal>git add CHANGELOG.md</terminal>
+      <terminal>git commit -m "chore: prepare release v1.2.0"</terminal>
+
+  [5] create the tag
+      <terminal>git tag -a v1.2.0 -m "Release v1.2.0"</terminal>
+
+  [6] push tag to trigger release
+      <terminal>git push origin v1.2.0</terminal>
+
+  [7] create new unreleased section
+      empty section for next cycle
+
+
+post-release
+
+  [ ] verify release notes rendered correctly
+  [ ] check changelog links work
+  [ ] announce release (if applicable)
+  [ ] update documentation with new features
+  [ ] close related issues
+
+
+PHASE 13: HANDLING HOTFIXES
+
+
+hotfix changelog entry
+
+for urgent fixes:
+
+  # Changelog
+
+  [Unreleased]
+  ### Fixed
+  - Hotfix items here
+
+  ## [1.2.1] - 2024-01-16
+
+  ### Fixed
+  - Critical security vulnerability in auth
+  - Regression introduced in 1.2.0
+
+
+hotfix process
+
+  [1] create hotfix branch from release tag
+      <terminal>git checkout -b hotfix/1.2.1 v1.2.0</terminal>
+
+  [2] add fix and update changelog
+      create version section for hotfix
+
+  [3] commit, tag, release hotfix
+      <terminal>git tag -a v1.2.1 -m "Hotfix v1.2.1"</terminal>
+
+  [4] merge back to main and develop
+      <terminal>git checkout main && git merge hotfix/1.2.1</terminal>
+
+  [5] main unreleased should stay intact
+      don't lose changes already tracked there
+
+
+PHASE 14: CHANGELOG QUALITY CHECKLIST
+
+
+before publishing a changelog:
+
+  [ ] follows keep a changelog format
+  [ ] versions in chronological order (newest top)
+  [ ] each version has release date
+  [ ] categories properly used (added, changed, etc.)
+  [ ] entries are user-facing, not implementation details
+  [ ] breaking changes include migration notes
+  [ ] entries use active voice
+  [ ] scope prefixes used where helpful
+  [ ] commit/issue links provided
+  [ ] version links at the bottom
+  [ ] no typos or grammatical errors
+  [ ] unreleased section exists (even if empty)
+
+
+testing your changelog
+
+  <terminal># verify markdown renders correctly</terminal>
+  <terminal># check that all links work</terminal>
+  <terminal># ensure version ordering is correct</terminal>
+  <terminal># confirm dates are in ISO format</terminal>
+
+
+PHASE 15: COMMON CHANGELOG ANTI-PATTERNS
+
+
+anti-pattern: implementation details
+
+problem: entries describe how, not what
+
+  bad:
+    - Refactored parser to use new library
+    - Changed variable names in auth module
+
+  good:
+    - Improved parsing error messages
+    - Fixed authentication edge case
+
+
+anti-pattern: missing migration info
+
+problem: breaking changes without guidance
+
+  bad:
+    ### Changed
+    - Removed old API endpoint
+
+  good:
+    ### Changed
+    - Removed deprecated /v1/chat endpoint
+      Migration: Update to /v2/chat endpoint (see migration guide)
+
+
+anti-pattern: vague entries
+
+problem: non-specific descriptions
+
+  bad:
+    - Various improvements
+    - Bug fixes
+    - Performance optimizations
+
+  good:
+    - Reduced database query time by 40%
+    - Fixed crash when handling unicode input
+    - Added caching for API responses
+
+
+anti-pattern: developer-only changes
+
+problem: listing internal changes
+
+  bad:
+    - Added unit tests
+    - Updated dependencies
+    - Fixed linting errors
+
+  (these should be in commit history, not changelog)
+
+  good:
+    (only include what affects users)
+
+
+anti-pattern: wrong categorization
+
+problem: misclassifying changes
+
+  bad:
+    - New feature listed under "Fixed"
+    - Removal listed under "Changed"
+
+  good:
+    - New features under "Added"
+    - Removals under "Removed"
+    - Behavior modifications under "Changed"
+
+
+PHASE 16: MAINTAINING CHANGELOG CONSISTENCY
+
+
+entry formatting
+
+consistent style within changelog:
+
+  ### Added
+  - Feature name
+    Additional details if needed
+
+  - Another feature
+    Details spanning
+    multiple lines
+
+  - Scope: Feature with scope prefix
+
+
+capitalization
+
+  [ok] Added, Changed, Deprecated, Removed, Fixed, Security
+  [ok] Each entry starts with capital letter
+  [ok] Proper nouns and acronyms capitalized (API, URL, JSON)
+
+
+punctuation
+
+  [ok] entries don't end with periods
+  [ok] complete sentences in details end with periods
+  [ok] lists don't use trailing punctuation
+
+
+version format
+
+  ## [1.2.3] - 2024-01-15
+
+  - version in brackets
+  - space after bracket
+  - dash before date
+  - ISO date format
+  - no time in date
+
+
+PHASE 17: CHANGELOG FOR MONOREPOS
+
+
+monorepo changelog strategies
+
+for projects with multiple packages:
+
+option 1: single changelog
+
+  # Changelog
+
+  ## [2.0.0] - 2024-01-15
+
+  ### Added
+  - (package-a) New feature in package-a
+  - (package-b) New feature in package-b
+
+  ### Changed
+  - (core) Core library change affecting all packages
+
+
+option 2: per-package changelogs
+
+  package-a/CHANGELOG.md
+  package-b/CHANGELOG.md
+  CHANGELOG.md (root, for project-wide changes)
+
+
+option 3: combined with sections
+
+  # Changelog
+
+  ## [2.0.0] - 2024-01-15
+
+  ### package-a
+  - New feature
+  - Bug fix
+
+  ### package-b
+  - Different feature
+  - Different fix
+
+
+choosing the right approach
+
+  small monorepos (2-3 packages)
+    use single changelog with scope prefixes
+
+  medium monorepos (3-10 packages)
+    use per-package changelogs with root summary
+
+  large monorepos (10+ packages)
+    use independent per-package changelogs
+    generate combined view automatically
+
+
+PHASE 18: CHANGELOG ANALYSIS AND REPORTING
+
+
+extracting insights
+
+changelog data can inform decisions:
+
+  release frequency
+    analyze version dates to find release cadence
+
+  change type distribution
+    count categories to find project focus
+
+  breaking changes
+    track breaking changes to assess stability
+
+  hotfix frequency
+    many hotfixes indicates quality issues
+
+
+example analysis
+
+  <terminal># count changes by type in last year</terminal>
+  <terminal>grep "^###" CHANGELOG.md | sort | uniq -c</terminal>
+
+  <terminal># find release frequency</terminal>
+  <terminal>grep "^## \[" CHANGELOG.md | head -20</terminal>
+
+
+PHASE 19: CHANGELOG RULES (STRICT MODE)
+
+
+while this skill is active, these rules are MANDATORY:
+
+  [1] ALWAYS use keep a changelog format
+      categories: added, changed, deprecated, removed, fixed, security
+
+  [2] write for USERS, not developers
+      explain the impact of changes
+      omit internal implementation details
+
+  [3] include unreleased section
+      place at top of changelog
+      even if empty, keep the placeholder
+
+  [4] use semantic versioning
+      MAJOR.MINOR.PATCH
+      determine version from actual changes
+
+  [5] add release date to each version
+      format: YYYY-MM-DD
+      no time component
+
+  [6] link to issues and commits
+      provide traceability
+      use (#123) or (abc1234) format
+
+  [7] include migration notes for breaking changes
+      tell users how to update their code
+      link to detailed migration guides if needed
+
+  [8] update changelog BEFORE release
+      not after, not during
+      changelog is part of the release
+
+  [9] use active voice in entries
+      "Added feature" not "Feature was added"
+      start each entry with a verb
+
+  [10] never clear changelog history
+      keep all historical entries
+      project history is valuable
+
+
+FINAL REMINDERS
+
+
+changelog is user-facing documentation
+
+treat it with same care as API docs.
+it's often the first thing users check when upgrading.
+
+
+consistency builds trust
+
+consistent format and quality signals professionalism.
+users trust projects with well-maintained changelogs.
+
+
+changelog enables fearless upgrades
+
+clear migration notes and change descriptions
+let users upgrade with confidence.
+
+when in doubt
+
+document more rather than less.
+users can skip irrelevant info,
+but missing info causes confusion and frustration.
+
+the goal
+
+transparent project history.
+clear upgrade paths.
+informed user base.
+
+now go document your changes.