{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "codex-goals",
  "slug": "goals",
  "title": "Keep notes private and goals verifiable",
  "summary": "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.",
  "category": "Planning",
  "tags": [
    "goals",
    "proof",
    "skills"
  ],
  "sources": [
    {
      "label": "Codex workflows companion",
      "url": "https://lapis-fossil-vsbc.here.now/#goals"
    },
    {
      "label": "Published workshop recording",
      "url": "https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0"
    }
  ],
  "sourceUnits": [
    "src/content/final/chunk-13-keep-notes-local-make-goals-verifiable.md",
    "src/content/final/chunk-13-keep-notes-local-make-goals-verifiable.md#Keep Notes Local, Make Goals Verifiable",
    "src/content/final/chunk-13-keep-notes-local-make-goals-verifiable.md#Keep Notes Local, Make Goals Verifiable/The Move",
    "src/content/final/chunk-13-keep-notes-local-make-goals-verifiable.md#Keep Notes Local, Make Goals Verifiable/Notes Become Goals",
    "src/content/final/chunk-13-keep-notes-local-make-goals-verifiable.md#Keep Notes Local, Make Goals Verifiable/Long Agent Work Needs Intervals",
    "src/content/final/chunk-13-keep-notes-local-make-goals-verifiable.md#Keep Notes Local, Make Goals Verifiable/Understanding Becomes Proof Design",
    "src/content/final/chunk-13-keep-notes-local-make-goals-verifiable.md#Keep Notes Local, Make Goals Verifiable/Ask For Lists, Not Comfort",
    "src/content/final/chunk-13-keep-notes-local-make-goals-verifiable.md#Keep Notes Local, Make Goals Verifiable/Treat Public Skills As Candidates",
    "src/content/final/chunk-13-keep-notes-local-make-goals-verifiable.md#Keep Notes Local, Make Goals Verifiable/Force Known Context",
    "src/content/final/chunk-13-keep-notes-local-make-goals-verifiable.md#Keep Notes Local, Make Goals Verifiable/Copyable Artifact: Goal Packet",
    "src/content/final/chunk-13-keep-notes-local-make-goals-verifiable.md#Keep Notes Local, Make Goals Verifiable/Claim Boundaries",
    "src/lib/content/sections.ts",
    "src/lib/content/sections.ts#goals",
    "src/lib/content/sections.ts#recordingSpans"
  ],
  "collection": "codex",
  "categoryId": "planning",
  "wordCount": 1212,
  "url": "/topics/codex-goals/",
  "markdownUrl": "/markdown/codex-goals.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/codex-goals.json",
  "headings": [
    {
      "id": "the-move",
      "text": "The Move",
      "level": 2
    },
    {
      "id": "notes-become-goals",
      "text": "Notes Become Goals",
      "level": 2
    },
    {
      "id": "long-agent-work-needs-intervals",
      "text": "Long Agent Work Needs Intervals",
      "level": 2
    },
    {
      "id": "understanding-becomes-proof-design",
      "text": "Understanding Becomes Proof Design",
      "level": 2
    },
    {
      "id": "ask-for-lists-not-comfort",
      "text": "Ask For Lists, Not Comfort",
      "level": 2
    },
    {
      "id": "treat-public-skills-as-candidates",
      "text": "Treat Public Skills As Candidates",
      "level": 2
    },
    {
      "id": "force-known-context",
      "text": "Force Known Context",
      "level": 2
    },
    {
      "id": "copyable-artifact-goal-packet",
      "text": "Copyable Artifact: Goal Packet",
      "level": 2
    },
    {
      "id": "claim-boundaries",
      "text": "Claim Boundaries",
      "level": 2
    },
    {
      "id": "related-resources",
      "text": "Related resources",
      "level": 2
    }
  ],
  "markdown": "# Keep notes private and goals verifiable\n\nAgent-heavy work creates a lot of half-formed context: dictated notes, failed prompts, benchmark ideas, security worries, skill candidates, and \"try this later\" scraps.\n\nDo not commit that pile. Keep scratch private, ignored, and temporary until it **earns its way into a goal**.\n\n```text\nprivate scratch note\n-> reviewed goal packet\n-> bounded agent work\n-> proof scenario\n-> saved evidence\n-> next goal\n```\n\n## The Move\n\nUse a project-local scratch space for messy notes and a **reviewed goal packet** for actual work.\n\nLocal 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.\n\n> 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.\n>\n> — John Lindquist\n\n- Scratch notes are not documentation.\n- Goals are not wish lists.\n- A note is where messy thinking lands.\n- A goal is what survives review and becomes work.\n\n## Notes Become Goals\n\nA 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.\n\nExample:\n\n```text\nScratch note:\nCheckout submit stayed disabled after selecting shipping.\n\nGoal:\nFind the smallest cause of the disabled checkout submit state.\n\nLikely areas:\n- checkout form state\n- shipping selection reducer\n- submit button disabled logic\n\nProof:\n- reproduce failing state\n- add or run component test\n- run checkout smoke test\n- capture before/after result\n\nStop if:\n- payment-provider adapter must change\n- no reproducible failing state exists\n```\n\nPrivate notes stay private. Sanitized patterns can become docs later.\n\n## Long Agent Work Needs Intervals\n\nTreat long agent runs as **interval work**.\n\nSet 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.\n\nField rule:\n\n```text\nIf the agent has a bounded goal and a proof command,\nstep away until the interval ends.\nWatching the terminal harder does not make the benchmark finish.\n```\n\nGood launch shape:\n\n```text\nStart a migration lane with:\n- allowed files\n- files to avoid\n- verification command\n- check-in interval\n- stop condition\n\nReturn when:\n- the timer fires\n- the agent reports blocked\n- the proof command finishes\n- a boundary conflict appears\n```\n\n**AFK does not mean unsupervised merge.** It means the work unit is bounded enough that the human can leave and return to concrete evidence.\n\n## Understanding Becomes Proof Design\n\nYou still need judgment. What changes is the unit of understanding.\n\n> The best you can hope for is understanding the scenarios that prove the code works the way you expect it to.\n>\n> — John Lindquist\n\nThe 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.\"\n\nExamples:\n\n| Task | Proof Scenario | Evidence | Does Not Prove |\n|---|---|---|---|\n| Checkout disabled state | Shipping selected, submit enables | Component test, smoke test | Every payment-provider state |\n| Billing retry | Duplicate event processed once | Fixture, idempotency test, log | All provider outage modes |\n| Auth/session rotation | Stale session rejected safely | Security test, route check | Every browser/session store |\n| Performance change | Same fixture before/after | Benchmark output | Production latency |\n\n**Proof scenarios are how codebase understanding stays grounded** when code is moving quickly.\n\n## Ask For Lists, Not Comfort\n\nAvoid vague reassurance prompts:\n\n```text\nAre you sure?\nIs this correct?\nWhy did this work?\n```\n\nAsk for structured reasons instead:\n\n```text\nDo not reassure me.\n\nList 5 reasons this proof actually covers the checkout disabled-state bug.\nFor each reason, include:\n- the behavior it checks\n- the evidence source\n- what it does not prove\n- one way this could still be wrong\n```\n\nMore useful prompts:\n\n```text\nList 5 ways this benchmark could be misleading.\n```\n\n```text\nList 7 security assumptions this auth/session change depends on.\n```\n\n```text\nList 4 reasons the smoke test covers the regression, then list 4 gaps it leaves open.\n```\n\nAgents are good at sounding certain. **Lists force certainty to expose its assumptions.**\n\n## Treat Public Skills As Candidates\n\nPublic skills are **supply-chain inputs**. Evaluate before installing.\n\nFor a software task, search with multiple terms instead of one narrow phrase.\n\nExample task:\n\n```text\nImprove accessibility checks for a Svelte checkout flow.\n```\n\nSearch terms:\n\n```text\naccessibility audit\na11y test\nSvelte accessibility\nPlaywright axe\nWCAG checker\nkeyboard navigation\nscreen reader smoke test\nARIA validation\nform accessibility\ncontrast checker\n```\n\nThen ask a model council or **[Oracle](https://github.com/johnlindquist/oracle)** to compare candidates:\n\n```text\nCompare candidate skills for this task.\n\nFor each candidate:\n- what it claims to do\n- source/repo/package origin\n- maintenance signals\n- install or execution risk\n- whether it reads project files\n- whether it runs code\n- what useful prompt or function can be extracted without installing\n- recommendation: install / adapt / reject\n```\n\nReading a skill is not the same as trusting it. Installing it is a separate decision.\n\n## Force Known Context\n\nIf 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.**\n\nWeak:\n\n```text\nFind the right skill and fix checkout.\n```\n\nBetter:\n\n```text\nWe use SvelteKit.\nThe failing path is /checkout.\nThe bug is submit disabled after shipping selection.\nDo not touch the payment provider adapter.\nThe proof is the checkout component test plus billing smoke test.\nSearch for skills only if they help inspect this exact scenario.\n```\n\n## Copyable Artifact: Goal Packet\n\n```text\nScratch source:\n- note id or summary:\n- why this matters now:\n\nGoal:\n- what should be true when this is done:\n\nKnown context:\n- repo area:\n- likely files:\n- constraints:\n- files/tools to avoid:\n\nAgent work:\n- first inspection step:\n- allowed edits:\n- stop conditions:\n\nProof scenario:\n- user path or system behavior:\n- test:\n- smoke check:\n- benchmark:\n- security check:\n- debug/log evidence:\n\nReason list required:\nAsk the agent to list:\n- 5 reasons this proof covers the goal\n- 5 gaps this proof leaves open\n- 3 assumptions that could make the result wrong\n\nPacing:\n- check-in interval:\n- what to inspect when returning:\n\nSkill evaluation, if needed:\n- 10 search terms:\n- candidate skills:\n- Oracle/Fusion comparison saved?\n- source scraped/read before install?\n- useful parts extracted?\n- install decision: install / adapt / reject\n\nCompletion:\n- evidence attached:\n- remaining uncertainty:\n- next goal created:\n```\n\n## Claim Boundaries\n\nDo not share private note contents, global ignore files, local config, machine paths, usernames, or private skill contents.\n\nDo 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.\n\nDo not claim developers no longer need to understand code. The narrower claim is stronger: understanding should be grounded in proof scenarios.\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/#goals)\n- [Resource directory and portable download](/topics/codex-resources/)\n- [Published recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0)"
}
