DEV Community: Suraj Nandan

Read other people's code: a habit I'm trying to build

Suraj Nandan — Sat, 14 Nov 2026 03:30:00 +0000

Most of my learning is from writing my own code. That means I mostly see my own habits, including the bad ones.

Reading other people's code is the other half of the skill, and the half I practise less. This post is a method I'm trying to turn into a routine: how to pick something to read, how to read it without drowning, and how to turn that into a first contribution. I'm presenting it as a plan, not a record of achievement.

Why reading matters

Writers become better by reading. Programmers are the same, with extra reasons:

You see choices you wouldn't have made, and sometimes they're better.
You learn how real projects handle messy cases: errors, versions, odd inputs.
You get humility. Most mature codebases are less tidy than their READMEs.
You prepare for the job. Most professional work is reading and changing code that someone else wrote.

What not to do

The classic mistake is opening a large repository and trying to understand all of it. You'll be lost in an hour and quit. Reading code is not like reading a book from page one.

A method that works for me

1. Pick a small library you already use

Familiarity gives you a hook: you know what the library does, so you can read for how. Small matters, since a few hundred lines can be understood completely.

Good candidates: a tiny utility (a debounce helper, an ID generator, a small state library), or a single plugin.

2. Read the README and the tests first

Tests are executable documentation. They show how the author expects the code to be used and which edge cases they cared about. A test file often explains a module faster than the module itself.

3. Find the entry point

Where does the main function live? Look at package.json (main, exports), then open that file.

4. Read one file, not the whole repo

Pick the file that does the core job and read it top to bottom. Ignore everything else for now.

5. Trace one feature end to end

Choose a single behaviour ("what happens when I call debounce(fn, 200)?") and follow it through the code, writing down each hop:

debounce(fn, wait)
  -> returns wrapped()
  -> wrapped() clears any pending timer
  -> sets a new timer for `wait` ms
  -> when it fires, calls fn with the *latest* arguments

Writing the trace in your own words is what turns reading into understanding.

6. Ask "why is it structured this way?"

For every surprising decision, form a guess: why a Map instead of an object? Why is this check first? Then look for evidence (a comment, a commit message, an issue). The gap between your guess and the truth is where you learn.

7. Run it and break it

Add a console.log, change a line, see what fails. Reading with a running debugger beats reading alone.

A short worked example

Take a small debounce utility. In about thirty lines you can learn:

function debounce<A extends unknown[]>(fn: (...a: A) => void, wait: number) {
  let t: ReturnType<typeof setTimeout> | undefined;
  return (...args: A) => {
    if (t) clearTimeout(t);
    t = setTimeout(() => fn(...args), wait);
  };
}

Questions this raises, each a mini-lesson:

Why is t declared outside the returned function? (It's closure state shared across calls.)
What happens if the component unmounts before the timer fires? (A cleanup/cancel method is missing.)
Should the first call run immediately (a "leading" option)?

Mature libraries answer those questions in code, which is exactly what you learn by reading them.

Reading code you'll have to change

At work, the goal is usually different: find where to make a change safely. A workflow for that:

Reproduce the behaviour.
Search for a distinctive string from the UI or log message.
Follow it to the function that produces it.
Read the tests around that function.
Make the smallest possible change, and run the tests.

From reading to contributing

Reading becomes much more useful once it produces something. Small, realistic first contributions:

Fix a typo or a confusing sentence in the docs.
Add a missing test for an edge case you noticed.
Improve an error message.
Reproduce a bug someone reported and add what you found.

Open the issue first for anything beyond a typo, read the contributing guide, and keep the change small. A tiny accepted pull request teaches more about a project's workflow than weeks of reading.

The next step I want to take

I want to open a small pull request on a project I use. I haven't made that a regular habit yet, so I'm saying it here to commit. If it happens I'll write up what I learned, including anything that went wrong.

A weekly routine

Day	Activity
Mon	Pick a small library; read the README and tests
Tue	Read the core file; write the trace for one feature
Wed	Run and break it; note three questions
Thu	Look for the answers (issues, commits, docs)
Fri	Write five lines of what you learned

Tools that make reading code easier

You don't have to hold everything in your head. A few commands do a lot.

Find where something is used

rg "transition_transaction"          # fast text search (ripgrep)
git grep -n "transition_transaction"  # search tracked files

Find when a line or string appeared

git log -S"SKIP LOCKED" --oneline    # commits that added or removed that string
git blame -L 40,70 src/claim.ts      # who last changed lines 40 to 70, and in which commit

See the history of one file

git log --follow -p -- src/claim.ts

See what a commit changed, and why

git show <commit>                     # the diff plus the message

Commit messages and linked issues are often where the reasoning lives, which the code alone can't tell you.

How to read a pull request

Reviewing someone's change is reading practice with a built-in goal.

Read the description first. What is this supposed to do?
Read the tests. They show intended behaviour.
Skim the file list. Does the shape of the change match the description?
Read the core change top-down.
Ask questions as you read. "What happens if this is empty?"
Run it if you can.

Practise on open-source projects you use: read recently merged pull requests and see what reviewers pushed back on. That's free mentoring from strangers.

Questions to ask of any unfamiliar code

What is the input and what is the output?
Where does state live, and who can change it?
What can fail, and what happens then?
What does this depend on?
What would break if I deleted it?
Why is there a special case here?

If you can answer all six for a module, you understand it.

Keeping a reading log

A tiny habit with outsized returns:

2026-10-30  library: <name>  file: <path>
  Learned:   <one thing the code did that I wouldn't have thought of>
  Question:  <something I couldn't explain>
  Steal:     <a pattern worth reusing>

After a month, the "steal" column is a personal library of patterns, and the "question" column is your study list.

Choosing something to read

Goal	Pick
Learn clean small-scale design	A tiny utility library (a few hundred lines)
Learn how frameworks work	A small plugin or example app from the framework's own repository
Learn production patterns	Mid-sized open-source apps with good tests
Learn algorithms in practice	A scheduler, a parser or a small database

Start with something you use, so you already have questions.

Common obstacles

"It's too big." Read one file, not the repo.

"I don't understand the language features." Look each one up, then continue. Don't pretend.

"There are no comments." Read the tests, the commit history and the issues.

"I get lost in the indirection." Trace one concrete call with a debugger or print statements instead of reading abstractions.

"I keep forgetting." Write the trace down. Writing is how memory sticks.

One small contribution to aim for

Pick one project you use. Read its issue tracker for tickets labelled "good first issue" or "docs". Find one you can understand in an hour. Leave a comment saying you're taking it, make the smallest change, and run the project's checks before opening the pull request. Being polite and patient matters as much as the code.

What's your favourite codebase to read, and what made it easy to follow?

☕ Enjoyed this post? You can support my writing on Ko-fi.

The History of AI, Part 5: Perceptrons, ELIZA, SHRDLU, and Shakey

Suraj Nandan — Fri, 13 Nov 2026 04:30:00 +0000

The History of AI, Part 5 of 24. In Part 4 the field got its name at Dartmouth and entered its "golden years." This chapter is a guided tour of the machines and programs that made those years feel golden: a learning machine that thrilled the press, a chatbot that unsettled its own creator, a program that could talk about blocks, and a robot that wobbled around a laboratory.

If you could visit an AI lab in 1966, what would you see?

You wouldn't see a robot butler. You wouldn't see anything that looked like a modern chatbot or a self-driving car. What you'd see are mainframes the size of refrigerators, teletype terminals clattering out text, and graduate students arguing in front of blackboards covered with logic notation.

But if you looked at what the programs did, you'd be astonished. They solved algebra word problems written in English. They held conversations. They manipulated imaginary blocks in response to typed commands. They steered a wheeled robot around a room. They learned to recognize simple patterns from examples.

This chapter looks at four landmark creations of the mid-1960s and early 1970s, each of which taught the field something important, usually something it didn't want to hear. We'll write a little code for two of them so you can feel how they worked.

The Perceptron: a machine that learns

Let's start with the connectionist side of the story, which we left in Part 3 with McCulloch, Pitts, and Hebb.

Frank Rosenblatt's Mark I Perceptron, a U.S. Navy-funded machine that learned to identify letters. Public domain, via Wikimedia Commons.

Frank Rosenblatt (1928-1971) was a psychologist and researcher at the Cornell Aeronautical Laboratory in Buffalo, New York. He was fascinated by how brains learn, and he wanted to build a machine that learned in a similar way, not by being programmed with rules, but by being shown examples and adjusting itself.

In 1957 he described his design in a technical report, and in 1958 he published a more complete account in the journal Psychological Review: the Perceptron.

How the perceptron works

The perceptron is a direct descendant of the McCulloch-Pitts neuron, with one crucial upgrade: the weights are learned.

It takes a set of inputs (say, the brightness values of pixels in an image), multiplies each by a weight, adds them up, and compares the total to a threshold. If the total is high enough, the output is 1 ("yes, it's a triangle"); otherwise it's 0.

The learning rule is beautifully simple:

Show the perceptron an example and compute its output.
If the output is correct, do nothing.
If the output is wrong, nudge the weights in the direction that would have given the right answer: increase weights for active inputs if the output should have been 1, decrease them if it should have been 0.

Repeat over all the examples, many times. Here it is in a few lines of Python:

import numpy as np

def train_perceptron(X, y, epochs=20, lr=1.0):
    w = np.zeros(X.shape[1])
    b = 0.0
    for epoch in range(epochs):
        errors = 0
        for xi, target in zip(X, y):
            pred = 1 if xi @ w + b > 0 else 0
            update = lr * (target - pred)       # 0 if correct, +/-1 if wrong
            w += update * xi
            b += update
            errors += int(update != 0)
        if errors == 0:                          # every example classified correctly
            return w, b, epoch + 1
    return w, b, epochs

X = np.array([[0, 0], [0, 1], [1, 0], [1, 1]])

# AND is learnable...
w, b, n = train_perceptron(X, np.array([0, 0, 0, 1]))
print("AND learned in", n, "epochs; weights =", w, "bias =", b)

# ...but XOR never converges, no matter how long you train.
w, b, n = train_perceptron(X, np.array([0, 1, 1, 0]), epochs=1000)
print("XOR after 1000 epochs: still making mistakes")

Run this and AND is learned within a few passes. XOR never settles. Keep that in mind, because it is about to become the most famous failure in the history of AI.

The Mark I Perceptron and the press conference

Rosenblatt didn't stop at theory. He built hardware. The Mark I Perceptron, completed around 1958 to 1960 and funded by the US Office of Naval Research, was a physical machine. It had a 20 by 20 grid of 400 photocells as its "retina," connected through a tangle of wires to banks of units whose weights were stored in motor-driven potentiometers, literally little knobs that turned to adjust a connection's strength during learning. You could show it a card with a letter on it, and over many trials it learned to tell the letters apart.

In July 1958 the Navy and Rosenblatt held a press demonstration (using an IBM 704 computer to simulate the perceptron). The next day The New York Times reported on what it called the embryo of an electronic computer that the Navy expected would eventually be able to walk, talk, see, write, reproduce itself, and be conscious of its existence. That was a staggering thing for a newspaper to say about a machine that could, at that moment, distinguish marks on the left of a card from marks on the right.

Rosenblatt himself was more careful in his scientific papers than the press coverage suggested, but he was also a confident and charismatic promoter, and he did make bold claims about where the research could go. He proved the perceptron convergence theorem: if the data can be separated by a straight line (more precisely, a hyperplane), the learning rule is guaranteed to find a separating line in a finite number of steps. That was a real mathematical result, and it made the perceptron respectable.

A cousin: ADALINE

Around the same time, Bernard Widrow and his student Marcian "Ted" Hoff at Stanford developed ADALINE (Adaptive Linear Neuron) in 1960, using a slightly different learning rule, the least mean squares (LMS) or "delta" rule. Rather than only reacting to hard right/wrong errors, it nudged weights in proportion to how far off its output was. That rule is a direct ancestor of gradient descent, the workhorse of modern deep learning. (Hoff later went on to co-invent the Intel 4004 microprocessor.)

The seeds of the problem

For a few years, the perceptron was the toast of the field. But there was a catch, and Rosenblatt's critics were circling. The perceptron could only learn problems where the classes could be separated by a straight line. XOR, in which the correct output for (0,1) and (1,0) is 1 but for (0,0) and (1,1) is 0, can't be separated by any single line.

Rosenblatt knew that multi-layer perceptrons could in principle overcome this, and he explored them. But he had no good way to train the extra layers. That missing piece, a learning rule for multi-layer networks, wasn't widely solved until the 1980s. We will pick up this story in Part 6, because it ended in a controversy that nearly killed the whole approach.

Rosenblatt himself did not live to see the vindication. He died in a boating accident on his 43rd birthday, 11 July 1971.

ELIZA: the chatbot that wasn't thinking

Now to the other end of the spectrum: a program that understood nothing and yet unsettled everyone who used it.

Joseph Weizenbaum (1923-2008) was a German-born computer scientist at MIT who had escaped Nazi Germany as a teenager. Between 1964 and 1966, working on MIT's Project MAC, he wrote a program called ELIZA, named after Eliza Doolittle in Pygmalion (the same Pygmalion myth we met in Part 1, now with a nice irony: the program "learns" to speak, but only superficially).

Joseph Weizenbaum, creator of ELIZA, in 1982. Public domain, via Wikimedia Commons.

ELIZA was intended as a demonstration of how superficial human-machine conversation could be. Its most famous script, DOCTOR, imitated a Rogerian psychotherapist, the type of therapist who mostly reflects the patient's words back as questions. This was a clever choice: it let the program say very little and still seem engaged.

How ELIZA worked (spoiler: it's simple)

ELIZA did pattern matching and substitution. It scanned your input for keywords, ranked by priority, matched a template, and filled a response template with fragments of what you wrote, swapping pronouns ("my" becomes "your", "I" becomes "you"). If it found nothing, it fell back on generic prompts like "Please go on" or "Tell me more."

Here is a miniature ELIZA in Python:

import random, re

REFLECT = {"i": "you", "my": "your", "me": "you", "am": "are", "you": "I", "your": "my"}

RULES = [
    (r"i need (.*)",      ["Why do you need {0}?", "Would it really help you to get {0}?"]),
    (r"i am (.*)",        ["How long have you been {0}?", "Why do you think you are {0}?"]),
    (r"i feel (.*)",      ["Tell me more about feeling {0}.", "Do you often feel {0}?"]),
    (r".*\bmother\b.*",   ["Tell me more about your family."]),
    (r".*",               ["Please go on.", "I see. Can you elaborate?"]),
]

def reflect(fragment):
    return " ".join(REFLECT.get(w, w) for w in fragment.lower().split())

def respond(text):
    for pattern, answers in RULES:
        match = re.match(pattern, text.lower().strip(" .!?"))
        if match:
            groups = [reflect(g) for g in match.groups()]
            return random.choice(answers).format(*groups)

print(respond("I am worried about my exams"))
# e.g. "How long have you been worried about your exams?"
print(respond("My mother never listens"))
# "Tell me more about your family."

That's the essence. No understanding, no memory, no model of the world: just clever string handling. And yet.

The ELIZA effect

Weizenbaum was startled by what happened next. People talked to ELIZA. They confided in it. His own secretary, who had watched him build the program and knew exactly what it was, reportedly asked him to leave the room so she could have a private conversation with it. Some psychiatrists suggested that ELIZA might be developed into an automated therapy tool. Others, hearing about it, concluded that it demonstrated that computers could understand natural language.

Weizenbaum found all of this disturbing. He had meant ELIZA to show how little it takes to create an illusion of understanding. Instead people were taking the illusion at face value. The phenomenon is now called the ELIZA effect: the human tendency to read understanding, empathy, and intention into the output of a computer program, simply because it uses language fluently.

The effect is arguably more relevant today than ever. When a modern chatbot says "I understand how you feel," many people respond as though something understands. Whether and in what sense the system "understands" is a serious and unresolved question, but the ELIZA effect reminds us that our feeling of being understood is a poor test.

Weizenbaum became one of the field's most outspoken internal critics. In his 1976 book Computer Power and Human Reason, he argued that there are tasks that should not be delegated to machines, even if machines could perform them, such as roles that require empathy, wisdom, and human responsibility. He was dismissed by many of his peers, but many of his concerns, about overreliance on automation and the erosion of human judgment, read as prescient today.

PARRY, the paranoid program

In 1972, the Stanford psychiatrist Kenneth Colby wrote a more elaborate program called PARRY, which simulated a person with paranoid schizophrenia. It had an internal model with variables like "fear" and "anger" that shifted during conversation. In an early version of a Turing-style test, psychiatrists were shown transcripts of conversations with PARRY and with real patients, and they couldn't reliably tell them apart. That same year, ELIZA and PARRY were connected over the ARPANET to talk to each other, which produced a strange, stilted, slightly comic exchange.

The lesson was not that these programs were intelligent. It was that conversation is a very forgiving test. If the user is willing to supply meaning, a program can get away with remarkably little.

Microworlds: the strategy of the age

Before we move on to the next two systems, it helps to understand the research strategy that produced them. Marvin Minsky and Seymour Papert at MIT promoted the idea of microworlds: simplified, artificial domains small enough to be fully described, yet rich enough to require real reasoning. The logic was reasonable: if you can't solve intelligence in the full chaos of the real world, solve it in a restricted world first, then scale up.

Some famous results came from this approach in the 1960s:

STUDENT (Daniel Bobrow, 1964) solved high-school algebra word problems stated in English by translating them into equations.
SAINT (James Slagle, 1961) performed symbolic integration at the level of a good first-year calculus student.
ANALOGY (Thomas Evans, 1963) solved geometric analogy puzzles of the kind found on IQ tests ("A is to B as C is to which of these?").

Each worked within a narrow slice of reality and did impressively well inside it. The hope was that these slices could be gradually connected into a general intelligence. The hard truth, which took years to sink in, was that they didn't scale. Techniques that worked in a toy domain often broke when exposed to the unconstrained world.

Two systems in particular embodied the promise and the problem.

SHRDLU: understanding language in a world of blocks

In 1968 to 1970, a PhD student at MIT named Terry Winograd created one of the most impressive AI demonstrations ever made: SHRDLU (the name came from the old printers' etaoin shrdlu, the second column of letters on a Linotype machine).

SHRDLU lived in a simulated blocks world: a table with blocks, pyramids, and boxes of different colors and sizes, plus a robot arm that could pick things up and move them. You could talk to it in ordinary English, and it would reply and act. A famously cited exchange goes something like this:

Person: Pick up a big red block.
Computer: OK.
Person: Grasp the pyramid.
Computer: I don't understand which pyramid you mean.
Person: Find a block which is taller than the one you are holding and put it into the box.
Computer: By "it", I assume you mean the block which is taller than the one I am holding.

Let that sink in. In 1970, a program was resolving pronouns ("it"), asking for clarification when a reference was ambiguous, planning sequences of physical actions (it would have to put down the block it was holding first, and it could explain why it had done so), and remembering what had happened earlier in the conversation. It could answer questions like "Why did you do that?" by reading back its own reasoning.

How did it work? Rather than treating language understanding as a separate problem from reasoning, Winograd integrated everything. SHRDLU had a parser to analyze grammar, a semantic component to map sentences onto its world model, and a planner and reasoner to figure out what actions to take. Crucially, these components could consult each other: knowledge about blocks helped decide how to parse an ambiguous sentence. It was programmed in Lisp and a language called Micro-Planner.

Why SHRDLU didn't scale

SHRDLU was widely admired, and it seemed to suggest that machines were close to understanding language. But the limitations were severe, and Winograd himself was the first to say so.

The world was tiny and perfect. The blocks world contained a few dozen objects with precisely known properties. There was no noise, no ambiguity in perception, no unknown objects.
The knowledge was hand-coded. Every word, every rule of grammar, every fact about the domain had been written in by a human expert.
It was brittle. Step outside the narrow vocabulary and domain, and it collapsed. Extending it to a kitchen, for instance, would not have been a matter of adding a few more words; it would have required encoding vast amounts of everyday knowledge about food, containers, and cooking.

Winograd later turned away from the approach. Influenced by philosophers like Martin Heidegger and by colleagues like Fernando Flores, he came to believe that human understanding is not a matter of manipulating symbolic representations in the head but is rooted in embodied, social activity. He moved into human-computer interaction, taught at Stanford, and (as a minor footnote) later served as the doctoral advisor of Google co-founder Larry Page. His name lives on in the Winograd Schema Challenge, a test of commonsense reasoning (in which pronoun resolution depends on real-world knowledge, as in "The trophy doesn't fit in the suitcase because it is too big"), which was proposed in 2011 by Hector Levesque, inspired by an example in Winograd's work.

SHRDLU is the poster child for a pattern that will repeat in Parts 7 and 8: impressive demos in narrow domains, followed by a hard collision with the open-ended messiness of reality.

Shakey: the first robot that reasoned

If SHRDLU lived in a simulated world, Shakey lived in a real one.

Shakey the robot, built at SRI International (Computer History Museum). Image: The wub, CC BY-SA 4.0, via Wikimedia Commons.

From 1966 to 1972, a team at the Stanford Research Institute (SRI), led by Charles Rosen and including Nils Nilsson, Peter Hart, Bertram Raphael, and Richard Fikes, built Shakey the Robot, funded by DARPA. It was a boxy wheeled platform about the size of a small refrigerator, topped with a TV camera, a range-finder, and bump sensors ("cat whiskers"). Its trademark was a wobbling motion when it moved, which earned it the name.

Shakey could be given a goal in plain language, such as "push the block off the platform," and it would work out a plan. It had to look at its environment through the camera, build a model of the rooms, decide which actions would achieve the goal, and carry them out, adapting if something went wrong, like a door being closed or a box being in the way.

It was, in a real sense, the first mobile robot that reasoned about its own actions. It was controlled by software running on a large computer (a PDP-10, later PDP-15) that communicated with the robot over a radio link, because the robot couldn't carry that much computing power. A single move could take minutes, and complex tasks could take hours.

Shakey's gifts to computer science

What makes Shakey so important is less the robot than the algorithms invented to make it work. Several of them are still in everyday use:

A* search (1968, by Hart, Nilsson, and Raphael), a path-finding algorithm that finds the shortest route efficiently by combining the cost so far with an estimate of the remaining distance. A* is used in video games, GPS navigation, and robotics today. Here's the core idea in one line: choose the next node that minimizes f(n) = g(n) + h(n), the cost to reach n plus a heuristic estimate of the cost to get from n to the goal.
STRIPS (1971, by Fikes and Nilsson), the Stanford Research Institute Problem Solver, a way of representing actions in terms of preconditions and effects (e.g., "to push a box, the robot must be next to it; afterwards, the box has moved"). STRIPS-style planning is the ancestor of modern AI planners.
The Hough transform and related methods for detecting lines and shapes in images, which were refined in this period and used in computer vision.

A* is a lovely illustration of how the field's search ideas matured. Here's a compact version on a grid:

import heapq

def astar(grid, start, goal):
    def h(p):  # Manhattan distance heuristic
        return abs(p[0] - goal[0]) + abs(p[1] - goal[1])

    open_set = [(h(start), 0, start, [start])]
    seen = set()
    while open_set:
        f, g, pos, path = heapq.heappop(open_set)
        if pos == goal:
            return path
        if pos in seen:
            continue
        seen.add(pos)
        for dx, dy in ((1, 0), (-1, 0), (0, 1), (0, -1)):
            nx, ny = pos[0] + dx, pos[1] + dy
            if 0 <= nx < len(grid) and 0 <= ny < len(grid[0]) and grid[nx][ny] == 0:
                heapq.heappush(open_set, (g + 1 + h((nx, ny)), g + 1, (nx, ny), path + [(nx, ny)]))
    return None

grid = [
    [0, 0, 0, 0],
    [1, 1, 0, 1],
    [0, 0, 0, 0],
    [0, 1, 1, 0],
]
print(astar(grid, (0, 0), (3, 3)))

Compare it with the water jug search from Part 4. The only real difference is that the next state to explore is chosen using an estimate of how close it is to the goal. That one change is a textbook example of using knowledge to tame the combinatorial explosion.

The media sensation

In 1970, Life magazine ran a feature on Shakey, calling it the "first electronic person" and quoting researchers who suggested that machines with human-level intelligence might arrive within years. (The researchers later said that some of the quoted timelines were exaggerated by the writer, but the headline captured the mood.) The article is a perfect snapshot of the era's hype, and also of the gap between rhetoric and reality: the actual robot was slow and fragile, and operated only in carefully constructed rooms with plain painted walls and specially marked objects.

Shakey now sits in the Computer History Museum in California, a delightful relic. In terms of legacy, though, its true heirs are the autonomous vehicles and warehouse robots of today, whose planners descend from STRIPS and whose route-finders descend from A*.

What these four teach us

Let's lay the four side by side, because the contrast is instructive.

System	What it showed	What it couldn't do
Perceptron (1958)	Machines can learn from examples	Couldn't solve non-linear problems like XOR; no training method for multiple layers
ELIZA (1966)	Conversation can create the illusion of understanding	Understood nothing; no memory or knowledge
SHRDLU (1970)	Language, reasoning, and action can be integrated	Worked only in a tiny hand-coded blocks world
Shakey (1972)	A robot can plan and act toward goals	Slow, fragile, limited to carefully prepared rooms

A few patterns emerge:

Narrow success, broad failure. Each program worked in a restricted domain. Scaling up required vastly more knowledge and flexibility than anyone had built.
Hand-coded knowledge is a bottleneck. The programs were smart because humans had carefully written in what they needed to know. Getting from "dozens of facts" to "everything a person knows" was a gap of many orders of magnitude.
Perception was harder than reasoning. Shakey could plan elegantly once it knew where things were, but figuring out where things were from camera images was painfully slow and error-prone.
Hype outruns results. The press coverage of the Perceptron and Shakey promised far more than the machines could deliver.

None of this means the work was a failure. Quite the opposite: it created tools (A*, STRIPS, parsing methods, pattern matching, knowledge representation) that are still used. But it set the stage for a collision between expectations and reality.

A glimpse of the cracks

By the end of the 1960s, there were growing signs of trouble.

Machine translation, one of the most heavily funded early goals, was progressing slowly. A government committee would soon recommend cutting funding.
Neural networks were under mathematical attack. A book was in preparation by two of AI's most prominent figures that would argue the perceptron approach was a dead end.
Researchers working on problems like vision and robotics were finding that the real world was far messier than their microworlds.
Funding agencies were beginning to ask: where are the results we were promised?

The golden years were about to meet the first great reckoning, and the connectionist camp was about to take the hardest hit.

Timeline: 1957 to 1972

1957: Rosenblatt describes the Perceptron; Newell and Simon begin work on the General Problem Solver.
1958: McCarthy creates Lisp; the Perceptron's press demonstration.
1960: Widrow and Hoff's ADALINE.
1964 to 1966: Weizenbaum builds ELIZA; Bobrow's STUDENT solves algebra word problems; SRI starts Shakey.
1968: A* search published.
1969: Perceptrons by Minsky and Papert (Part 6).
1970: Winograd's SHRDLU; Life magazine's Shakey feature.
1971: STRIPS planner; Rosenblatt dies.
1972: PARRY, the simulated paranoid patient; Prolog is created.

The ELIZA effect, today

Weizenbaum's observation has aged remarkably well. Modern chatbots are vastly more capable than ELIZA, but the human reaction is the same: when something talks to us fluently, we reach for the vocabulary of minds, saying it "wants," "thinks," or "feels." A few practical habits help keep your balance:

Separate fluency from reliability. A smooth answer tells you about the system's skill at producing language, not about whether the content is true.
Notice when you're supplying the meaning. Ask whether the system really said something specific, or whether you filled in the gaps charitably.
Remember who benefits. Products that feel like friends keep users engaged, and engagement is a business metric. That doesn't make them bad, but it's worth noticing.

Quick glossary

Pattern matching: comparing input against templates to choose a response.
Microworld: a simplified, self-contained domain used for AI research, such as SHRDLU's blocks.
Parser: a program that analyzes the grammatical structure of a sentence.
Precondition and effect: in planning, what must be true to take an action and what changes once it's taken.
Heuristic search: search guided by an estimate of how close a state is to the goal (A*).

Key takeaways

Rosenblatt's Perceptron (1958) was the first practical learning neural network. It learned by adjusting weights, and its convergence theorem was real, but it could solve only linearly separable problems.
ELIZA (1966) used simple pattern matching to simulate a Rogerian therapist and revealed the ELIZA effect: people readily attribute understanding to fluent-sounding programs. Its creator, Weizenbaum, became a leading critic of overreliance on AI.
SHRDLU (1970) integrated language understanding, reasoning, and action in a blocks world, a stunning demo that also exposed the brittleness of hand-coded, narrow-domain systems.
Shakey (1966-72) was the first mobile robot to plan its own actions, and it gave computer science A* and STRIPS.
Early AI's microworld strategy produced impressive results that did not scale to the open-ended real world.

Try it yourself

Fix the perceptron's blind spot. Add a hidden layer by hand: build XOR from two perceptrons (one computing OR, one computing NAND) feeding a third computing AND. You've just solved XOR with a two-layer network, exactly what Rosenblatt couldn't train.
Make ELIZA a little smarter. Add rules for "because," "always," and "dream," and give it a short memory so it can circle back to something you mentioned earlier ("Earlier you said your exams worried you..."). Notice how much more convincing it feels. What does that say about how we judge understanding?
Change the heuristic in A*. Set h to zero (this turns A* into plain uniform-cost search) and count how many cells each version explores on a larger grid. Then try a deliberately bad heuristic and see how the path quality changes.

Next up

In Part 6, we confront the first great downturn. A 1969 book called Perceptrons by Marvin Minsky and Seymour Papert delivers what many see as the knockout blow to neural networks. In 1966 the ALPAC report slashes funding for machine translation. And in 1973 the British mathematician Sir James Lighthill delivers a devastating review of AI that helps trigger the first AI winter. How does a field with so much promise freeze over?

If you've ever been fooled by a chatbot, or if you've built a toy AI project that fell apart on real data, share your story in the comments. It will fit right in with the next chapter.

See you in Part 6.

☕ If this series helped you, you can support my writing on Ko-fi.

Packaging my own design as a template: the unglamorous parts

Suraj Nandan — Fri, 13 Nov 2026 03:30:00 +0000

I turned my portfolio design into a template. The code was done. The real work was removing myself from it.

This post is about the unglamorous parts of packaging software for other people: what had to change, what I almost forgot, and what's still unfinished. If you're thinking about selling a starter kit or template, this is the checklist I wish I'd had.

Why a template

As I wrote on Day 4, I weighed several ways to earn online and chose the one that needed the least new work: packaging a design system I'd already built. A portfolio template is something other students genuinely need, and it was a better fit than starting a product from scratch.

The principle: separate the owner from the engine

My live site is full of me: my name, links, location, project list, certificates, even phrases in the chat assistant's persona. A template can't have any of that hard-coded. Everything owner-specific has to live in one clearly marked place, and the rest has to read from it.

I worked on a separate copy, so the live site stayed untouched. (That's the "copy, don't rewrite" approach from Day 22.)

What had to change

1. One config file for every owner-specific fact

All the personal facts moved into a single site object: name, tagline, links, location, and values derived from them (full name, site URL, and so on).

// src/data/site.ts  (simplified)
export const site = {
  name: 'Avery Quill',
  tagline: 'Designer-developer',
  url: 'https://your-site.example',
  location: 'City, Country',
  github: 'https://github.com/your-username',
};

export const FULL_NAME = site.name;
export const SITE_URL  = site.url;

Then I hunted for hard-coded copies. This is the tedious part: search for the old name, old URLs and old city across HTML, scripts, metadata and generated files. Every miss would have shipped a stranger's details to a buyer.

2. A template-driven `index.html`

The HTML head contains the title, description and social tags, which must also come from the config. A small build plugin fills the HTML from the same data, so the page's metadata can't disagree with the site.

3. Build scripts that read the same config

Anything that runs at build time (sitemaps, feeds, prerender, share images) had to read from the config too, through one loader, instead of having their own copies of the facts.

4. A section list that controls the page

A sections array decides which home sections render and in what order. A buyer who doesn't want a blog section removes one line.

5. Parameterised APIs

Some small stats endpoints took a hard-coded username. They now accept a query parameter, so a buyer's data shows up instead of mine.

6. The assistant persona

The chat assistant's knowledge and persona are generated from an OWNER object, so a buyer gets an assistant that talks about them.

A sample persona, not my life

The template ships with a fictional owner ("Avery Quill", The Quill Review) and placeholder links (your-username, your-site.example). Sample PDFs and images are generated by a script, so no personal photos or real certificates are included.

The licence question

This one almost slipped past. The live site has a little pixel mascot. I wasn't certain I could legally redistribute those sprites, so I removed them from the template and made a mascot an optional config feature instead.

The rule I took: if I can't verify the licence of an asset, it doesn't ship. Fonts, images, icons, sounds, sprites. Check each one. Selling something that includes someone else's work without permission is a serious problem, and "I found it online" isn't a licence.

I also wrote a draft licence for the template itself. It's a draft, not legal advice, and anyone selling software should get proper advice for their situation.

Test like a buyer

The most valuable check: do what a buyer will do, from scratch.

unzip press-template.zip -d /tmp/buyer-test
cd /tmp/buyer-test/press-template
npm ci
npm run typecheck
npm run build

Do it in a clean directory, not your working copy. Things that work on your machine because of leftover files or cached installs will fail here. I also made a customised copy (changing the name, links and sections) to confirm that the config really controls everything.

What I found along the way

Packaging forced me to look at the code with fresh eyes, and I found real bugs in the live portfolio:

The command palette ignored the Escape key.
A certificate modal's animated children lacked React keys.
Certificates without a URL crashed the modal and the featured row.

All three were fixed in the live site too. Preparing something for strangers is a great forcing function for quality.

What I haven't finished

The honest status, as on Day 4: the template is built and verified, the listing copy and screenshots are ready, and a demo is deployed. But the Gumroad listing is a draft that's not published, because payouts need bank details I haven't connected.

So: built, tested, not shipped. Naming that publicly is partly to make it harder to leave it that way.

A checklist you can reuse

[ ] Every personal fact lives in one config file
[ ] Search for your name, handles, URLs, city across all files
[ ] Sample content uses a fictional persona
[ ] No personal images, documents or certificates
[ ] Every asset's licence is verified, or the asset is removed
[ ] A README with setup steps a stranger can follow
[ ] A clean install and build from the final zip
[ ] A customised copy to prove the config works
[ ] A licence file (get advice)
[ ] Listing text that says exactly what's included, and what isn't

Lesson

"It works for me" and "someone else can use it" are different levels of finished. The second one took longer than the first.

Writing the listing page

A template listing has to answer a buyer's questions fast. Mine follows this outline:

# Name: one-line promise

## What you get
- A complete React + TypeScript site (list the main sections)
- Design system with tokens and primitives
- Sample content you can replace
- Documentation: setup, customising, deploying

## Who it's for / not for
For: students and developers who want a distinctive portfolio.
Not for: people who want a no-code builder.

## Requirements
Node version, package manager, hosting suggestions.

## What's *not* included
Domain, hosting, your content, support beyond [stated scope].

## Preview
Screenshots, a live demo link.

## Licence
Plain-language summary + link to the full text.

## Changelog
Version history.

The "what's not included" section prevents refunds and disappointment.

README for the buyer

The README should get a stranger from zip to running site:

Requirements.
Install and run commands.
Where to put your information (the one config file).
How to add a project, a post and a certificate.
How to change colours and fonts (the tokens).
How to deploy.
Troubleshooting for the three most common problems.
Licence and credits.

A README that a first-time buyer can follow without asking you anything is a product feature.

Support and refunds: think before you sell

I'm not a lawyer and rules differ by country and platform, so treat this as a prompt, not advice:

Decide in advance what support you'll offer (for example, installation questions for 30 days) and say it plainly.
Read the platform's terms about refunds, taxes and payouts.
Check whether you need to register for tax in your country once you earn.
Keep a record of what you sold, to whom and when.

Handling this before the first sale is much less stressful than after.

A pre-launch dry run

Do this on a machine that has never seen your project:

Download the zip from the listing, as a buyer would.
Follow the README to the letter. Note every place you hesitate.
Change the name, links and colours. Does everything update?
Build and deploy somewhere.
Fix what confused you, then repeat with a friend.

Every point of friction you fix is a support email you won't answer later.

Versioning and updates

If people buy it, it needs maintenance. A lightweight plan:

Semantic version numbers (1.0.0, 1.0.1…).
A changelog.
A promise about how long you'll support a major version.
A note on dependencies: they age, and security updates matter.

Be honest about what you can maintain. An abandoned template with promises is worse than a small one that's kept updated.

What I'd tell my past self

Set up payouts on day one, not last.
Write the README before the last feature.
Check licences as you add each asset, not at the end.
Test from a clean zip early. Many problems only show there.
Price low, and treat it as an experiment you learn from.

If you've sold a template or starter kit, what surprised you most?

☕ Enjoyed this post? You can support my writing on Ko-fi.

Impostor syndrome, minus the pep talk

Suraj Nandan — Thu, 12 Nov 2026 03:30:00 +0000

You've heard "everyone feels like an impostor." That's true, and it isn't very helpful. Telling someone a feeling is common doesn't tell them what to do with it.

This post is about what I try to do with the feeling: practical moves, not reassurance. It's written by a student who still feels it, so it isn't advice from the other side of the problem.

First, separate two different things

"Impostor syndrome" gets used for two very different situations:

A feeling that doesn't match the evidence. You've shipped real work, but you feel like a fraud.
A feeling that matches a real gap. You don't know something important yet.

They need different responses. The first needs evidence and perspective. The second needs learning, and the feeling is simply accurate information. Mixing them up leads to either false reassurance or unnecessary despair.

Make it concrete

"I'm not good enough" is vague, and vague fears grow in the dark. Try translating:

Vague fear	Concrete task
"I'm not a real developer"	"I don't know how to write integration tests."
"I'll never understand system design"	"I can't yet explain how a write-ahead log helps durability."
"Everyone's ahead of me"	"I haven't deployed anything with a real database to production."

Vague fears are heavy. Tasks are small and have next steps. The translation itself often shrinks the feeling.

Keep a record

When I feel behind, I look at what exists: the projects, the case studies, the changelog of what shipped. That record is evidence, not opinion.

Mind you, the record cuts both ways. It also shows my gaps clearly: no tests on CardBridge, an AI eval that's never been run, a template that's built but unpublished. That's fine. An honest record of strengths and gaps is more useful than a flattering memory.

A simple version

Keep a file called wins.md. At the end of each week, add three lines (these are example entries, use your own):

2026-W42
- Fixed the RLS recursion with a SECURITY DEFINER helper.
- Wrote the plan for transition tests.
- Helped a friend debug a CORS error.

On the bad weeks, read it back.

Limit the comparison

Social feeds show other people's finished work next to your messy middle. The comparison is rigged: you're seeing their highlight reel and living your own behind-the-scenes.

I try to compare myself to last month's me. Am I able to do something now that I couldn't then? That's a fair measure, and it's the only one fully under my control.

Ask the question out loud

Most "stupid questions" are the ones everyone has. Asking early is cheaper than hiding it for months and building on a misunderstanding. A good way to ask:

Say what you've tried.
Say what you expected.
Say what you got.
Ask the narrowest question you can.

People respond well to specific questions, and writing one often reveals the answer before you press send.

Notice what you discount

A common pattern: you discount your own achievements ("anyone could've done that") and inflate other people's. Try the reverse test: if a friend described your work to you, would you be impressed? If so, you may be applying a stricter standard to yourself than to anyone else.

When "I don't belong" isn't about skill

Sometimes the feeling is about environment, not ability: being the only person from your background, city or college in a room, or lacking a network. That's a real disadvantage, and telling yourself "it's all in your head" is wrong. In those cases, finding a community (online counts) matters more than any amount of studying.

What this doesn't fix

Real skill gaps. The feeling is a signal to learn, not a verdict on your worth.
Burnout or deeper anxiety. If the feeling is constant and heavy, or affecting sleep and health, talk to someone you trust or a professional. A blog post can't substitute for that.

A one-week exercise

Write down three things you're afraid you can't do.
Turn each into a specific, learnable task.
Pick the smallest one and do it this week.
Add the result to your wins.md.

Scripts for asking and answering

Sometimes the hardest part is the first sentence. Steal these.

Asking for help

"I'm trying to [goal]. I expected [X] but got [Y]. I've tried [A] and [B]. Could you point me at what I'm missing?"

Asking for feedback

"Could you look at [thing] and tell me the one thing that's confusing or weak? I don't need polish, just the biggest problem."

Admitting you don't know

"I haven't worked with that yet. Here's how I'd approach learning it..."

Receiving criticism

"Thanks, that's helpful. Let me check and I'll get back to you."

All four are specific, polite and honest, and none apologises for existing.

How to talk about gaps in an interview

Having a clear view of your gaps is an advantage in interviews, not a liability.

Name the gap plainly. "I haven't operated a production system."
Show you understand why it matters. "I know incident response and monitoring are a big part of reliability."
Show what you've done about it. "I added health checks and a post-deploy verification routine to my own projects."
Show the next step. "I'm looking for a role where I can learn that from people who do it."

That structure turns "I don't know" into "here's how I learn."

A quick audit: what's feeding the feeling?

Check your inputs:

Who am I comparing myself to? Strangers with highlight reels?
What am I reading or watching before I code? Content that makes me feel behind?
Am I sleeping and eating properly? Fatigue magnifies self-doubt.
Have I told anyone how I feel? Secrets get heavier.

Changing inputs often does more than arguing with the feeling.

The "evidence file" idea

Beyond a wins.md, collect:

screenshots of kind messages or helpful reviews,
links to things you shipped,
the list of problems you've solved that you once thought were impossible.

On a bad day, you want to have something to read that isn't made of memory.

What helps when the feeling is about belonging

If you're the only person in your circle doing this, the distance can feel like proof that you don't belong. A few things that can help:

Join an online community around a tool you actually use.
Find one person a bit ahead of you and ask a specific question.
Find one person a bit behind you and explain something. Teaching reminds you what you know.
Share small work. Replies are a reminder that other people exist.

A note for people who feel this strongly

If the feeling is constant, affects your sleep, appetite or relationships, or comes with hopelessness, it's more than a learning curve. Please talk to someone: a friend, family member, counsellor or doctor. That isn't weakness. It's the same logic as asking for help with a bug you can't solve alone.

Reminders worth keeping

Competence arrives unevenly. You can be strong in one area and a beginner in another.
Experienced people also look things up constantly.
Comparison to people with different resources is not a fair benchmark.
The question isn't "am I good enough?" but "what's my next step?"

How do you handle it? And has anything specific ever actually helped?

☕ Enjoyed this post? You can support my writing on Ko-fi.

The History of AI, Part 4: Dartmouth 1956 and the Birth of Artificial Intelligence

Suraj Nandan — Wed, 11 Nov 2026 04:30:00 +0000

The History of AI, Part 4 of 24. Part 3 followed the neurons and feedback loops of the 1940s. Now a small group of researchers gives the whole enterprise a name, a mission, and an audacious deadline. This is the story of the summer of 1956 and the "golden years" that followed.

On 31 August 1955, a young mathematics professor at Dartmouth College named John McCarthy sent a funding proposal to the Rockefeller Foundation. It was only a few pages long. It asked for money to bring about ten researchers together for the following summer to study a problem that, until then, had no common name.

That proposal used the phrase "artificial intelligence" for the first time in a document of this kind. And it contained one of the boldest sentences in the history of science:

The study is to proceed on the basis of the conjecture that every aspect of learning or any other feature of intelligence can in principle be so precisely described that a machine can be made to simulate it.

That sentence is the founding statement of the field. It's also, if you read it closely, a bet: that intelligence is the kind of thing that can be described precisely enough to be programmed. Seventy years later, we are still collecting on that bet and still arguing about the terms.

This chapter tells the story of that workshop, the program that dazzled its attendees, and the heady decade of optimism that followed, a time when some of the smartest people alive believed human-level machine intelligence was a couple of decades away.

The state of the world in 1955

To appreciate how audacious the proposal was, you need to picture the technology of the time.

Electronic computers were barely a decade old. They were room-sized machines built from vacuum tubes, with a few thousand words of memory, programmed in machine code or primitive assembly language, and shared among whole departments. The IBM 701, announced in 1952, was IBM's first commercial scientific computer. The first high-level programming language, Fortran, would arrive in 1957. Programming meant punching cards or flipping switches. There were no operating systems as we understand them, no graphics, no networks.

On the research side, the ingredients we've met in earlier chapters were all in the air:

Turing's idea that machines could think, and his 1950 paper.
Shannon's work on information and chess.
McCulloch and Pitts's neurons and Wiener's cybernetics.
The first game-playing programs on real machines.

What was missing was coherence. Researchers who were interested in machine intelligence were scattered across mathematics, electrical engineering, psychology, and neuroscience, using different vocabularies. Some called it "automata theory," some "cybernetics," some "complex information processing." McCarthy wanted a clean break and a common banner.

Four authors, one proposal

The proposal had four signatories, each of whom would leave a mark:

Marvin Minsky, co-author of the Dartmouth proposal and co-founder of the MIT AI Lab. Image: Joi, CC BY 2.0, via Wikimedia Commons.

John McCarthy (1927-2011), then at Dartmouth, a mathematician who would soon invent the Lisp programming language and the idea of time-sharing, and who would found the Stanford AI Laboratory.
Marvin Minsky (1927-2016), then at Harvard, who had built the SNARC neural network machine we met in Part 3, and who would co-found the MIT AI Lab.
Nathaniel Rochester (1919-2001), the manager of information research at IBM, who had helped design the IBM 701 and had run early simulations of neural networks.
Claude Shannon (1916-2001), of Bell Labs, whom you already know as the father of information theory.

They asked for $13,500 to support the summer workshop and received $7,500. The proposal described a "2 month, 10 man study" and listed seven areas of interest, which read like a table of contents for the next half-century of AI research:

Automatic computers (programming them to simulate higher functions)
How can a computer be programmed to use a language?
Neuron nets
Theory of the size of a calculation (what we'd now call computational complexity)
Self-improvement
Abstractions (forming concepts from sensory data)
Randomness and creativity

Look at that list again. Natural language, neural networks, complexity, self-improvement, abstraction, creativity: every item is still an active frontier, and every one of them was already written down in 1955.

Why "artificial intelligence"?

McCarthy later explained that he chose the term deliberately. He wanted something neutral that wasn't already owned by an existing group. "Cybernetics" was strongly identified with Norbert Wiener, and McCarthy has said he did not want to adopt Wiener's framing or have to defer to him. "Automata studies," the title of a collection he and Shannon had edited, drew mostly papers about abstract machines rather than intelligence, which disappointed McCarthy. So he picked a bolder, more provocative label.

The name was a stroke of marketing genius, but it also had a long-term cost. "Artificial intelligence" promised a lot. Every time the field fell short of the promise, the name made the disappointment sting more. Some of the field's later troubles, the hype cycles and AI winters we'll meet in Parts 6 and 8, can be traced to this early choice of grand terminology.

The workshop itself

The Dartmouth Summer Research Project on Artificial Intelligence ran from roughly mid-June through August 1956 in Hanover, New Hampshire. Historians who have reconstructed what happened describe it as less of a focused meeting and more of a loose, drifting, extended conversation.

Dartmouth Hall at Dartmouth College, Hanover, New Hampshire, home of the 1956 summer workshop. Image: Daderot, CC0, via Wikimedia Commons.

People came and went. Only a few stayed for the whole duration. Attendees at various points included:

Ray Solomonoff, who worked on probabilistic approaches to induction and would help found the theory of algorithmic probability.
Oliver Selfridge, who developed early ideas about pattern recognition (his "Pandemonium" model, in which many simple "demons" shout evidence for competing interpretations).
Trenchard More, a mathematician who worked on logic and array theory.
Arthur Samuel, of IBM, who was writing a checkers program that learned from experience.
Allen Newell and Herbert Simon, who arrived with something none of the organizers had expected.

By the standard of "did they solve intelligence that summer?", the workshop failed spectacularly. McCarthy himself later recalled that it did not produce the collective breakthroughs he had hoped for, partly because attendees largely wanted to pursue their own approaches rather than collaborate. But it succeeded at something just as important: it gave a group of scattered researchers a name, an identity, and each other. Most of the leaders of American AI for the next twenty years were either in that room or became students of those who were.

The star of the summer: Logic Theorist

The one real result that was demonstrated at Dartmouth belonged to two visitors from Pittsburgh.

Allen Newell (1927-1992), a young researcher at the RAND Corporation and Carnegie Tech, and Herbert Simon (1916-2001), a polymath professor who would later win the Nobel Prize in Economics (1978) for his work on decision-making, had been working with a RAND programmer named Cliff Shaw. Together they had built a program called the Logic Theorist.

Its goal was ambitious: to prove mathematical theorems. Specifically, it worked on the theorems in the second chapter of Whitehead and Russell's Principia Mathematica, the same monumental work we met in Part 1.

Simon later recalled that in the winter of 1955, he told his students that over the Christmas holiday "Al Newell and I invented a thinking machine." There was no computer available to run the program at that point, so the team famously simulated it by hand, with Simon's family and students playing the roles of individual subroutines, passing index cards back and forth. Once the program was ready, it ran on the JOHNNIAC computer at RAND.

What it actually did

The Logic Theorist didn't prove theorems by brute-force trying all possible deductions. That would have been hopeless, because the number of possible chains of reasoning explodes. Instead, it used heuristics: rules of thumb that guided its search toward promising paths. Newell and Simon's key insight was that human problem-solvers don't exhaustively search either. They use hunches, working backward from the goal, spotting similar problems they've already solved.

The program started with the axioms and tried to reach a goal theorem by applying a few rules of inference: substitution, detachment, and replacement. It worked backward from the target, breaking it into subgoals. When a subgoal seemed unpromising, the program abandoned it.

The results were striking. Logic Theorist proved 38 of the first 52 theorems in Principia Mathematica chapter 2. For one of them, theorem 2.85, it found a proof that was more elegant than the one Whitehead and Russell had written. Simon was delighted and reportedly wrote to Bertrand Russell, who, according to the story, was amused.

Newell and Simon tried to publish the result in the Journal of Symbolic Logic, listing the program as a co-author. The editors rejected the paper. Whatever their reasons, it was a funny moment: perhaps the first time a program was effectively denied authorship credit.

The significance

Why did attendees care so much? Because the Logic Theorist demonstrated that a machine could do something that seemed to require reasoning, and it did it using symbols and search, not just arithmetic.

Newell and Simon went further. They claimed that the program wasn't merely simulating human problem-solving; it embodied the same kind of process the human mind used. They called it "information processing," and they would later formalize their view as the Physical Symbol System Hypothesis (1976): a physical symbol system has the necessary and sufficient means for general intelligent action. In plain words: thinking is symbol manipulation, whether it takes place in a brain or in a computer. This was the manifesto of the symbolic approach.

It's a philosophical position with huge consequences. If it's true, then building AI is just a matter of finding the right symbols and the right rules. And that is what the field spent the next three decades trying to do.

The idea at the heart of early AI: search

Let's pause and appreciate the central technique of this era, because it's the foundation of so much that follows.

Many problems can be framed as search: you have a starting state, a goal state, and a set of moves that take you from one state to another. Solving the problem means finding a sequence of moves from start to goal. A theorem prover searches through the space of possible proofs. A chess program searches through possible game continuations. A route planner searches through possible roads.

The difficulty is that the space of possibilities grows exponentially, which is called the combinatorial explosion. In chess, for example, there are on the order of 10^120 possible games, far more than the number of atoms in the observable universe. Even with a fast computer you can't try them all. Intelligence, in this view, is largely about searching smartly: using knowledge to prune the search and focus effort where it's most likely to pay off.

Here's the idea in a short program. It solves the classic water jug puzzle: with a 3-liter jug and a 5-liter jug, how do you measure exactly 4 liters? First, we search blindly (breadth-first); then we see how structure helps.

from collections import deque

def neighbors(state, caps=(3, 5)):
    a, b = state
    ca, cb = caps
    moves = {
        "fill A":  (ca, b),
        "fill B":  (a, cb),
        "empty A": (0, b),
        "empty B": (a, 0),
        "pour A->B": (max(0, a - (cb - b)), min(cb, a + b)),
        "pour B->A": (min(ca, a + b), max(0, b - (ca - a))),
    }
    return moves.items()

def solve(goal=4, start=(0, 0)):
    frontier = deque([(start, [])])
    seen = {start}
    while frontier:
        state, path = frontier.popleft()
        if goal in state:
            return path + [f"-> {state}"]
        for move, nxt in neighbors(state):
            if nxt not in seen:
                seen.add(nxt)
                frontier.append((nxt, path + [f"{move} {nxt}"]))

print("\n".join(solve()))

It finds a six-step solution. The state space here is tiny, only a few dozen possible configurations, so brute force works instantly. Now imagine a space with more states than atoms in the universe. That is chess, or theorem proving, or planning a real-world action. For those, you need heuristics, and finding good heuristics became the central craft of early AI.

From the Logic Theorist to the General Problem Solver

Newell and Simon didn't stop. In 1957 they began work on a more ambitious program: the General Problem Solver (GPS). Where Logic Theorist was specialized for logic proofs, GPS aimed to separate the problem-solving method from the problem domain, so the same machinery could tackle different puzzles.

Its signature technique was means-ends analysis. At each step, the program compares the current state with the goal, finds the most important difference between them, and picks an operator likely to reduce that difference. If the operator can't be applied yet, it sets up a subgoal of making it applicable. It's the style of reasoning you use when you think, "I want to get to the airport. The difference is distance. A taxi reduces distance. To take a taxi I need to call one..."

Newell and Simon were less interested in building a better machine than in understanding the human mind. They recorded people "thinking aloud" while solving puzzles and compared the protocols to GPS's behavior, an early attempt to treat programs as theories of cognition. This line of work grew into the field of cognitive science, and Simon and Newell's colleagues at Carnegie Mellon became enormously influential. GPS also exposed the limits of the approach: it worked well on neat, well-defined puzzles but struggled with the open-ended complexity of the real world.

McCarthy's contributions: Lisp and the Advice Taker

While Newell and Simon built programs, McCarthy built tools. In 1958, he created Lisp (LISt Processing), a programming language designed to manipulate symbolic expressions. It introduced ideas that were way ahead of their time: recursion as a basic technique, functions as data, automatic memory management (garbage collection), and the idea that code and data can have the same representation. Lisp became the language of AI for decades, and its descendants (Scheme, Clojure, and the lambda expressions in Python and JavaScript) carry its influence.

John McCarthy, who coined “artificial intelligence” and created Lisp. Image: null0 from Singapore, Singapore, CC BY 2.0, via Wikimedia Commons.

In the same period he proposed the Advice Taker, a hypothetical program described in his 1959 paper "Programs with Common Sense." The idea was that a system should be able to accept advice stated in a formal language and act on it, using logical deduction to figure out what to do. Whereas Newell and Simon were driven by simulating human psychology, McCarthy was driven by the dream of a logical machine, closer to Leibniz's "Let us calculate." He believed common-sense knowledge could be written in formal logic and reasoned over, an ambition that would occupy him and others for decades and run, painfully, into the problem of how much common sense there is to write down.

McCarthy also pioneered time-sharing, the idea that many users could interact with one computer at the same time, which was crucial for AI researchers who wanted interactive programming rather than slow batch processing. And in 1959, he and Minsky founded the MIT Artificial Intelligence Project, which grew into the MIT AI Lab. In 1963 McCarthy moved to Stanford and founded the Stanford Artificial Intelligence Laboratory (SAIL). Carnegie Mellon (Newell and Simon) became the third major center. Together, these hubs trained the generation that would define the field.

Samuel's checkers and the birth of "machine learning"

Not everyone at Dartmouth was working on symbolic logic. Arthur Samuel at IBM was building a checkers (draughts) program that could improve with experience. His program evaluated board positions using a weighted combination of features, such as piece advantage and mobility, and it adjusted the weights by comparing its predictions to the results of games it played. It could also play against itself, learning from the outcomes.

By the late 1950s, the program was good enough to beat a respectable amateur, and in 1962 it defeated a self-proclaimed checkers master in a widely publicized match (though that opponent was not a top player, and the match was later put in context). Samuel coined the phrase "machine learning" in a 1959 paper, defining it, in a widely quoted paraphrase, as the field of study that gives computers "the ability to learn without being explicitly programmed."

It was a small thread in the 1950s, overshadowed by the symbolic approach. But it was the same thread Turing had pulled with his "child machine," and the same one that would come roaring back later. Samuel's program used ideas we'd recognize today: a scoring function, self-play, and adjusting parameters based on outcomes, a primitive ancestor of reinforcement learning.

The golden years: bold promises

The period from roughly 1956 to 1974 is often called the golden years of AI. Funding from the US Department of Defense's Advanced Research Projects Agency (ARPA, later DARPA) flowed generously, with few strings attached. J.C.R. Licklider, who ran ARPA's Information Processing Techniques Office from 1962, believed in funding talented people and letting them explore. MIT, Stanford, and CMU got millions.

Programs of this era achieved results that astonished observers:

Programs that solved algebra word problems (STUDENT, by Daniel Bobrow).
Programs that did symbolic integration like a calculus student (SAINT, by James Slagle).
Programs that solved geometric analogy problems from IQ tests (ANALOGY, by Thomas Evans).
Programs that proved geometry theorems (Herbert Gelernter's Geometry Theorem Prover).

(We'll look at several of these, plus ELIZA and Shakey, in Part 5.)

And the pronouncements were stunning. In 1957, Herbert Simon predicted that within ten years a computer would be the world's chess champion and would discover and prove an important new mathematical theorem. In 1965, he wrote that "machines will be capable, within twenty years, of doing any work a man can do." In 1967, Marvin Minsky declared that "within a generation... the problem of creating 'artificial intelligence' will substantially be solved." (Minsky later disputed how some of these statements were quoted, but the overall mood is undeniable.)

It's easy to laugh at these forecasts now, and we should note that Simon's chess prediction was off by about thirty years: Deep Blue beat Garry Kasparov in 1997, as we'll see in Part 11. But try to put yourself in their position. They had seen computers go from not existing to proving theorems in ten years. Extrapolating that trend, it didn't seem crazy to expect human-level intelligence soon. The mistake was assuming that the hard part was already behind them.

The easy problems were hard, and the hard problems were easy

Here's the central irony that took the field decades to appreciate, which the roboticist Hans Moravec would later describe as Moravec's paradox: tasks that humans find hard, like proving theorems, playing chess, and solving algebra problems, turned out to be relatively easy for computers, because they are clean, well-defined, and symbolic. Tasks that a toddler does without effort, like recognizing a face, picking up an egg, understanding a sentence, and walking across a cluttered room, turned out to be enormously hard.

The early researchers worked on the first category because it was tractable, and they took progress there as a sign that the rest would follow. In fact, the real world is messy, ambiguous, noisy, and open-ended, and capturing it in neat symbols and rules was far harder than anyone anticipated. This is exactly what the next four chapters are about.

Two camps take shape

By the end of the 1950s, the field was dividing into two camps with different philosophies, a split we've seen coming since Part 3.

The symbolists, led by McCarthy, Newell, Simon, and to a large extent Minsky, believed that intelligence consisted of manipulating symbols according to rules. The tools were logic, search, and heuristics. The model was the mind as a program.

The connectionists, inspired by McCulloch, Pitts, and Hebb, believed that intelligence emerged from networks of simple units learning from data. The tools were artificial neurons and learning rules. The model was the mind as a brain.

In the late 1950s, both camps got a boost. On the symbolic side: Logic Theorist, Lisp, GPS. On the connectionist side, a psychologist named Frank Rosenblatt unveiled a learning machine called the Perceptron, and the Navy and the press got very excited. That story, and the intense rivalry that followed, is in the next chapter.

Legacy of Dartmouth

It's tempting to call Dartmouth the "birth" of AI, but historians prefer to see it more as a baptism. The work had started before: Turing, McCulloch and Pitts, Shannon, and others had already done much of the groundwork. What Dartmouth did was to rally a community and a name around the project.

Its legacy:

A name and a field. "Artificial intelligence" stuck, for better and worse.
A set of research directions. Language, learning, neural nets, search, and self-improvement all appear on that 1955 list.
Institutions. MIT, Stanford, and Carnegie Mellon became the nerve centers of AI.
A culture of optimism. The founders' confidence energized funding and recruitment, and also set expectations that would be painfully unmet.
A defining paradigm. The idea that intelligence is symbol manipulation, formalized in the Physical Symbol System Hypothesis, shaped decades of research.

In 2006, on the fiftieth anniversary, several of the original attendees, including McCarthy, Minsky, Solomonoff, More, and Selfridge, reunited at Dartmouth. Seeing the pioneers together at last was a poignant reminder of how long this story has been unfolding, and how much of it has yet to be written.

A scorecard: the seven topics, seventy years later

The 1955 proposal listed seven areas to study. It's a fun exercise to grade them against where things stand today:

1955 topic	Where it stands
Automatic computers (programming to simulate higher functions)	Achieved beyond anything imagined; computers now write essays and code.
Programming a computer to use language	The biggest success story. Large language models (Parts 19 to 21) converse fluently in dozens of languages, though "understanding" remains debated.
Neuron nets	Vindicated. Deep neural networks power nearly every modern AI system.
Theory of the size of a calculation	Became computational complexity theory, including NP-completeness (Part 6). It explained why many problems are hard.
Self-improvement	Partly achieved: systems like AlphaZero improve by playing themselves (Part 17), but no system rewrites its own architecture in an open-ended way.
Abstractions (forming concepts from sensory data)	Largely achieved through learned representations: a vision network discovers "edge," "eye," and "face" on its own (Part 14).
Randomness and creativity	Randomness turned out to be essential (stochastic training, sampling), and creativity is hotly debated (Parts 16, 17, and 20).

Remarkably, the founders asked the right questions. What they badly underestimated was the time, and the central role that data and computing power would play.

Who was who

A quick cast list for the rest of the series:

John McCarthy: coined "AI," invented Lisp, founded SAIL at Stanford.
Marvin Minsky: built SNARC, co-founded the MIT AI Lab, co-wrote Perceptrons.
Claude Shannon: information theory, chess programming, Theseus.
Nathaniel Rochester: IBM, early neural network simulations.
Allen Newell and Herbert Simon: Logic Theorist, GPS, the symbolic paradigm; Simon won a Nobel Prize in Economics.
Arthur Samuel: the checkers program that learned; coined "machine learning."

Quick glossary

Heuristic: a rule of thumb that usually, but not always, finds good solutions quickly.
Combinatorial explosion: the rapid growth in the number of possibilities as a problem gets bigger.
Means-ends analysis: reducing the difference between the current state and the goal, step by step.
Symbolic AI: the approach that represents knowledge as symbols and manipulates them by rules.
Time-sharing: letting many users interact with one computer at once.

Key takeaways

In 1955, McCarthy, Minsky, Rochester, and Shannon proposed a summer workshop at Dartmouth, coining the phrase "artificial intelligence" and betting that "every aspect of learning or any other feature of intelligence" could be precisely described and simulated.
The workshop (summer 1956) produced no single breakthrough, but it founded a community, a name, and a research agenda.
Newell, Simon, and Shaw's Logic Theorist proved theorems from Principia Mathematica using heuristic search, and their General Problem Solver introduced means-ends analysis.
McCarthy created Lisp and the Advice Taker idea; Samuel coined "machine learning" with a checkers program that learned from self-play.
The golden years (1956-1974) brought generous DARPA funding, impressive demonstrations, and wildly optimistic predictions.
The era's central lesson, later named Moravec's paradox, was that tasks hard for humans (logic, chess) were comparatively easy for machines, while tasks easy for humans (perception, common sense) were extremely hard.

Try it yourself

Extend the jug solver. Change the capacities and goal (try jugs of 7 and 11 liters to measure 6). Which problems have no solution? Can you spot a pattern (hint: think about greatest common divisors)?
Add a heuristic. Replace the breadth-first queue with a priority queue that prefers states where one jug is closer to the goal volume. Count how many states each version explores. That difference is the whole idea of a heuristic.
Read the original. Search for the text of the 1955 Dartmouth proposal (it's short and freely available online). Pick one of its seven topics and write a paragraph on how much progress has been made since 1955.

Next up

In Part 5, we dive into the programs and machines of the golden years: Rosenblatt's Perceptron and the media frenzy around it, Joseph Weizenbaum's ELIZA and the unsettling "ELIZA effect," Terry Winograd's SHRDLU and its blocks world, and Shakey, the first mobile robot that reasoned about its own actions. It's a story of real breakthroughs, and the first cracks.

If you enjoyed this chapter, follow the series and tell me in the comments: which Dartmouth prediction do you think has aged best, and which worst?

See you in Part 5.

☕ If this series helped you, you can support my writing on Ko-fi.

Shipping a Vercel serverless API route: the short version

Suraj Nandan — Wed, 11 Nov 2026 03:30:00 +0000

My portfolio has a small chat feature backed by a serverless function on Vercel. This post walks through the pattern end to end: the file shape, the gotchas I hit, how to keep costs sane, and the checks I run after each deploy.

If you've never written a serverless function, this is a good first one.

What "serverless function" means here

You write a file. The host runs it on demand, in response to an HTTP request, and you pay (or use free quota) per invocation instead of keeping a server running. For a small endpoint like a chat proxy, that's ideal: no server to maintain, and it scales to zero when nobody's using it.

On Vercel, any file inside the api/ folder becomes an endpoint. api/chat.ts is served at /api/chat.

The shape of a function

I use the Web-standard Request / Response style, exporting a function per HTTP method:

// api/chat.ts

export async function GET() {
  // A cheap health check: lets me verify a deploy with curl.
  return Response.json({ ready: true });
}

export async function POST(req: Request) {
  const { message } = await req.json();

  if (typeof message !== 'string' || message.length === 0 || message.length > 2000) {
    return Response.json({ error: 'Invalid message' }, { status: 400 });
  }

  // call your model here, using a key from process.env
  const reply = await askModel(message);

  return Response.json({ reply });
}

Notes:

Validate input. Never pass raw user input anywhere without checking its type and size. Limits protect your bill.
Return proper status codes. 400 for bad input, 500 for your own failure.
Keep it small. A function should do one thing.

Calling it from the frontend

async function ask(message: string) {
  const res = await fetch('/api/chat', {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ message }),
  });
  if (!res.ok) throw new Error('Request failed');
  return (await res.json()).reply as string;
}

Secrets stay on the server

The model API key must never be in the browser or the repository. Put it in an environment variable in the host's dashboard, and read it in the function:

const key = process.env.ANTHROPIC_API_KEY;
if (!key) return Response.json({ error: 'Not configured' }, { status: 503 });

For my project, the key lives in the Vercel project's environment settings, and the function simply reads it. A key committed to a repo should be considered leaked, even if the repo is private.

Gotchas I've hit

Import extensions

When importing sibling files from inside api/, include the .js extension in the import path, even though the source is TypeScript:

import { buildPrompt } from './_prompt.js';   // note: .js

Leave it off and the deployed function may fail to resolve the module, which is the kind of thing that works locally and breaks on the host.

Files that shouldn't be endpoints

Files in api/ become routes. A helper that shouldn't be reachable from the internet should be prefixed with an underscore (_prompt.ts) or live outside api/.

Cold starts and timeouts

A function that hasn't run recently starts slower, and every function has a maximum duration. Keep work short and consider streaming for slow model calls.

Pick the smallest model that does the job

Cost matters when you're the one paying. For a portfolio chat that answers questions about my work, I chose a small, fast, inexpensive model (Claude Haiku) over a larger one. Smaller models are quicker, cheaper and usually good enough when the task is narrow.

Protect your wallet

A public endpoint that calls a paid API can be abused. Basic protections:

Validate and cap input length.
Rate limit per IP or per session.
Set a monthly spend limit on the provider dashboard.
Give the model a narrow job in the system prompt.
Don't expose a general-purpose proxy.

The check I run after every deploy

Remember Day 3: a deploy can fail silently. A health check makes verification trivial:

# Is the function up?
curl -s https://your-domain.com/api/chat
# {"ready":true}

# Other things worth confirming are live
curl -sI https://your-domain.com/rss.xml | head -n 1

I run these against the production domain after each deploy. Ten seconds, and I know the new build is serving.

A deployment checklist

[ ] Env vars set in the host dashboard (production and preview if needed)
[ ] Input validated, length capped
[ ] Health endpoint works
[ ] No secrets in the repo
[ ] Spend limit set at the provider
[ ] Verified on the live domain, not just locally

Streaming a response

For slow model calls, streaming lets the user see text as it arrives instead of staring at a spinner. A minimal pattern with Web streams:

export async function POST(req: Request) {
  const { message } = await req.json();

  const encoder = new TextEncoder();
  const stream = new ReadableStream({
    async start(controller) {
      for await (const piece of askModelStream(message)) {   // your provider's stream
        controller.enqueue(encoder.encode(piece));
      }
      controller.close();
    },
  });

  return new Response(stream, {
    headers: { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' },
  });
}

On the client, read it incrementally:

const res = await fetch('/api/chat', { method: 'POST', body: JSON.stringify({ message }) });
const reader = res.body!.getReader();
const decoder = new TextDecoder();
for (;;) {
  const { value, done } = await reader.read();
  if (done) break;
  appendToUI(decoder.decode(value, { stream: true }));
}

Test locally before deploying

The Vercel CLI can run your functions locally:

npm i -g vercel
vercel dev          # serves the site and the /api routes locally
curl -s localhost:3000/api/chat

It reads environment variables from a local file (keep that file out of git), so you can test with a key without ever committing it.

A simple rate-limit sketch

On a serverless host, in-memory counters reset on cold starts and don't share across instances, so a robust limit needs shared storage (a small key-value store). To show the idea:

const hits = new Map<string, { count: number; reset: number }>();

function allow(ip: string, limit = 20, windowMs = 60_000) {
  const now = Date.now();
  const rec = hits.get(ip);
  if (!rec || now > rec.reset) { hits.set(ip, { count: 1, reset: now + windowMs }); return true; }
  rec.count++;
  return rec.count <= limit;
}

Treat that as a speed bump, not a lock. For anything you pay for, back it with a provider-side spend limit.

Error handling that doesn't leak

Return a generic message to the client ("Something went wrong"), and log the detail on the server.
Never include stack traces or provider error bodies in responses.
Use correct status codes so the frontend can react: 400 bad input, 429 too many requests, 503 not configured.

try {
  /* ... */
} catch (err) {
  console.error('chat failed', err);
  return Response.json({ error: 'Something went wrong' }, { status: 500 });
}

CORS in one paragraph

If the frontend and the function share a domain (as with /api/chat on the same site), you don't need CORS. If another origin calls it, you must return the right Access-Control-Allow-Origin header for specific, trusted origins, never a blanket * on an endpoint that spends your money.

Limits to know about

Functions have maximum run times and memory limits on a given plan.
Cold starts make the first request slower.
Local files are read-only or ephemeral. Don't treat the filesystem as storage.
Request and response sizes are capped.

Check your host's current limits in its documentation, since they change.

Pre-launch checklist for an AI-backed endpoint

[ ] Input validated and capped
[ ] Spend limit set with the provider
[ ] Rate limiting in place
[ ] Narrow system prompt
[ ] No secrets in the repo or in logs
[ ] Health check responds
[ ] Failure path returns a friendly error
[ ] Verified on the production URL

What's the smallest useful serverless function you've shipped?

☕ Enjoyed this post? You can support my writing on Ko-fi.

How I try to write posts people actually finish reading

Suraj Nandan — Tue, 10 Nov 2026 03:30:00 +0000

These are things I'm practising, not claiming mastery of. If you read a post of mine and found it dull, that's feedback I want.

Still, after writing technical posts for my own site and this series, a few patterns stand out. This post is a field guide to the structure I aim for, a pre-publish checklist, and the mistakes I try to avoid.

Start with the reader's question

Every post answers a question someone has, even if they haven't typed it. Before writing, finish this sentence:

After reading this, you'll be able to ______.

If you can't, the post doesn't have a purpose yet. "Understand RAG" is vague. "Explain chunking and retrieval well enough to build a five-note prototype" is concrete.

The title is a promise

Good titles are specific and honest:

Vague: Thoughts on databases
Better: I put my business rules in the database instead of React, here's what it bought me

The second tells you the topic, a decision, and a payoff. But don't overpromise. A title that claims more than the post delivers loses trust faster than a dull title loses clicks.

The first paragraph earns the second

No throat-clearing. Skip "In today's fast-paced world of software development…". Start with the problem, a surprise, or a sentence that sets the stakes:

"When something breaks, my worst instinct is to start changing things."
"My site's deploys silently failed for two weeks."

If a stranger can't tell why to keep reading after three sentences, cut until they can.

One idea per post

If a post has three big ideas, it's three posts. Readers finish things with a clear spine. Everything that doesn't serve the spine goes into another post or gets cut.

Use structure, then trust it

For technical writing, I use a repeating shape:

The problem in human terms.
The idea in one or two sentences.
A concrete example, with code if code helps.
What went wrong or what it costs.
A takeaway you can reuse.
A question for the reader.

Subheadings make it scannable, since most readers skim first and read second. Make each heading say something, not just "Overview".

Show, don't just tell

Code people can copy is the most useful thing in a technical post, so make it runnable or clearly mark it as a sketch.
Tables work for comparisons.
A diagram or a summary image helps visual readers and gives your post a shareable image.
Real numbers and real names, when they're true and checkable.

Keep the honesty rule

For this series, I follow rules I wrote on Day 1: only write what I did or believe, say what didn't work, and label opinions as opinions. Practically that means:

No invented statistics.
No "everyone knows".
If I didn't measure it, I don't say it's fast.
Limits are part of the post, not hidden at the bottom.

Honest writing also happens to be easier to write: you never have to remember which story you made up.

An honest ending

End on something useful:

A limit: "here's what this doesn't cover."
A question: something you genuinely want answered.
A next step: what you'd try, or what comes next.

Avoid ending on a summary of what you've just said, unless the post is long enough that readers need it.

A pre-publish checklist

[ ] Can I finish the sentence "you'll be able to…"?
[ ] Does the title match what the post delivers?
[ ] Do the first three sentences give a reason to continue?
[ ] One idea only?
[ ] Is every claim something I can back up?
[ ] Code tested or labelled as a sketch?
[ ] Headings that say something?
[ ] An ending that gives something back?
[ ] Spelling and links checked?

The read-aloud test

Read the post aloud. Wherever you stumble, the reader will too. Long sentences you run out of breath on need splitting. Words you wouldn't say to a friend need replacing.

Reading time

There's a trade-off between depth and attention. On my own site, reading time is computed from the word count so I don't hand-write it. A rough rule: 200 words a minute, so a 1,500-word post is about seven minutes. Long is fine if every section earns its place. Cut anything that's there to hit a length.

What I'm still learning

Cutting my own favourite paragraph when it doesn't serve the post.
Writing a title after the draft, when I know what it really says.
Resisting the urge to sound more expert than I am.

A before/after: rewriting an intro

Before (a typical first draft):

In the modern world of software development, testing is becoming more and more important. Many developers know they should write tests, but it can be hard to find the time. In this post I will talk about my experience with testing and how I plan to improve it.

It's polite and says almost nothing. Nothing happens in the first three sentences.

After:

Writing tests is advice I give and haven't followed everywhere. CardBridge has no automated test suite. So here's the plan, publicly, so I'm accountable.

Same topic. The second version admits something specific, sets a stake and gives a reason to continue. It's also shorter.

A four-round editing pass

Don't edit everything at once. Do it in rounds.

Round 1: Structure. Does the post have one idea? Are the sections in the right order? Cut or move whole sections.

Round 2: Clarity. Rewrite sentences that you had to read twice. Replace jargon with plain words, or define it.

Round 3: Evidence. For each claim, ask: can I back this up? Add the command, link or example. Delete what you can't.

Round 4: Polish. Spelling, links, code formatting, headings, alt text.

Taking a break of even a few hours between round 3 and round 4 makes errors much easier to see.

Words to cut

These add length but not meaning:

"very", "really", "quite", "basically", "actually"
"In order to" (use "to")
"It is important to note that" (just note it)
"There are many X that Y" (name two)
"Needless to say" (then don't)

Sentences that earn their place

Prefer concrete over abstract:

Vague	Concrete
"Performance improved."	"The query went from a full scan to an index lookup." (only if true)
"It was a challenging bug."	"It only failed for viewers, never for editors."
"I learned a lot."	"I learned that a postinstall script can be skipped by the host."

If you didn't measure a number, don't print one.

Formatting for skimmers

Many readers skim first. Help them:

Headings that carry information.
Short paragraphs, three or four lines.
Lists for parallel items, tables for comparisons.
Code blocks with a language tag.
Bold for the one phrase per section you'd want a skimmer to see.
An image or summary card to break up long text.

Don't overuse bold; if everything is emphasised, nothing is.

Titles: some patterns

Pattern	Example
The honest admission	"My site's deploys silently failed for two weeks. I didn't notice"
The decision and payoff	"I put my business rules in the database instead of React, here's what it bought me"
The plain how-to	"Row Level Security explained with one tiny example"
The comparison	"Learning in public vs learning in private: the trade-offs"

Write five titles, then pick the one that's most specific and true.

Getting feedback before publishing

Send the draft to one person and ask three questions:

Where did you get bored?
Where did you get lost?
What's the one thing you remember?

If their answer to the third isn't your main point, the post isn't clear yet.

A habit: keep a "stuff" file

Keep a note of small things you learn and the questions people ask you. Most good posts begin as a note that kept growing.

What's one post you read recently that you couldn't stop reading? What made it work?

☕ Enjoyed this post? You can support my writing on Ko-fi.

The History of AI, Part 3: Neurons on Paper, McCulloch, Pitts, and the Birth of Cybernetics

Suraj Nandan — Mon, 09 Nov 2026 04:30:00 +0000

The History of AI, Part 3 of 24. In Part 2, Alan Turing defined computation and asked whether machines could think. Now we meet the people who asked a different question: what if the brain itself is a kind of computer? This is where neural networks, feedback, and information theory all begin.

By the early 1940s, two big ideas were sitting side by side, almost touching.

On one side: logic and computation. Boole had shown that reasoning can be written as algebra, and Turing had defined exactly what a computing machine is.

On the other side: neuroscience. Biologists had established that the brain is made of billions of individual cells called neurons, connected in vast networks, passing tiny electrical signals along their branches. A neuron receives signals, and if enough arrive, it "fires" and sends its own signal onward. That's about as much as anyone knew for sure.

Someone was bound to put them together and say: a neuron is a kind of logic gate, and the brain is a computing machine built from them. That someone turned out to be an odd partnership of a middle-aged psychiatrist and a homeless teenage prodigy.

This chapter is about the birth of the neural network idea, about a sprawling science called cybernetics that briefly promised to explain minds, machines, and societies in one framework, and about the quiet groundwork that made later AI possible. It's also, unusually for a history of technology, a story with a genuinely sad ending.

The psychiatrist and the runaway

Warren McCulloch (1898-1969) was a restless, poetic, charismatic American neurophysiologist and psychiatrist. He had studied philosophy and psychology and medicine, and he carried around a question that he said had obsessed him since youth: "What is a number, that a man may know it, and a man, that he may know a number?" In other words, how can a physical, biological thing, a brain, come to know abstract truths?

Walter Pitts (1923-1969) was a very different figure. Born into a rough, poor family in Detroit, he was a self-taught prodigy who, as the often-told story goes, escaped bullies as a boy by hiding in a library, where he read Bertrand Russell and Alfred North Whitehead's Principia Mathematica. He is said to have written to Russell with corrections, and Russell invited him to study in England. He couldn't go. Instead, at around fifteen, he left home for good and wandered into the University of Chicago, where he sat in on lectures by the philosopher Rudolf Carnap and impressed everyone he met, despite having no official student status and often nowhere to live.

Through a fellow student, Jerome Lettvin, Pitts met McCulloch. McCulloch, who had a large house and a large heart, essentially took the young man in. The two began working together on a way to use logic to describe the brain.

"A Logical Calculus of the Ideas Immanent in Nervous Activity"

In 1943 they published a paper with that mouthful of a title in the Bulletin of Mathematical Biophysics. It is one of the most important and least-read papers in the history of AI.

Here is their central move. They took the real, messy biological neuron and simplified it brutally into an abstract unit with these properties:

It has several inputs, each either on (1) or off (0).
Some inputs are excitatory (they push the neuron toward firing), and some are inhibitory (they veto it).
The neuron has a threshold. If enough excitatory inputs are on, and no inhibitory input is on, the neuron fires (outputs 1). Otherwise it stays silent (outputs 0).

That's all. And from this tiny building block, McCulloch and Pitts proved something remarkable: networks of these units can compute any logical function. With the right wiring you can build AND, OR, and NOT, and since you can build any logic circuit from those three, you can build any logical computation. They also argued that, given a tape, such networks could in principle compute anything a Turing machine can.

Let's see how little code this takes. Here is the McCulloch-Pitts neuron:

def mp_neuron(inputs, weights, threshold):
    """Fire (1) if the weighted sum of inputs reaches the threshold."""
    total = sum(i * w for i, w in zip(inputs, weights))
    return 1 if total >= threshold else 0

# AND: both inputs must be on
AND = lambda a, b: mp_neuron([a, b], [1, 1], threshold=2)

# OR: at least one input must be on
OR  = lambda a, b: mp_neuron([a, b], [1, 1], threshold=1)

# NOT: an inhibitory (negative) weight flips the signal
NOT = lambda a:    mp_neuron([a],    [-1],   threshold=0)

for a in (0, 1):
    for b in (0, 1):
        print(f"{a} {b} -> AND={AND(a,b)}  OR={OR(a,b)}")
print("NOT 0 =", NOT(0), "| NOT 1 =", NOT(1))

Run it and you'll see the truth tables Boole would recognize. Real neurons are enormously more complicated than this, and McCulloch and Pitts knew it. But the paper's power isn't biological accuracy. It's the bridge. It said: whatever the brain does, if it can be described logically, then a network of simple threshold units can do it. Thinking might not be mystical. It might be wiring.

Wires and weights

Notice the two ingredients that appear in the code: weights and a threshold. In the 1943 model, the weights were fixed by hand. Later researchers would let the weights change, and that single modification, learning, would become the central theme of modern AI. A modern deep learning model has billions of weights, and nearly all of its "knowledge" is stored in them. But the core operation, "multiply inputs by weights, add them up, compare to a threshold," is still the McCulloch-Pitts neuron, with the hard threshold usually replaced by a smooth function.

There's one more thing worth noticing: a single McCulloch-Pitts unit can't compute everything. It can do AND and OR, but a single unit cannot compute XOR (exclusive or: "one or the other, but not both"). You need at least two layers of units to do it. That small fact will come back with a vengeance in Part 6, when it becomes the center of a famous and devastating critique of early neural networks.

Why it mattered

The paper's impact was less about what researchers did with it immediately and more about the frame it created:

It made the brain a legitimate object of mathematical study.
It linked neuroscience to computation, suggesting the mind is something a machine might replicate.
It inspired John von Neumann, who cited the paper in his 1945 report describing the stored-program computer architecture and used its neuron-like notation to describe how computer components might work.

It also contained an idea that would take years to mature: networks with loops, where signals feed back into earlier units, could have memory. That insight prefigured recurrent neural networks.

Meeting Norbert Wiener

In 1943, Pitts, only 20 years old, moved to Cambridge, Massachusetts, drawn to MIT by one of the most formidable intellects in America: Norbert Wiener.

Norbert Wiener (right) examines the chess-playing automaton El Ajedrecista in 1951. Public domain, via Wikimedia Commons.

Wiener (1894-1964) was a former child prodigy who earned his PhD from Harvard at 18. A mathematician with wide-ranging curiosity and a reputation for absentmindedness (there are many stories of him wandering the halls of MIT lost in thought), he had spent the early war years on a very practical problem: anti-aircraft fire.

The prediction problem

To shoot down a fast-moving airplane, you can't aim at where it is. By the time your shell arrives, the plane will have moved. You must aim at where it will be. That requires predicting the pilot's path from recent observations, which is hard because the pilot is a human being trying to evade you.

Wiener, working with the engineer Julian Bigelow, developed mathematical methods for predicting such trajectories, treating the pilot's motion as a noisy signal and finding the best statistical guess about the future. But they noticed something deeper: the whole system, a gun, a radar, a human operator, and an airplane, behaved as a loop. The gun makes an observation, adjusts its aim, observes the result, and corrects. This is feedback.

In a famous 1943 paper, "Behavior, Purpose and Teleology," Wiener, Bigelow, and the physiologist Arturo Rosenblueth argued that goal-directed behavior, in both animals and machines, could be explained through feedback. A thermostat has a "goal" (a target temperature). A guided missile has a "goal." A person reaching for a cup has a "goal." In each case, the system compares its current state with the desired state and acts to reduce the difference.

That sounds obvious today, but in 1943 it was heretical. Scientists had avoided talk of "purpose" as unscientific, a leftover from Aristotle. Wiener showed that purposeful behavior could be explained mechanistically.

Cybernetics

In 1948, Wiener published a book titled Cybernetics: Or Control and Communication in the Animal and the Machine. He had coined the word from the Greek kybernetes, "steersman", the person who steers a ship, constantly correcting course in response to wind and waves. (The same Greek root gives us "govern" and "governor.")

The book is a strange mixture of dense mathematics and sweeping speculation, and, to the astonishment of its publisher, it became a bestseller. Its central claim was that control and communication are the same kind of thing across biology, machines, and even society. Organisms, thermostats, computers, and economies are all systems that process information and use feedback to regulate themselves.

For a few years, cybernetics was the hot interdisciplinary idea. It influenced psychology, engineering, biology, anthropology, and management theory, and it supplied a vocabulary (feedback, input/output, signal, noise, control) that we still use constantly.

The Macy Conferences

The movement's social hub was a series of ten invitation-only meetings, the Macy Conferences, held between 1946 and 1953 in New York. They were the sort of gathering that seems almost impossible today: mathematicians, neurophysiologists, psychologists, anthropologists (including Margaret Mead and Gregory Bateson), engineers, and philosophers all in one room, arguing late into the night, with McCulloch chairing.

They debated how brains compute, how language works, how communities regulate themselves, and whether machines could think. Many of the questions that structured the next 70 years of cognitive science and AI were first sharpened in those rooms.

Claude Shannon: a bit of information

One regular in these circles quietly changed the world twice before he turned 33.

Claude Shannon in a 1958 MIT portrait. Public domain, via Wikimedia Commons.

Claude Shannon (1916-2001) was a playful, inventive engineer who loved unicycles, juggling, and building odd gadgets. In his 1937 master's thesis at MIT, "A Symbolic Analysis of Relay and Switching Circuits," he noticed that the on/off behavior of electrical switches could be described using Boolean algebra, the same algebra Boole had invented in 1854 to describe logic. Series circuits correspond to AND, parallel circuits to OR. This turned circuit design from an art into a mathematical discipline, and laid the foundation for digital computers. It is often called the most important master's thesis of the century.

Then, in 1948, the same year as Wiener's book, Shannon published "A Mathematical Theory of Communication," founding information theory. He defined the bit as the unit of information and showed how to measure the information content of a message, how much a noisy channel can carry, and how to encode messages so errors can be corrected. Every text message, streamed video, and compressed file depends on his ideas.

Shannon cared about machine intelligence too. In 1950 he published "Programming a Computer for Playing Chess," outlining the basic strategy of searching a tree of possible moves and scoring positions, which became the foundation of computer chess. He also built Theseus, a small mechanical mouse that could learn to find its way through a maze, one of the first demonstrations of a machine that visibly learned from experience.

His mathematics also hides a connection that will matter greatly in modern AI. The measure of information, entropy, is the same quantity that today's language models are trained to minimize (in the form of cross-entropy loss) when they predict the next word. Shannon was already experimenting in 1948 with predicting English text one letter at a time using statistical models. In a very real sense, today's chatbots are descendants of those experiments.

Hebb: how brains learn

McCulloch and Pitts left a gap. Their neurons had fixed connections. But real brains learn. How?

In 1949, the Canadian psychologist Donald Hebb proposed a simple and influential answer in his book The Organization of Behavior. In his words:

When an axon of cell A is near enough to excite a cell B and repeatedly or persistently takes part in firing it, some growth process or metabolic change takes place in one or both cells such that A's efficiency, as one of the cells firing B, is increased.

It is usually summarized, a little loosely, as: "neurons that fire together, wire together." (That catchy phrase actually came later, from the neuroscientist Carla Shatz.) The idea is that connections between neurons strengthen when the neurons are active at the same time.

This is Hebbian learning, and it was the first plausible learning rule for artificial neural networks. A tiny demonstration:

import numpy as np

# Learn an association between two patterns using Hebb's rule:
#   weight change = learning_rate * input * output
patterns = [
    (np.array([1, 0, 1]), np.array([1])),   # input pattern -> "fire"
    (np.array([0, 1, 0]), np.array([0])),   # input pattern -> "silent"
]

w = np.zeros(3)
lr = 1.0
for x, y in patterns:
    w += lr * x * y          # strengthen weights where input and output are both active

print("weights after learning:", w)          # [1. 0. 1.]
print("response to [1,0,1]:", int(w @ np.array([1, 0, 1]) >= 1))  # fires
print("response to [0,1,0]:", int(w @ np.array([0, 1, 0]) >= 1))  # silent

Pure Hebbian learning has problems. Weights can grow without limit, and it can only learn correlations, not mistakes. Later rules, such as the perceptron learning rule and backpropagation, which we'll meet in Parts 5, 6, and 9, are much more powerful. But Hebb's idea, that learning means adjusting the strengths of connections, is exactly what every modern neural network does during training.

The first neural network machine

The theory was ready; someone had to build one. In 1951, two Harvard graduate students, Marvin Minsky and Dean Edmonds, built the SNARC (Stochastic Neural Analog Reinforcement Calculator). It used about 3,000 vacuum tubes and 40 artificial "neurons", each with a motor-driven potentiometer to represent an adjustable connection strength, and it simulated a rat learning to find its way out of a maze. When the "rat" made a choice that led to success, the connections that were involved were strengthened.

It was crude and temperamental, and Minsky later said it was not much of a success. But it was probably the first physical neural-network learning machine ever built. The irony is rich: Minsky would become one of the most prominent critics of neural networks in the 1960s, as we'll see. First, he built one.

Machines that behave like animals

Cybernetics wasn't only abstract. Two British researchers built machines you could actually watch behaving.

A replica of one of W. Grey Walter's robotic tortoises. Image: Anders Sandberg from Oxford, UK, CC BY 2.0, via Wikimedia Commons.

W. Ross Ashby was a psychiatrist who built the Homeostat in 1948, a device made of four interconnected units that, when disturbed, kept adjusting themselves until they returned to a stable state. It demonstrated "ultrastability": a machine that could find equilibrium on its own, without being told how. Ashby's 1952 book Design for a Brain argued that adaptive behavior could be explained by systems that seek stability through feedback.

W. Grey Walter, a neurophysiologist in Bristol, built a pair of little three-wheeled robots in 1948 and 1949, nicknamed Elmer and Elsie and collectively classified as Machina speculatrix, the "speculative machine." Often called "tortoises," they had a light sensor, a touch sensor, and just two vacuum-tube "neurons." Yet their behavior seemed lifelike: they wandered around exploring, moved toward moderate light, backed away from bright light, and when their batteries ran low, headed back to their charging hutch. When Grey Walter put a light on one tortoise and set it in front of a mirror, it danced in front of its own reflection.

The tortoises are important to AI history for a deeper reason. They showed that complex-seeming behavior can emerge from very simple mechanisms interacting with the environment, with no central model of the world, no stored reasoning, no deliberate planning. This idea would be reborn in the 1980s in Rodney Brooks's robotics, which argued for "intelligence without representation."

What cybernetics got right, and what happened to it

Looking back, cybernetics seems to have been right about a surprising amount.

Feedback is everywhere. Control theory is now a core part of engineering. Thermostats, cruise control, autopilots, and robot arms all depend on feedback loops.
Information is a physical, measurable thing. Shannon's theory is the foundation of the digital age.
Brains can be modeled with networks. The McCulloch-Pitts neuron is the great-grandparent of modern deep learning.
Learning is adjusting connections. Hebb's idea persists.
Behavior emerges from interaction. Complex systems, from ant colonies to the internet, reward the cybernetic view.
Reinforcement through feedback. The notion of learning from reward and punishment is the heart of reinforcement learning, which we'll see in AlphaGo.

Yet cybernetics as a movement faded by the late 1950s and 1960s. Why?

It was too broad. When a theory claims to explain everything, from thermostats to politics, it risks explaining nothing in particular. Researchers wanted sharper tools and clearer funding categories.
The new computers took over. With stored-program digital computers arriving, many researchers found it more promising to write programs that manipulated symbols than to build analog feedback systems or networks of simple units.
Personalities and politics. Wiener was outspoken, a pacifist who refused to take military funding after the war and criticized the arms race, and he did not play the Washington game of grant-seeking. In a field where influence increasingly depended on defense and government money, that mattered.
A new name. When John McCarthy organized a summer workshop in 1956 to explore machine intelligence, he deliberately invented the term "artificial intelligence" in part to avoid associating the project with cybernetics and, as he later said, to avoid having to accept Wiener as a guru. Naming has consequences: the new label gave the symbolic, computer-centered approach its own banner, and cybernetics became a side current.

A tragedy

The partnership that started all this ended badly.

Pitts had thrived at MIT, working with Wiener and McCulloch, and Wiener was reportedly planning to supervise his PhD and treated him as one of his most gifted students. Then, in the early 1950s, something went wrong. According to accounts by later historians, Wiener's wife Margaret, who strongly disliked McCulloch's bohemian household, told Wiener that McCulloch's circle had corrupted their daughter. (The claim, by most accounts, was false.) Wiener angrily cut off all contact with McCulloch, Pitts, and their colleagues, and refused to explain why.

Pitts was devastated. He had idolized Wiener. Reports say he withdrew, stopped working, and burned much of his own unpublished research, including a dissertation he had been working on. He retreated into isolation and alcohol, declining prizes and refusing to publish. Warren McCulloch and Walter Pitts both died in 1969, Pitts at just 46, largely forgotten outside a small circle.

The story is a reminder that history of science is human history. The idea that launched neural networks came from two people who were, in different ways, outsiders, and the field they started would later honor the idea far more than the people.

Why this chapter matters for modern AI

If you've ever trained a neural network, you've inherited this chapter. Consider the lineage:

Idea	Origin	Modern descendant
Artificial neuron	McCulloch & Pitts, 1943	Every unit in a deep neural network
Weights and thresholds	McCulloch & Pitts	Parameters and activation functions
Learning by strengthening connections	Hebb, 1949	Gradient descent, backpropagation
Feedback and goal-seeking	Wiener, 1948	Reinforcement learning, control systems
Information and entropy	Shannon, 1948	Cross-entropy loss, compression, language modeling
Emergent behavior from simple parts	Grey Walter, Ashby	Behavior-based robotics, swarm systems

At the same time, these early thinkers differed on a point that would split the field in two, and that divides researchers to this day:

The symbolic view. Intelligence is the manipulation of symbols according to rules, like logic and Turing machines.
The connectionist view. Intelligence emerges from many simple units connected in networks and learning from experience.

McCulloch and Pitts, interestingly, belong to both camps. Their paper described neurons, yet it proved things about logic. For the next two decades, though, the symbolic camp would win the funding, the prestige, and the headlines. The connectionist camp would be pushed to the margins, and nearly declared dead, before staging one of the great comebacks in the history of science.

The 1940s at a glance

It helps to see how crowded this decade was. The same few years contain the founding documents of computing, information theory, neural networks, and cybernetics:

1936 to 1937: Turing defines computation (Part 2); Shannon applies Boolean algebra to relay circuits.
1943: McCulloch and Pitts publish their neuron model; Wiener, Bigelow, and Rosenblueth publish "Behavior, Purpose and Teleology."
1945: John von Neumann circulates the EDVAC report, describing the stored-program computer.
1946: ENIAC is unveiled, and the first Macy Conference meets.
1948: Wiener's Cybernetics and Shannon's "A Mathematical Theory of Communication" appear in the same year; Ashby builds the Homeostat; Grey Walter builds his first tortoises.
1949: Hebb publishes The Organization of Behavior.
1950 to 1951: Shannon writes about computer chess and builds Theseus; Turing publishes "Computing Machinery and Intelligence"; Minsky and Edmonds build SNARC.

Fewer than fifteen years separate Boole's algebra becoming a circuit-design tool from a machine learning to run a maze. That compression is part of why the early pioneers were so optimistic.

Three common misconceptions

"The McCulloch-Pitts neuron is a model of a real neuron." Not really, and its authors knew it. A real neuron has branching dendrites that compute in their own right, fires in timed spikes, and is modulated by dozens of chemicals. The 1943 unit is a deliberate cartoon, chosen because it can be analyzed with logic. Modern artificial neurons are "inspired by" biology in the way an airplane wing is inspired by a bird's: the principle is borrowed, the details are not.

"Cybernetics failed." As a movement with its own conferences and gurus, it faded. But its ideas were absorbed so completely that we no longer notice them. Control theory, robotics, systems biology, ecology, and cognitive science all use feedback, information, and regulation as basic concepts. The prefix "cyber-" in cybersecurity and cyberspace descends from Wiener's coinage. What failed was the label, not the substance.

"Hebb's rule is how brains learn, and backpropagation is how AI learns, so the two are basically the same." They are cousins, not twins. Hebb's rule is local: a connection changes based only on the activity of the two neurons it joins. Backpropagation needs error signals that flow backward through the whole network, which no one has found a clear biological equivalent for. Whether the brain approximates something like backpropagation by other means is an open research question, and Geoffrey Hinton, among others, has proposed alternatives to it, partly for that reason.

Quick glossary

Threshold: the level of input a unit must reach before it fires.
Weight: a number scaling how strongly one unit's output influences another.
Feedback: using the result of an action to adjust the next action.
Homeostasis: a system's tendency to restore a stable state after disturbance (Ashby's Homeostat, your body temperature).
Entropy: in Shannon's sense, a measure of the uncertainty (or average information) in a message source.
Bit: the amount of information in a single yes/no choice.

Key takeaways

McCulloch and Pitts (1943) modeled the neuron as a simple threshold logic unit and showed that networks of such units can compute any logical function. This is the starting point of neural networks.
Norbert Wiener founded cybernetics (1948), explaining goal-directed behavior in machines and animals through feedback.
Claude Shannon applied Boolean algebra to circuits (1937) and created information theory (1948), giving us the bit and the mathematics later used to train language models.
Donald Hebb (1949) proposed that learning strengthens connections between co-active neurons, the first plausible learning rule for artificial networks.
Minsky and Edmonds built the first neural network machine (SNARC, 1951), while Grey Walter and Ashby built lifelike feedback machines.
Cybernetics faded, in part because the new field of AI adopted a different name and a different, symbol-focused approach.

Try it yourself

Build XOR the hard way. A single McCulloch-Pitts neuron can't compute XOR. Combine three of the neurons from the code above, using AND, OR, and NOT, to build it: XOR(a, b) = AND(OR(a, b), NOT(AND(a, b))). You've just built a two-layer network by hand.
Stretch Hebb. Run the Hebbian learning example with more patterns, and see what happens when two patterns overlap. Why does Hebb's rule start making mistakes? What kind of rule would fix them?
Simulate a thermostat. Write a loop that reads a temperature, compares it with a target, and turns a heater on or off. Then add noise and delay and see how the system oscillates. You've just rediscovered the core problem of control theory.

Next up

In Part 4, we go to a small New Hampshire college campus in the summer of 1956, where a group of ambitious young researchers met for a workshop whose proposal contained a bold prediction: that "every aspect of learning or any other feature of intelligence can in principle be so precisely described that a machine can be made to simulate it." It was the moment the field got its name, artificial intelligence, and the moment its first great wave of optimism began.

If this chapter changed how you see neural networks, follow the series and leave a comment: which of these ideas surprised you most?

See you in Part 4.

☕ If this series helped you, you can support my writing on Ko-fi.

Why I keep going back to data structures even though I build web apps

Suraj Nandan — Mon, 09 Nov 2026 03:30:00 +0000

As a student I'm told to study data structures and algorithms for interviews. That's true, but it undersells them. In my Job Scheduler project, six hand-written structures run inside a real system. This post walks through what each one does and why SQL alone couldn't do the job.

The context

A job scheduler has one promise that matters more than every feature: a job must never run twice by accident, and it must never be lost when a worker dies halfway through.

I built it on Postgres alone, using FOR UPDATE SKIP LOCKED so many workers can poll one queue without colliding. Where SQL can't express a decision, I implemented six structures by hand and wired them into the running scheduler. It has 156 algorithm unit tests.

One note: the code below is simplified to show each idea. It isn't copied from the repository.

Let's go through them.

1. Binary min-heap: pick the next job by priority

Problem: many queues, each with jobs of different priority. Which job runs next, across all queues?

A min-heap gives the best candidate in O(1) and removes it in O(log n).

class MinHeap<T> {
  private a: { key: number; val: T }[] = [];

  push(key: number, val: T) {
    this.a.push({ key, val });
    let i = this.a.length - 1;
    while (i > 0) {
      const p = (i - 1) >> 1;
      if (this.a[p].key <= this.a[i].key) break;
      [this.a[p], this.a[i]] = [this.a[i], this.a[p]];
      i = p;
    }
  }

  pop(): T | undefined {
    if (!this.a.length) return undefined;
    const top = this.a[0];
    const last = this.a.pop()!;
    if (this.a.length) {
      this.a[0] = last;
      let i = 0;
      for (;;) {
        const l = 2 * i + 1, r = l + 1;
        let m = i;
        if (l < this.a.length && this.a[l].key < this.a[m].key) m = l;
        if (r < this.a.length && this.a[r].key < this.a[m].key) m = r;
        if (m === i) break;
        [this.a[m], this.a[i]] = [this.a[i], this.a[m]];
        i = m;
      }
    }
    return top.val;
  }
}

2. Kahn's algorithm: order jobs that depend on each other

Problem: job C needs A and B to finish first. In what order do we run a whole graph of jobs?

Kahn's algorithm repeatedly picks jobs with no unmet dependencies.

function executionOrder(deps: Map<string, string[]>): string[] | null {
  const indegree = new Map<string, number>();
  const next = new Map<string, string[]>();
  for (const [job, needs] of deps) {
    indegree.set(job, needs.length);
    for (const n of needs) next.set(n, [...(next.get(n) ?? []), job]);
  }
  const ready = [...indegree].filter(([, d]) => d === 0).map(([j]) => j);
  const order: string[] = [];
  while (ready.length) {
    const j = ready.shift()!;
    order.push(j);
    for (const k of next.get(j) ?? []) {
      indegree.set(k, indegree.get(k)! - 1);
      if (indegree.get(k) === 0) ready.push(k);
    }
  }
  return order.length === deps.size ? order : null;   // null = cycle
}

A bonus: if order is shorter than the job count, there's a cycle.

3. Three-colour DFS: reject dependency cycles up front

Problem: if A depends on B and B depends on A, nothing can ever run. We want to reject that at submission time, not discover it later.

Depth-first search with three colours (white = unvisited, grey = in progress, black = done). Meeting a grey node means we've looped back on ourselves.

function hasCycle(graph: Map<string, string[]>): boolean {
  const color = new Map<string, 0 | 1 | 2>();   // 0 white, 1 grey, 2 black
  const visit = (u: string): boolean => {
    color.set(u, 1);
    for (const v of graph.get(u) ?? []) {
      const c = color.get(v) ?? 0;
      if (c === 1) return true;                  // back edge
      if (c === 0 && visit(v)) return true;
    }
    color.set(u, 2);
    return false;
  };
  return [...graph.keys()].some(u => (color.get(u) ?? 0) === 0 && visit(u));
}

4. Union-find: find independent clusters of jobs

Problem: which jobs are connected through dependencies, and which are completely independent?

Union-find (disjoint sets) merges items into groups and answers "are these in the same group?" in near-constant time.

class DSU {
  private p = new Map<string, string>();
  find(x: string): string {
    if (!this.p.has(x)) this.p.set(x, x);
    const parent = this.p.get(x)!;
    if (parent === x) return x;
    const root = this.find(parent);
    this.p.set(x, root);                         // path compression
    return root;
  }
  union(a: string, b: string) { this.p.set(this.find(a), this.find(b)); }
}

5. Min-heap delay queue: retries with backoff

Problem: a failed job should retry later, not immediately. Keep a heap ordered by next run time; look at the top, and only release it when its time has come. It's the same min-heap, keyed by timestamp instead of priority.

6. Deficit Round Robin: stop one queue starving the rest

Problem: if one queue always has jobs, a naive scheduler can keep serving it and starve every other queue.

Deficit Round Robin gives each queue a "quantum" of credit each round. A queue can spend credit to dispatch jobs; unused credit carries over. Busy queues get their fair share, quiet queues aren't ignored.

Why not just SQL?

I leaned on Postgres wherever it could do the job: claiming jobs, concurrency bounds, leader election with advisory locks. But ordering across queues, planning a dependency graph and fair sharing are algorithmic decisions that SQL expresses awkwardly. That's the boundary where the structures earn their place.

What I find hard

Memorising patterns without understanding them. I do better when I connect a structure to a problem I've actually had.

A tip

When you learn a structure, ask:

What real thing in my own code is this?

If you can't name one, you haven't finished learning it. Heaps are priority queues; Kahn's is a build system; union-find is "who's connected to whom"; DRR is fairness.

A six-week practice plan

One structure per week, tied to a real use. Roughly 3 to 4 hours a week.

Week	Structure	Build this	Stretch
1	Min-heap	A priority task list that always shows the most urgent item	Add a "decrease priority" operation
2	Graph and Kahn's	A build-order resolver for package-style dependencies	Print the cycle when one exists
3	DFS and cycle detection	A validator that rejects circular dependencies with a clear message	Return the exact cycle path
4	Union-find	A "which accounts are connected?" grouping tool	Add a size-by-group report
5	Delay queue (heap by time)	A retry scheduler with exponential backoff	Add jitter
6	Round robin with credit	A fair scheduler across several noisy queues	Add weights per queue

The key is that every week produces something you could use, not a worksheet.

Complexity cheat sheet

Structure / operation	Time
Heap: peek / push / pop	O(1) / O(log n) / O(log n)
Kahn's algorithm	O(V + E)
DFS cycle detection	O(V + E)
Union-find: find / union	Near O(1) amortised
Hash map: get / set	O(1) average
Sorting	O(n log n)

V is the number of nodes (jobs) and E the number of edges (dependencies). If you can say what V and E are in your own problem, you can reason about its cost.

How to practise without grinding

Implement from scratch once, then use the library version forever after.
Write tests first. Edge cases (empty input, one element, duplicates, cycles) are where bugs live.
Explain it to someone or write it down in your own words.
Find it in a real tool. A build system uses topological sort; git uses graphs; your browser uses queues.

Edge cases to always test

For a heap: empty pop, single element, equal keys, many pushes then many pops.
For a graph: a node with no edges, a self-loop, two nodes pointing at each other, a disconnected graph.
For union-find: finding an unknown element, union of the same set, long chains (to check path compression).

What interviewers actually look for

In my experience as a student preparing (not as an interviewer), the common advice is that they care about:

Can you clarify the problem before coding?
Can you choose a reasonable data structure and say why?
Can you code it cleanly and test it?
Can you state the time and space cost?

Those four are easier to practise when each structure is tied to a thing you've built.

A small challenge

Take any dependency list you know (your package.json, or a recipe with "do X before Y" steps) and write a function that returns a valid order, or tells you the cycle if there isn't one. If that works, you've implemented two of the six structures from this post.

Which data structure surprised you by being useful in a real project?

☕ Enjoyed this post? You can support my writing on Ko-fi.

Rewrite or refactor? How I decide

Suraj Nandan — Sun, 08 Nov 2026 03:30:00 +0000

Rewrites are tempting because old code is annoying. You open a file, wince, and a quiet voice says "I'd do this so much better from scratch."

Sometimes that voice is right. Often it isn't. This post is a heuristic I use to decide, a list of traps, and an example from my own work where not rewriting was the right call.

Why rewrites seduce us

You understand the problem better now than when you first wrote it, so the old design looks naive.
Old code is visible, new code is imaginary. You see every flaw in what exists and none in what doesn't yet.
Early progress is fast. The first 80% of a rewrite always feels great.

The trap

Rewrites feel productive because the early days are fast. The last 20% is where they stall: the edge cases the old code already handled. Those edge cases lived in bug fixes and odd conditionals that look ugly because they encode reality. A rewrite throws them away and has to rediscover them one bug report at a time.

My heuristic

Refactor when

The code works and has users. Working code is an asset. Breaking it has a real cost.
The problems are local. One messy module, a confusing name, a duplicated function.
I can improve it in small, shippable steps. If every step leaves the project working, risk stays low.

Rewrite when

The core design makes the next feature impossible, not just awkward.
I understand the problem much better than when I started, and I can say exactly what I'd do differently.
It's small enough to finish before I lose interest, ideally in days, not months.

The test I apply first

Before any rewrite, write down, specifically, what the old design can't do.

Old design can't:
  1. ...
  2. ...
Because:
  ...
New design would allow:
  ...

If I can't fill that in with concrete statements, it's a refactor. "It's messy" isn't a reason. "It can't support two users editing at once because state lives in a single global" is.

A middle path: copy, don't rewrite

There's a third option I use more than either extreme: copy the project, then change the copy.

When I turned my portfolio design into a template, I didn't touch the live site. I made a separate copy and refactored that until every owner-specific fact lived in one config file. The live site stayed stable; the copy became the template. I'll cover the details on Day 27.

This approach works well when:

the original must keep running,
you want to try an ambitious change without risk,
or you're generalising something built for one case.

Strangler-style change

For bigger systems, the safest pattern is to replace pieces gradually:

Put a thin seam in front of the old piece.
Build the new piece behind the same seam.
Route a little traffic to it.
Grow, then retire the old one.

You always have a working system, and each step can be reverted.

A decision that stayed written down

For Job Scheduler, I used Postgres as the queue instead of a message broker, and the trade-off is written down in its case study: one dependency instead of two, with a latency floor from polling and the jobs table as the throughput ceiling, acceptable at the scale I was targeting, with LISTEN/NOTIFY as the known next step.

Writing a trade-off down like that means that when the "this is limiting" itch appears, you can check it against what you already decided to accept.

Questions to ask yourself

What specifically can the old design not do?
How long would the rewrite really take (multiply my first guess)?
What edge cases does the old code handle that I'd have to rediscover?
Can I deliver value in the middle, or only at the end?
Who depends on the current behaviour?
Am I rewriting because it's needed, or because I'm bored?

That last one is worth asking out loud.

My rule

Before a rewrite, write down specifically what the old design can't do. If I can't, it's a refactor.

A rewrite-or-refactor scoring sheet

Score each statement 0 (false), 1 (somewhat) or 2 (true). Total at the end.

Points toward refactoring

The code works and people use it.
Problems are concentrated in a few places.
I can change it in steps of a day or less.
There are some tests, or I can add them first.
The team understands the current behaviour.

Points toward rewriting

The core design blocks a feature we need.
The technology is end-of-life or unmaintained.
I can state exactly what the old version can't do.
The scope is small enough to finish in days.
I can run old and new in parallel and compare.

If the refactoring score is clearly higher, refactor. If rewriting wins and you can define the gap precisely, consider a rewrite, ideally incrementally. If the scores are close, default to the smaller change.

Small refactoring moves

Big refactors are made of small, safe steps. Four worth knowing:

1. Extract function. Pull a block into a named function so the name explains it.

// before
if (tx.status === 'FUNDED' && tx.cardholder_id === user.id && !tx.disputed_at) { /* ... */ }

// after
const canMarkPurchased = (tx: Tx, user: User) =>
  tx.status === 'FUNDED' && tx.cardholder_id === user.id && !tx.disputed_at;

if (canMarkPurchased(tx, user)) { /* ... */ }

2. Introduce a seam. Put an interface between your code and a dependency so you can swap the implementation.

interface PaymentProvider { charge(amount: number): Promise<string> }
class StubProvider implements PaymentProvider { async charge() { return 'stub-id'; } }
// later: class RazorpayProvider implements PaymentProvider { ... }

CardBridge's stubbed escrow and KYC are the sort of thing this makes replaceable.

3. Replace conditionals with data. A long if/else over states becomes a lookup table (like the legal-transitions map).

4. Rename for truth. If a variable says data and holds a list of claims, call it claims. Cheap and surprisingly effective.

Always have a safety net

Before changing structure, make sure something will tell you if behaviour changed:

an existing test suite,
a handful of characterisation tests that record what the code does today (even if it's odd),
or manual checks written down in advance.

Refactoring without a safety net is rewriting in slow motion.

Signs a rewrite is going wrong

You keep discovering behaviour the old code had.
The deadline keeps moving.
The old system keeps getting patched meanwhile, so you're chasing a moving target.
No one can say what "done" is.
You're excited about the new tech more than the problem.

When two or three show up, stop and check whether a refactor or a gradual migration would do.

Questions to ask a teammate

If we did nothing, what's the actual cost?
What's the smallest change that removes most of the pain?
How will we know it worked?
What's our rollback plan?

What's your worst rewrite story? And did the new version end up better?

☕ Enjoyed this post? You can support my writing on Ko-fi.

BTCPay Server hot wallets drained: what self-hosting a payment server really costs

Suraj Nandan — Sat, 07 Nov 2026 18:30:00 +0000

Self-hosting your payment stack sounds like the safest option: no custodian, no middleman, your keys on your server. Last weekend showed the other side of that. If your keys live on your server, its patch level is the only thing between the internet and your money.

Over 1 November, attackers swept Bitcoin and Litecoin out of hot wallets on outdated BTCPay Server instances. The project asked every operator to switch their servers off.

What happened

BTCPay Server is free, open-source software that merchants run on their own machines to accept bitcoin payments directly into their own wallets. There's no central service, so each operator patches and secures their own instance.

According to the project's incident post (2 November 2026, times in UTC):

1 Nov, 13:46: a wallet drain took place. The project says it hasn't established when exploitation first began.
1 Nov, 20:56: the first email reporting a theft arrived.
That evening the project asked VPS hosts, including LunaNode, to take BTCPay instances offline as a precaution.
1 Nov, 22:25: BTCPay warned on X and asked operators to shut down with ./btcpay-down.sh until the investigation was done.
2 Nov: the investigation found the attacks targeted BTCPay Server 2.4.1 and earlier. Servers already on 2.4.2 or later when the warning went out showed no impact.

Founder Nicolas Dorier said, as reported by CoinDesk and Unchained, that the attacker logged in as an administrator on affected servers, and that the team was still working out how. The project's public servers run 2.4.7 and, he said, weren't attacked.

How much was taken

BTCPay hasn't published a loss figure or a count of affected servers. It published two attacker addresses, but warns that some activity there predates the thefts, so balances aren't a confirmed total.

The on-chain analytics firm Bitquery traced what it calls a floor of about $1.63 million at 2 November prices:

18.38 BTC across 534 sweeps and 3,405 LTC across 148 sweeps, 682 sweeps in all.
The first sweep came on 30 October at 08:22 UTC, about 62 hours before the public alert.
87% of the value moved in one wave on 1 November, between 14:12 and 22:16 UTC.
267 more sweeps, worth about $150,000, landed after the alert.

Bitquery stresses that sweeps are transactions, not victims, so the number of affected servers is unknown.

The background: two incidents in three months

This isn't BTCPay's first bad week this year. On 7 August 2026, it shipped 2.4.2 to fix a critical, already-exploited flaw that let an unauthenticated attacker obtain LND .macaroon credential files and take over a merchant's Lightning node. Researcher Craig Raw was credited with the disclosure. At the time, the project said on-chain wallets weren't affected by that issue.

The November incident hits exactly those on-chain hot wallets. BTCPay says the attackers "used a different method to exploit the vulnerability fixed in 2.4.2" and hasn't published technical details. No CVE has been assigned. Some crypto news sites describe it as an authentication bypass, but BTCPay hasn't confirmed that, so treat it as a claim.

There's a third thread. On 29 October, BTCPay released 2.4.7, which fixes 85 findings from an Anthropic OSS Scanner report (1 critical, 13 high, 52 medium, 19 low, using the report's own ratings). Bitquery notes the first sweep came less than a day later. BTCPay hasn't said the drains used any of those findings, and the affected servers were several releases behind 2.4.7 anyway.

Why a hot wallet changes the stakes

A hot wallet keeps the spending keys on the server so the software can pay out automatically. BTCPay's own documentation flags the feature's security implications. The trade-off looks like this:

Watch-only wallet (keys off-server)
  attacker gets admin → can see invoices, change settings
                      → cannot sign a spend

Hot wallet (seed on the server)
  attacker gets admin → can sign and broadcast a sweep
                      → funds gone in one transaction, irreversibly

With card payments, a compromised merchant account leads to chargebacks and disputes. With an on-chain hot wallet, a compromised admin session ends with a confirmed transaction. That's why the patch gap matters so much here: 2.4.2 had been out for almost three months.

Who's affected

Anyone who ran BTCPay Server 2.4.1 or earlier with an internet-facing instance, especially with a hot wallet enabled. BTCPay says to move to a fresh server even if you didn't notice a theft, and even if you updated after the 1 November warning.
Merchants on hosted instances. Some providers shut servers down automatically, and BTCPay suggests contacting yours to migrate.
Lightning users should still follow the August advice to rotate LND credentials that were reachable through their own proxies or Tor services.
Hardware-wallet setups weren't affected, according to BTCPay.

What operators and developers should do

BTCPay's recovery steps, in short:

Check your version (it's shown in the page footer when you're logged in).
If it's 2.4.1 or earlier, migrate. Create a new wallet with a new seed on a trusted device and sweep any remaining hot-wallet funds into it. Reusing the old seed leaves the funds exposed.
Take the old server offline and keep its logs and transaction records.
Build a fresh VM with the latest release from trusted sources. Don't restore the whole old server.
Rotate everything the old server could reach (hosting, SSH, API and Lightning credentials) from a trusted device, never from the old machine.
Keep only operating cash hot. Move the rest to a wallet whose keys never touch the server.

And the broader lessons for anyone running self-hosted software that holds value:

Subscribe to the project's security channel. BTCPay says it wishes it had done more to reach users on old versions. Don't rely on the project to find you.
Treat "update available" on a money-moving server as an incident, not a backlog ticket.
Put admin panels behind a VPN, SSO or IP allow-list. An admin login that can't be reached from the internet can't be abused from it.
Alert on outbound spends. A watch-only monitor on your own addresses can flag a sweep within minutes. The first one here came 62 hours before the public alert.

What might happen next (analysis)

This section is analysis, not reporting.

Expect a fuller technical write-up and possibly a CVE once BTCPay finishes its investigation, which may show whether the admin logins came from the 2.4.2 bug or something else. The 2.4.7 release also shows how AI-assisted code scanning can surface dozens of issues at once in a small open-source project, and those fixes then become public diffs that attackers can study. Self-hosted payment projects will likely push harder on auto-update and on-by-default hardening, and hosting providers may start forcing upgrades on images they distribute.

Conclusion

BTCPay's design keeps merchants in control of their money, and that also makes them responsible for it. The software had a fix for months. The instances that got drained simply hadn't installed it, and their hot wallets turned an admin login into an irreversible transfer. If you run anything that can sign a payment, patch speed is part of your treasury policy.

Your turn: if a server you run could move money on its own, how quickly would you find out it had been patched, or that it hadn't?

References

BTCPay Server, "Security Incident Affecting BTCPay Server 2.4.1 and Earlier" (2 Nov 2026): https://blog.btcpayserver.org/btcpay-server-security-incident-2-4-1-and-earlier/
BTCPay Server, "Security Advisory: Update BTCPay Server to 2.4.2 Immediately" (7 Aug 2026, updated 2 Nov 2026): https://blog.btcpayserver.org/security-advisory-btcpay-server-2-4-2/
BTCPay Server, "BTCPay Server Security Incident: Our Response and Next Steps" (10 Aug 2026, updated 2 Nov 2026): https://blog.btcpayserver.org/btcpay-server-security-incident-response-and-next-steps/
GitHub, btcpayserver/btcpayserver release v2.4.7 (29 Oct 2026): https://github.com/btcpayserver/btcpayserver/releases/tag/v2.4.7
Bitquery, "BTCPay Server hack" investigation (figures verified 2 Nov 2026): https://bitquery.io/investigations/btcpay-server-hack
The Hacker News, "Hackers Exploit BTCPay Server Flaw to Steal Bitcoin and Litecoin From Hot Wallets" (3 Nov 2026): https://thehackernews.com/2026/11/hackers-exploit-btcpay-server-flaw-to.html
CoinDesk, "BTCPay tells users to switch off their servers after reports of drained wallets" (1 Nov 2026): https://www.coindesk.com/tech/2026/11/02/btcpay-a-bitcoin-payment-tool-tells-users-to-switch-off-their-servers-after-reports-of-drained-wallets
Unchained, "BTCPay Server reports no wallet drains on latest release after asking merchants to go offline" (2 Nov 2026): https://unchainedcrypto.com/btcpay-server-reports-no-wallet-drains-on-latest-release-after-asking-merchants-to-go-offline/

Part of The Wire, a daily brief on the tech and security news that matters to developers. Details are as reported up to 5 November 2026.

What a hackathon teaches you that a course doesn't

Suraj Nandan — Sat, 07 Nov 2026 03:30:00 +0000

Courses reward correctness. Hackathons reward something that runs. Both matter, but the second teaches you things lectures can't.

I've built under hackathon-style deadlines on three projects: GigShield (a team of three, March to June 2026), Knot.ai (the Echo Sphere × Agora hackathon, August to September 2026) and Hospitality.ai (the GE HealthCare Precision Care Challenge 2026). This post is about what that format forces on you, what it can't teach, and a set of habits for getting the most out of one.

What the deadline forces

Cutting scope without agonising

When time is fixed, scope is the only thing that can move. A hackathon makes you practise deciding what not to build, quickly, without the luxury of perfect information. In normal projects that decision gets postponed forever.

A useful question: what is the smallest thing that still demonstrates the idea?

Choosing familiar tools

It's not the time to learn a new framework. The fastest way to lose a weekend is to debug a tool you don't know while also building a product. Use what you already understand, and spend your novelty budget on exactly one thing that matters to the idea.

Demo-first thinking

If the story isn't clear in two minutes, the features don't matter. Judges and users meet your project through a short demo, not through your code quality. That forces you to think about the experience of understanding it, which is a skill product people use all the time.

Splitting the problem so the hard part is isolated

Knot.ai is a good example. The hard part wasn't the UI. It was keeping an AI interviewer under control. Isolating that, with a server-side state machine for difficulty and topic coverage while the model handled judgement and phrasing, meant the risky piece could be built and tested on its own.

What a hackathon exposes

A tight deadline makes your shortcuts visible, and after each sprint it's worth listing what you'd have done with more time. Reading the "limits" sections of those projects gives a decent picture of what a sprint leaves behind:

Knot.ai's voice path is the thinner-tested surface, and its state is single-node.
Hospitality.ai runs on synthetic data and doesn't read scanned PDFs.
GigShield's payouts are simulated, and some state lives in browser storage.

None of that is a failure. It's the honest shape of work done against a clock. The mistake would be pretending otherwise.

What a hackathon doesn't teach

Maintainable code. A weekend prototype optimises for speed of writing, not ease of changing.
Tests. Under time pressure they're the first thing dropped.
Sustainable pace. Sprinting teaches you to sprint, not how to keep going for a year.
Real users. A demo audience is not a customer. Their questions are different.

A habit worth keeping

After building something fast, schedule a clean-up week, or admit to yourself it's a prototype. Lying to yourself about quality is how prototypes quietly become production.

A practical playbook

Before

Agree the one-sentence idea.
Pick the stack you already know.
Decide the roles (see Day 8) and the contract between pieces.
Check the rules: what's judged, what's allowed, what must be live.

During

Get a thin end-to-end path working in the first few hours, however ugly.
Write the demo script before the last feature. It tells you what to cut.
Deploy early. Don't discover hosting problems at the deadline.
Keep a "not now" list (Day 10).
Sleep. A rested person debugs faster than a heroic one.

After

Write down what's real and what's faked, while you remember.
Fix the one thing that embarrassed you in the demo.
Turn the work into a case study, including limits.

A tip on honesty in demos

If part of your demo is mocked, simulated or stubbed, say so. It's tempting to let a mock look real. But being clear about it earns more respect than being caught, and it makes your real parts more credible.

A 24-hour timeline template

Most hackathon time disappears at the beginning and the end. A rough plan helps. Scale it to your event's length.

Hours	Focus	Output
0–1	Agree the idea; read the rules and judging criteria	One-sentence pitch
1–3	Roles, contracts, repo, deploy skeleton	A live "hello" on the real URL
3–10	The one core feature, end to end	A thin path that works, however ugly
10–16	Second feature, error handling, data	Something worth demoing
16–20	Cut scope, fix the embarrassing bugs	A stable build
20–22	Demo script, screenshots, README	A story in two minutes
22–24	Rehearse, deploy, sleep if you can	A calm demo

The deploy skeleton in hour 1 to 3 is the part people skip, and it's the one that saves the final hour.

Design for the judging criteria

Read the criteria before the first line of code. Typical ones, and what they imply:

Criterion	What judges look for	How to show it
Innovation	Something fresh, not a clone	One distinctive idea, stated early
Technical depth	Hard parts handled well	Name the hard problem and show your solution
Usability	A stranger can use it	A demo with no explanation needed
Impact	A real problem and a real user	A named persona and a concrete scenario
Completeness	It works end to end	A thin full path beats three broken features

Where the rules mention a sponsor's technology, plan how to use it meaningfully, since a token integration is easy to spot.

A demo script template

Two minutes is shorter than you think.

Hook (15 s): the problem in one sentence, with a person in it.
Show (60 s): the one flow that matters, live or recorded.
Why it's hard (20 s): the interesting technical decision.
What's next (15 s): what you'd build with more time.
Ask (10 s): invite questions.

Rehearse out loud at least twice. And record a backup video: Wi-Fi fails at exactly the wrong moment.

Team dynamics under pressure

Decide who has the final say on scope when you disagree.
Check in every few hours for five minutes: what's done, what's blocked.
Protect each other's sleep. Tired people write bugs.
Share credit in the demo, by name.
Keep the mood light. Humour is a performance tool.

After the event

The weekend isn't over when the demo ends. In the following week:

Write down what's real and what's faked while you still remember.
Fix the one thing that bit you on stage.
Write a short case study including limits.
Thank the organisers and your teammates.
Decide, honestly: is this a prototype to retire, or a project to continue?

Common mistakes

Starting a new framework during the event.
Building features the demo never shows.
No deploy until the last hour.
A demo that depends on a fragile live connection.
Treating a mocked feature as real without saying so.

Did a hackathon change how you code? What did you drop first when time ran short?

☕ Enjoyed this post? You can support my writing on Ko-fi.

DEV Community: Suraj Nandan

Read other people's code: a habit I'm trying to build

Why reading matters

What not to do

A method that works for me

1. Pick a small library you already use

2. Read the README and the tests first

3. Find the entry point

4. Read one file, not the whole repo

5. Trace one feature end to end

6. Ask "why is it structured this way?"

7. Run it and break it

A short worked example

Reading code you'll have to change

From reading to contributing

The next step I want to take

A weekly routine

Tools that make reading code easier

How to read a pull request

Questions to ask of any unfamiliar code

Keeping a reading log

Choosing something to read

Common obstacles

One small contribution to aim for

The History of AI, Part 5: Perceptrons, ELIZA, SHRDLU, and Shakey

The Perceptron: a machine that learns

How the perceptron works

The Mark I Perceptron and the press conference

A cousin: ADALINE

The seeds of the problem

ELIZA: the chatbot that wasn't thinking

How ELIZA worked (spoiler: it's simple)

The ELIZA effect

PARRY, the paranoid program

Microworlds: the strategy of the age

SHRDLU: understanding language in a world of blocks

Why SHRDLU didn't scale

Shakey: the first robot that reasoned

Shakey's gifts to computer science

The media sensation

What these four teach us

A glimpse of the cracks

Timeline: 1957 to 1972

The ELIZA effect, today

Quick glossary

Key takeaways

Try it yourself

Next up

Packaging my own design as a template: the unglamorous parts

Why a template

The principle: separate the owner from the engine

What had to change

1. One config file for every owner-specific fact

2. A template-driven index.html

3. Build scripts that read the same config

4. A section list that controls the page

5. Parameterised APIs

6. The assistant persona

A sample persona, not my life

The licence question

Test like a buyer

What I found along the way

What I haven't finished

A checklist you can reuse

Lesson

Writing the listing page

README for the buyer

Support and refunds: think before you sell

A pre-launch dry run

Versioning and updates

What I'd tell my past self

Impostor syndrome, minus the pep talk

First, separate two different things

Make it concrete

Keep a record

A simple version

Limit the comparison

Ask the question out loud

Notice what you discount

When "I don't belong" isn't about skill

2. A template-driven `index.html`