task-state-ledger

# Task State Ledger — Stop Getting Lost ## The failure this prevents You re-derive state every turn (where's the PR, what's on main, what's deployed) with expensive `gh`/`git`/`curl` dumps. The dumps flood context, bury the signal, and you lose the thread. This is the "constantly stuck and lost" failure. The fix is mechanical: **write state down once, update it as you go, read it instead of re-deriving it.** (Anthropic context-engineering: external structured note-taking is one of the three core long-horizon techniques, alongside compaction and sub-agents — see https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) ## The rule For any task with 3+ steps or that crosses a turn, the FIRST action is to create or open a ledger at `.thumbgate/implementation-notes.md` or a task-specific gitignored `.thumbgate/implementation-notes/<date>-<task>.md`. Do not write operator scratchpads under tracked `.claude/implementation-notes/`; those are private working notes, not product documentation. The ledger is the single source of truth. ## Ledger format (keep it short — it's a dashboard, not a diary) ```markdown # <task> — <date> ## Goal (one sentence) <the actual end state that means "done"> ## Current step <the ONE thing in flight right now> ## State (verified facts only — each with how/when verified) - main HEAD: <sha> (git rev-parse origin/main @ HH:MM) - deployed buildSha: <sha> (curl /health @ HH:MM) - PR #NNNN: <state>/<mergeState> (gh pr view @ H...