| name | fc-commit-message |
| description | Use when: writing commit messages, reviewing changes before committing, or planning changesets. Enforces message format, code quality checks, and documentation standards for commits. |
Commit Message & Changeset Guidelines
Analysis
As a Senior developer, you will analyze the changes in staged files and generate a commit message that follows the guidelines below.
CRITICAL: Review ALL changed files without exception. Use git diff or the changes tool to get a complete list of modified files, then analyze each one thoroughly:
- List ALL files that have changes (added, modified, or deleted)
- For EACH file, examine every added, removed, and modified line
- Ensure no file is overlooked or ignored in your analysis
- Consider the cumulative impact of changes across all files
Determine the scope based on ALL changes combined. Analyse deeply each change and determine the appropriate level of detail for the commit message (minimal, standard, or comprehensive).
⚠️ When multiple unrelated files are changed (e.g., infrastructure files + documentation + scripts), ensure the commit title and scope reflect the breadth of changes - don't focus on just one aspect.
Identify when there are multiple changes that span different areas of the codebase, and decide when to include a detailed description with section headers and bullet points.
Required Format Structure
Title (First Line)
⚠️ CRITICAL: The title MUST represent ALL changes in the commit, not just one file or aspect.
- Summary: If there are multiple unrelated files or areas changed (e.g., Dockerfile + docs + scripts), the title must either:
- Use a generic scope that covers all changes (e.g.,
[✨feat][project] or [✨feat][repo])
- Mention all major aspects in the description (e.g., "Add commit guidelines, Dockerfile, and demo script")
- NEVER focus only on one file when multiple unrelated files are changed
- Length: 120 characters maximum
- Unique: only the first line can be a title
- Imperative Mood: "add" not "adds" or "added", present tense
- Format:
[emoji][scope]: description
- Example single area:
[✨feat][auth]: Add WebSocket integration
- Example multiple areas:
[✨feat][project]: Add commit guidelines, Dockerfile, and demo script
- Capitalization: First letter capitalized
- Blank line: Always add a blank line after the title
Summary Paragraph
- DO NOT include if
- The commit is straightforward and self-explanatory from the title
- The changes are minor and do not require additional context
- Length: 100-200 characters (1-2 sentences)
- Focus: What changed and why (not how)
- Tense: Present tense
- Blank line: Always add a blank line after the summary
Detailed Description (for commits with multiple changes)
- DO NOT include if
- Summary paragraph is not needed
- The commit only affects a single area or is straightforward
- The commit is a simple fix or minor enhancement that does not require additional context
- The commit does not introduce any new patterns, migrations, or complex logic that would benefit from additional explanation
- If included:
- Organization: Use section headers with relevant emojis
- Sub-items: Use bullet points under each section
- Grouping: Group related changes together
- References: Include file names, layers, or components when relevant
- Line length: Limit body lines to 120 characters
- Special sections (all optional, include as needed, always in this order):
## ✨ New Features: New features## 💥 Breaking Changes: Document any backward-incompatible changes## 🛡️ Security: Highlight security-related changes## 📊 Performance: Detail performance optimizations## 🧪 Tests: Describe new or updated tests## 📄 Documentation: Note documentation updates
- Explain what and why, not how
- Blank line before footer
Emoji Guide
Use these standard emojis to categorize change types:
| Emoji | Meaning | Use Case |
|---|
[🔧refactor] | Refactoring | Code refactoring without behavior change |
[🖥️ui] | UI | User interface changes |
[🛠️infra] | Infrastructure | Build tools, CI/CD, workflows |
[🛡️security] | Security | Security improvements or fixes |
[📊perf] | Performance | Performance optimizations |
[📚docs] | Documentation | Documentation updates |
[🚀ci] | Deployment | Release or deployment-related changes |
[💥breaking] | Breaking Change | Breaking changes |
[🧪test] | Tests | Adding or updating tests |
[🖋️style] | Formatting | Code formatting changes (no logic change) |
[📦chore] | Dependencies | Adding or updating dependencies |
[⚙️config] | Configuration | Changes to configuration files |
[🐛fix] | Bug Fix | Fixes to existing bugs |
[✨feat] | Feature | New functionality or features |
Scope (optional)
Specify the affected component: [auth], [api], [database], [ui], etc.
Things to Avoid
- ❌ Never use "WIP", "temp", or placeholder text
- ❌ Never include redundant or duplicate information
- ❌ Never omit the scope from the title
- ❌ Never use imperative beyond the first sentence in the summary
- ❌ Never exceed line length guidelines without good reason (and then explain why)
- ❌ Never write a title that focuses on only one file when multiple unrelated files are changed - the title must represent ALL changes or use a generic scope
Footer (optional)
- Reference issues:
Fixes #123 or Closes #456
- Note breaking changes:
BREAKING CHANGE: description
Examples
Simple fix (Level 1):
[✨feat][api]: handle null response in user lookup
More complex changes:
- (Level 2) Use Feature with context when changes apply to only one area but require additional context to understand the impact.
- (Level 2) Use Breaking change when introducing backward-incompatible changes.
- (Level 3) Use Detailed Example when changes span multiple areas or require detailed explanation. This format includes section headers, bullet points, and references to related documentation or issues.
When Generating Commit Messages
- Analyze ALL changes using git diff or the changes tool - list every modified file and review all changes
- Determine scope: Single file, component, or multiple areas? Consider ALL files in your analysis
- Pick appropriate detail level (minimal, standard, or comprehensive) based on the totality of changes
- Select emoji that best represents the primary change across all files
- Define scope (the area/component affected) - if multiple files span different areas, reflect that
- Write imperative title that completes: "This commit will..." and accurately reflects ALL changes:
- ⚠️ If multiple unrelated files are changed (e.g., Dockerfile + docs + scripts), the title MUST mention all major aspects or use a generic scope like
[project] or [repo]
- ❌ BAD:
[✨feat][docs]: Add commit message guidelines (when Dockerfile and scripts were also added)
- ✅ GOOD:
[✨feat][project]: Add commit guidelines, Dockerfile, and demo script
- Add summary explaining the why, covering all significant changes
- Add details if changes span multiple areas, multiple files, or are complex
- Remove footer with co-authored-by
- Output in code block using quadruple backticks
Tips for Better Commit Messages
- Be specific: "Fix null reference in user service" is better than "Bug fix"
- Explain context: Why were these changes needed? What problem do they solve?
- Use present tense: "Add feature" not "Added feature"
- Keep it scannable: Use headers and bullet points for readability
- Reference issues: Use #123 format to link to related issues
- Link to docs: Reference design docs or specifications when relevant
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
