Manual QA tester — tests product behavior like a real user, not code. Triggers on keywords: test, QA, check behavior, verify feature, manual testing, протестируй, потыкай, проверь как работает

2026-05-203

name	release
description	Automated documentation updates — CHANGELOG, README, docs. Fully automatic, no confirmations.
model	sonnet

Release — Automated Documentation Updates

Analyzes git history and automatically updates CHANGELOG, README, and documentation files.

Activation: /release or /release 3.8 (with explicit version)

When to Use

After merging features to main/develop
Before creating a release tag
Weekly documentation maintenance
After significant changes

Process

PHASE 1: COLLECT

Step 1.1: Find Base Commit

git log -1 --format=%H CHANGELOG.md

If CHANGELOG.md doesn't exist, use first commit or last tag.

Step 1.2: Extract Current Version

Read CHANGELOG.md → parse latest version header (e.g., ## [3.7] - 2026-02-14)

Step 1.3: Collect New Commits

git log --oneline BASE_COMMIT..HEAD

Step 1.4: Collect Changed Files

git diff --stat BASE_COMMIT..HEAD

Step 1.5: Filter Commits

Skip:

ai/** files (internal development)
Merge commits (prefix "Merge")
.gitignore-d files
docs: prefix commits (already documented)

PHASE 2: ANALYZE

Step 2.1: Parse Commits

Map Conventional Commits prefixes to CHANGELOG categories:

Prefix	Category
`feat:`	Added
`fix:`	Fixed
`refactor:`	Changed
`BREAKING CHANGE:`	Breaking Changes
`security:`	Security
`perf:`	Changed
`test:`	Skip
`docs:`	Skip
`chore:`	Changed (if user-facing)
`build:`	Architecture
`ci:`	Architecture

Step 2.2: Group Related Commits

Detect patterns:

Same ticket ID: BUG-084-01, BUG-084-02, ..., BUG-084-29 → single entry
Same scope: fix(hooks): X, fix(hooks): Y → single entry
Same component: multiple commits touching same domain

Step 2.3: Rewrite to User-Facing

Technical → User-Facing:

Technical	User-Facing
`fix(hooks): add chmod check`	Hooks — fix permissions error on Windows
`feat(agents): add toc analyst`	Bug Hunt — TOC Analyst for constraint analysis
`refactor(coder): split into modules`	Coder agent — improved modularity (internal)

Step 2.4: Determine Version Bump

Auto-detect (unless explicit version arg):

BREAKING CHANGE → MAJOR (3.7 → 4.0)
feat: → MINOR (3.7 → 3.8)
fix:, chore: → PATCH (3.7.0 → 3.7.1)

If user provided version (e.g., /release 3.8) → use that, warn if downgrade.

Step 2.5: Check README Sections

Read README.md and identify sections needing updates:

Version badge (first line or top)
Skills table (if new skill added)
Project structure (if new directories)
Feature descriptions (if major changes)

Step 2.6: Scan docs/

Check docs/ files referenced by changed files:

Extract doc links from modified code
Check if doc content is stale (version, API, examples)

PHASE 3: EXECUTE

All updates are automatic — no confirmations.

Step 3.1: Update CHANGELOG.md

Prepend new version section:

## [X.Y] - YYYY-MM-DD

### Added
- **Component** — user-facing description

### Changed
- **Component** — what changed and why

### Fixed
- **Component** — what was broken and how fixed

### Removed
- **Component** — removed and replacement

### Security
- **Component** — improvement description

### Architecture
- Technical changes affecting system structure

---

Update Version History table at bottom (if exists).

Step 3.2: Update README.md

Version badge: ![Version](https://img.shields.io/badge/version-X.Y-blue)
Skills table: add new skill row
Project structure: reflect new directories
Feature descriptions: update if major changes

Step 3.3: Update template/README.md

Same as README.md if template has own README.

Step 3.4: Update docs/ Files

Only if provably stale:

Version numbers
API signatures
Code examples
CLI commands

Step 3.5: Update package.json

If packages/create-dld/package.json exists:

{
  "version": "X.Y.Z"
}

PHASE 4: REPORT

Step 4.1: Show Summary

status: completed
version: X.Y
files_modified:
  - path: CHANGELOG.md
    lines_added: 45
    lines_changed: 2
  - path: README.md
    lines_changed: 8
  - path: template/README.md
    lines_changed: 8

changelog_preview: |
  ## [X.Y] - YYYY-MM-DD

  ### Added
  - **Feature** — description

  ### Fixed
  - **Component** — description

Step 4.2: Suggest Next Steps

Next steps:
1. Review changes: git diff
2. Commit: git add CHANGELOG.md README.md docs/ && git commit -m 'docs: release vX.Y'
3. Tag: git tag vX.Y
4. Push: git push && git push --tags

DO NOT auto-commit or auto-tag. Human reviews first.

Edge Cases

Case	Action
No commits since last CHANGELOG	Exit with "Nothing new to document"
Only `ai/` changes	Exit with "Only internal changes, nothing to publish"
No CHANGELOG.md	Create from scratch with current version
No git tags	Use CHANGELOG.md last modification as base
Version arg conflicts	Use explicit arg, warn if downgrade
100+ commits	Summarize by category ("15 bug fixes", "8 features")
README has no version badge	Skip badge update
No package.json	Skip package.json update

Filtering Rules (SSOT)

Include:

.claude/** (if user-facing)
template/.claude/**
template/** (non-.claude)
docs/**
packages/**
src/**

Exclude:

ai/** (internal development)
test/** (not user-facing)
Merge commits
docs: prefix commits (already documented)
.gitignore-d files

Commit Grouping Examples

Example 1: Ticket ID

BUG-084-01 fix(hooks): chmod check
BUG-084-02 fix(hooks): error message
...
BUG-084-29 fix(template): explain tiers

→ **Template framework** — audit: 29 fixes (BUG-084)

Example 2: Same Scope

fix(hooks): chmod check
fix(hooks): error log path
fix(hooks): Windows compatibility

→ **Hooks** — improved error handling and cross-platform support

Example 3: Same Component

feat(agents): add toc analyst
feat(agents): add triz analyst
feat(agents): add validator

→ **Bug Hunt** — three new analysis agents (TOC, TRIZ, Validator)

Changelog Entry Format (Keep a Changelog 1.1.0)

## [X.Y] - YYYY-MM-DD

### Added
- **Feature Name** — user-facing description
- **Component** — what's new

### Changed
- **Component** — what changed and why
- **Agent** — improvement description

### Fixed
- **Component** — what was broken and how fixed
- **Bug** — root cause and solution

### Removed
- **Component** — removed and replacement
- **Deprecated feature** — migration path

### Security
- **Component** — vulnerability fixed or improvement

### Breaking Changes
- **API** — old vs new behavior, migration steps

### Architecture
- Technical changes affecting system structure
- Refactorings, dependency updates (if user-impacting)

---

Rules:

Date format: YYYY-MM-DD
Version format: [X.Y] (brackets required)
Entry format: - **Component** — description (em dash, not hyphen)
Order: Added → Changed → Fixed → Removed → Security → Breaking Changes → Architecture
Skip empty sections

Quality Checklist

Before completing:

Output Format

status: completed | blocked
version: X.Y
commits_analyzed: N
files_modified:
  - path: ...
    lines_added: N
    lines_changed: N
changelog_preview: |
  ...
next_steps: |
  1. Review: git diff
  2. Commit: git add ... && git commit -m 'docs: release vX.Y'
  3. Tag: git tag vX.Y
  4. Push: git push && git push --tags

What NOT to Do

Wrong	Correct
Auto-commit changes	Report, suggest commit command
Auto-create git tag	Suggest tag command
Auto-push to remote	Suggest push command
Ask for confirmation	Fully automatic analysis + updates
Include `ai/` changes	Filter out internal development
One line per commit	Group related commits
Use hyphens in entries	Use em dash (—)
Skip version in README	Update if badge exists