changelog-priorities-pattern

Playbook — CHANGELOG.md + priorities.md auto-update pattern

Goal: keep CHANGELOG.md and docs/priorities.md current across every p24 ecosystem project with minimal manual effort. This playbook is the source of truth for the rollout — copy the templates below into each target repo.

Origin issue: #2231.

p24-infra is DB-backed as of #5391 (phase 2 of #5364). The templates and rollout checklist below (plain hand-edited docs/priorities.md) describe the pattern as it still applies to the other 5 repos — whatsup-android-chat-puller, et-operational-platform, Art-Agency, brandpilot, radekkonarski-personal-brand. In p24-infra only, docs/priorities.md is now generated read-only output of scripts/priorities.py render: the structured P0–P3/human-action rows live in Supabase dev_r_priorities, the narrative session log in dev_r_agent_sessions (type='interactive'), and the write path is scripts/priorities.py add/update/resolve/ log — never a hand edit of the file. This removes the concurrent-checkout merge-collision class the markdown pattern documented against itself. Migrating the other 5 repos to the same DB-backed pattern is explicitly out of scope for 5364 phase 1–2; revisit later if the collision problem recurs there too. See docs/playbooks/priorities-status-sync.md for the DB-backed resolution/render operations, and CLAUDE.md §Changelog & Priorities for the current p24-infra session-start/session-end instructions.

---

The pattern in one screen

Three changelog triggers

1. On PR merge to dev — append the PR’s changes to [Unreleased] in CHANGELOG.md (/update-changelog --pr <N>, or the optional GH Actions hook in §4).
2. On session end — /update-changelog (no args) fills any gaps from recent commits.
3. On release cut (rc/vX.Y.Z → main) — /update-changelog --release X.Y.Z renames [Unreleased] → [X.Y.Z] — YYYY-MM-DD and opens a fresh [Unreleased].

Two priorities triggers

1. At session start — read docs/priorities.md to orient on active P0/P1 risks.
2. At session end — remove completed items, add new risks/blockers, bump Last updated:.

The generic skill lives at .claude/commands/update-changelog.md (this repo) and is deployed to ~/.claude/commands/update-changelog.md on each workstation/runner so every repo can call it.

---

1. Template — CHANGELOG.md

# Changelog
 
All notable changes to <project> are documented here, in
[Keep a Changelog](https://keepachangelog.com) format.
 
## [Unreleased]
 
### Added
### Changed
### Fixed
### Removed
 
---
 
## [X.Y.Z] — YYYY-MM-DD
 
### Fixed
- Description of the change (#PR)

Backfill the first released block from the repo’s existing version history (e.g. for whatsup-android-chat-puller, import the latest entry from docs/playbook-release-versioning.md as the [0.3.12] block). Keep empty subsections in [Unreleased] — the skill relies on them.

2. Template — docs/priorities.md

# Priorities — <project>
Last updated: YYYY-MM-DD
 
Living checklist of active risks, maintenance items, and strategic initiatives.
Update at the start/end of each substantive session.
 
## 🔴 P0 — Active risks (fix before next release)
| Item | Status | Issue / Ref |
|---|---|---|
 
## 🟠 P1 — Do this sprint
| Item | Status | Issue / Ref |
|---|---|---|
 
## 🟡 P2 — Backlog / opportunistic
| Item | Status | Issue / Ref |
|---|---|---|

Seed it with the repo’s known active risks (from memory, open issues, or the team).

3. Template — ## Changelog & Priorities section for each repo’s CLAUDE.md

Paste this block into every project’s CLAUDE.md. It is written so any spawned agent follows it without extra instructions in its prompt.

## Changelog & Priorities
 
**`CHANGELOG.md`** (repo root, Keep-a-Changelog format with an `[Unreleased]` section) — keep current:
 
1. **On PR merge to `dev`** — add the merged change to `[Unreleased]`: `/update-changelog --pr <N>`.
2. **At session end** — run `/update-changelog` (no args) to fill gaps from recent commits.
3. **On release cut** (`rc/*` → `main`) — `/update-changelog --release <X.Y.Z>` renames
   `[Unreleased]` → `[X.Y.Z] — YYYY-MM-DD` and opens a fresh `[Unreleased]`.
 
**`docs/priorities.md`** — orient and maintain:
 
1. **At session start** — read it to see active P0/P1 risks before starting work.
2. **At session end** — strike completed items, add new risks/blockers, bump `Last updated:`.
   Commit the update with the session's work, or standalone as `docs: update priorities`.

If a repo already has a “Session Start & End — priorities.md” section (as p24-infra does), fold the changelog triggers in and cross-reference the existing priorities text instead of duplicating it.

4. Optional (P2) — GH Actions hook .github/workflows/update-changelog.yml

Skill-first is sufficient to start. Add this only once a repo wants the update to happen without a human running the skill. It MUST follow the p24-infra error-notification standard (Discord embed + GH issue on failure). Template:

name: update-changelog
on:
  pull_request:
    types: [closed]
    branches: [dev]
jobs:
  changelog:
    if: github.event.pull_request.merged == true
    runs-on: self-hosted
    steps:
      - uses: actions/checkout@v4
        with: { ref: dev, fetch-depth: 0 }
      - name: Update [Unreleased] from merged PR
        run: python scripts/ci/update_changelog.py --pr "${{ github.event.pull_request.number }}"
      - name: Commit
        run: |
          git config user.name "changelog-bot"
          git config user.email "ecotrans.automation@gmail.com"
          git add CHANGELOG.md
          git diff --cached --quiet || git commit -m "docs: update changelog (#${{ github.event.pull_request.number }})"
          git push origin dev
      - name: Notify on failure
        if: failure()
        env:
          HOOK: ${{ secrets.P24_DISCORD_INFRA_SCRIPTS_ERRORS_WEBHOOK_URL }}
        run: |
          curl -s -X POST "$HOOK" -H "Content-Type: application/json" \
            -d '{"embeds":[{"title":"RED ERROR — update-changelog","color":15158332,"description":"PR #${{ github.event.pull_request.number }} changelog update failed"}]}'
          gh issue create --repo ${{ github.repository }} \
            --title "[Infra] update-changelog — workflow failed (PR #${{ github.event.pull_request.number }})" \
            --label bug --body "update-changelog.yml failed; see the run log."

scripts/ci/update_changelog.py (the non-interactive twin of the skill) is intentionally not shipped yet — build it when the first repo adopts the P2 hook, so it can be tested against a real PR.

---

Per-repo rollout checklist (Wave 2)

Apply in this order; start with whatsup as the reference implementation. Each is a separate PR to that repo’s dev branch — a p24-infra worker cannot do it cross-repo, so each gets its own issue.

For every repo:

• Create CHANGELOG.md from §1 (backfill the latest release block from the repo’s version history)
• Create docs/priorities.md from §2 (seed with known active risks)
• Add the ## Changelog & Priorities section from §3 to CLAUDE.md
• Deploy the global skill (below) so /update-changelog resolves in that repo

Order	Repo	Notes
1	radieu/whatsup-android-chat-puller	Reference impl. Import [0.3.12] from docs/playbook-release-versioning.md. Highest release frequency.
2	radieu/et-operational-platform	Already has the et-specific update-changelogs (plural) skill — keep it; add this generic one alongside.
3	radieu/Art-Agency	Portal, periodic releases.
4	radieu/brandpilot	Brand automation, active.
5	radekkonarski-personal-brand	Content repo, lower frequency.

Global skill deployment

The canonical copy is .claude/commands/update-changelog.md in this repo. To make /update-changelog available everywhere, copy it to each workstation/runner’s global command dir:

cp .claude/commands/update-changelog.md ~/.claude/commands/update-changelog.md

Do this on the dev workstation and on the bms-4 / vps-i1 runners.