Smaqit Release Analysis

Release Analysis

Analyze repository changes since the last release, assess their severity, and suggest the next semantic version.

When to use this skill

Use this skill at the start of a release workflow to:

• Collect all changes since the last git tag
• Assess whether changes constitute a MAJOR, MINOR, or PATCH release
• Suggest the next semantic version based on change severity

How to execute

Step 1: Find Latest Git Tag

Run git tag --sort=-v:refname to list existing tags in descending version order.

git tag --sort=-v:refname | head -1

If no tags exist, the repository is at version 0.0.0 and the suggested version will be v0.1.0.

Step 2: Collect Changes

Collect changes from three sources:

A. Git commit history:

git log <last-tag>..HEAD --pretty=format:"%s"

If no tags exist:

git log --pretty=format:"%s"

B. File changes analysis: Analyze actual file modifications to supplement commit messages. This is especially important in grafted/shallow repositories where commit history may be incomplete.

# If tags exist:
git diff <last-tag>..HEAD --stat --name-status

# If no tags exist (compare against empty tree):
git diff 4b825dc5c39fd418cd129ae01eb94d5aa75a7d7f..HEAD --stat --name-status

Extract key insights:

• New files added (especially features, agents, skills, workflows)
• Modified core components (installers, configuration)
• Deleted functionality (potential breaking changes)
• Number of files changed and scope of modifications

C. Session history (if exists): Read markdown files in .smaqit/history/ directory. These contain documented session work with completed tasks and decisions.

Step 3: Assess Change Severity

Analyze the collected changes from commit messages, file changes, and session history to determine severity level:

MAJOR (X.0.0) - Breaking changes:

• Removed features or commands
• Changed behavior that breaks existing usage
• Incompatible API changes
• Deleted files that were part of public API
• Keywords to look for: "Breaking", "Removed", "Incompatible"
• File patterns: Deletions of core functionality

MINOR (0.X.0) - New features, non-breaking changes:

• Added features, commands, or capabilities
• New functionality
• Deprecated features (warning, not removal)
• New files added (agents, skills, workflows)
• Keywords to look for: "Added", "New", "Deprecated"
• File patterns: New agents/, skills/ files

PATCH (0.0.X) - Bug fixes only:

• Fixed bugs or issues
• Documentation updates
• Internal refactoring with no user-facing changes
• Keywords to look for: "Fixed", "Corrected", "Bug"
• File patterns: Changes to existing files without new features

Step 4: Suggest Next Version

Based on the assessed severity and latest tag, calculate the next semantic version:

• MAJOR: Increment X in vX.Y.Z (e.g., v1.2.3 → v2.0.0)
• MINOR: Increment Y in vX.Y.Z, reset Z to 0 (e.g., v1.2.3 → v1.3.0)
• PATCH: Increment Z in vX.Y.Z (e.g., v1.2.3 → v1.2.4)

Special case: If current version is 0.Y.Z:

• Breaking changes still increment Y, not X (0.Y.Z is pre-1.0 API)
• First stable release should be v1.0.0

Output

Provide a structured summary in YAML format:

changes:
  - type: Added
    description: "Release agent for automated workflow"
    reference: "#123"
  - type: Fixed
    description: "Bug in version detection"
    reference: "#124"
severity: MINOR
latest_tag: v0.2.0
suggested_version: v0.3.0
rationale: "New features added (release agent), no breaking changes detected"

Output fields:

• changes: List of changes with type, description, and optional reference
• severity: MAJOR, MINOR, or PATCH
• latest_tag: Most recent git tag (or "none" if no tags exist)
• suggested_version: Next version following semver rules
• rationale: Brief explanation of the severity assessment

Notes

• This skill only analyzes and suggests - it does not modify any files
• The suggested version is a recommendation that must be approved before use
• Session history files (.smaqit/history/) are optional - if they don't exist, rely solely on git log
• File-based analysis is critical in grafted/shallow repositories where commit history may be incomplete
• Focus on user-facing changes; internal implementation details should not drive severity
• When in doubt between severities, prefer conservative (e.g., MINOR over MAJOR)
• The empty tree SHA 4b825dc5c39fd418cd129ae01eb94d5aa75a7d7f is a Git constant for comparing against an empty state

Converted and distributed by TomeVault — claim your Tome and manage your conversions.