Reconcile State Before Acting
Every assumption you carry in from memory, a summary, or a handoff is a guess until a command confirms it. Reconcile observed state against expected state, write down the delta, and only then change anything.
Procedure
- Capture expected state first, in one line per claim. Example: "branch is clean", "file
src/Api.py exists and matches HEAD", "no server on port 8080". If you cannot state the expectation, you do not have one and must not assume it.
- Read actual repository state before touching files:
git status --porcelain=v1 and git log --oneline -5 and git stash list.
- Check for work in flight that a summary would not mention: open editors' lock files,
.git/MERGE_HEAD (mid-merge), .git/rebase-merge (mid-rebase), and ls .git/*.lock.
- Check process and port reality when the task involves a running service:
pgrep -fl node, lsof -nP -iTCP:8080 -sTCP:LISTEN.
- Inspect the artefact you were told exists:
ls -la <path> and wc -l <path>. Absence is a finding, not an error to route around.
- Compute the delta between steps 1 and 2-5 and write it to
notes/reconcile-<task>.md as three lists: confirmed, contradicted, unknown.
- Resolve every
contradicted entry before proceeding. If you cannot, stop and report it rather than editing on top of it.
- Only after the lists are stable, begin the actual task, and re-run step 2 immediately before any commit or destructive step.
- Record the facts you will re-assert at the end so drift is detectable: the HEAD sha (
git rev-parse --short HEAD), the line count of the file you will edit, and the listening port.
- Clear or account for stale locks from an interrupted run (
.terraform.tfstate.lock.info, *.pid, .git/index.lock) before starting; a stale lock imitates a live process.
- Capture environment coordinates (
git rev-parse --abbrev-ref HEAD, python --version, pwd) and compare them to what the task assumes.
Pitfalls
- Trusting a handoff note that says "tests pass" when the working tree has uncommitted edits that were never run.
- Assuming a cached directory listing or a prior
ls output is still true after another process ran.
- Reading a file's content from memory of an earlier read instead of re-reading it before an edit.
- Editing on top of a dirty tree and then committing unrelated changes you did not author.
- Treating a port or process as free because it was free five minutes ago.
- Reconciling file contents but not the branch, so edits land on
main instead of the feature branch.
- Trusting a green CI badge from an older commit as evidence about the current tree.
Verification
git status --porcelain=v1
# passes when it prints only files you intended to change, or nothing
Report to the user as an observation: the reconcile note path, plus the counts of confirmed/contradicted/unknown, and any contradicted claim you resolved or escalated.
1---2name: reconcile-state-before-acting3description: Use when resuming a task, inheriting another agent's work, or opening a repo after a gap. Establishes observed reality before any mutation, because memory and handoff notes drift from disk.4metadata:5 source: https://skillmd.com/skills/jiayaoqijia/reconcile-state-before-acting6---78# Reconcile State Before Acting910Every assumption you carry in from memory, a summary, or a handoff is a guess until a command confirms it. Reconcile observed state against expected state, write down the delta, and only then change anything.1112## Procedure13141. Capture expected state first, in one line per claim. Example: "branch is clean", "file `src/Api.py` exists and matches HEAD", "no server on port 8080". If you cannot state the expectation, you do not have one and must not assume it.152. Read actual repository state before touching files:16 `git status --porcelain=v1` and `git log --oneline -5` and `git stash list`.173. Check for work in flight that a summary would not mention: open editors' lock files, `.git/MERGE_HEAD` (mid-merge), `.git/rebase-merge` (mid-rebase), and `ls .git/*.lock`.184. Check process and port reality when the task involves a running service: `pgrep -fl node`, `lsof -nP -iTCP:8080 -sTCP:LISTEN`.195. Inspect the artefact you were told exists: `ls -la <path>` and `wc -l <path>`. Absence is a finding, not an error to route around.206. Compute the delta between steps 1 and 2-5 and write it to `notes/reconcile-<task>.md` as three lists: confirmed, contradicted, unknown.217. Resolve every `contradicted` entry before proceeding. If you cannot, stop and report it rather than editing on top of it.228. Only after the lists are stable, begin the actual task, and re-run step 2 immediately before any commit or destructive step.239. Record the facts you will re-assert at the end so drift is detectable: the HEAD sha (`git rev-parse --short HEAD`), the line count of the file you will edit, and the listening port.2410. Clear or account for stale locks from an interrupted run (`.terraform.tfstate.lock.info`, `*.pid`, `.git/index.lock`) before starting; a stale lock imitates a live process.2511. Capture environment coordinates (`git rev-parse --abbrev-ref HEAD`, `python --version`, `pwd`) and compare them to what the task assumes.2627## Pitfalls2829- Trusting a handoff note that says "tests pass" when the working tree has uncommitted edits that were never run.30- Assuming a cached directory listing or a prior `ls` output is still true after another process ran.31- Reading a file's content from memory of an earlier read instead of re-reading it before an edit.32- Editing on top of a dirty tree and then committing unrelated changes you did not author.33- Treating a port or process as free because it was free five minutes ago.34- Reconciling file contents but not the branch, so edits land on `main` instead of the feature branch.35- Trusting a green CI badge from an older commit as evidence about the current tree.3637## Verification3839 git status --porcelain=v140 # passes when it prints only files you intended to change, or nothing4142Report to the user as an observation: the reconcile note path, plus the counts of confirmed/contradicted/unknown, and any contradicted claim you resolved or escalated.