GitFlow: An Intelligent Workflow Assistant for Automated Git Conflict Diagnosis and Resolution

Introducing an automated Git workflow skill designed specifically for AI Agents, which can automatically diagnose and resolve Git conflicts, branch chaos, and incorrect commits. It enables intelligent management of Git workflows through automated recovery, PR generation, and document synchronization.

The design of GitFlow stems from a deep observation of modern development workflows: while Git is powerful, its complexity imposes a significant cognitive burden on developers. Especially in emergency situations, developers may lose code or mess up the repository state due to operational errors.

The project's core philosophy can be summarized in three key terms: Automated Recovery, Labeled PR, and Document Synchronization. When a Git workflow issue is detected, the Agent first attempts to diagnose and fix it automatically; all repair operations are reported via Pull Requests with appropriate labels; at the same time, relevant documents are automatically updated to keep them in sync.

This design philosophy reflects respect for developers' time—letting machines handle repetitive diagnosis and repair tasks so developers can focus on more creative work. At the same time, the PR mechanism ensures all automated operations are transparent and auditable.

GitFlow's functional system is designed around the complete lifecycle of Git workflows, forming a closed loop from problem diagnosis to automatic repair and report generation.

Diagnosis is the foundation of all automated operations. GitFlow identifies the root cause of issues by comprehensively analyzing the output of multiple Git commands. Specifically, it checks git status to understand the current workspace state, looks at git log to grasp commit history, and analyzes git reflog to track reference change records.

This multi-dimensional analysis method can identify various common Git problem scenarios: a detached HEAD state usually means the developer switched to a historical commit; merge conflicts indicate code changes between branches that cannot be automatically reconciled; lost commits may result from incorrect reset operations; and uncommitted local changes may face the risk of loss when switching branches.

GitFlow adopts a layered risk assessment strategy, determining the level of automation based on the danger level of the operation. This cautious approach is necessary because Git operations can sometimes be destructive, and incorrect automated decisions may lead to data loss.

Safe Level operations include detached HEAD state repair and standard merge conflict resolution. These operations have low risk, so the Agent can directly perform recovery and generate a PR report. For example, when a detached HEAD is detected, the Agent can automatically create a branch to save the current state and then guide the user back to the correct branch.

Warning Level involves scenarios where uncommitted local changes may be lost. In such cases, the Agent first creates a safe backup branch, then performs the repair operation, and proactively notifies the user of what happened and what protective measures were taken.

Dangerous Level includes irreversible operations such as force pushes and permanent deletion of commits. For such operations, the Agent strictly follows the principle of manual confirmation, providing clear options for the user to choose from and never executing them without permission.

After all automated repairs are completed, GitFlow uses the GitHub CLI (gh) to create a Pull Request. This design has several benefits: first, it maintains the code review culture—even automated operations need to go through the PR process; second, it provides a complete audit trail so team members can see what the Agent did and why; finally, it allows human developers to review and fine-tune the results of automated repairs.

PR titles follow a strict label format: [label] Repair Summary. The project defines a complete label system: [feat] for new features, [fix] for bug fixes, [style] for code format adjustments, [docs] for document updates, [refactor] for code refactoring, [chore] for build processes, and [ci] for CI/CD changes.

This labeling method not only makes PRs easy to understand at a glance but also facilitates subsequent changelog generation and version management.

When the core logic or design philosophy of the skill changes, GitFlow automatically updates README.md and SKILL.md to maintain document accuracy. This mechanism of synchronizing documents with code solves the common problem of outdated documents in software projects.

In many projects, code evolves while documents stagnate, making it difficult for new members to quickly understand the system and old members to rely on orally transmitted knowledge. GitFlow ensures that knowledge always exists in written form and is consistent with the current implementation through automated document synchronization.

GitFlow's tech stack is designed to be simple and practical, making full use of existing tools and platforms.