nicolas-codemate/fix-rebase-conflicts

Fix-Rebase-Conflicts — Methodical Rebase Conflict Resolution

This skill resolves rebase conflicts carefully. It distinguishes trivial conflicts (imports, namespaces, cosmetic) from real semantic conflicts. For real conflicts, it analyzes the commit introducing the change against the current ticket context. When in doubt, it asks the user instead of guessing.

Inputs

$ARGUMENTS

• --with-tests — also run functional tests after static checks (default: skip tests)
• --no-continue — stop after the report instead of running git rebase --continue (default: auto-continue)
• --file <path> — limit analysis to a single conflicted file (repeatable)

Phase 0 — Verify Rebase Is In Progress

Worktree caveat: in a git worktree, .git is a file pointing to the real git directory, so [ -d .git/rebase-merge ] always returns false. Always resolve rebase paths through git rev-parse --git-path — never hardcode .git/....

REBASE_MERGE_DIR=$(git rev-parse --git-path rebase-merge)
REBASE_APPLY_DIR=$(git rev-parse --git-path rebase-apply)

if [ ! -d "$REBASE_MERGE_DIR" ] && [ ! -d "$REBASE_APPLY_DIR" ]; then
    # Cross-check: a rebase can also be inferred from `git status --porcelain=v2 --branch`
    if ! git status --porcelain=v2 --branch | grep -qE '^# branch.head \(no branch'; then
        echo "ERROR: aucun rebase en cours."
        exit 1
    fi
fi

If git diff --name-only --diff-filter=U is empty, the rebase has no remaining conflicts. Tell the user to run git rebase --continue themselves and stop.

Phase 1 — Build Context (once, up front)

REBASE_MERGE_DIR=$(git rev-parse --git-path rebase-merge)
REBASE_APPLY_DIR=$(git rev-parse --git-path rebase-apply)

CONFLICTS=$(git diff --name-only --diff-filter=U)
BRANCH=$(git rev-parse --abbrev-ref HEAD)
REBASE_HEAD=$(git rev-parse REBASE_HEAD 2>/dev/null \
              || cat "$REBASE_MERGE_DIR/stopped-sha" 2>/dev/null)
ONTO=$(cat "$REBASE_MERGE_DIR/onto" 2>/dev/null \
       || cat "$REBASE_APPLY_DIR/onto" 2>/dev/null)

# The "incoming" commit being applied
git log -1 --format='%H%n%s%n%n%b' "$REBASE_HEAD"

Locate ticket context, in this order:

1. .claude-work/{ticket-id}/ticket.md
2. .claude_resolve/{ticket-id}/ticket.md
3. Branch name (e.g. feature/ABC-123-...) → infer ticket ID
4. Last commit subject on the feature branch (git log -1 ORIG_HEAD --format=%s if available)

Display a one-line summary before touching anything:

Rebase: {BRANCH} onto {ONTO}
Stopped at: {short-sha} {subject}
Ticket: {id} — {title (if known)}
Conflicts: {N} fichier(s)

Phase 2 — Per-File Conflict Resolution

For each conflicted file, follow this flow strictly. Process files sequentially — do not parallelize.

Step 2.1 — Read & Classify Each Conflict Block

Read the file. A single file may contain several <<<<<<< ... ======= ... >>>>>>> blocks. Classify each block independently:

| Class | Definition | |---|---| | A — Imports/namespace | The block sits exclusively in use / import / from / namespace / require lines at the top of the file. No logic affected. | | B — Cosmetic / mechanical | Both sides do the same thing in slightly different style (formatting, reordering of independent items, identical logic with different whitespace). | | C — Real semantic conflict | At least one side changes runtime behavior, signatures, control flow, or data shape. |

If the file mixes classes, resolve each block independently and aggregate the summary at the file level.

Step 2.2 — Resolve By Class

Class A — Imports / namespace (auto-fix, no question)

1. Take the union of imports from both sides.
2. Verify every imported symbol is still referenced in the body of the file. Example for PHP:

   grep -E '^use ' {file} | awk '{print $NF}' | sed 's/;//' | while read sym; do
       short=$(basename "${sym//\\//}")
       grep -q "\b$short\b" {file} || echo "UNUSED: $sym"
   done
   

   Adapt for JS/TS (import { X } from), Python (from x import Y), Go (import "...").
3. Drop unused imports.
4. Keep imports sorted in the project's prevailing convention (look at neighboring files).
5. Record one line in the summary: "Imports merged, N unused removed."

Class B — Cosmetic / mechanical (auto-fix, lightweight note)

Pick the version that matches the project's prevailing style (formatter config, neighboring code). Note the choice in the summary in one line.

Class C — Real semantic conflict (analyze before touching)

Do all of the following before deciding:

1. Inspect the incoming commit (the one being applied):

   git log -1 --format=full "$REBASE_HEAD"
   git show --stat "$REBASE_HEAD"
   git show "$REBASE_HEAD" -- "{file}"
   

2. Inspect the other side (what is now on HEAD in this region):

   git log -5 --format='%h %s' HEAD -- "{file}"
   git blame -L {line-start},{line-end} HEAD -- "{file}"
   

3. Cross-reference with ticket intent:
   • Does the incoming commit's purpose align with the current ticket's goal?
   • Is the HEAD-side change part of the rebase target's evolution (i.e. came from main) or part of the feature being rebased?
   • Are both sides trying to solve the same problem, or different problems that touched the same lines?

Then decide:

• Clearly resolvable — one side is unambiguously correct given the ticket and the commit's intent (e.g. incoming adds the very behavior the ticket asks for; ours-side is a stale unrelated change from main that's compatible if combined):

  • Apply the fix with Edit.
  • Add a structured entry in the summary (see Phase 4).

• Ambiguous, complex, or risky — anything where the choice would be a guess:

  • Do not edit the file yet.
  • Use AskUserQuestion with:
    • File path and line range
    • 2–3 line description of what each side is trying to do
    • The introducing commit's subject + sha
    • Your best-guess recommendation, clearly labeled as a recommendation not a decision
    • Options: take ours / take theirs / hand-merge / skip for now
  • Wait for the user's answer. Apply exactly what they pick.

Bias toward asking. A wrong auto-resolution can introduce a silent bug that survives the rebase and lands in the merge. The cost of one extra question is much lower than the cost of a buggy rebase.

Step 2.3 — Stage The Resolved File

After every block in the file is resolved, double-check no conflict markers remain before staging:

if grep -qnE '^(<<<<<<<|=======|>>>>>>>)' "{file}"; then
    echo "ERREUR: marqueurs de conflit encore présents dans {file}"
    exit 1
fi
git add "{file}"

Phase 3 — Static Analysis Must Pass

Auto-detect the project's static tooling and run it. Do not consider the work done if any tool fails.

Detection (in order)

• composer.json → check scripts.{lint,phpstan,psalm,cs} and binaries in vendor/bin/ (phpstan, psalm, php-cs-fixer, phpcs)
• package.json → check scripts.{lint,typecheck,check} and tsc/eslint
• pyproject.toml / mypy.ini / ruff.toml → mypy, ruff check
• .golangci.yml → golangci-lint run
• Makefile targets named lint, check, static, qa, analyse

Run

Run the detected tools sequentially. Prefer running them only on files touched during this rebase when the tool supports a file list:

TOUCHED=$(git diff --name-only "$ONTO"...HEAD)

If a tool fails:

1. Read its output carefully.
2. If the cause is trivial and a direct consequence of the conflict resolution (e.g. an unused import the cleanup missed, a stale type reference) → fix and re-run.
3. Otherwise → report the failure to the user with the relevant tool output. Do not continue further. Do not silence or work around the error.

Phase 4 — Reporting & Auto-Continue

Display a single consolidated report:

=== Résolution des conflits de rebase ===

Auto-résolus (sans question) :
  - {file}: imports fusionnés, {N} inutilisés supprimés
  - {file}: cosmétique, version "theirs" alignée sur le style du projet

Résolus avec analyse (à relire) :
  - {file}:{lines}
      Commit entrant : {sha} "{subject}"
      Décision       : pris theirs
      Justification  : le commit entrant ajoute le chemin d'erreur exigé
                       par le ticket {id} ; le côté "ours" était un refactor
                       local devenu obsolète après l'évolution de main.

Résolus par toi (instructions appliquées) :
  - {file}:{lines}: {résumé du choix utilisateur}

Outils statiques :
  ✔ phpstan (level 8)   — 0 erreur sur les fichiers touchés
  ✔ php-cs-fixer        — propre
  ✔ tsc --noEmit        — propre

[--with-tests]
Tests fonctionnels : {statut}

Auto-continue (default)

After printing the report, automatically run git rebase --continue unless any of these blockers apply:

• --no-continue was passed
• Static analysis is not green
• A Class C conflict was resolved by user instruction via AskUserQuestion and the user explicitly asked to stop and review
• The rebase is interactive (.git/rebase-merge/interactive exists) and stopped on a non-conflict step (edit, break)

If continuing:

git -c core.editor=true rebase --continue

The core.editor=true override prevents an interactive editor from blocking on the commit-message confirmation step. If the rebase stops again on a new conflict, re-enter the skill loop (Phase 0) on the new conflict set — fully sequential, no parallelism. Keep going until the rebase completes, the work tree is clean, or a blocker stops the loop.

Final hand-off

Once the rebase completes (.git/rebase-merge and .git/rebase-apply both gone):

Rebase terminé. {N} commit(s) replayés.
État final : git log --oneline {ONTO}..HEAD

If a blocker stopped auto-continue, print the blocker reason and the manual next step:

Auto-continue désactivé : {raison}.
Quand tu es prêt :
  git rebase --continue

Phase 5 — Functional Tests (only if --with-tests)

Detect and run the project's primary test command:

• PHP: composer test, vendor/bin/phpunit, vendor/bin/pest
• JS/TS: npm test, npm run test:unit, pnpm test, yarn test
• Python: pytest
• Go: go test ./...
• make test if present

Run the unit/functional suite — not the whole CI pipeline. If tests fail:

• Report which tests failed and the relevant output.
• Do not attempt to fix the tests automatically.
• Stop and let the user decide.

Anti-patterns To Avoid

• Do not auto-resolve with git checkout --ours/--theirs blindly — that short-circuits the per-block analysis the user explicitly asked for.
• Do not run git rebase --abort automatically — that throws away the work. Auto---continue is fine (the user opted in by default), but --abort is destructive and always requires explicit user confirmation.
• Do not stash, reset, or git restore to "make things cleaner". Destructive git is forbidden globally.
• Do not mix mechanical and semantic fixes silently — every Class C decision needs an entry in the summary.
• Do not skim the introducing commit's diff to "save context". If the file is large, read git show $REBASE_HEAD -- {file} in full. This analysis is the whole point of the skill.
• Do not present a Class C analysis and then resolve anyway "because it seems likely" — if it required a paragraph of reasoning, ask.
• Do not test [ -d .git/rebase-merge ] or any other .git/... path directly. In a worktree, .git is a file, not a directory, and the check silently always returns false — so the skill thinks no rebase is in progress when one is. Always go through git rev-parse --git-path rebase-merge (and friends).

Language

User-facing messages and the final report in French. Commands, code, log keys, and the AskUserQuestion option labels can stay in English where it reads more naturally.

NOW

Begin with $ARGUMENTS:

1. Verify rebase is in progress (Phase 0)
2. Build context once (Phase 1)
3. For each conflicted file: classify each block, resolve Class A/B inline, analyze Class C against the introducing commit + ticket, ask when ambiguous (Phase 2)
4. Stage each resolved file only after marker-free check
5. Run static analysis on touched files; do not stop until green (Phase 3)
6. Display the consolidated report, then auto-run git rebase --continue unless a blocker applies (Phase 4). If a new conflict surfaces, loop back to Phase 0 sequentially.
7. If --with-tests, run the functional suite once the rebase has fully completed (Phase 5)