Write notes

write-notes

Every other skill opens by sending you here: answer its note form and write the note before you do the work. A note is a few lines of your own intent and plan — it forces the thinking out of your head and onto the page, where a wrong assumption is cheap to catch and a reviewer (or future you) can see why you did what you did. This skill is the how; each skill carries its own form.

When this applies

The moment you pick up any skill to do real work — usually before you implement — and again if your understanding changes mid-task. Skip it only for a trivial one-line change in a place you already know.

Write the note

• Answer every question concretely — name the code. The skill you're working under has a "Write a note first" section: its questions. Answer each in a sentence or two, citing the actual files, functions, and data flow you found — the note doubles as a check that you understood the code, so a vague answer ("it handles the data") means you haven't yet; go read more. "I don't know yet" is a valid answer that becomes an open question to resolve or ask before you proceed. Research findings (deep-research) and sweep enumerations (search-codebase) land here too — the note is the single artifact of the task's thinking.
• Surface what you're unsure about — don't only state confidence. Every form ends in risks & unknowns: describe where you're least sure, the assumption that would break this if it's wrong, and how you'd catch the mistake. The insight is in what you don't yet know — a note that only sounds confident hides the bug it should have surfaced.
• Where it goes. Wherever your team records intent before work — a task/issue comment, the draft PR description, or a scratch file in the global notes directory (see below). It is a thinking artifact, not a committed source file; keep it unless your project tracks notes.
• Keep it short and honest. A few lines per answer, not an essay. Write what's true now; update it when you learn more. A note that launders a guess into confidence is worse than none.
• Then act. Only once the note's open questions are resolved (or asked) do you start the work — and the skill's own gates confirm you did: Gate A's first box, Note, checks this note exists; Gate B checks you finished what it planned.

Where scratch files go

A note written to disk goes in one global, user-local directory — never inside the repository. A scratch file in the clone shows up in git status, is one git add -A away from being committed, and dies with the clone; the global directory survives branch switches and re-clones. Resolve the location in this order:

1. TALE_AGENT_NOTES_DIR — an absolute path, if set. The explicit override for power users and CI.
2. Otherwise the OS default:
   • Linux: $XDG_DATA_HOME/tale/agent-notes/ (or ~/.local/share/tale/agent-notes/ when XDG_DATA_HOME is unset)
   • macOS: ~/Library/Application Support/Tale/agent-notes/
   • Windows: %APPDATA%\Tale\agent-notes\

Inside it, key notes by repository so parallel checkouts stay separated, and date the file: <repo-slug>/<date>-<topic>.md — e.g. tale-project-tale/2026-07-06-fix-webhook-retry.md. Create the directories on first use. Never create a notes/ directory (or any scratch file) under the repo root — a task/issue comment or the draft PR description remain the alternatives when your team should see the note.

Why a note, not just a thought

A written intent is a commitment device: it proves you understood the code before you touched it, it catches the wrong-problem and the divergent-second-copy before a line is written, it answers "why did you build it this way?" later, and it survives a handoff or a context reset. The cost is a minute; the saving is a whole wasted change. Never skip it to "save time" — the skip is what costs time.