git-workflow

@taylorsatula/git-workflow

taylorsatula

339

26 forks

Updated 1/6/2026

View on GitHub

DO NOT COMMIT unless user explicitly tells you to. Use this skill EVERY SINGLE TIME before creating a git commit. Provides mandatory commit message format, staging rules, and post-commit summary requirements for the MIRA project

Installation

$skills install @taylorsatula/git-workflow

Claude Code

Cursor

Copilot

Codex

Antigravity

Details

Repositorytaylorsatula/mira-OSS

Path.claude/skills/git-workflow/SKILL.md

Branchmain

Scoped Name@taylorsatula/git-workflow

Usage

After installing, this skill will be available to your AI coding assistant.

Verify installation:

skills list

Skill Instructions

name: Git Workflow description: DO NOT COMMIT unless user explicitly tells you to. Use this skill EVERY SINGLE TIME before creating a git commit. Provides mandatory commit message format, staging rules, and post-commit summary requirements for the MIRA project

Git Workflow - MIRA Standards

Expert guidance for git operations in the MIRA project, emphasizing clear commit messages and proper staging practices.

🎯 Purpose

This skill provides git workflow standards for the MIRA project:

Streamlined commit message format (CONTEXT → INSIGHT → APPROACH → CHANGES)
Safe staging practices to prevent accidental commits
Post-commit summary requirements

🔀 OSS Sync Workflow

MANDATORY: Ask Before Every Commit

MIRA maintains two repositories (origin = private, oss = public OSS).

Before EVERY commit, you MUST ask:

"Sync to OSS after this commit?"

The repos have divergent codebases, so syncing requires running makeoss.sh:

Yes → After commit: ./makeoss.sh (auto-commits to OSS with same message)
No → Just push to origin as normal

⚙️ Git Staging Rules

Critical Staging Protocol

DO NOT attempt to commit unless the user explicitly tells you to
NEVER use git add -A or git add . without explicit permission
Always review changes before staging
Stage specific files intentionally
Verify what you're committing with git status and git diff

Safe Staging Pattern

# Review what changed
git status
git diff

# Stage specific files only
git add path/to/file1.py path/to/file2.py

# Verify staged changes
git diff --cached

📝 Git Commit Format

CRITICAL: Syntax Rules

Use literal newlines in quotes, NEVER HEREDOC

# ✅ CORRECT - Use literal newlines
git commit -m "prefix: summary

CONTEXT:
What triggered this work"

# ❌ WRONG - NEVER use HEREDOC (causes shell EOF errors)
git commit -m "$(cat <<'EOF'
Message here
EOF
)"

Commit Template

git commit -m "prefix: summary (50 chars max)

CONTEXT:
[What situation triggered this work - symptom, user report, or need]

INSIGHT: (optional - skip if obvious)
[The key realization: root cause for bugs, design decision for features]

APPROACH:
[Why this solution over alternatives, trade-offs considered]

CHANGES:
- Specific modifications with file names

IMPACT: (only when notable - skip if none)
- Breaking/Security/Performance notes

PRESERVES: (for refactors only)
- What behavior is unchanged

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>"

Section Guide

Section	Required?	When to Use
CONTEXT	Always	The trigger - what situation led to this commit
INSIGHT	Optional	The "aha" moment - root cause for bugs, key design decision for features. Skip if obvious.
APPROACH	Always	Why this solution, what alternatives considered
CHANGES	Always	Specific file/method modifications
IMPACT	Optional	Only when there's actual impact (breaking, security, perf metrics)
PRESERVES	Refactors	What existing behavior remains unchanged

Semantic Prefixes

feat: - New feature or functionality
fix: - Bug fix or error correction
refactor: - Code restructuring without functional changes
perf: - Performance improvements
security: - Security-related changes
test: - Adding or modifying tests
docs: - Documentation updates
chore: - Maintenance tasks, dependency updates
style: - Code formatting, whitespace fixes
revert: - Reverting previous commits

Remember: Commit messages are permanent documentation. Write for developers searching git history months from now.

📊 Post-Commit Summary (Required)

After every commit, provide a detailed summary:

✅ Commit Successfully Created

Commit Hash: abc123def
Files Changed: 3 files (+45, -12)

Key Accomplishments:
- [Specific achievement 1]
- [Specific achievement 2]
- [Specific achievement 3]

Benefits:
- [How this improves the codebase]
- [What problems this solves]

Next Steps:
- [What the human should consider next]
- [Any follow-up work needed]

🚫 Critical Anti-Patterns

Git Commit HEREDOC (Recurring Issue)

This is a persistent mistake that causes shell EOF errors:

# ❌ NEVER DO THIS
git commit -m "$(cat <<'EOF'
Message here
EOF
)"

# ✅ ALWAYS DO THIS
git commit -m "Summary

Details with literal newlines"

Why this matters: HEREDOC syntax in git commits causes shell parsing errors and breaks the commit flow. Always use literal newlines within quotes.

🔍 Example Commits

Bug Fix (with INSIGHT)

git commit -m "fix: preload Vault secrets at startup

CONTEXT:
Users reported Gemini/OpenRouter failing while Anthropic worked. After ~1hr
uptime, requests for uncached secrets returned 403 Forbidden.

INSIGHT:
AppRole token has 1-hour TTL. Secrets cached on first access work forever.
Keys first accessed after expiry trigger calls with dead token - Anthropic
was cached early, OpenRouter wasn't.

APPROACH:
Preload ALL secrets at startup while token is fresh. Security-equivalent
since secrets end up in memory anyway. Simpler than token refresh, no race
conditions, no failure modes.

CHANGES:
- Added preload_secrets() to vault_client.py
- Called in main.py lifespan startup

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>"

Simple Feature (no INSIGHT needed)

git commit -m "feat: add root endpoint with service status

CONTEXT:
User curling localhost:1993 during install got 404, thought install failed.

APPROACH:
Informational endpoint confirming service is running with pointers to
/v0/api/chat and /v0/api/health. No auth - just service discovery.

CHANGES:
- Added GET / endpoint in create_app()

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>"

Refactor (with PRESERVES)

git commit -m "refactor: split monolithic deploy.sh into modules

CONTEXT:
deploy.sh grew to 2,416 lines / 17 steps - cognitive overload, merge conflicts,
impossible to debug individual steps.

APPROACH:
Library files (shared functions) + step scripts. Used 'source' for variable
flow without temp files. ~8 logical groups over 1:1 mapping to reduce file
count while keeping clear boundaries.

CHANGES:
- Created deploy/deploy.sh thin orchestrator (~80 lines)
- Created deploy/lib/{output,services,vault}.sh
- Created step scripts: config, preflight, dependencies, python, etc.

PRESERVES:
- All 17 deployment steps execute identically
- Same interactive prompts and variable flow

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>"

Performance (with IMPACT metrics)

git commit -m "perf: add parallel tool execution to generic provider

CONTEXT:
Generic provider executed tools sequentially - 2 tools x 1s = 2s+ total.

INSIGHT:
ThreadPoolExecutor pattern from Anthropic path directly applicable. Critical:
context propagation via invoke_with_context for RLS security.

APPROACH:
Emit all ToolExecutingEvent upfront, then concurrent execution with
as_completed(). Preserves circuit breaker recording for both paths.

CHANGES:
- Replace sequential loop with ThreadPoolExecutor (lines 697-750)
- Add invoke_with_context wrapper

IMPACT:
- 27% faster total (4.58s -> 3.36s for 2 one-second tools)

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>"

💡 Best Practices

Before Committing:
- Run git status to see what changed
- Run git diff to review actual changes
- Stage files intentionally with specific paths
- Run git diff --cached to verify staged changes
Writing Messages:
- Start with semantic prefix
- Keep summary under 50 characters
- CONTEXT: the trigger, not the solution
- INSIGHT: only when there's a non-obvious discovery (skip for simple features)
- APPROACH: explain trade-offs, why this over alternatives
- CHANGES: specific file/method names
After Committing:
- Always provide post-commit summary
- Include commit hash and file stats
- Highlight key accomplishments
- Note any follow-up work needed
For Complex Bug Fixes:
- INSIGHT is critical - trace the causal chain to actual origin
- Explain why obvious solutions don't work in APPROACH
- Think of future developers searching git history

🎓 When to Use This Skill

Invoke this skill when:

Creating any git commit
User asks about commit message format
Need guidance on staging files
Uncertain about semantic prefix to use

More by taylorsatula

View all

real-pytest-no-mocks-real-tests

339

Write pytests that test real public interfaces with actual components, no mocking, and precise assertions. MIRA-specific patterns. Use when creating or reviewing tests.

investigate-dependencies

339

Conduct thorough dependency audits to identify redundant code, unused features, and improper usage patterns. Examines each import to ensure we're leveraging existing capabilities rather than reinventing functionality.

fail-fast-no-hedging

339

Eliminate component hedging anti-patterns that mask infrastructure failures. Build systems that fail loudly when broken instead of limping along in degraded states. Critical for production reliability and operational visibility.

contextvar-opportunity-finder

339

Detect explicit user_id parameters in functions to identify potential opportunities for using ambient context. This is an investigation tool that flags instances for human review, not a prescriptive analyzer.