Agent-heavy work creates a lot of half-formed context: dictated notes, failed prompts, benchmark ideas, security worries, skill candidates, and "try this later" scraps.
Do not commit that pile. Keep scratch private, ignored, and temporary until it earns its way into a goal.
private scratch note
-> reviewed goal packet
-> bounded agent work
-> proof scenario
-> saved evidence
-> next goal
The Move
Use a project-local scratch space for messy notes and a reviewed goal packet for actual work.
Local conventions such as .notes/ and .goals/ can work well when they are globally ignored and treated as private workspace files. The names are not important. The boundary is.
Notes is just kind of like the junk, or the research, or whatever. Goals are the things I can feed into the model to produce work.
— John Lindquist
- Scratch notes are not documentation.
- Goals are not wish lists.
- A note is where messy thinking lands.
- A goal is what survives review and becomes work.
Notes Become Goals
A goal packet is a reviewed project-local work item that turns scratch notes into bounded agent work, names the proof scenario, and records what counts as done.
Example:
Scratch note:
Checkout submit stayed disabled after selecting shipping.
Goal:
Find the smallest cause of the disabled checkout submit state.
Likely areas:
- checkout form state
- shipping selection reducer
- submit button disabled logic
Proof:
- reproduce failing state
- add or run component test
- run checkout smoke test
- capture before/after result
Stop if:
- payment-provider adapter must change
- no reproducible failing state exists
Private notes stay private. Sanitized patterns can become docs later.
Long Agent Work Needs Intervals
Treat long agent runs as interval work.
Set an explicit check-in interval before launch. Leave the agent with a stop rule and proof requirement. Step away. Come back to inspect evidence, not vibes.
Field rule:
If the agent has a bounded goal and a proof command,
step away until the interval ends.
Watching the terminal harder does not make the benchmark finish.
Good launch shape:
Start a migration lane with:
- allowed files
- files to avoid
- verification command
- check-in interval
- stop condition
Return when:
- the timer fires
- the agent reports blocked
- the proof command finishes
- a boundary conflict appears
AFK does not mean unsupervised merge. It means the work unit is bounded enough that the human can leave and return to concrete evidence.
Understanding Becomes Proof Design
You still need judgment. What changes is the unit of understanding.
The best you can hope for is understanding the scenarios that prove the code works the way you expect it to.
— John Lindquist
The useful unit is no longer "I have read every line." The useful unit is "I know the scenario, the boundary, and the evidence that prove this behavior."
Examples:
| Task | Proof Scenario | Evidence | Does Not Prove |
|---|---|---|---|
| Checkout disabled state | Shipping selected, submit enables | Component test, smoke test | Every payment-provider state |
| Billing retry | Duplicate event processed once | Fixture, idempotency test, log | All provider outage modes |
| Auth/session rotation | Stale session rejected safely | Security test, route check | Every browser/session store |
| Performance change | Same fixture before/after | Benchmark output | Production latency |
Proof scenarios are how codebase understanding stays grounded when code is moving quickly.
Ask For Lists, Not Comfort
Avoid vague reassurance prompts:
Are you sure?
Is this correct?
Why did this work?
Ask for structured reasons instead:
Do not reassure me.
List 5 reasons this proof actually covers the checkout disabled-state bug.
For each reason, include:
- the behavior it checks
- the evidence source
- what it does not prove
- one way this could still be wrong
More useful prompts:
List 5 ways this benchmark could be misleading.
List 7 security assumptions this auth/session change depends on.
List 4 reasons the smoke test covers the regression, then list 4 gaps it leaves open.
Agents are good at sounding certain. Lists force certainty to expose its assumptions.
Treat Public Skills As Candidates
Public skills are supply-chain inputs. Evaluate before installing.
For a software task, search with multiple terms instead of one narrow phrase.
Example task:
Improve accessibility checks for a Svelte checkout flow.
Search terms:
accessibility audit
a11y test
Svelte accessibility
Playwright axe
WCAG checker
keyboard navigation
screen reader smoke test
ARIA validation
form accessibility
contrast checker
Then ask a model council or Oracle to compare candidates:
Compare candidate skills for this task.
For each candidate:
- what it claims to do
- source/repo/package origin
- maintenance signals
- install or execution risk
- whether it reads project files
- whether it runs code
- what useful prompt or function can be extracted without installing
- recommendation: install / adapt / reject
Reading a skill is not the same as trusting it. Installing it is a separate decision.
Force Known Context
If the relevant files, constraints, stack, or proof command are already known, put them directly in the prompt. Search should fill unknowns, not rediscover known facts.
Weak:
Find the right skill and fix checkout.
Better:
We use SvelteKit.
The failing path is /checkout.
The bug is submit disabled after shipping selection.
Do not touch the payment provider adapter.
The proof is the checkout component test plus billing smoke test.
Search for skills only if they help inspect this exact scenario.
Copyable Artifact: Goal Packet
Scratch source:
- note id or summary:
- why this matters now:
Goal:
- what should be true when this is done:
Known context:
- repo area:
- likely files:
- constraints:
- files/tools to avoid:
Agent work:
- first inspection step:
- allowed edits:
- stop conditions:
Proof scenario:
- user path or system behavior:
- test:
- smoke check:
- benchmark:
- security check:
- debug/log evidence:
Reason list required:
Ask the agent to list:
- 5 reasons this proof covers the goal
- 5 gaps this proof leaves open
- 3 assumptions that could make the result wrong
Pacing:
- check-in interval:
- what to inspect when returning:
Skill evaluation, if needed:
- 10 search terms:
- candidate skills:
- Oracle/Fusion comparison saved?
- source scraped/read before install?
- useful parts extracted?
- install decision: install / adapt / reject
Completion:
- evidence attached:
- remaining uncertainty:
- next goal created:
Claim Boundaries
Do not share private note contents, global ignore files, local config, machine paths, usernames, or private skill contents.
Do not claim a model council can guarantee supply-chain safety. It can compare candidates and surface risk. The install decision still belongs to the human and the repo owner.
Do not claim developers no longer need to understand code. The narrower claim is stronger: understanding should be grounded in proof scenarios.