Git Workflow

# 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
```bash
# 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**

```bash
# ✅ 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

```bash
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:

```bash
# ❌ 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)
```bash
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)
```bash
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)
```bash
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 sc