ai-superpower/.ai/instructions/skills/git.instructions.md

Git Instructions

🚨 GIT POLICY - ABSOLUTELY CRITICAL

NEVER EVER make git commands without explicit user approval!

Forbidden Commands - DO NOT RUN:

1. ❌ git add - User runs this themselves (including git add ., git add -A, git add )
2. ❌ git commit - User runs this themselves
3. ❌ git push - User runs this themselves
4. ❌ git push --force - User runs this themselves
5. ❌ git reset - User runs this themselves
6. ❌ ANY command that modifies git repository or server state

What You CAN Do:

• ✅ git status - Show current state
• ✅ git diff - Show changes
• ✅ git log - Show history
• ✅ Show the command user should run
• ✅ Explain what the command will do

Exception:

Only if user explicitly says:

• "commit this now"
• "push this now"
• "go ahead and commit"

Otherwise: SHOW the command, WAIT for user to run it

---

Best Practices

• Always show git diff before suggesting commits
• Show git status to verify what will be committed
• Explain impact of each git operation
• User controls git commands, you analyze and advise
• Never assume user wants to commit
• Reliability over speed

---

Commit Message Workflow

When the user asks for a commit message:

1. Run git diff --staged or git diff — read what actually changed
2. Documentation check — scan the changed files and ask: does any docs/ or README.md need updating based on these changes? If yes, flag it clearly before writing the message. Do not block the commit — just surface it.
3. Write the commit message only — one short subject line, optionally a blank line and brief body if the change needs context. Output must be only the message text inside one fenced code block. Do NOT wrap it in a git commit command.

Output format is mandatory for copy/paste:

• Always use one fenced code block (prefer text language tag)
• Put only commit message content inside the block
• Do not add prose before or after the block
• Do not add labels like "Suggested message:" outside the block

Correct:

fix(scope): concise subject

optional body line

Wrong:

• Suggested commit message: fix(scope): concise subject
• Plain text without a fenced block

Format:

<type>: <what changed>

<optional: why, or what is not obvious from the diff>

Types: feat, fix, docs, refactor, chore

Commit message rules

Only include what actually changed in this commit.

• Run git diff --staged (or git diff if nothing staged) and read it fully before writing
• List only files and lines that appear in the diff
• If a file appears in the diff but only has whitespace or comment changes, omit it from the body
• Never mention changes that are not in the diff — even if you remember discussing them earlier in the session
• If unsure whether something changed, check the diff — do not guess

Format rules:

• Subject line: max ~72 chars, imperative mood ("Fix", "Add", "Remove" — not "Fixed", "Added")
• Body: optional, only when the why is not obvious from the diff
• No bullet-pointed list of every file changed unless the diff spans many unrelated files
• No "CHANGES:" headers, no file-by-file breakdowns for single-topic commits
• No "Expected:", "Result:", "Impact:" or any speculative outcome sections — commit messages describe what changed, not what is predicted to happen
• Bullet points state what changed, not why it was wrong or how it works — keep each line short and factual
  • ✅ use MC_HOST_minio for S3 auth
  • ❌ Use MC_HOST_minio env var for direct S3 auth (no mc alias set)
• Do not describe runtime behavior, incident narrative, or manual operations in the commit message body
  • ❌ gitea failed on startup
  • ❌ Redis services cleaned up manually
  • ❌ Certificate renewed successfully
  • ✅ disable redis sub-chart
  • ✅ set queue type to level

All projects:

• Treat commit messages as change logs of repository state, not behavior reports
• Never include runtime status, deployment outcomes, test run narratives, or manual operation confirmations unless the user explicitly asks for a release note or status report instead of a commit message