working-notes-scratchpad
verifiedc9d9e410-d6d0-449a-890b-99a3eaf0ccb8
Maintain a persistent scratchpad file (progress log, open questions, decisions, current failing command) during long work so nothing is lost. Use for any task spanning many steps.
Metadata
Skill file
# Working Notes Scratchpad
Use for any task that spans many steps — debugging, a long feature, a research
session. A single persistent scratchpad file is your external working memory:
it survives context loss, session breaks, and your own forgetting.
## 1. The scratchpad sections
One file, five sections, always in this order:
```markdown
# Scratchpad — <task>
## Plan
The ordered steps / leaves for this task. Cross items off as done.
## Progress
Append-only, timestamped. One line per step taken, in order.
## Open Questions
Unresolved questions that will block progress later.
## Decisions
Decisions made and why (so you don't re-litigate them).
## Current Failure
The exact failing command + error, updated as you iterate.
```
## 2. The Progress section — append-only, timestamped
```markdown
## Progress
- 14:02 Ran `pytest tests/test_token.py -q` -> 12 passed, 3 failed.
- 14:07 Added `access_token` cookie name to middleware.
- 14:15 `pytest tests/test_middleware.py` -> 2 failures left (redirect loop).
- 14:22 Traced loop to `get_token()` reading wrong header.
```
Rules:
- **Append, never rewrite.** The history of what you tried is valuable (it is
exactly what debugging needs when a "fix" makes things worse).
- **Timestamp every entry.** Order matters, and later you need to know *when*
something happened.
- **One line per step.** A step that needs a paragraph is actually several steps.
## 3. The Current Failure section — the exact command + error
This is the most important section. When you hit an error, record the exact
command and the exact error so debugging can resume without replay:
```markdown
## Current Failure
Command: pytest tests/test_middleware.py::test_redirect_loop -x
Error:
E AssertionError: assert 500 == 302
E + where 500 = <Response [500]>.status_code
Last changed: src/auth/middleware.py:get_token() (cookie name hardcoded)
```
If you fix it, move the resolution to Progress and clear the section. The section
should always describe the *current* blocking failure — one, not five.
## 4. Re-read before each step
Before taking any new step, **re-read the scratchpad** — do not rely on memory:
```text
1. Read the scratchpad top to bottom.
2. Check "Current Failure" and "Open Questions".
3. Decide the next step from "Plan" + "Progress" (not from memory).
4. Take the step, then append a new Progress line.
```
This is the whole discipline: read → act → append. It is what makes the scratchpad
actually useful instead of a write-only log.
## 5. One canonical location
Keep the scratchpad in **one** file. Do not maintain three scratchpads (a repo
`NOTES.md`, a local `/tmp` file, and a task comment) — they diverge and you stop
trusting any of them. Pick one and reference it.
```bash
# Common choices:
# ./NOTES.md (repo-root, shared)
# .hermes/scratch/<task>.md (personal)
# notes/scratchpad.md (personal, git-ignored)
```
## Guardrails
- Do **not** let the scratchpad go stale — if "Current Failure" is 20 steps old,
the scratchpad has stopped being your working memory.
- Do **not** duplicate the scratchpad in multiple places — one file, one truth.
- Do **not** rewrite the Progress section — append-only preserves the debugging
trail.
- Do append the *exact* failing command + error, not a paraphrase.
- Do re-read the scratchpad before each step; reading is what makes it memory.
## Pitfalls
- **Stale scratchpad** — you stop updating it, and when you need it most (after a
context loss) it is empty or outdated.
- **Duplicated in three places** — fragments diverge, and you no longer know which
is current.
- **Rewriting instead of appending** — you "clean up" the Progress section and
destroy the history of what you already tried.
- **Paraphrased errors** — "it failed somehow" instead of the exact command and
traceback means the next session must reproduce the failure from scratch.
- **Write-only usage** — you append diligently but never re-read, so the scratchpad
is a diary, not memory.
## Verify / Checklist
- [ ] The scratchpad has all five sections: Plan, Progress, Open Questions, Decisions, Current Failure.
- [ ] Progress entries are append-only, timestamped, and one line per step.
- [ ] "Current Failure" contains the exact command + error, and is current.
- [ ] The scratchpad lives in exactly one canonical location.
- [ ] You re-read the scratchpad before taking each new step.
- [ ] Decisions are recorded with reasons, so they are not re-litigated.Attached files
No attached files.