gitplan

name	gitplan
description	Plan and execute coherent Conventional Commit groupings for large, tangled working tree changes across many files.
disable-model-invocation	false
allowed-tools	Bash, Read, Glob, Grep, Edit, Write, WebSearch, Skill

Don't invoke this skill if we're just reviewing a couple files. This skill is ONLY applicable when untangling 15+ files with multiple inter-twingled edits.

Review and plan git commits

More on these workflows: photostructure.com/coding

Never create megacommits. Each commit should be focused, coherent, and reviewable.

If the repository has a layered structure (e.g. shared utilities → core → feature packages → app), work through it from the lowest-level layer upward so dependencies land before their consumers.

Workflow

Phase 1: Identify Themes

1. Scan all current changes with git status and git diff --stat — use subagents to preserve context and give summaries.
2. For complex diffs, use git diff -U150 but limit JSON/lockfiles to the first ~50 lines.
3. Identify logical themes/groupings. Each theme must have a single coherent purpose — a unifying "why" that explains every file in the group. If you can't state the purpose in one sentence without using "and", split the theme. Never create catch-all buckets like "housekeeping", "misc", "cleanup", or "various fixes". Every file belongs in a theme because of what it does, not because it's small or doesn't fit elsewhere. Orphan files that truly don't relate to any theme get their own single-file commit.
4. Bundle related docs/plans with their code changes. If a planning doc, design note, or task file corresponds to a theme, commit it alongside the code it describes — never lump it into a separate "docs" commit. Docs that don't correspond to any code change can go in a docs-only commit.
5. Present the themes to the user as a numbered list with brief descriptions. Order by increasing complexity/risk.
6. Ask: "Which theme should we focus on first?"

Phase 2: Stage, Review, and Commit (per theme)

1. Stage only files belonging to the selected theme using git add <files>, including any related docs/plans decided in Phase 1.
2. Review the staged changes (use the review-staged skill if available). Use a capable model — reviews are important.
3. If issues are found:
   • Present them clearly with priority, problem, and proposed fix.
   • Apply fixes incrementally, re-staging as needed.
   • Re-review until clean.
4. Present the proposed commit message and ask for approval. When the user approves, commit immediately — no second confirmation.
   • Commit messages drive the changelog. The body should describe user-facing behavior changes (what users will see/experience), not just implementation details. Lead with the "what changed for users" — implementation notes are secondary.

Phase 3: Repeat

1. Check git status for remaining changes.
2. If more changes exist, return to Phase 1 and pick the next theme.
3. Continue until all changes are committed or the user stops.

Review Guidelines

Review the staged code for potential issues and improvements. Follow any project conventions documented in the repository root (e.g. CLAUDE.md, AGENTS.md, contributing guides).

Review Focus

Critical Issues First

• Logic errors, security vulnerabilities, performance problems
• Breaking changes or API compatibility issues
• Resource leaks (memory, file handles, database connections)

Code Quality

• Adherence to the project's language conventions and error-handling patterns
• Anti-patterns: hardcoded paths, magic numbers, tight coupling
• Missing documentation on exported functions

Testing & Documentation

• Test coverage for critical paths and edge cases
• Documentation accuracy and completeness
• Test fixture updates if needed

Response Format

For each issue:

• Priority: Critical/High/Medium/Low
• Code: Quote specific problematic code
• Problem: Clear explanation of the issue
• Solution: Concrete fix or improvement suggestion
• Context: File/line reference for easy navigation

For documentation or trivial implementation issues, suggest the edit to the user and apply if they accept.

For other issues, provide a unique identifier for each issue (e.g. #A or #B), a summary of the issue, where it's located, and a proposed solution. Ask the user and apply if they accept.