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

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

1. 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

2. 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

3. After Committing:

   • Always provide post-commit summary
   • Include commit hash and file stats
   • Highlight key accomplishments
   • Note any follow-up work needed

4. 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