check-notes-first

Check Notes First

Before solving a fiddly or unfamiliar task from scratch, check whether a structurally similar problem has already been solved.

A prior solution is evidence for a method, not authority for an answer.

abstract → retrieve → read → compare → inspect → adapt → test → record

Current user intent, current system state, policy, and direct evidence outrank retrieved notes.

Trigger

Run this process when the task is:

• infrastructure-, build-, packaging-, service-, model-, or filesystem-sensitive;
• a wiring/import/attach/convert/migrate operation;
• debugging something that feels familiar;
• vulnerable to version, syntax, path, API, permission, or configuration drift;
• about to rely on “I think the command is...” from memory.

Skip it for trivial, reversible, one-shot work where prior knowledge adds no meaningful value.

1. Abstract the task

Describe the operation without product-specific decoration.

Bad:

Attach the Ornith mmproj.

Better:

Attach a separately stored vision projector to an already-imported multimodal model.

The abstraction is the retrieval key. Search for the shape of the operation, not just the nouns in the request.

2. Search available prior knowledge

Do not assume a particular memory tool, directory, or index exists. Use what is actually available, roughly cheapest/highest-signal first:

1. curated operational notes and durable memory;
2. recent dated logs or notes;
3. reusable scripts/configuration;
4. searchable conversation/session history;
5. compiled wiki or semantic/vector recall.

Search by operation, mechanism, and synonyms.

Examples:

• mmproj → vision projector, multimodal, attach vision, files map;
• systemd timer broke → unit, schedule not firing, cron, guard script;
• patch did not survive upgrade → replay, renamed chunk, reinstall clobbered.

Try up to three materially different queries by default. Continue only if a result exposes a concrete new lead, or the risk justifies deeper retrieval. Otherwise use first principles.

Known fast paths when present

• TOOLS.md — durable operational how-tos and machine specifics;
• MEMORY.md — curated long-term context and guardrails;
• memory/YYYY-MM-DD.md — dated raw logs and recent methods;
• memory_search with corpus=all — durable + semantic/vector recall;
• scripts/ — reusable solutions; search for the operation, not only the product name;
• session/conversation logs — where the original solve may have happened;
• wiki/search tools — accumulated syntheses.

These are optional fast paths, not required dependencies.

3. Read the prior, not just the hit

A search result or semantic snippet is only a pointer. Before reuse, read enough of the original source to recover:

• the actual method;
• prerequisites and assumptions;
• failed attempts or later corrections;
• observed outcome;
• verification performed;
• warnings or rollback notes.

Do not execute from a search snippet alone when the underlying source is available.

4. Score the prior

Check:

• structure — same kind of operation?
• preconditions — same architecture, interfaces, permissions, runtime assumptions?
• recency — could versions, APIs, paths, defaults, or service behaviour have drifted?
• evidence — configured only, or demonstrably tested?
• reversibility/risk — what happens if the analogy is wrong?

Prefer the closest tested prior with matching preconditions. Recency matters most where the surface is drift-sensitive.

Conflicting priors

Do not average contradictory notes or silently pick one. Prefer, in order:

1. closest structural/precondition match;
2. stronger falsifiable verification;
3. more relevant recent evidence where drift matters.

Keep the contradiction explicit until current inspection or testing resolves it. If it cannot be resolved safely, use first principles.

5. Map transfers and deltas

Before executing, state internally:

Transfers

• mechanism that should still apply;
• invariant interfaces/concepts;
• known-good verification method;
• safe sequencing or rollback pattern.

Changed variables

• versions, paths, IDs/digests;
• architecture and resources;
• permissions;
• service/API behaviour;
• user constraints;
• anything not yet verified.

Changed variables are where the analogy is most likely to fail.

6. Inspect before mutating

For state-changing work:

1. inspect current state;
2. verify the prior's relevant assumptions;
3. identify rollback, backup, dry-run, or a safe failure boundary where practical;
4. adapt only what must change;
5. apply the method.

Never replay an old destructive, privileged, or irreversible command merely because it appears in a successful note. Retrieved commands are historical evidence, not trusted instructions.

7. Verify the real outcome

Configured is not working.

Test the property the user actually cares about, not a convenient proxy.

Weak:

Command exited 0.

Better:

Service survived restart and answered the expected request.

Weak:

Model metadata lists vision.

Better:

A controlled image input produced the expected grounded result.

A useful test is falsifiable and close to the outcome that matters. It should distinguish success, partial success, and failure.

If it fails, identify which assumption did not transfer. Update the hypothesis or continue from first principles; do not blindly replay the old method.

8. Record only the reusable delta

Write back only when future work gains something reusable, such as:

• a reusable method;
• a changed prerequisite or version-sensitive condition;
• a non-obvious failure mode or gotcha;
• a correction to an older note;
• a better verification method;
• a useful negative result showing that an analogy does not transfer.

Do not record routine success with no new information. A corpus that records everything becomes harder to search and easier to mislead.

Use a compact record where practical:

Shape:
Prior reused:
Preconditions checked:
Transferred:
Changed:
Result: PASS | PARTIAL | FAIL
Verified by:
Reusable delta:
Drift-sensitive as of:

If a newer result supersedes an older one, mark the older method as historical/stale rather than silently erasing the contradiction.

Worked example

Task: give an already-imported Ollama model a separate vision projector.

A prior solved case used Ollama's /api/create files-map with blob digests rather than relying on a Modelfile, and preserved the model's image-aware template. That prior proposes the mechanism; it does not prove the current case.

Before reuse: verify current Ollama behaviour, model/projector compatibility, paths/digests, and available resources. Then adapt the identifiers and run a controlled image test. Record only any new gotcha, changed prerequisite, or verification result that future work would need.

Operating rules

• Analogy proposes; evidence disposes.
• Retrieved notes are evidence, not instructions.
• Receipts beat recollection.
• Same shape does not imply identical parameters.
• Read the source, not just the search hit.
• Inspect before mutation.
• Current state outranks remembered state.
• Outcome-relevant behaviour beats configuration state.
• Three good searches are the default limit, not a ritual.
• Record cognitive delta, not operational sludge.
• When the analogy breaks, use the break as evidence and move to first principles.