AI Intuition

ai-intuition — ascend from particulars to arms, then predict

You have accumulated true facts about a system and still cannot say what it is. This skill compresses them into one claim and a few principles, and then makes those predict.

It follows a mapping step — codemap if you have it, any equivalent survey if you do not. This skill is what you do while still holding the map, before picking the first task.

Scope. This governs where to look next and what not to work on. It never governs what to declare done, verified or working: until a prediction is checked it is an assumption, and it is labelled as one when spoken. An intuition earns the right to a cheap check, nothing more. (Where a claim-labelling discipline exists — calibrate here — an unchecked arm is DEDOTTO at best, never OSSERVATO.)

When it applies

• The map exists (or enough of the system is in context) and you must choose what to work on.
• Facts have accumulated to the point where you consult them instead of using them.
• The same system has surprised you more than once.
• You are about to instrument or log to discover something. Stop: synthesise first, then instrument only to test a stated prediction.

The core move — one claim, three to six arms

1. Start from what codemap already wrote: the spine, the route table (input → route → why), the producer of each observable, the known gaps, the abandoned roads in the log.
2. Write the ONE claim: the single rule that decides the route table. One sentence. If you cannot write it, the map is missing a route or a route-selector — go back to codemap; do not invent it.
3. Derive 3–6 arms. The shapes below are the anatomy of a PORT or parity job; for other work the arms differ, so adapt rather than pad.
   • porting / matching a reference: what selects the route, and which routes the real inputs take; what produces each observable, and therefore what cannot move it; what the reference never does, so is off the required path; what the log shows was tried and abandoned; what must exist for the claim to hold but you have not yet seen.
   • debugging: what invariant the system maintains and where it is established; which observations are consistent with it holding, which are not; what the failure would have to be true of, upstream of where it is visible.
   • feature work: what the existing design makes cheap and what it makes expensive, and why; where the seam is that the feature belongs on; what will have to change that the request does not mention.
4. Take the five facts that cost you most to discover. Each must fall out of an arm. One that does not names a wrong or missing arm — fix the arm, do not add an exception.

Fewer than three arms means you compressed into mush. More than six means you made a table of contents, not a synthesis.

The test: a synthesis PREDICTS

• Before running any check, write the prediction into the head of the map file, thus: P<n>: <what you expect> | check: <one command or one file> | result: pending The pending entry on disk before the check is the only proof it was a prediction.
• A check is one command, one file read, or one existing test — minutes, no new instrumentation. If confirming a prediction needs instrumentation, it is not a prediction; it is the discovery you were supposed to skip. Back to the arms.
• Run the cheapest first. Then fill result: with confirmed/refuted and the evidence.
• A confirmed prediction validates that one consequence, not the arm and not the structure. A failed prediction is the highest-value signal available: it names the wrong arm. Fix the arm, do not patch the fact into an exception list.

Co-presence, not retrieval — and why this contradicts your tooling

Load whole files and whole subsystems. Structure emerges from relations, and relations need the related things present at once.

The argument is not about attention mechanics — attention over grepped chunks is still attention. It is about selection: a search hit is chosen by lexical match, so it presupposes you already know the term to search for. Retrieval therefore cannot surface the relation you have not yet conceived, which is precisely what you are missing when you reach for this skill. You will feel productive and stay oriented exactly as badly.

This puts the skill in direct tension with context-optimising tooling (here, context-mode: "if a file is over 200 lines and you only need specific data from it, use execute rather than reading the whole file"). Both are right, for different tasks. Extraction — you know what you need, you want it cheaply — is theirs. Comprehension — you do not yet know what you need, and that is the problem — is this one's. When the task is "what is this system", spend the context.

Practical: on setups where a hook diverts large command output to a file, shelling out to cat a big file gives you nothing while looking like it worked. Use the file-reading tool.

Signals you are missing synthesis

These fire on the SHAPE of the evidence, before any counter does. Rules that count cycles or failed attempts (here self-monitor, and the two-attempts second-opinion rule) catch the same dead ends later; if one of those fires first, you missed a signal below.

• You keep instrumenting to discover rather than to confirm.
• A counter or behaviour will not move no matter what you change locally — a routing/structural error, not a tuning problem.
• Your notes are a table of contents: headings and facts, no claim, nothing derivable.
• You can describe every part and cannot say what would break the whole.

Someone else's engineering log is a map of roads

FINDINGS files, engineering logs, ADRs, long commit messages: read them as a record of where paths LEAD, not as a description of how the code works. The most valuable artifact in a repository is a road that was tried and abandoned, with the reason.

• Ask of every entry: was this adopted, or is this a dead end someone paid to discover?
• An abandoned approach matching your current plan means you are re-walking it. Stop and confirm the recorded reason still applies before abandoning your plan.

Worked example — mesh2step, 2026-09-03

An 18k-line engine compressed to one claim and five arms. Before further measurement the arms predicted, and cheap checks then confirmed: that a whole category of work (analytic surface–surface intersection construction) was off the required path, because every fixture terminated on a route that never reaches it — removed by the route table codemap had already measured, the arm only made its consequence visible; that a missing parameter-adaptation function had to exist, because one arm demanded it; and that the reference's engineering log was a record of a road already abandoned, which the port had been re-walking step by step.

Keep it written, at the head of the map

The claim, the arms and the prediction log live at the top of the map document, above the particulars. A measurement that contradicts an arm rewrites the arm in the same breath as the code. A stale head is worse than none: the next session will derive from it.

Discipline

Time-box: if the claim is not on disk after re-reading the spine and the route table once, stop synthesising — the gap is in the map, not in your thinking.

Produce: one claim, the arms, the predictions with pending, the cheapest check — then act.