Skip to content

task-observer: new docs/ai/scratch-files from 2026-06-22 #60

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
divad12 wants to merge 1 commit into
base: master
Choose a base branch
from
Open

task-observer: new docs/ai/scratch-files from 2026-06-22 #60

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .claude/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,6 +125,7 @@ Do not run full validation suites after every small edit by habit. Run the narro
| Editing AGENTS.md, .agents/skills/, docs/ai/ | writing-docs.md |
| Maintaining or troubleshooting ask-intern | ask-intern.md |
| Operating or changing the learning system | learning-system.md |
| Managing scratch files for long-running autonomous workstreams | scratch-files.md |
- Re-read the hard rules before implementation.

## Session Tools
Expand Down
21 changes: 21 additions & 0 deletions docs/ai/scratch-files.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# Scratch Files for Long-Running Workstreams

## Contract

- Keep one `scratch.md` per long-running autonomous workstream as its single control surface.
- Structure the file with three sections: **Current Truth** (what is true now and what the next agent needs after compaction), **Next Steps** (ordered queue of what to do), and **Archaeology** (completed items and older logs).
- After context compaction or a long idle period, re-read `scratch.md` first, then update the Current Truth section before continuing.
- **Compaction cleanup** — after compaction, move completed Next Steps into a short Archaeology entry, delete duplicated detail in favor of short notes or links, and compact the Current Truth section before proceeding. A current-control section that grows as large as the archive defeats the file's purpose.
- The scratch file is a control surface, not an evidence log. Artifacts (test results, run outputs, screenshots) live in separate files. The scratch file holds current truth and the next queue only.
- Gauge: resuming after compaction should require only "What's next? Write it down, then do it." If re-reading the scratch file takes more than two minutes, it is overdue for cleanup.

## Canonical Files

- `docs/specs/<feature>/scratch.md` — feature-level control surface for a long-running autonomous task
- `scratch.md` at project root — when the workstream spans the whole project

## Notes

- A scratch file is separate from living triage files and per-run artifacts. Triage files explain what happened; scratch state tells the next agent what to do without rediscovering the thread.
- Archaeology grows from the bottom; current sections stay at the top. Compaction cleanup keeps the top sharp.
- If the file is too large to re-read quickly, compact before continuing — a bloated scratch file is worse than none.