Yu256 Walicord Commit

Commit Skill

This skill helps you create meaningful commit messages based on actual staged changes.

Process

Step 1: Review Staged Changes

Check what's been staged:

git diff --cached

If the diff is small (< 100 lines), show the full diff to understand the changes. If the diff is large, use git diff --cached --stat for an overview.

Step 2: Analyze Changes

Based on the diff, identify:

• What changed: Files, functions, logic modified
• Why it changed: The root cause and true purpose, not just the surface-level action
• Impact: What this enables or fixes

CRITICAL - Understanding "Why":

• BAD: Surface-level reason ("to simplify the structure", "to refactor code")
• GOOD: Root cause and business/technical reason ("to fix utopia doc generation issue", "to prevent race condition in concurrent requests")

Examples:

• Don't say: "Changed struct to be simpler"
• Instead say: "Flattened struct because nested structure caused utopia to generate incorrect API docs"
• Don't say: "Added validation"
• Instead say: "Added validation to prevent SQL injection vulnerability in user input"
• Don't say: "Refactored error handling"
• Instead say: "Unified error handling to ensure consistent error responses for API clients"

CRITICAL - When Purpose is Unclear: If you cannot determine the root cause from the diff alone, or if you find yourself writing surface-level reasons:

• ASK the user for clarification
• Example: "I see you flattened the struct structure. What problem does this solve? (e.g., API doc generation issue, performance problem, maintenance concern?)"
• Do not guess or assume - get the true purpose from the user

CRITICAL: Base your analysis ONLY on the actual changes visible in the diff.

• Never mention intermediate changes that were made and then reverted before committing
• Never mention implementation details that don't appear in the final diff
• Focus only on what actually changed between the previous commit and the staged changes

Step 3: Craft Commit Message

Create a commit message following conventional commits format:

<type>: <short summary>

<optional body with more details>

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• refactor: Code refactoring (no behavior change)
• test: Adding or updating tests
• chore: Maintenance tasks (deps, config, etc.)
• perf: Performance improvements
• style: Code style changes (formatting, etc.)

Guidelines:

• Summary: Clear, concise (max 72 chars), imperative mood
• Body: Explain the root cause/true purpose (why) and what changed, not the "how"
  • Focus on business value, technical reasons, or problems being solved
  • Avoid describing implementation details or surface-level actions
  • Ask yourself: "Why did we need to make this change?" repeatedly until reaching the root cause
• Reference issues/PRs if applicable

Step 4: Present for Confirmation

Present to the user in this format:

Proposed commit message:
---
[Commit message]
---

Is this commit message accurate?

Step 5: Handle User Response

• If approved: Proceed to commit
• If corrections requested: Update the commit message

Step 6: Execute Commit

Commit with the approved message:

git commit -m "$(cat <<'EOF'
[Commit message here]
EOF
)"

Then run git status to confirm the commit succeeded.

Examples

Example 1: API Structure Fix

Diff: Flattened nested UserProfile struct in api/models.rs

Bad Commit Message (Surface-level):

refactor: simplify UserProfile struct

Simplified the nested structure for better readability.

Good Commit Message (Root cause):

fix: flatten UserProfile struct to fix utopia OpenAPI generation

Nested structure caused utopia to generate incorrect schema where
inner fields were not properly exposed in the API documentation.
Flattening the struct ensures all fields are correctly documented
for API clients.

Purpose: Flatten the struct to fix incorrect OpenAPI schema generation

Notes

• Always check git status before and after committing
• If there are unrelated changes, suggest splitting into multiple commits
• Keep commits atomic - one logical change per commit
• Never commit secrets, credentials, or sensitive data

Converted and distributed by TomeVault — claim your Tome and manage your conversions.