# scratchpad

Working memory for the current session. Use this to save facts discovered mid-task
(file paths, config values, error messages) so they are not lost across tool calls.

## When to use

- You found a file path during exploration and need to reference it later.
- An error occurred and you want to record what was tried before attempting a fix.
- You are in a multi-step task and need to remember the overall goal.
- You want to collect findings before composing the final answer.

## When NOT to use

- Do NOT use for progress tracking — use `todo` for that.
- Do NOT use for final answers — the final answer goes in the assistant message.

## Parameters

| Field    | Type   | Required | Description |
|----------|--------|----------|-------------|
| action   | string | **yes**  | One of: `write`, `append`, `read`, `clear` |
| section  | string | no       | Section name: `goal`, `findings`, `artifacts`, `errors`, `main`. Defaults to `main` on write/append. |
| content  | string | no       | **Required for `write` and `append`**. The text to save. |

## Actions

### write
Overwrite a section with new content.

```json
{"action": "write", "section": "findings", "content": "The config file is at /etc/app/config.yml"}
```

### append
Add text to the end of an existing section.

```json
{"action": "append", "section": "findings", "content": "Port is 8080"}
```

### read
Return the contents of one section, or all sections if `section` is omitted.

```json
{"action": "read", "section": "findings"}
```

### clear
Erase one section, or the entire scratchpad if `section` is omitted.

```json
{"action": "clear", "section": "errors"}
```

## Common mistakes

1. **Missing `content` on write/append** — The call will fail. Always provide `content`.
2. **Putting text in `section` instead of `content`** — `section` is the category name (e.g. `"findings"`), `content` is the actual text.
3. **Using `op` instead of `action`** — The parameter is called `action`, not `op`.
4. **Passing text as the action value** — `{"action": "your text"}` is wrong. Use `{"action": "write", "content": "your text"}`.

## Full example workflow

```
# Step 1: Set the goal
{"action": "write", "section": "goal", "content": "Fix the database connection error"}

# Step 2: Record what you found
{"action": "write", "section": "findings", "content": "Error says 'connection refused on port 5432'"}

# Step 3: Add more info
{"action": "append", "section": "findings", "content": "PostgreSQL service is stopped"}

# Step 4: Check what you saved
{"action": "read"}

# Step 5: After fixing, clear errors
{"action": "clear", "section": "errors"}
```