| name | git-history-diagnostic |
| description | Use when something worked before and is now broken (a regression), or the operator asks "when did this break", "find the commit that caused X", "it used to work", "compare to a previous version". Locates where a regression entered by comparing commits / bisecting history. Do NOT use for net-new bugs that never worked, for routine rollback (workflows/git-discipline.md), or as a substitute for reproduce-before-fix (FR-10). |
| source_inspiration | conceptual-only |
| license_status | clean-room-original |
| fusebase_flow_version | 3.3 |
| risk_level | low |
| invocation | automatic |
| expected_outputs | ["the commit (or range) that introduced the regression, with evidence","a diff explaining the causing change","handoff to zoom-out / validation-and-qa for the actual fix"] |
| related_workflows | ["git-discipline.md","verification-gate.md"] |
| hook_dependencies | ["none"] |
Git History Diagnostic
Style: Mode-B-lite.
Purpose
Regression archaeology: when behavior that previously worked is now broken, locate where it broke by comparing commits / bisecting history — so the fix targets the actual causing change, not a guess. Read-only diagnosis; the fix is handed to zoom-out + validation-and-qa.
When to invoke
- "It used to work" / "this is a regression" / "when did X break".
- A test that passed at an earlier commit now fails.
- Operator points to a known-good prior state and a now-broken current state.
Do not invoke when
- The behavior never worked (net-new bug → normal debugging).
- Routine rollback of a known commit →
workflows/git-discipline.md.
- Reproduction isn't established yet → run FR-10 reproduce-before-fix first (you need a reliable signal to bisect against).
Required inputs
| Input | Where it lives | If missing |
|---|
| A reliable broken/works signal (test or repro) | test suite / repro steps | establish via FR-10 first; bisecting needs a yes/no test |
| Last-known-good reference (commit/tag/date) | operator / git history | search backward from HEAD for the transition |
| Current broken state | HEAD | — |
Procedure
- Pin the signal. Define a deterministic check that returns good/bad (a test command, a repro). Bisection is only as reliable as this signal.
- Bracket. Identify a known-good commit (or tag/date) and a known-bad commit (usually HEAD). Verify the signal at both ends.
- Bisect. Narrow the range with
git bisect run on the pinned signal (see § Bisect mechanics; manual good/bad stepping or binary search when the signal is not scriptable) until the first bad commit is found.
- Explain. Show that commit's diff; identify the specific change that introduced the regression (file:line).
- Hand off. Pass the finding to
zoom-out (root-cause vs revert decision) and validation-and-qa for the fix + regression test. Do not fix here.
- Capture. If the regression class is recurring, note it in
docs/problem-catalog/.
Bisect mechanics
git bisect start
git bisect bad HEAD
git bisect good <known-good>
git bisect run <signal-cmd>
git bisect skip
git bisect log > state/bisect-<slug>.log
git bisect reset
git bisect run exit-code contract (the signal command MUST encode it):
| Exit code | Meaning |
|---|
| 0 | good |
| 1–124, 126–127 | bad |
| 125 | cannot test this commit → auto-skip |
| ≥128 | aborts the whole bisect — wrap signals that can be signal-killed |
Wrap non-conforming signals: git bisect run sh -c '<build> || exit 125; <test> || exit 1'.
Pickaxe shortcut — before (or instead of) a full bisect, when the regression plausibly traces to a known string/symbol: git log -S '<symbol>' --oneline -- <path> (or -G '<regex>') lists only commits that added/removed it — often pins the culprit in one command.
Output artifacts
| Artifact | Path or location | Mode |
|---|
| Regression-origin finding | chat (Mode A) + optional ticket note | Mode A / Mode-B-lite |
| Causing-commit diff excerpt | chat / handoff | Mode A |
Failure cases
| Failure mode | Detection | Response |
|---|
| No deterministic signal | bisect gives inconsistent results | go back to FR-10; build a stable repro/test |
| Regression spans multiple commits | each end behaves inconsistently | report the range; treat as design issue via zoom-out |
| "Good" reference also broken | step 2 verify fails | search further back for the true good state |
| Signal still bad N brackets back (2–3 extensions: N → 2N → 4N commits, all bad) | step 2 verify keeps failing ever further back, incl. commits the operator KNOWS worked | Stop bisecting — history is likely not the cause. Suspect environment/CLI/dependency drift: diff the lockfile (git diff <good>..HEAD -- package-lock.json), compare fusebase --version + Node version against the last-known-working session, check whether fusebase update rewrote CLI-managed files (see fusebase-flow-health-check for CLI_LAYER_DRIFT). Re-verify the signal in a clean checkout/fresh install; resume bisect only once a genuinely good state reproduces. |
Escalation path
- Cause spans many commits / cross-cutting →
workflows/architect-escalation.md.
- Fix design →
flow-skills/zoom-out/SKILL.md then validation-and-qa.
- Ambiguous good-reference → ask operator in chat (FR-19).
Anti-patterns
- Do not fix in this skill (diagnosis only).
- Do not bisect without a deterministic signal (false culprit).
- Do not auto-revert the causing commit — zoom out first (it may be load-bearing).
- Do not leave the repo in bisect state —
git bisect log for evidence, then git bisect reset before any handoff or fix work.
Clean-room note
Original Fusebase Flow content. Designed after reviewing public AI coding workflow patterns; no third-party code, prompts, skill files, or hook scripts are copied. See docs/source-map.md.
