changelog

Use when an internal or player-facing changelog must be drafted from repository and production history.

SKILL.md

GitHub
<!-- codex-studio-delegation: governed -->

Resolve every role through ../../../.codex/docs/plugin-agent-delegation.md; do not require a repository-local .codex/agents/ or .codex/agent-packs/ tree. Before default delegation, run python3 ../../../tools/codex_studio/agent_delegation.py resolve --project-root <project-root> --role <role> and use only its returned role contract.

Codex Interaction Contract

  • Ask one decision question per turn and wait for the answer before asking another.
  • Use request_user_input for structured choices when it is available; otherwise ask the same concise question directly.
  • Use Codex custom agents by role and profile when delegation is useful.
  • Treat any approved write as one complete proposed changeset. Before writing, present every target path and material edit together; do not add unlisted files or behavior.
  • A new path, expanded scope, or material change requires a revised complete proposed changeset and fresh approval.

Output Safety

Draft both changelog variants in conversation. Before writing either file, show their complete proposed changeset with every target path and ask once for approval.

Phase 1: Parse Arguments

Read the argument for the target version or sprint number. If a version is given, use the corresponding git tag. If a sprint number is given, use the sprint date range.

Verify the repository is initialized: run git rev-parse --is-inside-work-tree to confirm git is available. If not a git repo, inform the user and abort gracefully.


Phase 2: Gather Change Data

Read the git log since the last tag or release:

git log --oneline [last-tag]..HEAD

If no tags exist, read the full log or a reasonable recent range (last 100 commits).

Read sprint reports from production/sprints/ for the relevant period to understand planned work and context behind changes.

Read completed design documents from design/gdd/ for any new features implemented during this period.


Phase 3: Categorize Changes

Categorize every change into one of these categories:

  • New Features: Entirely new gameplay systems, modes, or content
  • Improvements: Enhancements to existing features, UX improvements, performance gains
  • Bug Fixes: Corrections to broken behavior
  • Balance Changes: Tuning of gameplay values, difficulty, economy
  • Known Issues: Issues the team is aware of but have not yet resolved
  • Miscellaneous: Changes that do not fit the above categories, or commits whose messages are too vague to classify confidently

For each commit, check whether the message contains a task ID or story reference (e.g. [STORY-123], TR-, #NNN, or similar). Count commits that lack any task reference and include this count in the Phase 4 Metrics section as: Commits without task reference: [N].


Phase 4: Generate Internal Changelog

# Internal Changelog: [Version]
Date: [Date]
Sprint(s): [Sprint numbers covered]
Commits: [Count] ([first-hash]..[last-hash])

## New Features
- [Feature Name] -- [Technical description, affected systems]
  - Commits: [hash1], [hash2]
  - Owner: [who implemented it]
  - Design doc: [link if applicable]

## Improvements
- [Improvement] -- [What changed technically and why]
  - Commits: [hashes]
  - Owner: [who]

## Bug Fixes
- [BUG-ID] [Description of bug and root cause]
  - Fix: [What was changed]
  - Commits: [hashes]
  - Owner: [who]

## Balance Changes
- [What was tuned] -- [Old value -> New value] -- [Design intent]
  - Owner: [who]

## Technical Debt / Refactoring
- [What was cleaned up and why]
  - Commits: [hashes]

## Miscellaneous
- [Change that didn't fit other categories, or vague commit message]
  - Commits: [hashes]

## Known Issues
- [Issue description] -- [Severity] -- [ETA for fix if known]

## Metrics
- Total commits: [N]
- Files changed: [N]
- Lines added: [N]
- Lines removed: [N]
- Commits without task reference: [N]

Phase 5: Generate Player-Facing Changelog

# What is New in [Version]

## New Features
- **[Feature Name]**: [Player-friendly description of what they can now do
  and why it is exciting. Focus on the experience, not the implementation.]

## Improvements
- **[What improved]**: [How this makes the game better for the player.
  Be specific but avoid jargon.]

## Bug Fixes
- Fixed an issue where [describe what the player experienced, not what was
  wrong in the code]
- Fixed [player-visible symptom]

## Balance Changes
- [What changed in player-understandable terms and the design intent.
  Example: "Healing potions now restore 50 HP (up from 30) -- we felt
  players needed more recovery options in late-game encounters."]

## Known Issues
- We are aware of [issue description in player terms] and are working on a
  fix. [Workaround if one exists.]

---
Thank you for playing! Your feedback helps us make the game better.
Report issues at [link].

Phase 6: Output

Output both changelogs to the user. The internal changelog is the primary working document. The player-facing changelog is ready for community posting after review.


Phase 7: Complete Proposed Changeset

Present the internal and player-facing drafts first. The canonical saved output is docs/CHANGELOG.md. Show the exact insertion as the complete proposed changeset and ask once for approval.

  • If docs/CHANGELOG.md exists, append the new version section without replacing prior history and place newest entries first at the top of the version list.
  • If it does not exist, create it with the new version section.
  • Keep the player-facing variant in conversation for $patch-notes; do not invent a second changelog path.
  • Write only the approved insertion. Any different path or changed content requires revised approval.

After an approved write: Verdict: CHANGELOG WRITTEN. If declined: Verdict: COMPLETE — changelog generated in conversation.

Phase 7: Next Steps

  • Use $patch-notes [version] to generate a styled, saved version for public release.
  • Use $release-checklist before publishing the changelog externally.

Guidelines

  • Never expose internal code references, file paths, or developer names in the player-facing changelog
  • Group related changes together rather than listing individual commits
  • If a commit message is unclear, check the associated files and sprint data for context
  • Balance changes should always include the design reasoning, not just the numbers
  • Known issues should be honest — players appreciate transparency
  • If the git history is messy (merge commits, reverts, fixup commits), clean up the narrative rather than listing every commit literally