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
• 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 intent or why is not obvious from the diff
• NEVER list filenames in the commit message. The git UI already shows which files changed. Your job is to describe topics, not files. No file-by-file breakdowns, and no "CHANGES:" headers.
• Translate technical changes into a high-level topic summarization. A human reading the message should immediately understand what the goal was without having to interpret individual code or file edits. Describe the business/functional accomplishment, not the technical steps taken.
  • ❌ docs/ai-context.md: add homelab k3s target, domain pattern
  • ✅ document development environment and deployment context
• No "Expected:", "Result:", "Impact:" or any speculative outcome sections — commit messages describe the accomplished goal, not what is predicted to happen
• Bullet points state the high-level topics, not technical line edits or how it works — keep each line short and factual
  • ✅ configure direct S3 authentication for MinIO
  • ❌ 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 external redis dependency
  • ✅ configure queue type to persistent level
• Do not summarize or quote the exact content of text/description changes — the diff shows the content, the message states the topic of the change
  • ❌ Remove "harmless" framing, add operational guidance: daily return to 0 expected
  • ✅ update operational expectations for Ghost Blocks panel
• Body format: use prose (one sentence) for a single goal; use bullets ONLY when multiple completely distinct goals or topics were accomplished in the same commit.

Body length example — what "too much explanation" looks like vs. the correct abstract version:

❌ Too detailed — describes files, code references, and technical mechanics:

chore(minio): pin image to RELEASE.2025-10-15T17-29-55Z

Chart 5.4.0 bundles RELEASE.2024-12-18 which does not return Last-Modified
metadata on objects. Thanos compactor falls back to ULID creation time and
deletes valid blocks as stale partial uploads (>48h old).

Also add comment on thanos-sidecar image noting all Thanos containers
(compactor, blocks-exporter, init container, ghost cleanup job) share
this single image reference.

✅ Correct — states the high-level intent and reasoning clearly without itemizing files or specific code additions:

chore(minio): downgrade minio version to fix object metadata loss

The newer chart release causes valid block deletion by the compactor due
to missing Last-Modified metadata on objects. Version is pinned to an
older stable release to prevent data loss.

Also clarified shared image dependencies for Thanos services in documentation.

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