If AGENTS.md sets a different convention for this topic, follow AGENTS.md.
Location
Everything temporary goes in .scratchpad/ at the repository root. Never use /tmp, the system temp folder or a session-specific scratch folder. The user expects to find the files in one place, and files outside the project are lost between sessions.
Before the first write, make sure .scratchpad/ is in .gitignore. If not, add it in its own commit:
# Working notes
.scratchpad/
Layout
Use the feature slug (from the branch, see git-commit-organizer) as a subfolder:
.scratchpad/
└── <slug>/
├── progress.md step, status and commits; used to resume after an interruption
├── interview-decisions.md answers from on-the-spot
├── verification-report.md verify-against-spec
├── browser-test-report.md browser-acceptance-testing
├── redteam-report.md red-team-review
├── change-list.md triage-findings-list
├── production-readiness-report.md
├── retrospective.md session-retrospective-rules
├── pr-body.md write-visual-pr
├── manual-env.sh helpers to start an isolated server
├── manual-data/ isolated data for manual checks (scratch database, fixtures)
├── scripts/ reproduction and verification scripts
└── transcripts/ archived session transcripts
Reports
Every long task ends with a report file, even if the user did not ask for one. Tell the user the path. A report that only exists in the chat is lost when the context is compacted.
Progress file
Keep progress.md current during any loop:
| Step | Status | Commits | Notes |
| --- | --- | --- | --- |
| 1 Walking skeleton | done | 0c31ee8, 84ae35f | |
| 2 Cancel an order | in progress | | |
If the session stops (usage limit, crash, new day), the next session reads this file and continues.
Manual test environment
- Keep the data of manual checks (a scratch database, fixtures) inside
.scratchpad/<slug>/, never the real data. - Use a dedicated port that other sessions do not use.
- Put start and stop helpers in
manual-env.shso each check is one command. - Stop every server you start by the PID that the start helper saved. Do not use
pkill -fwith a pattern that also appears in the command you run. It can stop your own shell. After the stop, wait until the port is free (lsof -iTCP:<port> -sTCP:LISTEN); apgrepright afterkillcan still see the process. - Mutation checks and backups also go in
.scratchpad/<slug>/, not in/tmp. - Keep test credentials in the helper script, not in chat messages.
Briefing subagents
When you delegate work, include these rules in the brief:
- Write any file only under
.scratchpad/<slug>/. Do not edit repository files unless the task says so. - Use their own port and data if they start a server, and stop it at the end.
- Say which claims were verified and which were inferred.