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 --statStep 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 #456Step 4: Commit Message Suggestion
Generate a conventional commit message:
<type>(<scope>): <description>
<body - what and why>
<footer - breaking changes, issues>Types:
feat: New featurefix: Bug fixrefactor: Code restructuringdocs: Documentation onlytest: Adding testschore: 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 #123Step 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
- [x] Unit tests pass
- [x] Integration tests pass
- [x] Manual testing performed
- [x] No console errors
### Commit Messagefix(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
- [x] Unit tests pass (15 test cases for validation)
- [x] Integration tests pass
- [x] Manual testing performed
- [x] Works with screen readers (a11y tested)
### Commit Messagefeat(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.