global-skills/skills/git-workflow/SKILL.md

name, description, concerns

name	description	concerns
git-workflow	Atomic commit grouping, selective staging, conventional commit messages, and clean git history hygiene. Use when preparing commits, staging changes selectively, reviewing git diffs, or standardizing commit messages.	system-one-balance

Git Workflow & Atomic Staging

Enforces clean, logical version control hygiene, atomic commits, and conventional commit standards across repositories.

---

Phase 0: Setup and Protocols

1. Non-Negotiable Invariants:
   • Never Stage Unrelated Edits: Inspect git status and diffs before staging. Stage only files directly relevant to the current task. Preserve untouched user work.
   • Never Use Destructive Resets: Never execute git reset --hard or git checkout . without explicit user instruction.
   • Verify Before Committing: Run quality gates (tests, linter) before creating commits.

---

Phase 1: Ingest and Check

1. Run git status to inspect modified, staged, and untracked files.
2. Review git diff for staged vs. unstaged changes to ensure no extraneous edits or debug logs are included.
3. Identify the logical boundaries of the work to separate independent changes.

---

Phase 2: Processing (Core Logic)

Step 1: Logical Commit Grouping

Group changes into focused, cohesive commits rather than bulk-committing unrelated subsystems:

1. Infrastructure & DDL: Table migrations, config schemas, and models.
2. Core Logic: Services, domain algorithms, and processors.
3. API & Routes: Web endpoints, controllers, and schemas.
4. Tests & Docs: Automated tests, documentation, and specs.

Step 2: Selective Staging

• Stage specific files explicitly:

  git add path/to/file1 path/to/file2
  

• Avoid blanket git add . when unstaged experimental edits exist in the workspace.

Step 3: Conventional Commit Formatting

Follow standard conventional commit prefixes:

• feat(<scope>): New functionality or feature.
• fix(<scope>): Bug fix or regression resolution.
• refactor(<scope>): Code restructuring without behavioral change.
• perf(<scope>): Performance optimization.
• sec(<scope>): Security hardening or vulnerability fix.
• docs(<scope>): Documentation updates.
• test(<scope>): Adding or updating tests.
• chore(<scope>): Tooling, dependencies, or maintenance.

---

Phase 3: The System One Balance Pass

• Augment, Don't Handcuff:
  • Safe operations (e.g. git status, git diff, staging known files, creating a commit) must be frictionless fast paths.
  • Do NOT prompt the user with interactive confirmation modals for routine commits during an ongoing implementation.
  • Reserve confirmation prompts strictly for irreversible actions (git push --force, git branch -D, git clean -fdx).

---

Phase 4: Output Execution & Verification

1. Create the commit with a concise, descriptive message.
2. Verify commit creation:

   git log -n 1 --oneline
   

3. Confirm working tree status remains clean and expected.