Troubleshooting

GitHub File Doesn’t Match Workspace?

A proof-first 4-minute flow to find out which version is current before you overwrite good work.

If you open a file in GitHub and it looks different from what your agent sees in workspace, don’t panic and don’t overwrite yet. Most mismatches are simple context or sync issues.

What this usually means

You’re often comparing two different states: local workspace edits, remote branch history, or even a different account/repo path.

Step 1) Prove You’re Looking at the Same File

Confirm exact repo and branch on GitHub.
Confirm exact local path in workspace.
Match filename and extension exactly (watch similar names).

Step 2) Classify the Mismatch (Local Ahead vs Remote Ahead)

Run these checks in the workspace root:

git status --short

git branch --show-current

git log --oneline -n 5 -- path/to/file.md

Local ahead: file changed locally but not pushed yet.
Remote ahead: GitHub has newer commits not pulled locally.
Wrong context: right file name, wrong repo/branch/path.

Step 3) Fix with One Safe Move (No Guessing)

If local is ahead

Commit/push your local work.
Refresh GitHub and re-compare.

If remote is ahead

Pull remote changes first.
Resolve conflicts before asking the agent to continue editing.

If wrong context

Switch to the correct repo/branch.
Re-run one tiny canary: ask agent to quote line 1-3 from the target file.

Loop-break rule

Do not ask the agent to edit until you can prove the exact active file path and current branch in one message.

Copy/Paste Recovery Prompt

Before editing anything, prove context first:
1) Return current repo path and active branch.
2) Return exact absolute file path you will edit.
3) Quote lines 1-3 from that file.
4) Return git status --short only for that file.
If any mismatch exists, stop and explain the mismatch class (local ahead / remote ahead / wrong context).

High-Friction Mistakes

“Same file name” in different folders

Very common. Always use absolute path proof, not filename-only proof.

Comparing main branch on GitHub to a feature branch locally

This looks like data loss but is usually just branch mismatch.

Multiple accounts/workspaces

If behavior feels random, confirm you’re logged into the same account/workspace in both places before any edits.

Detached HEAD after checking a specific commit

If git branch --show-current returns nothing, you’re not on a normal branch. You may be viewing an old commit snapshot. Switch back to your working branch before editing.

Uncommitted merge/rebase state

If Git says merge/rebase is in progress, stop file edits and finish or abort that operation first. Partial merge state can make file content look inconsistent between local and GitHub.

Wrong remote (fork vs upstream)

Confirm git remote -v. Many mismatches are local changes tracked against a fork while GitHub browser is opened on upstream (or vice versa).

Known-good proof bundle before editing

git branch --show-current + git rev-parse --short HEAD + absolute file path + first 3 lines of file. If any one of these differs from your expected target, stop and re-align context first.

Safety note

Never paste tokens or secrets when sharing diagnostics. Share path/branch/commit info only.