Why Is This a Map? — Detecting Cargo Cult and Routing Back
A learner pastes a cart that works and cannot say why it uses a Map, why the quantity changes on that line, or what the function returns and why. The guided flow is not a scolding: reasoning step, learner attempt, the smallest useful hint, another attempt, and the reference only when nothing else moved — and when the answer is a blank, a route back to the concept stage that owns it.
The situation, the reflex, and why it stalls
Every lesson starts where being stuck starts: someone has a problem, and the first move that comes to mind feels like progress.
You have a cart in front of you that runs — yours, a tutorial's, or an assistant's. What three questions expose whether it was derived or pasted, and when the answer is a blank, where exactly does the learner go?
A learner shows you their cart. It uses a Map keyed by product id, the add function does map.set(id, { ...existing, quantity: existing.quantity + qty }), and it returns a new Map. It passes the tests. You ask why it is a Map and they say "the AI said it was more efficient". You ask what it returns and they scroll up to check.
Ask the AI for the full implementation and study it. The reasoning is in the code; reading a good implementation carefully is how experienced people learn, and a working cart is a fine place to start reading. If it is unclear, ask the AI to explain it, line by line.
The explanation arrives fluently and is retained for exactly as long as the tab is open. "A Map gives O(1) lookup" is a true sentence that answers nothing about this cart — a handful of items, rendered in insertion order — and the learner cannot say what n is, so cannot say whether O(1) matters.
- The explanation arrives fluently and is retained for exactly as long as the tab is open. "A Map gives O(1) lookup" is a true sentence that answers nothing about this cart — a handful of items, rendered in insertion order — and the learner cannot say what n is, so cannot say whether O(1) matters.
- The return value is understood as "the new Map" and not as a decision. Returning a new collection instead of mutating is a choice with consequences — every caller must reassign; a React state setter needs it; a repository does not — and none of that was in the explanation because the learner did not know to ask.
- The next concept starts with the same paste. Nothing about being explained addItem produced the ability to write changeQuantity; the count of things the learner can build from an empty file is still zero, and the count of things they can explain from a full one is rising, which feels like learning.
The move
Precisely enough to apply it to a problem you have never seen — not a slogan.
- Ask the three detection questions, of one line each. Why is this a Map — what does the key buy that an array would not, and at what size does it matter? Why is the quantity changed here — which rule does this line encode, and which example proves it? Why does this function return this value — who uses the return, and what would break if it mutated instead? A fluent answer with a consequence and a condition passes; a blank, or "the AI said", is a signal — not of failure, but of where derivation stopped.
- Route each blank to the stage that owns it. Cannot say why a Map: representation — the two structures side by side with their complexity rows, and the requirement that would flip the choice (Why This Data Structure?). Cannot say why the quantity changes here: rules and examples — rule → validation → code for one-entry-per-product, and add-again as the example (Rules Come From Examples). Cannot say why it returns a new Map: operations — inputs, outputs, side effects, and the mutate-versus-return decision (Inputs, Outputs and Side Effects).
- Then run the guided flow, and its shape is the whole point. The AI states one reasoning step — "what does the cart have to remember?" — and stops. The learner attempts it. If the attempt is close, the next step. If stuck, the smallest useful hint — the concept's hint ladder has seven rungs from question to reference — and another attempt. The reference is shown only when two hints have moved nothing, and then it is compared with the attempt, not read instead of one (The Hint Ladder).
- The rule the flow enforces, stated so it can be argued with: the assistant does not hand over the full implementation before the learner has attempted the step. That is not a ban on the reference — it is rung seven of seven — and it is not a ban on the assistant, which is doing the asking. It is the line between a tool that accelerates understanding and one that replaces it (No AI on the First Attempt).
The flow, as a pipeline
The guided flow with the failure of each step when it is skipped. The step most often skipped is the attempt, and skipping it is the difference between a tutor and a vending machine: both produce the reference eventually, and only one produces a learner who could have written it.
- 1State one reasoning step
The assistant asks the concept's question for this stage — "what does the cart have to remember?" — and stops.
fails by Stating the step and the answer together, which is the reference with a preamble.
- 2The learner attempts
In words, on paper, or in code: the state, the example, the pseudocode — whatever the step asked for.
fails by Being skipped because the learner "just wants to see it"; without an attempt there is nothing for a hint to move.
- 3The smallest useful hint
One rung of the concept's seven: question, concept, data, algorithm, pseudocode, partial, reference. Pick the lowest rung that addresses what the attempt got wrong.
fails by Two rungs at once, or the rung the tutor finds most interesting rather than the one the attempt needs.
- 4Another attempt
The same step, again, with the hint. Most gaps close here.
fails by Treating a second wrong attempt as failure; it is the signal that the next rung is needed, nothing more.
- 5The reference, compared
After two hints that moved nothing: show the reference, and ask where the attempt differed and whether the difference is a rule or a style.
fails by Showing it and moving on; read without comparison, it is the paste again, with a tutor's permission.
The three detection questions run before the pipeline and decide where it starts: a blank on "why a Map" starts at the representation stage, not at the top.
The same need, asked of the assistant three ways
The learner's question to the tool decides what comes back. The vague form returns the implementation; the better form returns an explanation to be retained briefly; the best form returns a question the learner can answer, which is the only form that leaves something behind. The device is the learner's side of the flow.
why The best form makes the learner name the callers — a React setter, a repository, a test — and the consequence for each. It can be answered without the tool, it produces a decision the learner owns, and it transfers to every operation that returns something. The middle form produces a paragraph that will be gone by the next concept; the first form produces the paste.
Blank → stage → lesson
The routing table. Each detection question, the shape of a fluent answer, and where a blank sends the learner. The last row is the case where the flow does not apply, because the cart was never derived at any stage.
| Detection question | A derived answer contains | A blank routes to |
|---|---|---|
| Why is this a Map? | what the key buys, what n is, why order matters for the view, the requirement that would flip it | representation — the two structures with complexity rows; the hash-map DSA lesson for the O(1) claim |
| Why is the quantity changed here? | the rule one-entry-per-product, the example add-again, what would show if the line were missing | rules and examples — rule → validation → code, and the trace of add-again through this line |
| Why does this function return this value? | the callers, what each does with the return, the mutate-versus-return decision and its consequence for React state or a repository | operations — inputs, outputs and side effects; the concept's frameworkNote |
| All three blank | nothing — the cart was received whole | the concept stage: the cart-from-nothing lab from the meaning sentence, pasted code closed; hints assume holes, not absence |
The implementation ladder
Concept, examples, pseudocode, code, tests, production — for the concept this lesson is about. Code is the fourth tab, not the first.
Shopping Cart = A temporary collection of products the user intends to purchase, held between browsing and checkout.
- Does a cart have identity? Yes, weakly. Two carts with the same items are still two carts, because each belongs to someone and will become a different order. It needs an id once it leaves memory; in memory the variable is the identity.
- Who owns it? A shopper — a logged-in user or an anonymous session. The owner is part of the state because "my cart" has to be findable again.
- How long does it exist? From the first add until checkout or abandonment. Whether it survives a reload, a closed browser or a login is not a property of the concept; it is a persistence decision made later, and each answer changes where the cart lives.
- Should it survive reload? Usually yes for a store, usually no for a demo. V1 in memory says no; V2 browser storage says yes on one device; V3 server storage says yes everywhere the user is logged in.
- Should it survive login? Only if an anonymous cart and a logged-in cart are merged — a rule that does not exist in V1 and appears as a modification later.
- itemscollection of CartItemkeepThe cart is its items; without them nothing else means anything.
- items[].productIdidkeepThe reference to what is being bought. The catalog owns the product; the cart only points at it.
- items[].quantityinteger > 0keepTwo laptops is one entry with quantity 2, not two entries — the rule "one entry per product" needs a quantity to hold.
- owneruser id or session iddependsSo the cart can be found again by the person it belongs to.
- items[].productNamestringderiveIt would be convenient to render the cart without a catalog lookup.
- items[].pricemoneydependsThe total needs a price per item.
- totalmoneydropEvery screen shows the total.
- currencycodedependsPrices need a currency to be added.
- createdAttimestampdropAbandoned carts might be expired or emailed about.
- update Add item — the updated cart
- delete Remove item — the updated cart
- update Change quantity — the updated cart
- read View items — the list of entries — product id and quantity — for rendering
- domain Calculate total — the sum of price × quantity over the entries
- delete Clear cart — the empty cart
- • Every quantity is greater than zero.
- • One logical entry per product.
- • The total is never negative.
- • An unknown product cannot be added.
- • Quantity cannot exceed available stock — if inventory is enforced here.
How to do it
Most important first.
- When a learner — or you — presents working code, pick one line and ask why it exists before asking whether it is correct; the correctness is visible in the tests, and the why is not (Why Does This Exist?).
- Classify each blank by stage, out loud: "that is a representation question", "that is a rules question". The classification is the route; the learner leaves with a lesson name, not with a verdict.
- When guiding, give one rung at a time and wait. The concept's hints are ordered — question, concept, data, algorithm, pseudocode, partial, reference — and skipping two rungs because the learner looked frustrated is the reflex wearing a kind face.
- When being guided by an assistant, ask it for the next question rather than the answer: "what should I be asking about the return value?" rather than "what does it return?" (Good Tool Use).
- After the flow, run the rebuild: reference hidden, one operation, the stall list. If the stall list is empty and the three questions are answered with consequences, the paste has become a derivation (Hide the Reference and Build the Cart Again).
Worked on a concrete problem
The move has to produce something. This is what it produced.
- Why is this a Map? Learner: "faster lookup". Hint one (concept): "what does the cart's view need — order, or lookup?" Attempt: "order, it renders in the order things were added". Hint two (data): "how many entries does one shopper's cart have?" Attempt: "a few — so the scan is nothing, and a Map only keeps insertion order in JavaScript". The learner now has the consequence and the condition, and chose the array for V1 with the map written beside it as "when the collection is large or uniqueness must be structural". Two hints, no reference.
- Why is the quantity changed here? Learner: blank. Route: rules. The concept's rule "one logical entry per product" with its example add-again; the learner traces [ Laptop × 1 ] + add Laptop through the pasted line and sees the spread-and-add is the increase branch. The line is now the rule, and the learner can say what would show if it were missing: two Laptop rows. Route taken, one rung, back in a few minutes.
- Why does it return a new Map? Learner: "the AI said immutability is better". Hint one (question): "who calls addItem, and what do they do with what comes back?" Attempt: "the React state setter — so it needs a new object or it will not re-render". Hint two: "and the concept's reference mutates and returns the same cart — who is right?" Attempt: "both; it depends on the caller, and the concept's frameworkNote says the framework wraps the behaviour". The return value is now a decision the learner can make per caller, which is what "understood" means here.
- A learner who blanks on all three: not three routes, one — the concept stage. All three blanks say the same thing, that the cart was received whole, and the right move is the cart-from-nothing lab from the meaning sentence, with the pasted code closed. The flow above is for a cart that was mostly derived with holes; a cart that was entirely pasted needs the loop, not hints.
How you know it worked
What now exists that did not before, and what question you can now ask.
- Each of the three questions gets a consequence and a condition, and the learner can say which example proves each line.
- A blank turned into a stage name and a lesson, and the learner came back to the same line rather than to a fresh paste.
- The reference, when finally shown, was compared with an attempt — "mine used a loop, theirs used find; same behaviour" — rather than read.
- The next concept started with a meaning sentence and a state canvas, not with a prompt for the code.
The questions you can now ask
The field this whole domain exists for. After this lesson, these are the questions to put to an unfamiliar problem.
- ?For this line — why this structure, why this change here, why this return — can the answer name a consequence, an example and a condition?
- ?Which stage owns each blank, and which lesson is the route back?
- ?What is the smallest hint that would move the next attempt — and did I wait for the attempt?
- ?After the flow, does the rebuild stall anywhere, and are the three answers now the learner's own?
What can go wrong
- Turning detection into a test the learner fails. The three questions locate a stage; a learner told "you don't understand your own code" learns to paste more quietly. The route is the output; the verdict is noise.
- Skipping rungs. Two hints given at once is the reference in instalments; the flow works because each hint is smaller than the gap and the attempt in between is where the understanding forms.
- Refusing the reference on principle. Rung seven exists because sometimes two hints move nothing; withholding it then is not rigour, it is a stall with a moral. Show it, and compare.
- Applying the flow to a fully pasted cart. Hints assume a derivation with holes; three blanks out of three means the loop was never run, and the move is the lab from the meaning sentence.
- One rung at a time is slower than the reference, always, on the first cart; it is faster by the third, because the third cart's hints are answered before they are given.
- Routing a blank to a stage costs a detour of a lesson, in the middle of a cart that was working; the detour is the only version in which the next cart does not need it.
- A guiding assistant that withholds the full implementation is less convenient than one that hands it over, and the inconvenience is the mechanism; a learner who can switch it off will, on a bad day, and that is a fair thing to know about oneself.
- "So never ask an AI for code." Ask it for the next question, the next rung, and — at rung seven — the reference to compare against. The line is asking for the implementation before the attempt, and the rule is scoped to learning a concept, not to shipping one you already understand.
- "Cargo cult is a beginner problem." The senior who keeps a retry wrapper because the last project had one, and cannot say what it retries or why, is running the same pattern with better vocabulary. The three questions are the same at every level.
- "If the learner can explain it after being told, they understand it." Explaining after being told is recall with a short half-life. The check is the rebuild and the modification — can they produce it, and can they change it — and both come after the flow, not instead of it.
Where this applies
Problem-solving advice is stated as universal far more often than it is. These labels say what each method is specific to — and where CONTESTED appears, the note gives the strongest form of the opposing view.
- GENERALWhy this structure, why this change here, why this return — asked of any working code, from any source, at any level of experience; the routes back are the stages of the loop, which every concept shares.
- CONTESTEDThe strongest opposing view: reading excellent implementations closely is how many good engineers learned, and a rule that the assistant withholds the full implementation until an attempt exists slows a learner who would have derived the reasoning from the code on their own. The reply here is scoped, not absolute: reading is rung seven of seven and is compared against an attempt; the delay is the mechanism by which the attempt exists at all; and the rule applies while a concept is being learned, not while a known one is being shipped. Where the learner can already answer the three questions before the paste, the flow has nothing to add and should not be run.
- ILLUSTRATIVEThe Map cart, the spread-and-add line and the two-hint exchanges are invented to show the flow; the hint rungs, the rules and the example add-again are quoted from the concept record.
Where the depth lives
This domain asks the question and hands the answer off by name.
- — The manifesto's review mode at /manifesto/review is the three detection questions turned into a habit for every line before it is merged.
- — The manifesto's Build Without AI mode at /manifesto/without-ai is the flow with the assistant removed entirely: attempt, then one rung of help from a person or a book, then attempt again.