When to Use
Invoke this skill:
-
After completing any non-trivial coding task
-
Before committing changes
-
When preparing PR descriptions
-
After think-about-whether-you-are-done confirms completion
Change Summary Workflow
Step 1: Gather Change Information
Collect information about what changed:
-
Modified Files: List all files that were changed
-
Change Types: Categorize changes (new, modified, deleted, renamed)
-
Scope: Identify affected components/modules
If using git, gather diff summary
git status git diff --stat
Step 2: Analyze Change Impact
For each significant change, document:
-
What Changed: Specific modification made
-
Why It Changed: Reason/motivation for the change
-
Impact: What this affects (functionality, performance, API)
Step 3: Generate Summary
Use this template:
Changes Summary
Overview
[1-2 sentence high-level description of what was accomplished]
Changes Made
New Files
| File | Purpose |
|---|---|
path/to/file.ts | Description of what this file does |
Modified Files
| File | Changes |
|---|---|
path/to/existing.ts | What was changed and why |
Deleted Files
| File | Reason |
|---|---|
path/to/old.ts | Why this file was removed |
Technical Details
Key Implementation Decisions:
- Decision 1 and rationale
- Decision 2 and rationale
Dependencies Added/Removed:
- Added:
package-name@version- reason - Removed:
old-package- reason
Breaking Changes
[List any breaking changes or "None"]
Migration Required
[Any steps needed to adopt these changes or "None"]
Verification Checklist
- Unit tests pass
- Integration tests pass
- Manual testing performed
- Documentation updated
- No console errors
- Performance acceptable
Related Issues/Tasks
- Fixes #123
- Related to #456
Step 4: Commit Message Suggestion
Generate a conventional commit message:
<type>(<scope>): <description>
<body - what and why>
<footer - breaking changes, issues>
Types:
-
feat : New feature
-
fix : Bug fix
-
refactor : Code restructuring
-
docs : Documentation only
-
test : Adding tests
-
chore : Maintenance tasks
Example:
fix(auth): resolve login timeout error
Increased timeout from 5s to 30s for login requests. The previous timeout was insufficient for users on slow connections.
Fixes #123
Step 5: PR Description (if applicable)
If changes are for a PR, expand the summary:
Summary
[Brief description of what this PR does]
Changes
[List of key changes]
Testing
[How this was tested]
Screenshots
[If UI changes]
Checklist
- Tests added/updated
- Documentation updated
- No breaking changes (or documented)
Changes Summary
Overview
Fixed the search timeout error that occurred when users had slow connections.
Changes Made
Modified Files
| File | Changes |
|---|---|
src/api/search.ts | Increased timeout from 5s to 30s |
src/api/search.test.ts | Added test for timeout handling |
Technical Details
Key Implementation Decisions:
- Used 30s timeout as it covers 99th percentile of actual search times
- Added retry logic with exponential backoff for transient failures
Dependencies Added/Removed:
- None
Breaking Changes
None
Verification Checklist
- Unit tests pass
- Integration tests pass
- Manual testing performed
- No console errors
Commit Message
fix(search): increase timeout to handle slow connections
Increased search API timeout from 5s to 30s and added retry logic. Users on slow connections were experiencing frequent timeout errors.
Fixes #456
</usage_example>
<usage_example> After adding a new feature:
Changes Summary
Overview
Added user email validation with real-time feedback on the registration form.
Changes Made
New Files
| File | Purpose |
|---|---|
src/utils/emailValidator.ts | Email validation utilities |
src/utils/emailValidator.test.ts | Tests for email validation |
Modified Files
| File | Changes |
|---|---|
src/components/RegistrationForm.tsx | Added validation to email field |
src/i18n/en.json | Added validation error messages |
Technical Details
Key Implementation Decisions:
- Used RFC 5322 compliant regex for validation
- Validation runs on blur to avoid interrupting typing
- Debounced validation (300ms) for performance
Dependencies Added/Removed:
- None (used built-in regex)
Breaking Changes
None - additive change only
Verification Checklist
- Unit tests pass (15 test cases for validation)
- Integration tests pass
- Manual testing performed
- Works with screen readers (a11y tested)
Commit Message
feat(registration): add email validation with real-time feedback
Added RFC 5322 compliant email validation to registration form. Validation runs on blur with debouncing for smooth UX.
Closes #789
</usage_example>
Iron Laws
-
NEVER write a file list without explaining WHAT changed and WHY for each entry
-
ALWAYS include a verification checklist so reviewers can confirm quality
-
NEVER omit the breaking changes section — always include it explicitly, even if "None"
-
ALWAYS use conventional commit format for commit messages attached to summaries
-
NEVER skip the summary step after non-trivial coding tasks — it is mandatory
Anti-Patterns
Anti-Pattern Why It Fails Correct Approach
Just listing filenames No context for what changed or why Explain what changed and the reason for each modification
Missing verification checklist Reviewers have no guidance on what to test Always include a checklist of what to verify
Omitting breaking changes section Users surprised by compatibility breaks Add explicit "Breaking Changes: None" when there are none
Vague commit messages ("Updates") Commit history loses traceability Use conventional commit format with type, scope, and rationale
Skipping summary under time pressure Missing context causes rework during review Always produce a summary after non-trivial tasks
Memory Protocol (MANDATORY)
Before starting: Read .claude/context/memory/learnings.md
After completing:
-
New pattern discovered -> .claude/context/memory/learnings.md
-
Issue encountered -> .claude/context/memory/issues.md
-
Decision made -> .claude/context/memory/decisions.md
ASSUME INTERRUPTION: If it's not in memory, it didn't happen.