Menu
Generate a human-readable diff between two spec versions showing exactly what changed
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | speckit-changelog-diff |
| description | Generate a human-readable diff between two spec versions showing exactly what changed |
| compatibility | Requires spec-kit project structure with .specify/ directory |
| metadata | {"author":"github-spec-kit","source":"changelog:commands/speckit.changelog.diff.md"} |
Generate a clear, human-readable diff between two versions of a spec. Instead of raw git diffs, produces a structured comparison that shows requirement-level changes, rewording, additions, and removals in plain language.
$ARGUMENTS
You MUST consider the user input before proceeding (if not empty). The user may specify:
.specify/scripts/bash/check-prerequisites.sh --json from the repo root and parsing REPO_ROOT, FEATURE_DIR, and AVAILABLE_DOCS. The spec artifacts live in $FEATURE_DIR/ (under specs/<feature>/), not under .specify/. FEATURE_DIR is absolute; derive the repo-relative form for any git show <ref>:<path> pathspec (which rejects absolute paths): REL_FEATURE_DIR="${FEATURE_DIR#$REPO_ROOT/}".git show "<ref>:$REL_FEATURE_DIR/spec.md".Identify Versions: Show what's being compared.
## Spec Diff
| Field | Version A | Version B |
|-------|-----------|-----------|
| Ref | `a1b2c3d` (v0.9) | `HEAD` (current) |
| Date | 2026-03-15 | 2026-04-11 |
| Author | @developer | @developer |
Requirement Diff: Show requirement-level changes.
## Requirement Changes
### Added (+3)
- ➕ REQ-007: Admin dashboard — manage users and view analytics
- ➕ REQ-008: Email verification — verify email before access
- ➕ REQ-009: Account rate limiting — per-account rate limits
### Modified (2)
- ✏️ REQ-002: Login
- Before: "Users can log in with email and password"
- After: "Users can log in with email/password and optional MFA"
- Change: Added MFA support
- ✏️ REQ-003: JWT tokens
- Before: "JWT tokens expire after 24 hours"
- After: "JWT tokens expire after 1 hour with refresh token support"
- Change: Security hardening — shorter expiry + refresh tokens
### Removed (-1)
- ❌ REQ-006: Social login (Google, GitHub OAuth)
- Reason: Deferred to v2.0
### Unchanged (4)
- REQ-001: Signup ✓
- REQ-004: Password reset ✓
- REQ-005: Profile management ✓
Scenario Diff: Show scenario-level changes.
## Scenario Changes
| Status | Scenario | Detail |
|--------|----------|--------|
| ➕ Added | Admin bulk management | New admin workflow |
| ➕ Added | Email verification flow | New onboarding step |
| ✏️ Modified | User login | Added MFA branch |
| ✓ Unchanged | User signup | — |
Structure Diff: Show phase and task structure changes.
## Structure Changes
| Element | Version A | Version B | Change |
|---------|-----------|-----------|--------|
| Phases | 2 | 4 | +2 new phases |
| Tasks | 8 | 18 | +10 new tasks |
| Integrations | 1 | 3 | +2 new integrations |
Impact Summary: Quantify the overall diff.
## Diff Summary
| Metric | Version A | Version B | Delta |
|--------|-----------|-----------|-------|
| Requirements | 6 | 8 | +2 net (+33%) |
| Complexity score | 34 | 66 | +32 (+94%) |
| Estimated effort | 25h | 50h | +25h (+100%) |
| Risk level | 🟢 Low | 🟠 Medium | ⬆️ Increased |
Output: Deliver the complete diff report.
Generate a full changelog from spec git history showing all requirement changes over time
Generate stakeholder notifications summarizing spec changes for team communication
Generate release notes for a specific version or tag from spec changes
Generate a custom checklist for the current feature based on user requirements.
Identify underspecified areas in the current feature spec by asking up
Map spec requirements to test files and calculate requirement-level coverage