Keep notes private and goals verifiable

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.

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.

Source references