View status

When to Use

• User asks to create a commit or "commit changes"
• User asks to review git status or diff
• User wants to analyze commit history
• After completing features/​fixes that need to be committed
• User mentions "conventional commits" or asks about commit format

---

Critical Patterns

Commit Format

<type>(<scope>): <subject>

[optional body]

[optional footer]

Types (in order of usage frequency)

Subject Rules

1. ✅ Use imperative mood: "add" NOT "added" or "adds"
2. ✅ Lowercase first letter
3. ✅ No period at the end
4. ✅ Maximum 120 characters
5. ✅ Describe WHAT, not HOW

Good:

• feat(book): add publication date validation
• fix(auth): resolve token refresh issue

Bad:

• feat(book): Added publication date validation (past tense)
• fix(auth): Resolve token refresh issue (uppercase)
• feat(book): add publication date validation. (period)

Body Rules (Optional)

1. Separate from subject with blank line
2. Explain WHY, not WHAT
3. Wrap at 72 characters per line
4. Can use bullet points with -

Footer Rules (Optional)

1. Reference issues: Closes #123, Fixes #456
2. Breaking changes: BREAKING CHANGE: <description>
3. ❌ NEVER add "Co-Authored-By" or AI attribution

---

Commit Workflow

1. Analyze Changes

git status                # See modified/​untracked files
git diff                  # See unstaged changes
git diff --staged         # See staged changes
git log --oneline -10     # See recent commit style

2. Group Related Changes

Rules:

• One commit = one logical change
• ❌ Don't mix features with fixes
• ❌ Don't mix multiple unrelated modules
• ✅ Multiple files are OK if they implement one feature

3. Generate Message

Analyze the changes and determine:

1. Type: feat, fix, refactor, etc.
2. Scope: Which module/​component is affected?
3. Subject: What does this change do?
4. Body (if needed): Why was this change necessary?
5. Footer (if needed): Issue references, breaking changes

4. Execute Commit

git add <files>
git commit -m "$(cat <<'EOF'
<type>(<scope>): <subject>

<body>

<footer>
EOF
)"

---

Code Examples

Simple Feature

feat(library/​book): add publication date validation

Validate that publication date is not in the future
when creating or updating a book.

Closes #234

Bug Fix with Context

fix(auth): resolve token refresh race condition

Multiple simultaneous requests could trigger parallel
token refreshes, causing some requests to fail.

- Add mutex lock during refresh
- Queue pending requests until refresh completes
- Add retry logic for failed requests

Fixes #567

Refactor (No Functional Change)

refactor(library/​book): extract ISBN validation to service

Move ISBN validation logic from command handler to
dedicated IsbnValidatorService for reusability.

No functional changes.

Breaking Change

feat(api)!: change pagination response format

BREAKING CHANGE: Pagination response now uses cursor-based
format instead of offset-based.

Before: { items: [], total: 100, page: 1 }
After: { items: [], nextCursor: "abc", hasMore: true }

Migration guide in docs/​migration/​v2-pagination.md

Aurora YAML Changes

feat(aurora): add category entity to library module

Define new Category aggregate with:
- id, name, description fields
- many-to-many relation with Book

Run: aurora load back module -n=library/​category

Dependency Update

chore(deps): update @nestjs packages to v10.2.0

- @nestjs/​core: 10.1.0 -> 10.2.0
- @nestjs/​common: 10.1.0 -> 10.2.0
- @nestjs/​platform-express: 10.1.0 -> 10.2.0

No breaking changes in this update.

Multiple Modules (Related Change)

feat(tesla): add maintenance validation across models

- Add validation in Model aggregate
- Update MaintenanceHistory to check model status
- Add integration tests for both modules

This ensures consistency when creating maintenance records.

---

Commands

# View status
git status

# View changes
git diff                    # Unstaged changes
git diff --staged          # Staged changes
git diff --cached          # Same as --staged

# Stage files
git add <file>             # Stage specific file
git add -p                 # Interactive staging (choose hunks)

# Commit
git commit -m "message"    # Simple commit
git commit                 # Opens editor for body

# View history
git log --oneline -20                      # Last 20 commits
git log --pretty=format:"%h %s" -20       # Custom format
git log --graph --oneline --all           # Visual graph

# Amend last commit (use with caution)
git commit --amend -m "new message"       # Change message
git commit --amend --no-edit              # Add files to last commit

---

Anti-Patterns to Avoid

---

Aurora-Specific Notes

1. YAML Changes

feat(aurora): add category entity to library module

Define new Category aggregate with id, name, description.

Run: aurora load back module -n=library/​category

2. Custom Logic in Generated Files

feat(library/​book): add complex ISBN validation logic

Implement custom validation in CreateBookHandler:
- Validate ISBN format (10 or 13 digits)
- Check checksum digit
- Verify not in blacklist

This logic is in a generated file marked as custom.

3. Multiple Related Modules

feat(tesla): integrate maintenance history with models

- Update Model aggregate with maintenance status
- Add validation in MaintenanceHistory creation
- Add integration tests

Changes span tesla/​model and tesla/​maintenance-history.

4. Test Commits

Option A: Combined with feature

feat(book): add ISBN validation with tests

- Add ISBN validation in CreateBookHandler
- Add unit tests for validation logic
- Add e2e tests for create endpoint

Option B: Separate commit

test(book): add unit tests for ISBN validation

Add comprehensive test coverage for:
- Valid ISBN-10 and ISBN-13 formats
- Invalid formats and checksums
- Edge cases (empty, null, special chars)

---

Decision Trees

Should I commit now?

Has code changed? ────NO───> No commit needed
      │
     YES
      │
Is it a logical unit? ────NO───> Break into smaller commits
      │
     YES
      │
Do tests pass? ────NO───> Fix tests first
      │
     YES
      │
  Create commit

What type should I use?

New functionality? ────YES───> feat
      │
      NO
      │
Fixing a bug? ────YES───> fix
      │
      NO
      │
No functional change? ────YES───> refactor
      │
      NO
      │
Only tests? ────YES───> test
      │
      NO
      │
Dependencies? ────YES───> chore(deps)
      │
      NO
      │
Documentation? ────YES───> docs
      │
      NO
      │
    Default: chore

How to scope?

Single module changed? ────YES───> Use <bc>/<module>
      │
      NO
      │
Multiple related modules? ────YES───> Use common <bc> or higher scope
      │
      NO
      │
Infrastructure? ────YES───> Use: ci, docker, config, deps
      │
      NO
      │
Core/​API/​GraphQL? ────YES───> Use: core, api, graphql
      │
      NO
      │
    Omit scope or use project name

---

Related Skills

This skill works with:

• aurora-cli: Commit YAML changes and regenerated code
• aurora-development: Commit business logic implementations (feat commits)
• jest-nestjs: Commit test files (test commits or include with feat)
• logger: Log commit information in session reports

Workflow:

1. Make changes (YAML modifications, business logic, tests)
2. Use aurora-cli to regenerate code (if YAML changed)
3. Use conventional-commits to create proper commit
4. Use logger to document the session (optional)

---

Resources

• Specification: https://www.conventionalcommits.org/
• Aurora Config: commitlint.config.js (read this for project-specific rules)
• Git Hooks: Pre-commit hooks may enforce format validation