DEV Community: Odilon HUGONNOT

Wrapping Go errors: where, and mostly why

Odilon HUGONNOT — Wed, 29 Jul 2026 09:00:02 +0000

Mid-review on an order confirmation mailer, I confidently explained that the right call is to wrap an error once, at the package boundary, not at every internal step. The functions that build the message stay silent, only the public function that sends the email adds useful context. I even quoted Dave Cheney to back it up. Except while researching this article, I found out Dave Cheney changed his own mind since then, and the real rule isn't about where you wrap, it's about what you choose to expose.

The advice I just gave

The code in question looked like this: two internal functions that build an email's content, and two public functions that call them before sending:

func buildOrderMessage(order Order) (Message, error) {
    tpl, err := loadTemplate("order-confirm")
    if err != nil {
        return Message{}, err // no wrap, propagate as-is
    }
    return tpl.Render(order)
}

func mailOrder(order Order) error {
    msg, err := buildOrderMessage(order)
    if err != nil {
        return fmt.Errorf("failed to build message for order %d: %w", order.ID, err)
    }
    return sender.Send(msg)
}

The idea: wrapping at every layer produces a noisy message like failed to send: failed to build message: failed to load template: open failed. Nobody reads those intermediate layers in production, only the final message and the root cause matter. Wrapping once, at the right spot, keeps the message readable and adds the context that actually carries value, here the order ID. That's a correct argument. It's just not the whole picture.

Except Dave Cheney changed his mind

In 2016, Dave Cheney published Don't just check errors, handle them gracefully and popularized pkg/errors. His recommendation at the time: wrap at every layer with errors.Wrap, specifically to build a readable stack of context without a traditional stack trace:

func ReadFile(path string) ([]byte, error) {
    f, err := os.Open(path)
    if err != nil {
        return nil, errors.Wrap(err, "open failed")
    }
    // ...
}

func ReadConfig() ([]byte, error) {
    config, err := ReadFile(path)
    return config, errors.Wrap(err, "could not read config")
}

The final message becomes could not read config: open failed: open /path: no such file or directory. Back then, the argument held: without wrapping at every level, a failure inside authenticate() bubbles up to the top of the stack showing just "no such file or directory," with no clue where or why.

Then in 2021, while looking for a maintainer to take over pkg/errors, Cheney wrote that he no longer wraps his errors at all. His reason: structured logging (slog fields rather than a concatenated string) carries that debug context better than nested layers of Wrap. The creator of the pattern ended up finding it redundant with modern tooling.

What matters here isn't picking a side between "always wrap" and "never wrap." It's understanding why both positions are defensible depending on what you're actually trying to solve: a readable production error message, or an API contract between packages.

The real question: what does %w commit you to

Since Go 1.13, %w in fmt.Errorf does more than decorate a message. It makes the inner error inspectable via errors.Is and errors.As from any caller. That means %w isn't a style choice, it's an API commitment:

// %w: exposing the inner error, callers can match on it
func LookupUser(id string) (*User, error) {
    row, err := db.QueryRow(...)
    if err != nil {
        return nil, fmt.Errorf("lookup user %s: %w", id, err)
    }
    // ...
}

// The caller can now do this, and rely on it staying true over time
if errors.Is(err, sql.ErrNoRows) {
    return http.StatusNotFound
}

The classic trap: LookupUser runs on database/sql today. The day it switches to an ORM, or a cache gets added in front of the query, sql.ErrNoRows stops bubbling up. The caller's errors.Is check silently breaks, no compile error, just a 404 that quietly becomes a 500 in production. The %w had turned an implementation detail (we use database/sql) into a public promise.

Which gives a simple rule straight from the Go 1.13 docs: default to %v, because it preserves the abstraction and exposes nothing. Reach for %w only when you consciously decide the caller needs to inspect the inner error, and in that case define your own sentinel rather than leaking a dependency's:

var ErrUserNotFound = errors.New("user not found")

func LookupUser(id string) (*User, error) {
    row, err := db.QueryRow(...)
    if errors.Is(err, sql.ErrNoRows) {
        return nil, fmt.Errorf("lookup user %s: %w", id, ErrUserNotFound)
    }
    if err != nil {
        return nil, fmt.Errorf("lookup user %s: %v", id, err) // internal detail, not exposed
    }
    // ...
}

The caller now matches on ErrUserNotFound, a sentinel the package owns. If database/sql disappears tomorrow, the contract still holds.

The public/private rule that actually holds up

Which leaves the "where" question. The most useful rule I found while digging comes from Efe Karakus's blog: wrap only at public boundaries, let private functions propagate as-is. His example makes the point well: a file path repeated three times in the error message, because every private layer kept adding its own redundant context.

// ❌ Every level wraps, even private functions
// "failed to read config from /etc/x: failed to read file from /etc/x: failed to open /etc/x: ..."

// ✅ Only public functions wrap
func readFile(path string) ([]byte, error) {
    f, err := os.Open(path)
    if err != nil {
        return nil, err // private, propagate as-is
    }
    return io.ReadAll(f)
}

func Read(path string) ([]byte, error) { // public, wraps once
    data, err := readFile(path)
    if err != nil {
        return nil, fmt.Errorf("failed to read config from %s: %w", path, err)
    }
    return data, nil
}

That's exactly what the order confirmation mailer was already doing, and that's why the initial advice wasn't wrong. It was just incomplete: it answered "where," not "%w or %v."

What I'm changing in the mailer

Revised version, applying both criteria together: where to wrap (the public boundary), and what to expose (only when the caller needs to act on it):

func buildOrderMessage(order Order) (Message, error) {
    tpl, err := loadTemplate("order-confirm")
    if err != nil {
        return Message{}, err // private, propagate as-is
    }
    return tpl.Render(order)
}

func mailOrder(order Order) error {
    msg, err := buildOrderMessage(order)
    if err != nil {
        // %v: the caller has nothing to match on for a template error,
        // it just needs to know which order failed
        return fmt.Errorf("failed to build message for order %d: %v", order.ID, err)
    }
    if err := sender.Send(msg); err != nil {
        if errors.Is(err, smtp.ErrRateLimited) {
            // %w here: the caller MUST be able to tell "retry later"
            // apart from a permanent send failure
            return fmt.Errorf("send order %d: %w", order.ID, smtp.ErrRateLimited)
        }
        return fmt.Errorf("send order %d: %v", order.ID, err)
    }
    return nil
}

The difference comes down to one line: the SMTP rate limit is wrapped with %w because the caller has a genuinely different action to take (retry with backoff). Everything else goes through %v, useful context for a human reading logs, without promising anyone that *template.Error will still be exposed ten versions from now.

Conclusion

The real trap isn't picking the wrong side between "wrap everywhere" and "wrap once." It's treating %w as a cosmetic message flourish when it's actually a contract clause. Once you ask "am I committing my package to always return this specific error," the position in the code becomes secondary. It also taught me to verify a quote before dropping it in a code review, even when it comes from a name as solid as Dave Cheney's.

Meta Tags Generator: Title, Open Graph and Twitter Card at Once

Odilon HUGONNOT — Tue, 28 Jul 2026 09:00:02 +0000

The familiar scene: you publish a page, share it on LinkedIn, and the preview shows the wrong title, a blank description, and a random image pulled from somewhere on the page. Or worse, no title tag at all because you forgot the CMS doesn't generate one automatically.

Meta tags live in the <head> and are invisible on the page. That's exactly why they get forgotten. Yet they're what separates a link someone clicks from a link that looks like a phishing attempt.

Three layers, three sets of rules

Search engines read <title> (shown as the blue clickable line in results, 50-70 characters) and <meta name="description"> (the grey snippet below it, 150-160 chars). Google can override your description with something it generates itself, but if you leave it blank, it picks the first paragraph it finds — rarely your best writing.

Social platforms (Facebook, LinkedIn, WhatsApp, Slack) read Open Graph tags: og:title, og:description, og:image and og:url. Without them, the preview is assembled from whatever the crawler finds first. The ideal OG image is 1200 × 630 px — large enough to be readable in a feed, small enough to load quickly.

Twitter/X has its own format, Twitter Cards, with twitter: prefixed tags. In practice, Twitter falls back to OG tags, but the twitter:card tag lets you choose between a small thumbnail (summary) and a full-width image (summary_large_image).

The most common mistakes

A title that's too long: Google truncates past roughly 600 pixels — not characters, because a capital "W" takes more space than a lowercase "i". A title that's too short wastes keyword real estate.

A generic description copy-pasted across every page: "Welcome to our website. Browse our products and services." The description doesn't directly affect rankings, but it's your only chance to speak to someone who's hovering over your link and hasn't decided to click yet. A generic description loses that conversion.

A missing OG image: the LinkedIn preview shows a blank square. The link looks broken.

OG tags in French but not in English, or different content per language: social crawlers don't follow language redirects. They see whatever the server returns for the URL they request.

Using the generator

I built a free meta tags generator that outputs all three layers at once: SEO, Open Graph and Twitter Card.

It shows a live preview of how your page will appear in Google (title + description + URL), on Facebook/LinkedIn (image + title + domain), and on Twitter (summary or large image). You see exactly what your visitors will see before you publish anything.

Character counters turn red when you exceed the limits. A global SEO score (out of 100) checks the basics: title length, description present, canonical URL set, OG image provided, viewport defined.

The generated code is ready to paste into your <head>, in the recommended order (charset and viewport first, then OG tags).

Open the meta tags generator

A few rules worth keeping

Put your main keyword early in the title, ideally in the first three words. The description doesn't directly affect Google rankings, but it drives click-through rate, which feeds back into position over time.

The canonical tag (<link rel="canonical">) prevents duplicate content when a page is accessible from multiple URLs: with and without www, with and without a trailing slash, with UTM parameters.

To validate after publishing: the Facebook Sharing Debugger (developers.facebook.com/tools/debug), the Twitter Card Validator, and Google Rich Results Test. The generator lets you skip the publish-test-fix-republish loop by showing the result upfront.

GOMAXPROCS and Kubernetes: Go App Throttled, How to Fix It

Odilon HUGONNOT — Mon, 27 Jul 2026 09:00:03 +0000

The Go pod is running in production. CPU limit set to 2, metrics look reasonable. But under load, P99 latencies spike intermittently with no obvious cause. No errors, no goroutine leaks, just latency blowing up on traffic bursts.

The root cause is usually invisible: GOMAXPROCS equals the number of CPUs on the physical node, not the container limit. Your Go app thinks it has 32 CPUs when it only has 2. The Linux kernel handles the gap in its own way — CFS throttling.

What GOMAXPROCS reads (and what it ignores)

By default, the Go runtime computes GOMAXPROCS via runtime.NumCPU(), which reads the number of CPUs available at the OS level. On a 32-core Kubernetes node, that returns 32 — regardless of what resources.limits.cpu says in your pod spec.

Kubernetes CPU limits are enforced through Linux cgroups (v1 or v2). Cgroups are transparent to processes: a pod with limits.cpu: "2" doesn't see two virtual CPUs, it sees all the node's CPUs and gets suspended when it consumes too much. The Go runtime, historically, never read cgroups. It trusted the physical core count.

package main

import (
    "fmt"
    "runtime"
)

func main() {
    // Inside a pod with limits.cpu: "2" on a 32-core node
    fmt.Println(runtime.NumCPU())      // → 32
    fmt.Println(runtime.GOMAXPROCS(0)) // → 32
}

CFS throttling: how the kernel slows you down

The Linux CFS (Completely Fair Scheduler) enforces CPU limits via two cgroup parameters: cpu.cfs_quota_us (allowed CPU time) and cpu.cfs_period_us (measurement window, 100 ms by default). A pod limited to 2 CPUs gets at most 200 ms of CPU time per 100 ms window.

When Go spawns 32 OS threads for 32 parallel goroutines, those threads compete for physical CPUs. Once their combined usage exceeds the cgroup quota within the current window, the kernel suspends all threads in the cgroup until the next window starts. That's throttling: a complete application freeze lasting anywhere from a few milliseconds to several tens of milliseconds. A handful of these per second is enough to tank your P99.

The signal shows up in Kubernetes Prometheus metrics:

container_cpu_cfs_throttled_periods_total
container_cpu_cfs_periods_total

# Throttling ratio (should be near 0)
rate(container_cpu_cfs_throttled_periods_total[5m]) /
rate(container_cpu_cfs_periods_total[5m])

The fix: automaxprocs (and Go 1.25)

Uber published go.uber.org/automaxprocs exactly for this. The package reads the cgroup at startup (v1 or v2), computes the effective quota by dividing quota_us / period_us, and calls runtime.GOMAXPROCS(n) with the right value.

Integration is a single blank import:

package main

import (
    "fmt"
    "runtime"

    _ "go.uber.org/automaxprocs" // reads cgroup in init()
)

func main() {
    // Inside a pod with limits.cpu: "2"
    fmt.Println(runtime.GOMAXPROCS(0)) // → 2
}

go get go.uber.org/automaxprocs

If you'd rather avoid the dependency and know the value at deploy time, set it manually:

import "runtime"

func init() {
    runtime.GOMAXPROCS(2) // match your limits.cpu
}

The downside of the manual approach: change the pod spec and forget to update the code, and you're back to square one. With automaxprocs, the value tracks the cgroup automatically.

Go 1.25: fixed in the runtime itself

Since Go 1.25 (August 2025), the runtime reads cgroups by default on Linux. If the process runs inside a container with a CPU quota lower than the node's core count, GOMAXPROCS is adjusted automatically — no external dependency needed. Go 1.25 also watches for quota changes at runtime, which matters if Kubernetes adjusts resource limits on a live pod.

Two GODEBUG options let you opt out if needed:

# Ignore cgroup quota (pre-1.25 behavior)
GODEBUG=containermaxprocs=0

# Keep the initial value, skip dynamic updates
GODEBUG=updatemaxprocs=0

On Go 1.25 and above, automaxprocs is no longer needed. On Go 1.24 and below, Uber's package remains the standard solution.

Verify it's working

To check the effective value inside a running pod:

# Open a shell in the pod
kubectl exec -it <pod-name> -- /bin/sh

# Read the cgroup v2 quota
cat /sys/fs/cgroup/cpu.max
# → 200000 100000  (= 2 CPUs: 200ms quota / 100ms period)

# Read cgroup v1 values
cat /sys/fs/cgroup/cpu/cpu.cfs_quota_us
cat /sys/fs/cgroup/cpu/cpu.cfs_period_us

If you expose Go runtime metrics via Prometheus, the gauge go_sched_gomaxprocs_threads (available with the runtime/metrics collector since Go 1.17) shows the current value. It should match your CPU quota, not the node's core count.

Conclusion

CFS throttling in Go Kubernetes workloads is a silent problem: no error logs, no obvious cause, just P99 latency spikes under load. The root cause is almost always the same — GOMAXPROCS sized to the node, not the container.

The fix is proportionate to the problem: one import or one runtime flag. On Go 1.25, it's handled by upgrading. On older versions, automaxprocs has been battle-tested at Uber scale for years. Either way, it's a five-minute change with a measurable effect the next time your traffic spikes.

Go 1.25 testing/synctest: No More Flaky Concurrent Tests

Odilon HUGONNOT — Sun, 26 Jul 2026 09:00:01 +0000

Three green tests locally, two red on CI. The outcome depends on how busy the build server is that day. This isn't a logic bug — it's a time.Sleep that assumes 100 ms is always enough for a goroutine to finish.

That test doesn't verify anything. It gambles.

testing/synctest, stable since Go 1.25 (August 2025), solves this at the root. No more guesswork, no more arbitrary waits: the clock advances on demand, inside an isolated bubble.

The test that lies

Debounce is a classic example of time-dependent concurrent code: trigger an action only if no call has happened in the last N milliseconds. Here's a simple implementation.

func Debounce(fn func(), delay time.Duration) func() {
    var timer *time.Timer
    var mu sync.Mutex
    return func() {
        mu.Lock()
        defer mu.Unlock()
        if timer != nil {
            timer.Stop()
        }
        timer = time.AfterFunc(delay, fn)
    }
}

And the naive test that goes with it:

// ✗ Fragile
func TestDebounce(t *testing.T) {
    called := 0
    debounced := Debounce(func() { called++ }, 50*time.Millisecond)

    debounced()
    debounced()
    debounced()

    time.Sleep(200 * time.Millisecond) // fingers crossed

    if called != 1 {
        t.Fatalf("want 1 call, got %d", called)
    }
}

This passes locally because your machine is fast and 200 ms feels like plenty. On a loaded CI runner, the time.AfterFunc goroutine may not have had a chance to run by the time called is read. Flaky. No error message explains why.

go test -race won't catch this either. There's no concurrent memory access at the same instant — the problem is purely temporal. Two different tools, two different failure modes.

What testing/synctest does

testing/synctest runs your test inside a "bubble". Inside the bubble, the time package uses a fake clock controlled by the test. That clock doesn't tick on its own: it only advances when all goroutines in the bubble are durably blocked — waiting on a channel, a mutex, a timer — but not on a syscall or network I/O.

The Go 1.25 API has exactly two functions:

synctest.Test(t, f) — runs f in a new bubble and waits for every goroutine in that bubble to exit before returning to the test framework.
synctest.Wait() — blocks until all other goroutines in the bubble are durably blocked. The explicit synchronization point: "background work is done for now."

Go 1.24 had an experimental preview behind GOEXPERIMENT=synctest with a slightly different API (synctest.Run() instead of synctest.Test()). Go 1.25 graduated the package to the standard library and finalized the API. No flags, no build tags — direct import.

Before and after

The same debounce test, rewritten with testing/synctest:

// ✓ Deterministic
import "testing/synctest"

func TestDebounce(t *testing.T) {
    synctest.Test(t, func(t *testing.T) {
        called := 0
        debounced := Debounce(func() { called++ }, 50*time.Millisecond)

        debounced()
        debounced()
        debounced()

        // Advances the virtual clock by 100 ms instantly.
        // The AfterFunc goroutine (fires at 50 ms) wakes up along the way.
        time.Sleep(100 * time.Millisecond)
        synctest.Wait()

        if called != 1 {
            t.Fatalf("want 1 call, got %d", called)
        }
    })
}

What happens inside the bubble:

The three debounced() calls each schedule a time.AfterFunc at 50 ms, canceling the previous one.
time.Sleep(100ms) blocks the test goroutine. All goroutines in the bubble are now durably blocked, so the runtime advances the virtual clock to 50 ms. The AfterFunc goroutine wakes up and runs called++.
The clock continues to 100 ms. The test goroutine wakes up. synctest.Wait() confirms the AfterFunc goroutine has finished.
The assertion on called is reliable. Always. No gambling.

Actual wall-clock time for the test: microseconds, not 200 ms.

What synctest doesn't cover

testing/synctest isn't a silver bullet. Three categories slip through.

Network I/O. A goroutine blocked on a network read isn't "durably blocked" in synctest's terms — an external process can unblock it at any time. If your code makes real HTTP calls, synctest.Wait() can't reason about its state. Fix: replace the network layer with an interface backed by a deterministic test implementation (net.Pipe(), httptest.Server, or a hand-rolled mock).

Syscalls and cgo. Same reason: the Go runtime doesn't control what the OS or C code does in the background. These calls are not considered durably blocking.

Package-level sync.WaitGroup (var wg sync.WaitGroup). These can't be associated with a bubble. Declare them inside the test function instead.

Ideal use cases: timers, tickers, debounce, rate limiters, TTL caches, retry with backoff — anything that chains time.After, time.Sleep, or time.AfterFunc with goroutines communicating over channels.

Conclusion

go test -race remains the right tool for real data races. testing/synctest targets a different class of failure: tests whose reliability depends on wall-clock timing. The two tools are orthogonal — use both.

If you have time.Sleep in your Go tests to "give the goroutine time to finish," that's the signal. testing/synctest will do the job faster and correctly. Go 1.25 has been out since August 2025 — no flags, no configuration, just import it.

📚 Related reading. If goroutines that never exit are your problem, the natural follow-up is Goroutine leaks in Go: detect, understand, fix.

39,000 Torrents: The Bug My Green Benchmark Never Caught

Odilon HUGONNOT — Sat, 25 Jul 2026 09:00:02 +0000

[Torrent911] Inception.2010.TRUEFRENCH.1080p.BluRay.x264-YIFY

That's a real filename. The goal: extract "Inception" and "2010" from it, query the TMDB API (The Movie Database, the open reference for film and TV metadata), and display the right card. Poster, rating, synopsis. Automatically, for a library of a few hundred files.

Context: a self-hosted PHP media server. Think Plex, but lighter, no cloud, no account. The interface looks vaguely like Netflix. The hard part is automatic recognition. Torrent release names follow no formal standard: [Torrent911] can come before the title, TRUEFRENCH can interrupt it, a release group trails at the end. Films have a year. TV shows almost never do. Popular anime have episode numbers with four digits: One.Piece.S01E1164.VOSTFR.

I had accumulated 39,188 real torrent names over the years: 22,058 films, 17,130 series. Enough to build an honest test bench. I used an AI assistant to replay variants quickly and analyze where the metrics leaked.

Two things happened. First, a clean data-driven optimization: measure, iterate, stop at the right time. Then, a classic trap: the benchmark was green while a silent bug turned every single TV show into a film match.

Two different lessons about what data measures — and what it doesn't.

A minefield inside a string

The pipeline has two distinct stages.

Stage one: extract a clean title and a year from the filename. This is the foundation. If it returns "Inception 1080p BluRay x264" instead of "Inception", TMDB finds nothing useful. Release naming puts the title first and technical metadata after, but the variations are endless: site prefixes ([Torrent911]), language tags (VOSTFR, TRUEFRENCH), codec (x264, H.265), resolution (1080p, 4K), release groups.

Stage two: query TMDB with the extracted title and pick the right result. A search for "Breaking Bad" returns dozens of results, including films and documentaries with the same name. You have to score and decide.

Three metrics to measure extraction quality: cleanliness (% of titles with no residual technical tag — a stray 1080p, WEB-DL, or S01E02 that should have been stripped), coverage (% of non-empty titles), and year recall (how often the year is correctly extracted). Cleanliness is the main metric. A "dirty" title produces false positives or zero results on TMDB. Coverage was already near 100% from V0.

V0 → V4: measure before you optimize

The test bench is entirely offline. It replays the extraction algorithm on all 39,188 corpus filenames, computes the metrics, and returns a report in a few seconds. Deterministic, 100% replayable, no network calls. This is where the AI assistant genuinely helps: building the bench, writing the variants, analyzing the 65 remaining leaks to find patterns. Not "the AI optimized the algorithm" — more like "the AI let me iterate five times in one hour".

Version

Approach

Cleanliness

Leaks

V0 — naive

Separator normalization only (. and _ → space)

10.84%

34,939

V1 — basic

Strip 8 known tags (1080p, BluRay…)

50.23%

19,492

V2 — cut at 1st tag

Truncate at the first technical marker found

99.83%

V3 — episode fix

Extended episode pattern to 3-4 digits (\d{0,4})

99.93%

V4 — experimental

Article normalization, bracket-rescue…

99.93%

V0 applies basic separator normalization. 10.84% cleanliness, 34,939 leaks. Catastrophic baseline, but that's the honest starting point.

V1 strips 8 known technical tags. 50%. The corpus has far more than eight conventions. This approach doesn't scale: every site and every release group has its own patterns.

V2 introduces the central idea: don't try to enumerate all known tags, just truncate at the first technical marker found. Release naming places the title at the start and technical metadata after. Cutting at the first tag brings cleanliness from 10.84% to 99.83%. 65 leaks remain across 39,000 names. This single shift in approach delivers 99% of the total gain.

// Step 1 — bracket prefixes are stripped first, no enumeration needed:
// [Torrent911], [HorribleSubs], [FW]... one pattern covers them all.
$clean = preg_replace('/\[.*?\]/', '', $clean);
$clean = preg_replace('/[._()[\]{}:]+/', ' ', $clean);

// Step 2 — everything after (and including) the first technical marker is discarded.
// This is what takes cleanliness from 10.8% to 99.8%.
$title = preg_replace(
    '/\b(multi|vff|truefrench|french|vostfr|bluray|web-?dl|hdtv|x264|x265|hevc'
  . '|10bit|remux|2160p|1080p|720p|480p|uhd|hdr|dts|aac|ac3|proper|repack'
  . '|extended|directors?-?cut|complete|s\d{1,2}e?\d{0,4}|e\d{2,4})\b.*/i',
    '', $clean
);
// s\d{1,2}e?\d{0,4}: the {0,4} (instead of {0,2}) catches 3-4 digit episodes
// (One Piece S01E1164, Plus Belle La Vie S12E248) — found by analyzing 39,000 torrents.

V3 fixes a case revealed by analyzing the 65 remaining leaks. Three and four digit episode numbers weren't captured: S01E1164 for One Piece, S12E248 for Plus Belle La Vie. One change in the regex (\d{0,2} → \d{0,4}) cuts the leak count in half, from 65 to 28. You can't guess this by looking at ten examples manually. The corpus forces it to appear in the statistics.

V4 tests more aggressive normalization. Result: 29 leaks — one more than V3. The data says stop. Adding complexity to regress is a no.

Extracted title cleanliness V0 to V4 — from 10% to 99.9% Extracted title cleanliness (% with no residual technical tag) 10.84% V0 naive 34,939 leaks 50.23% V1 basic cut 19,492 leaks 99.83% V2 cut at 1st tag 65 leaks 99.93% V3 + episode fix 28 leaks 99.93% V4 experimental 29 leaks

V2 (truncate at the first technical tag) delivers 99% of the gain. V3 halves the remaining leaks with a single regex character change.

Three lessons from this part.

The big lever was binary. Going from "keep everything" to "cut at the first technical tag": 10.8% → 99.8% cleanliness in one idea. Refinement (V3, V4) comes after, not before.

Large-scale data finds what the eye can't see. Without 39,000 examples, four-digit episode numbers stay invisible. The corpus forces them into the statistics.

Know when to stop. V4 is more complex and slightly worse than V3. YAGNI proven by data, not assumed.

TMDB matching and the premature optimization

Extracting a clean title is half the work. The other half: query TMDB and pick the right result from the candidates.

The scoring combines several signals. Title similarity counts for 65% (normalized comparison across all title variants). Year gap: 15%. Type coherence (film or TV): 10 to 18% depending on confidence. TMDB popularity (vote count): 12%, so obscure namesakes lose to well-known titles. Above 55: strong match. Between 35 and 55: quarantine for manual review. Below: rejected.

When the exact query doesn't produce a good result, the algorithm shortens it word by word until the confidence threshold is reached. A title with unusual punctuation may not match directly: we drop words from the end one at a time and keep the longest query that clears the threshold.

// Releases often append a subtitle or language tag after the actual title.
// Drop words FROM THE END, one at a time; keep the LONGEST query that clears
// the confidence threshold (55). The title is always at the start.
$words    = explode(' ', trim($title));
$minWords = max(1, count($words) - 4);   // at most 5 tries
$best = null; $bestScore = 0;
for ($n = count($words); $n >= $minWords; $n--) {
    $query = implode(' ', array_slice($words, 0, $n));
    foreach (tmdb_search($query, $year, $preferTv) as $cand) {
        $score = score_candidate($query, $year, $cand, $preferTv);
        if ($score > $bestScore) { $bestScore = $score; $best = $cand; }
    }
    if ($bestScore >= 55) break; // reliable match → stop truncating
}

This handles cases like "Avengers: Age of Ultron" (the colon disappears during cleanup) or foreign-language titles that don't match the English filename. Each iteration costs an API call, but avoids zero-match on titles with punctuation or special characters.

This is where an "optimization" had quietly slipped into the code. The variable $preferTv was supposed to signal to TMDB to prioritize TV results. To save API calls, I'd set the algorithm to query the "probable" type first (movie by default, unless the filename explicitly looked like a series), and only query tv if there were no candidates at all. The network test bench showed flattering numbers: 90% match rate for films, 96.7% for series.

I navigated it in real conditions. Every single TV show matched a film.

Breaking Bad → Breaking Bad Wolf (an indie film with the same name)
Game of Thrones → Game of Thrones: The Last Watch (an HBO documentary)
The Mandalorian → The Mandalorian and Grogu (an upcoming film)
One Piece → One Piece: Gold (a feature film)

0 correct out of 11 series.

Why the benchmark was showing green

The offline bench only measured extraction. Fair enough, that's its scope. It knew nothing about matching.

The network bench, though, provided the content type (movie or tv) directly from the known category of each corpus entry. It passed $preferTv = true for series directly. It never exercised the automatic type detection, because it didn't need to: the right answer was already baked into the request parameters. The auto-detection that ran in production had never been tested. The aggregate metric was green on a path that real navigation never took.

A benchmark tests what you tell it to test. Its blind spots are silent.

Before and after the fix: film/TV type detection for TMDB matching BEFORE « Breaking Bad » type = movie (auto-guessed) TMDB: movies only Breaking Bad Wolf ✗ false positive AFTER « Breaking Bad » movie + tv in parallel scoring picks by popularity Breaking Bad (TV series) ✓ correct match

The "save an API call" optimization removed tv from the circuit. Scoring can't choose between two types if it only sees one.

The fix: four levers

1. Always query both types.

Movie and tv are now queried every time. Scoring decides. Breaking Bad (TV series on TMDB, high popularity) beats any obscure namesake film on popularity score alone. This was the central regression: saving one API call had broken the selection logic. The fix is literally removing the condition that blocked the second type.

2. Folder structure as a signal.

Parsing the filename to guess film or series is fragile. A show organized in seasons — "Show/Season 1/", "Show/01/", "Show/02/" — may have no S01E01 in its folder name at all. The folder structure doesn't lie.

// A folder is a SERIES if it has multiple episodes (≥ 2 videos at top level)
// OR numbered season subdirectories (Season 1, Saison 3, 01, 02…).
// A film has a single video file. Folder SHAPE beats parsing the filename.
$videoCount = 0; $seasonish = 0;
foreach (scandir($folder) as $sub) {
    if ($sub[0] === '.') continue;
    if (is_dir("$folder/$sub")) {
        if (preg_match('/^(s\d{1,2}\b|saison|season|saga|arc|part|\d{1,3}$)/i', $sub))
            $seasonish++;
    } elseif (in_array(strtolower(pathinfo($sub, PATHINFO_EXTENSION)), $VIDEO_EXTS, true)) {
        $videoCount++;
    }
}
$isSeries = ($videoCount >= 2 || $seasonish >= 1);

This signal is used to weight the type coherence bonus in the score. It doesn't replace querying both types; it refines the decision.

3. Multilingual title merging.

TMDB returns multiple title variants per result: original, local, alternative. When you search for "Attack on Titan", TMDB may return "L'Attaque des Titans" (French) and "Shingeki no Kyojin" (Japanese). Deduplication by ID was keeping only the first title encountered: low similarity with the English query, potentially missed match.

Fix: aggregate all title variants by ID and score against the best one. Unexpected bonus: Spirited Away went from a weak match to a strong match, because "Sen to Chihiro no Kamikakushi" (the Japanese original title) was already in TMDB data and contributed to the similarity score.

4. Reinforced type coherence bonus.

When the folder structure clearly confirms a series (numbered subdirectories, dozens of video files), the tv type bonus in the score goes from 10% to 18%. The structural signal amplifies the scoring decision without overriding it.

Result: 11 series and anime matched correctly at high confidence, 18 films stay films. 0 → 11 on series.

Full source code

ShareBox is open source. The algorithm described in this article lives in functions.php: extract_title_year() (extraction), tmdb_match() (word-removal loop), tmdb_score_candidate() (scoring).

Conclusion

The large-scale data brilliantly optimized extraction. From 10.8% to 99.9% cleanliness in three measured iterations, across 39,000 names. The corpus surfaced a blind spot (S01E1164) no human would test manually, and it said stop when a more complex variant regressed by one unit.

The matching failed differently. An API cost optimization caused a regression invisible to the aggregate metrics, because the benchmark was feeding itself the right answer. Thirty seconds of real navigation found what a 96.7% success rate had hidden.

The real lesson: data optimizes brilliantly what it measures. A benchmark measures one path. It doesn't know others exist. The aggregate metric was an honest indicator; it wasn't a complete one. Testing in real conditions stays irreplaceable, even when everything is green.

Mathematics describes reality with absurd precision. Nobody really knows why.

Odilon HUGONNOT — Fri, 24 Jul 2026 09:00:02 +0000

In 1865, James Clerk Maxwell was reviewing his own equations. They described electricity and magnetism, two phenomena physicists of the time still treated as separate. Combining them, a number fell out of the calculation: the speed at which his theoretical electromagnetic waves would propagate was approximately 310,000 km/s.

That was also, within experimental uncertainty, the speed of light measured by Fizeau sixteen years earlier.

Maxwell drew the obvious conclusion: light is an electromagnetic wave. No experiment, no sensor — just symbols on paper. Hertz would confirm it experimentally in 1888, twenty-three years later.

This kind of moment repeats throughout the history of science with an unsettling regularity. Mathematics developed for entirely abstract reasons ends up describing physical reality with a precision that has no business existing. In 1960, physicist Eugene Wigner gave the phenomenon a name. He called it "the unreasonable effectiveness of mathematics in the natural sciences." And he was honest enough to admit he had no explanation.

Galileo raised the question, without the answer

In 1623, Galileo published Il Saggiatore, a scientific polemic responding to a Jesuit who disputed his work on comets. In passing, he slipped in an idea that would travel four centuries:

"The book of natural philosophy is perpetually open before our eyes, but it is written in characters different from those of our alphabet: triangles, squares, circles, spheres, cones, pyramids and other geometric figures."

This is intuition, not proof. Galileo did not demonstrate that nature is mathematical. He sensed it, stated it, and went back to his comets. In 1623, differential equations did not yet exist. Quantum mechanics, mathematical biology — nobody had the tools to verify it.

What is striking is that he was right without being able to know it. That kind of prophecy draws its value entirely from what came after.

The list that makes your head spin

Four examples. Any one of them could have passed for coincidence. Together they form a pattern.

Maxwell (1865). Four equations unifying electricity and magnetism. Combining them, Maxwell derived the speed of an electromagnetic wave: c = 1/√(ε₀μ₀) ≈ 300,000 km/s. That matched the speed of light measured by Fizeau in 1849. Maxwell concluded that light is an electromagnetic wave. Hertz confirmed it experimentally in 1888, twenty-three years later.

Schrödinger (1926). The equation describing the evolution of a quantum system predicted the energy levels of the hydrogen atom with a precision the instruments of the time could not yet reach. Troubling detail: the wave function is inherently complex. Not a computational shortcut where you take the real part at the end. Complex numbers are in the foundations of quantum mechanics. Remove them and you have no quantum mechanics.

Hodgkin and Huxley (1952). Five differential equations to model the action potential of a neuron, based on measurements from the giant squid axon. They predicted the exact shape of the electrical spike a neuron produces, including details that the instruments of the time could not yet resolve. The model was right before the equipment existed to verify it. Nobel Prize in physiology, 1963.

Lotka and Volterra (1925–1926). Alfred Lotka published his equations in 1925 to describe oscillations in chemical reactions. Vito Volterra independently rediscovered them in 1926, prompted by his son-in-law, a biologist trying to explain oscillations of predator and prey fish populations in the Adriatic: World War I had reduced fishing, predators had multiplied, then prey had bounced back. Two people who did not know each other, working on different problems, arriving at the same equations.

Complex numbers: the most troubling case

In 1545, Gerolamo Cardano published Ars Magna. Solving cubic equations, he encountered square roots of negative numbers. He manipulated them — it worked algebraically — but called them "subtle as they are useless." In 1572, Rafael Bombelli systematized their rules in Algebra and showed that you could find real roots of cubic equations by passing through imaginary territory.

For about three hundred and fifty years, complex numbers were an abstract algebraic tool. Elegant, useful for certain calculations, but with no connection to physical reality. Physicists sometimes used them as a computational shortcut, but "at the end you take the real part" — the physical world stayed real.

In 1926, Schrödinger wrote his equation. The wave function is intrinsically complex. Not a shortcut: complex numbers are in the foundations of quantum mechanics. Remove them, you have no quantum mechanics.

Three hundred and eighty-one years between the "useless" invention and the indispensable application.

Gap between mathematical invention and physical application: complex numbers (381 years), Riemannian geometry (61 years), Maxwell's equations (23 years) MATHEMATICS PHYSICS Complex numbers Cardano, 1545 381 years Quantum mechanics Schrödinger, 1926 Riemannian geometry Riemann, 1854 61 years General relativity Einstein, 1915 Maxwell's equations Maxwell, 1865 23 years Hertz confirmation Hertz, 1888

Math invented for abstract reasons, decades or centuries before becoming essential in physics.

Riemannian geometry is worth noting here. In 1854, Bernhard Riemann developed an abstract theory of curved spaces in his Habilitation lecture at Göttingen. No physical application in sight. In 1915, Einstein used it as the language of general relativity. Sixty-one years.

Wigner names the unease (1960)

Eugene Wigner, a Hungarian-born American physicist, delivered a lecture at NYU in 1959, published the following year in Communications in Pure and Applied Mathematics under the title "The Unreasonable Effectiveness of Mathematics in the Natural Sciences."

The paper opens with an anecdote: two former high school classmates run into each other. One became a statistician. He shows the other an article on population trends. The other points to a curve and asks what that symbol represents. "The Gaussian distribution, the bell curve." "But we're in population statistics — what does this have to do with pi?" The statistician shrugs.

Wigner builds the argument rigorously, example after example, and concludes:

"The miracle of the appropriateness of the language of mathematics for the formulation of the laws of physics is a wonderful gift which we neither understand nor deserve."

What is remarkable about this text is its honesty. Wigner does not propose an explanation. He names the phenomenon, documents it, and admits he does not understand it.

Three answers, none satisfying

Since 1960, responses have accumulated. None closes the debate.

The universe is mathematics (Tegmark, 2014). In Our Mathematical Universe, physicist Max Tegmark pushes the idea to its limit: physical reality is not described by a mathematical structure, it is one. Every consistent mathematical structure exists physically somewhere in a mathematical multiverse. It is elegant. It is also unfalsifiable by construction, which makes it as much a philosophical position as a scientific one.

It is survivorship bias (Hamming, 1980). Richard Hamming, in an article in the American Mathematical Monthly, turns the argument around: we only notice the math that works. Thousands of mathematical structures are developed without ever finding physical application. We select the mathematics to fit the problem, then present it as a miraculous coincidence. That is a genuine partial refutation. It does not account for complex numbers in quantum mechanics: there, the math does not "fit" the problem — it is the only language in which the problem can be written at all.

It is evolution (anthropic argument). Our brain evolved to model the physical world. That the abstract structures it produces should fit that same world is perhaps not so surprising. This is the most sober explanation. It does not account for math developed in an algebraic ivory tower that turns out to be indispensable in physics three centuries later.

It is a genuine mystery (Wigner, Penrose). Wigner himself, and Roger Penrose after him in The Road to Reality (2004), maintain that the correspondence is too precise, too repeated, too deep to be an artifact. There is something here we do not understand. That is not a mystical position — it is honesty about the state of the question.

Conclusion

What struck me digging into this is that the mystery is already in our code.

Big O is an abstract mathematical structure. Floating point rests on binary mantissas and exponents, and its quirks (0.1 + 0.2 !== 0.3) come directly from infinite fractions in base 2. Public key cryptography rests on properties of prime numbers that eighteenth-century mathematicians were studying out of pure curiosity. Artificial neural networks are linear algebra on matrices, nothing more.

We use structures every day whose effectiveness at describing reality has no definitive explanation. We have just learned to stop finding that strange.

Galileo had the intuition in 1623. Wigner named the problem in 1960. In 2026, the question remains open.

My Claude Code Skills in Production: What the Audit Taught Me

Odilon HUGONNOT — Thu, 23 Jul 2026 09:00:01 +0000

A Claude Code skill is a Markdown file you drop into ~/.claude/skills/. It describes a complete workflow: when to trigger it, how to execute it step by step, what it should produce. Claude reads it at the right moment and follows it. No manual command, no copy-pasted prompt. You say "publish this article" and the skill chains the checks, image generation, commit, deploy, and LinkedIn draft on its own.

I have nine in production on this site. Eight work well. One is problematic. And that one is the most interesting to analyze.

Nine skills, nine domains

To understand what follows, here's what my nine skills do. Each covers a specific domain of my workflow:

blog-article: write and publish an article (FR + EN, OG image, deploy, LinkedIn, dev.to)
blog-fix: fix a typo or bug on an already-published article without relaunching everything
fiche-livre: read a technical book PDF and produce a complete book review (summary, 5-axis radar, SVG diagrams, bilingual)
outil-factory: create or iterate on a free web tool (/outils/), with radar scoring and Playwright tests
veille-debug: diagnose bugs in the automated tech watch system (AI article generation, cron, registry)
vide-contexte: extract non-obvious insights from the current session to persistent memory before clearing context
deep-research: launch a multi-source search with adversarial verification and cited synthesis
frontend-design: visual direction guide to avoid producing generic Bootstrap output
feature-loop: manage the full feature cycle (spec, implementation, review, tests, merge)

Eight work cleanly. The ninth, feature-loop, clocks in at 1,002 lines and roughly 25,000 tokens. That's the one a recent audit put under the microscope.

What a skills audit actually looks at

Auditing a skill means measuring four things: raw length (lines, tokens), structure (body versus on-demand reference files), the density of urgency markers in the text, and what remains visible in long context, when Claude is on iteration 3 of a loaded session.

On the eight healthy skills, the numbers are clear: between 70 and 257 lines, 1,000 to 7,700 tokens, simple structure. feature-loop stands alone: 1,002 lines, 25,000 tokens, and text saturated with NON-NEGOTIABLE / NEVER / MANDATORY / LOCKED at every paragraph.

The diagnosis fits in one sentence: when everything is critical, nothing is.

Salience dilution

When Claude loads a skill, it loads the entire body. Everything in there competes for the model's attention. If ten rules are all marked MANDATORY, the model has no way to decide which one to prioritize when there's a conflict or a context constraint. It doesn't arbitrate: it averages. And averaging ten MANDATORY rules gives zero clear priority.

The invariants that actually change behavior — the ones that break the workflow if forgotten — drown in token micro-optimizations and design justifications. Result: the most important rules are followed with the same reliability as the least important. Which is: not always.

On the eight healthy skills, critical rules fit in ten lines maximum. The rest is either absent or in reference files loaded at the step that needs them.

The silent drift in long context

A skill loads at trigger time. But a work session accumulates: file reads, tool outputs, exchanges, iterations. By iteration 3 of a complex feature, feature-loop's SKILL.md is buried under thousands of tokens of accumulated context.

The rules at the top of the file, Claude still sees. The ones on page 8, less so. This isn't a bug. It's the physics of attention: a language model gives more weight to recent tokens and to tokens at the beginning of context. What's in the middle of a 25,000-token file, buried under tool outputs, is structurally less well processed.

The fix isn't to move everything to the top. It's to extract what doesn't belong in the body: design justifications, complete examples, 50-line bash recipes. Those belong in a references/ file loaded at the exact step that needs them. The skill body stays an execution contract, not an encyclopedia.

What distinguishes the skills that hold

The eight healthy skills share two characteristics that aren't obvious at first glance.

The description is a trigger, not a summary. Each skill has a frontmatter with a short description. That's what Claude reads to decide whether to invoke it. A description that summarizes the skill ("this skill creates book reviews") is less effective than one that lists concrete situations ("trigger on: 'book review', 'summarize this book', a book PDF provided"). The first says what the skill is. The second says when to call it — which is the only thing that matters at trigger time.

The body trusts the model. Short skills don't over-specify. They give the contract (goal, output format, critical steps) and let Claude reason about the rest. An 80-line well-structured skill outperforms a 400-line over-specified one, because every one of those 80 lines has value and the model can hold them all in mind simultaneously. Over-specification is usually codified mistrust. And mistrust in 400 lines produces a skill even Claude can't follow.

The public repo: six installable skills

I extracted six of my skills into a public repo: github.com/ohugonnot/claude-skills.

Six skills available, organized as a pipeline:

issue-mr: turn a vague idea into a well-formed issue, branch, and MR/PR shell
feature-loop: autonomous quality-gated loop — writer, test-writer, and reviewer are separate agents
senior-review: senior-level review by dimension (correctness, security, design, tests), blind reviewers
branch-wrap-up: clean branch close-out (conventional commit, push, memory capture)
book-distill: read a PDF and produce a verified reading note, citations checked word for word
vide-contexte: extract non-deducible session insights to persistent memory before /clear

Installation via the Claude Code marketplace in one line, or manually with a symlink:

# Via marketplace (recommended)
/plugin marketplace add ohugonnot/claude-skills
/plugin install feature-loop@web-developpeur-skills

# Or manually
git clone https://github.com/ohugonnot/claude-skills.git ~/claude-skills
ln -s ~/claude-skills/plugins/vide-contexte/skills/vide-contexte ~/.claude/skills/vide-contexte

Publishing these skills changed how I write them. A skill for personal use can lean on implicit context: project conventions, file structure, things I know without writing them. A public skill must work cold, on an unknown project, without a local CLAUDE.md. That constraint forces you to make explicit everything that was tacit. And an explicit skill is a better skill, even for personal use.

The search engine that changes discovery

The real problem with skills isn't writing them. It's discovery. If you have twenty skills spread across sub-folders, knowing which one to call for a given need becomes a problem in itself. The natural reflex is to type the skill name, but you still need to remember the name.

Claude Code now has a keyword-based skill search. Instead of memorizing the exact list, you can search by domain or intent: "something to publish an article", "a research skill", "to clean up context". The engine returns skills whose description matches.

This mechanism changes how you write descriptions. If that's what gets indexed, the description must contain the words users will type when searching — not the internal terms you use to name the concept. The difference is subtle but real: "clean context before /clear" triggers on "empty the context", "save before clear", "extract the session". A description oriented toward searched usage, not technical definition.

Conclusion

The real lesson from the audit isn't in the list of rules. It's in the gap between feature-loop and the other eight. A skill that's too long doesn't break because it's unreadable. It breaks because it dilutes: critical rules drown in noise, and the model no longer has a way to know which ones deserve priority attention.

A skill body isn't an exhaustive source of truth. It's an execution contract. The cleaner it is, the better it holds when context accumulates. Anything not strictly necessary for execution belongs elsewhere: in a reference file, in a script, or nowhere.

🧩 Installable skills

The five public skills are available at github.com/ohugonnot/claude-skills. For writing patterns from Anthropic's 17 official skills, see The rule vs the practice.

Claude Code's 17 Official Skills: the Rule vs the Practice

Odilon HUGONNOT — Wed, 22 Jul 2026 09:00:03 +0000

Anthropic's docs are clear: a SKILL.md should be under 500 lines. Their own docx skill is 590. I read all 17 of Anthropic's official skills, frontmatter by frontmatter, while building my own marketplace alongside. Every time, the same gap: the docs say one thing, the corpus does another. And the corpus is the one that's right.

Here's what actually comes out when you read the code instead of the docs.

The description is 90% of the skill

A skill is useless if it doesn't trigger at the right moment. And what decides triggering isn't the body of the SKILL.md, it's its description in the frontmatter. Claude reads the list of available skills (just name + description) and picks. So all of the "when to use it" must live in the description, not the body.

The counter-intuitive part, which Anthropic repeats in its own skill-creator: Claude under-triggers skills far more than it over-triggers them. It only consults a skill for a task it can't handle trivially. "Read this PDF" will never fire the PDF skill, even with a perfect description. Hence an explicit instruction: write descriptions that are a little pushy.

You see it in the code: the xlsx skill says "Use this skill any time a spreadsheet file is the primary input or output", pptx says "any time a .pptx is involved in any way". No shyness. You push triggering, you don't hold it back.

The 500-line rule nobody follows

"Keep the SKILL.md under 500 lines" is one of the most quoted rules. In practice, docx is 590 lines, and the docs themselves add "feel free to go longer if needed". The others range from 32 to 404. The truth: 500 is a target, not a law.

The real principle behind it isn't length, it's the context budget. The SKILL.md body loads on every trigger. If it's big because it holds the essentials, fine, go over. If it's big because it drags along detail that could live elsewhere, that's the fault. Size alone isn't the sin.

Progressive disclosure: mostly scripts, rarely references

The central skill pattern is staged loading: metadata (name + description) always in context, the body loaded on trigger, and resources (scripts/, references/) only on demand. A script can even execute without being loaded into context.

Except that in the corpus, 11 skills out of 17 are a single SKILL.md, with no subfolder at all. Splitting isn't the norm, it's the exception you reach for when the domain warrants it. And when you do split, it's mostly scripts/: pdf, docx, xlsx, pptx are first and foremost script boxes for deterministic operations. The references/ (docs loaded on demand) appear on only two skills. The lesson: pull the deterministic stuff into executable code long before you pull prose into a side file.

The "NOT for" Anthropic never writes

Writing my own skills, I systematically added a "NOT for X" clause to the description, to avoid false triggers. Reading the official ones, surprise: they almost never do it. Their descriptions list inclusions ("this includes…"), not exclusions.

The reason fits in one word: their domains don't overlap. The PDF skill and the Excel skill can't be confused, so no exclusion is needed, and they'd rather maximize triggering. My case is different: my skills touch each other (reviewing a diff, shipping a feature, wrapping up a branch are adjacent). The "NOT for" lets me disambiguate between my own skills. So it isn't a universal rule, it's a response to overlap. If your skills don't compete, don't add it: you'd only reduce your triggering, the worst flaw of all.

How they actually optimize a description

The most instructive part of the official skill-creator is that they don't guess a good description, they measure it. The protocol, unrolled:

20 eval queries: 8-10 that should trigger, 8-10 that shouldn't. Realistic and messy, the way a real user would type (file paths, personal context, typos, lowercase).
The negatives are near-misses, not obvious ones. "Write a fibonacci function" as a negative for a PDF skill tests nothing. Good negatives share keywords with the skill but need something else.
Each query run 3 times for a reliable trigger rate, then an improvement loop over 5 iterations.
You pick the description by its score on a held-out test set (60% train, 40% test), so you don't overfit the queries you already know.

It's an eval pipeline, not a finger in the air. Most people write a description by feel and move on. Anthropic treats it as the product.

At a glance: the assumption vs the practice

The gap, row by row, across the 17 official skills:

The common assumption

What the official corpus does

A SKILL.md is under 500 lines

docx is 590, and the docs add "go longer if needed"

The description just says when to use the skill

It must be pushy: the real risk is under-triggering

You split into references/ and scripts/ (progressive disclosure)

11 of 17 skills are a single file; when you split, mostly scripts/

You restrict the description ("NOT for") to avoid false triggers

Almost never written: distinct domains, they maximize triggering

A good description is written by feel

It's measured: 20 queries, each run 3 times, a 5-iteration loop, scored on a held-out test set

What to remember

The real lesson isn't in the list of rules, it's in the gap. The docs give clean heuristics; the corpus shows how competent people bend them when the ground demands it. Reading the 17 skills teaches more than reading the doc page, because you see the real trade-offs: going past 500 lines when the content deserves it, skipping the split two-thirds of the time, pushing triggering rather than restricting it.

If you keep one thing: the risk isn't that your skill triggers too much, it's that it doesn't trigger at all. Write the description to be found.

🧩 My skills, installable

I built a marketplace of Claude Code skills from my real workflow, applying these patterns. Browse and install them on the Skills page, including a skill-builder skill that condenses these principles. To frame an agent, see also the CLAUDE.md contexts.

Frequently asked questions

How many lines should a SKILL.md be?

Aim for under 500, but it's not a law: the official docx skill is 590. What matters is that the body doesn't drag detail that should live in a script or a reference file. Go over if the essential content warrants it, then add pointers to side files.

Why doesn't my skill trigger?

Almost always the description. Claude under-triggers by default and only consults a skill for a non-trivial task. Make the description more inclusive and "pushy" ("use this skill whenever… even if the user doesn't say…"), with real trigger phrases. And test: a one-step task will never trigger a skill, and that's normal.

Do I need references/ and scripts/ folders?

Not by default: 11 of the 17 official skills are a single SKILL.md. You split when the domain is heavy, and then mostly into scripts/ for deterministic work (file manipulation, validation). references/ only earns its place for large multi-variant domains.

Skill, CLAUDE.md or hook?

Skill = a capability triggered by its description when the situation calls for it. CLAUDE.md = context always loaded for a specific project. Hook = deterministic automation on an event, enforced by the harness, not the model. If it's "always do X", it's a hook or a CLAUDE.md, not a skill.

Event Sourcing and CQRS: A Practical Guide for Developers

Odilon HUGONNOT — Tue, 21 Jul 2026 09:00:07 +0000

The accountant walks up to your desk. "This account shows 150 dollars. Why?" You open the database, you look at the balance column. It says 150. That's all it can say. The twenty operations that led to that number? Overwritten, one by one, on every UPDATE. You can't answer.

That's the problem Event Sourcing solves. And CQRS is the companion that makes it usable day to day. These two words sound scary, we associate them with Kafka, microservices and unicorn architectures. The reality is simpler, and more useful. This guide lays out the mental model, says when these patterns are worth it (and when they're not), then traces a concrete implementation path in Go with PostgreSQL.

Event Sourcing in one sentence

Instead of storing the current state of a piece of data, you store every event that led to that state. The current state is recomputed by replaying the events in order.

A bank account is no longer a balance = 150 row. It's a list: Credited(200), Debited(70), Credited(20). The balance is the result of a computation, not a stored value. You've lost nothing, because you never overwrite anything. You only ever append.

// CRUD: you store the result. The history is overwritten.
account := Account{Balance: 150}

// Event Sourcing: you store the facts. The balance is recomputed.
events := []Event{Credited{200}, Debited{70}, Credited{20}}
balance := replay(events) // 150, rebuilt from the start

An event is a past fact, immutable, named in the past tense: OrderPlaced, PaymentConfirmed, AccountDebited. Once written, it never changes. That single decision shapes everything else.

CQRS in one sentence

You separate write operations (the commands, which change state) from read operations (the queries, which read state). Two paths, two models.

CQRS and Event Sourcing are two independent patterns. You can do CQRS without Event Sourcing, and the other way around. But in production they almost always go together: the write side produces events, and the read side serves from views computed off those events. The write model protects the business rules, the read model is optimized to be read fast.

The three real wins

You don't adopt Event Sourcing to look modern. You adopt it for three concrete things, and if none of them speaks to you, move on.

A free, immutable audit log. Every change is a timestamped event you never overwrite. In fintech, in healthcare, anywhere a regulator can ask "who did what, when", this is the argument that justifies everything else.
Temporal queries. "What was the balance last Tuesday at 2pm?" becomes trivial: you replay the events up to that date. With a CRUD table, that question is impossible to answer.
Rebuilding. A corrupted projection, a bug in a read view? You throw it away and recompute it from the events. The source of truth is intact by construction.

When NOT to use Event Sourcing

This is the section tutorials forget. Event Sourcing has a real cost: more code, a different mental model, a team to train. For most applications, a plain old CRUD with an audit table is more than enough.

Avoid Event Sourcing if your domain is a simple form that saves rows, if history doesn't interest you, if nobody will ever ask you "and before?", or if the team is discovering the topic on a project already under pressure. The pattern shines on domains where the history IS the data: accounts, payments, inventory, bookings, complex business workflows. Elsewhere, it adds friction without paying off.

The complete mental model

Three building blocks are enough to understand everything. Once they're clear, the rest is just implementation.

The aggregate is the guardian of business consistency. It's the one that says "no" when an operation is invalid (an account doesn't go below zero, an already-shipped order can't be cancelled). In Event Sourcing, the aggregate has no directly persisted state: its state is the result of replaying all its events from the beginning.

The command is an intent ("debit this account by 70"). It goes through the aggregate, which validates, and which produces one or more events if it's allowed, or an error if it isn't. Never both.

The projection is a view computed from the events. "The balance of every account" is a projection. "The list of pending orders" is another. These are what your queries read, and you can throw them away and recompute them at will.

The implementation path, and where to dig deeper

I've written a series of articles that take each block in hand, with real, tested Go code. Here's the order that makes sense for learning, from the mental model to production.

The starting point: understanding why writes must be serialized per aggregate while reads can be massively parallel, in concurrency vs parallelism in Go applied to Event Sourcing. It's also the article that defines the concepts with no prerequisites.
The aggregate: the Transition() function that replays events, and the Clone() trap Go makes you forget (slices share their backing array and silently corrupt old states), in CQRS in Go: the aggregate, Transition() and Clone().
The command handler: the Handle(ctx, state, cmd) (Events, error) signature that makes business logic testable without mocks or a database, in side-effect-free command handlers.
Storage: why PostgreSQL is enough as an event store, with an append-only table and optimistic locking via UNIQUE(aggregate_id, version), in PostgreSQL as an event store.
Multiple aggregates cooperating: event choreography over a central orchestrator, and sagas, in sagas and event choreography.
Reliability against duplicates: the idempotency key for retries and double-clicks, then the four idempotency layers of a complete CQRS system, in the basics of idempotency then commands, projections and outbox.
The advanced case: how to return a synchronous result to the HTTP client in an asynchronous system, and keep a consistent audit log, in the pubsub bridge and atomic audit.

The minimal stack that's enough

The biggest trap in Event Sourcing isn't the concept, it's over-engineering. You get sold Kafka, EventStoreDB, a distributed message bus and three brokers before you even have a single aggregate that works.

For 90% of projects, PostgreSQL alone does all the work. An append-only table for events, a UNIQUE constraint to handle concurrency, polling or LISTEN/NOTIFY for projections. Snapshots and an outbox to a broker only arrive when a real volume or integration problem demands them, not before. Start small. You'll add infrastructure the day the pain is real.

What to remember

Event Sourcing and CQRS aren't an architecture you adopt wholesale because it's fashionable. They're tools for a specific problem: when the history of your data matters as much as its current state. If a regulator, an accountant or a production bug might one day ask you "and before?", they're worth their cost.

The right first step isn't to re-architect everything. It's to take a single aggregate that matters (an account, an order, a wallet), model it as events on a PostgreSQL table, and see what changes. The rest follows, block by block.

Frequently asked questions

What's the difference between Event Sourcing and CQRS?

Event Sourcing describes how you store data: a sequence of immutable events rather than the current state. CQRS describes how you organize code: one path to write (commands), another to read (queries). They're two independent patterns, but in production you almost always combine them, because one feeds the other.

Do you need Kafka or EventStoreDB for Event Sourcing?

No. For the vast majority of projects, PostgreSQL is enough: an append-only table, a uniqueness constraint for concurrency, polling or LISTEN/NOTIFY for projections. Kafka and dedicated event stores answer specific volume or integration needs, not a prerequisite of the pattern.

Isn't Event Sourcing too complex for my project?

Often, yes. If your domain is a simple CRUD with no need for history, a classic audit table is enough and costs far less. Event Sourcing is worth its cost when the history is the data: accounts, payments, inventory, bookings, or any domain where "who did what, when" is a real question.

Where do you start concretely?

With a single aggregate that matters, modeled as events on a PostgreSQL table. Understand replay and the aggregate first, then the command handler, then storage, then idempotency. The linked article series follows exactly that order, with tested Go code.

What Science Actually Says About CVs (and 3 HR Myths to Drop)

Odilon HUGONNOT — Mon, 20 Jul 2026 09:00:03 +0000

My CV had just been redone — clean, two columns, badges, a QR code. I thought it looked great. And that's exactly when the doubt creeps in: great for whom? For me, who built it, or for the recruiter who'll scan it in seven seconds between two meetings?

I'd followed the usual advice, the kind you read on every HR blog. "75% of CVs are rejected by bots before a human sees them." "CVs with numbers get 40% more callbacks." Sentences I'd swallowed without ever clicking the source. So before patting myself on the back, I wanted to know one simple thing: what does science actually say about CVs, and what's just folklore copied from blog to blog?

I pointed AI at it. Not to write my CV — I'd already done that (36 iterations with Claude, the story is here). To dig out the real studies, demand primary sources, and flush out the invented numbers. Three research agents in parallel, one non-negotiable rule: no statistic without a verifiable source, and anything that smells like a myth, you flag it. What came back made me throw out half of what I thought I knew.

The myths I almost optimized for

The worst thing about bad advice is when it's precise. A round number, a source that sounds serious, and boom, you build your CV around it. Three examples you've definitely read, and they're all hot air.

"75% of CVs are rejected by the ATS before a human." False. The line traces back to a 2012 sales pitch by Preptel, a CV-optimization company that shut down in 2013. No study, no methodology, no published data. Ever. The reality, measured by surveying recruiters about their own tools: ATS systems rank and file applications, they almost never auto-reject. The only hard filters are knockout questions the recruiter sets by hand (work authorization, location, required certification). The automatic 75% wall doesn't exist.

Optimizing your CV against a rejecting robot means preparing for a fight that isn't happening. The real reader is still a busy human.

"Numbers get you 40% more callbacks." A ghost citation. The supposed source (TalentWorks) is a dead domain, and the original "40%" didn't even mean callbacks: it referred to meeting 40% of a job's requirements. The figure got laundered from blog to blog until it became a truth nobody checked. To be clear, I'm not saying numbers are useless — quite the opposite (more on that below). I'm saying the precise multiplier is invented.

"Recruiters read in an F-pattern." The famous F-pattern comes from a 2006 Nielsen Norman Group study on reading web pages, not CVs. The CV extrapolation was made by blogs, never by a study on recruiters. NN/g itself lists five reading patterns and notes the F is "rarely a perfect F." What stays true is that the top and the left draw attention. But "your recruiter reads in an F," nobody has shown that on a CV.

The common thread across these three myths: a clean number, a fuzzy authority, and zero link to a study. The reflex that saves you is to ask for the primary source. Nine times out of ten, it doesn't exist.

What's actually proven

The good news is there's real science underneath. Less sexy, more nuanced, but usable. Here's what holds up, with the honest level of evidence next to it.

Writing quality has a measured causal effect. This is the strongest evidence of the lot: a controlled experiment by van Inwegen, Munyikwa and Horton (2023) on roughly 480,000 jobseekers shows that receiving writing assistance raised the probability of being hired by 8%. Not the polish — the clarity. Writing better helps the employer assess your ability, not just guess it. A real randomized trial, large sample. If you keep one thing: sweat the sentence.

Two pages, for an experienced profile, is defensible. A ResumeGo simulation (2018) saw recruiters prefer two-page CVs over one-page ones, especially for managerial profiles. Take it with a grain of salt (study funded by a CV-writing service, and it's a simulation, not real hiring), but it lines up with the industry consensus: one page under ten years of experience, two beyond, three almost always penalized outside academia, medicine and law.

The photo isn't neutral. A study in Management Science (Ruffle & Shtudiner, 2015, 5,312 CVs sent) shows the photo introduces a measurable attractiveness and gender bias that can backfire on you. In the US and UK, omitting it is the norm and cuts discrimination risk. Verdict: no photo is a defensible choice, not negligence.

Vocabulary matters more than the "robot." Harvard's Hidden Workers study (2021), on 8,000+ workers, shows the real problem isn't auto-rejection, it's vocabulary mismatch: if you don't use the words from the posting, the recruiter searching their database doesn't find you. So yes, mirroring the job's language is worth it. Not to clear a fictional wall — to be findable and readable by the human who scans.

And the seven-second scan? The number comes from a TheLadders eye-tracking study, small (30 recruiters), commercial, never replicated. Treat it as a rhetorical image, not a measurement. But the idea behind it holds: the first second decides, and the top of the CV must instantly say "good profile." That part is solid.

The one real technical trap: columns

Where the ATS myth deflates, a very real problem takes its place: parsing. When an ATS reads your CV, it turns it into structured text, line by line, left to right. Give it two columns, and it reads across: your job title on the left blends with a skill from the right column, and the output becomes mush.

Practical tests on five ATS platforms (Workday, Greenhouse, Lever, iCIMS, Taleo) confirm it, with numbers: on a two-column layout, Taleo flat-out lost an entire job and returned an empty skills list. The CSS-styled skill "chips"? Either ignored or shattered into orphan tokens. The QR code? An image, so invisible to the parser. In short, everything that makes my CV pretty to a human eye makes it risky for a machine.

My two-column CV is gorgeous for a human and treacherous for a parser. Both are true at the same time.

The fix isn't to butcher the design, it's to keep two versions. The pretty two-column PDF for what you actually do with a freelance CV: send it directly, link it from your site, hand it over in person. And a single-column version, no chips, standard section headings, "Jan 2021" dates, for the corporate portals with an ATS. Free 30-second test: copy-paste your CV into a plain-text editor. If the columns scramble, the ATS sees the same mess.

The radar: scoring a CV on what actually matters

Once the folklore was set aside, eight criteria with real evidence behind them remained. I turned them into a grid and scored myself with it. No-mercy verdict on my own CV:

Criterion (evidence-backed)

Score

Why

Quantified impact

9/10

Almost every line carries a number (99.9% uptime, integration complexity −80%, response time ÷4).

Seniority & scope

8/10

Dev → Lead → Architect progression visible, explicit architecture decisions. Missing 1-2 "chose X over Y" trade-offs.

Writing & clarity

8.5/10

Action verbs, precise prose. The best-proven axis (the +8% trial).

Human readability / design

9/10

Good-looking, clear hierarchy, scannable in seconds.

ATS compatibility (parsing)

4.5/10

The flip side of the design: two columns + chips + QR break parsing. No flat version.

Hierarchy / top of CV

6.5/10

Experience starts on page 2. The strongest role sits below the fold.

Length / concision

6/10

Three pages. The seniority consensus caps at two.

Proof / portfolio (GitHub, projects)

8.5/10

Annotated projects with stack and substance, GitHub and portfolio linked. A real reason to click.

Overall: 7.5/10. The content is top-tier: quantified, senior, proven. The only two real weaknesses are mechanical, not substantive: ATS parsing caused by the design, and the length that top-loads badly. Exactly the kind of diagnosis you can't make on your own, because you confuse "I like my CV" with "my CV does the job."

What it actually changed

Three levers, in order of impact, and none touches the content (which is good):

A flat ATS version. Not instead of the pretty PDF: in addition. The two-column PDF for direct sending and the site, a single-column version for corporate portals. It's only a priority if you target big companies with an ATS. For freelance use where you share the link yourself, the human design stays the right call.

Go to two pages and lift the experience up. Compact the last page (merge old education, trim interests) and start the first role on page 1. The recruiter must read "Backend Architect, fintech" in the first seconds, not a wall of profile text.

Two substantive tweaks. Add a real architecture trade-off ("modular monolith over microservices because...") and, when the number exists, a business impact in euros or users. That's what moves you from "senior" to "architect" in a hiring manager's eyes.

Conclusion

The real value of AI in this story isn't that it wrote my CV. It's that it did the dirty work nobody does: trace every piece of advice back to its primary source and find that half of them are ghost citations. The CV-advice industry largely runs on folklore repeated with confidence, because nobody clicks the link.

And the lesson that outlives the CV: I'd spent time optimizing my CV against a rejecting robot — a robot that doesn't exist. Meanwhile the real reader, the busy human who decides in a few seconds, was there the whole time. That's often the scam of "best practices": they make you please the wrong judge.

The Ideal Cart: 5 Design Patterns That Earn Their Keep (and 2 Refused)

Odilon HUGONNOT — Sun, 19 Jul 2026 09:00:03 +0000

It all starts with a review question. I was reworking my notes on the Design Patterns book, the Gang of Four one, with examples that all came from the same universe: an online shop. Shipping fees for Strategy, the order for State, stock for Observer. And the question landed: "so what would the ideal cart be? One class that uses all the patterns?"

Excellent question. Wrong direction. And the answer deserves more than a paragraph, because it contains roughly everything I know about design.

The trap: the ultimate Cart class

The starting intuition is healthy: if all five examples come from the same shop, why not assemble everything? The trap is the word "class". A Cart class stacking Strategy, Decorator, State, Observer and a Facade "to show off" is exactly what the 1994 book calls pattern fever, and it warns against it as early as page 31: a pattern should only be applied when the flexibility it brings is actually needed.

The ideal cart is not a class. It is a small architecture where each pattern holds the exact post where it earns its keep. And the hiring criterion fits in one question, the most useful one in the book: what is going to change?

Five hires, five nameable problems

So I built the full checkout flow, starting from zero and introducing each pattern only when a real request demanded it. Here is the hiring log:

Shipping fees vary → Strategy. Standard post, express, store pickup: three calculations for the same question, "how much?". One ShippingFee interface, one class per carrier. Adding a new carrier tomorrow: one class, zero modification elsewhere.

interface ShippingFee {
    public function compute(Cart $c): float;
}
class StandardPost implements ShippingFee {
    public function compute(Cart $c): float { return 4.99; }
}

The promo stacks → Decorator. "Free shipping over €50" is not a property of the carriers, it is a wrapper around them. Same interface as what it wraps: to the rest of the code, a decorated carrier is a carrier.

class FreeShippingOver implements ShippingFee {
    public function __construct(private ShippingFee $base, private float $threshold) {}
    public function compute(Cart $c): float {
        return $c->total() >= $this->threshold ? 0.0 : $this->base->compute($c);
    }
}

The order has life stages → State. "Cancel" does not mean the same thing in the cart (empty it), paid (refund) or shipped (carrier return). Instead of an if/elseif on the status duplicated in every method, the order carries a state object it swaps at each stage, and cancel() delegates. Zero ifs, forever.

Paying must trigger the unknown → Observer. Email, stock, accounting, and the SMS marketing will ask for next month. The pay() method must not know that list: it announces, and subscribers react. A list of callbacks and one loop: that is the whole pattern, and it is the same one as your addEventListener.

The controller wants one button → Facade. A Checkout object receives the shipping strategy (possibly decorated) and the event bus, and exposes one placeOrder() method. The code receiving the POST knows only it.

The detail that changes everything: where decisions live

The most important piece of the ideal cart is none of the five patterns. It is the assembly:

// The ONLY place in the program that knows the concrete classes.
$checkout = new Checkout(
    new FreeShippingOver(new StandardPost(), 50),   // a Decorator around a Strategy
    $events,
);

Every concrete choice is made at the root, at assembly time. Checkout receives interfaces: it does not know whether shipping is decorated, nor who subscribed to the events. If you have read my Clean Architecture notes, you recognize the dependency rule: the two books, written twenty-three years apart, converge on exactly the same move.

And the second lesson is my favorite: the most central class is the dumbest. The Cart itself uses no pattern. It adds up lines. The patterns live around it, at the places that change, never at the center.

The two refusals (as important as the hires)

Along the way, two patterns applied and were turned down. A Singleton (Cart::getInstance(), "to access the cart from anywhere"): a global variable in disguise, untestable, and root injection already covers the need. A Command with an undo/redo history, "just in case": nobody asked to cancel step by step, and a pattern installed for an imaginary need is complexity paid upfront.

A good design shows in its absent patterns as much as its present ones. The list of what your code refuses to do says more than the list of what it can do; it is the same idea as language progress by subtraction, one floor down.

The result, playable

None of this stayed a drawing. The shop actually runs, and I turned it into the 13th guided project of the learning section: "The pattern shop" (in French), where the checkout gets built step by step, with the real AI prompts, the first drafts that crack, two predictions to make before reading, and a final challenge (a second promo, stacked on the first, without modifying a single existing class).

Every button in the demo goes through a pattern, and an event log at the bottom shows the Observer subscribers waking up when you pay. If you just want the skeleton, it is also in the book notes, as a boxed aside.

Conclusion

What stays with me from this exercise is not the code, it is the order of operations. Not once did I ask "which pattern should I put here?". I listed the shop's likely requests, and each pattern arrived as the answer to one precise request, with a problem name attached. The two times a pattern showed up without a problem to solve, it was sent home.

Maybe that is the real definition of the ideal cart: not the one containing the most patterns, but the one where every pattern can answer the question "what are you here for?" without stammering.

Big O for the Impatient: Why Your Loop Is Slow (and When It Matters)

Odilon HUGONNOT — Sat, 18 Jul 2026 09:00:04 +0000

The page loads in 80 ms locally. In prod, on the real database, it takes 9 seconds and freezes the tab. The code did not change. The data did: 60 test rows locally, 14,000 in production.

The culprit was a ten-line loop, perfectly readable, hunting duplicates in a list. It had no bug. It just had the wrong shape. And understanding that shape is all Big O is about. No math, promise: just enough to read your own code and know which part will explode as the data grows.

Big O measures a shape, not a speed

First intuition to break: O(...) does not tell you "this takes 3 milliseconds". It tells you how the time reacts when you double the data. It is a curve shape, not a stopwatch. Three families cover the overwhelming majority of the job:

O(1) — constant. Data size changes nothing. Reading array[5000] is as fast as array[5].
O(n) — linear. Twice the data, twice the time. A loop that walks everything.
O(n²) — quadratic. Twice the data, four times the time. The killer class, and the one my loop had.

Three growth curves: O(1) flat, O(n) straight, O(n²) exploding amount of data (n) → time → O(1) O(n) O(n²) at small scale, all three look alike then O(n²) breaks away

The trap: on 60 test rows, all three curves are glued together. It is at production scale that O(n²) breaks away.

That is why my bug was invisible locally: at n = 60, O(n) does 60 operations and O(n²) does 3,600. The difference is microseconds, nobody sees it. At n = 14,000, O(n) does 14,000 operations, O(n²) does 196 million. That, you feel.

The loop that breaks away

The offending code, stripped to the bone: for each element, I rescan the whole list to see if it appears twice.

// ✗ O(n²): a loop INSIDE a loop
const dupes = [];
for (const a of list) {
    for (const b of list) {        // ← the rescan that costs
        if (a.id === b.id && a !== b) dupes.push(a);
    }
}

The same trap hides in a sneakier shape, the one that got me for years: includes() inside a loop. It looks like a single loop, but includes hides a second one.

// ✗ disguised O(n²): each includes() rescans the whole array
const seen = [];
for (const item of list) {
    if (seen.includes(item.id)) continue;   // includes = O(n), in a loop = O(n²)
    seen.push(item.id);
}

The fix is one word: Set. A Set (or an object, or a Map) is a hash table: checking membership with .has() is O(1), whatever the size. The double loop collapses into a single one.

// ✓ O(n): the Set answers in O(1), one pass is enough
const seen = new Set();
const dupes = [];
for (const item of list) {
    if (seen.has(item.id)) dupes.push(item);   // O(1)
    seen.add(item.id);
}

My 9 seconds dropped to 40 milliseconds. No clever optimization, no cache: just the right curve shape.

Why the Set is magic: array versus linked list

To see where that O(1) comes from, you have to open the hood of data structures. It all rests on one question: where do the elements live in memory? Memory is one long row of numbered cells.

An array stores its elements in cells glued next to each other. Since it knows the start address, it instantly computes where the 5000th lives: read in O(1). The flip side: inserting at the front forces everything else to shift over by one, so O(n). That is exactly what unshift() does in JavaScript, where push() (append at the end) is free.

A linked list does the opposite: its elements are scattered anywhere, and each holds the address of the next, like a treasure hunt. Inserting shifts nothing (O(1)), but reading the 5000th forces you to follow the arrows one by one from the start (O(n)). You will almost never write one by hand: in PHP it is SplDoublyLinkedList, in Python collections.deque, in Go container/list, and in JavaScript… you code it yourself.

A hash table (the Set, the Map, Python's dict, PHP's array) plays in another league: a function turns the key directly into a memory position. No walking, no shifting: read, write, test membership, all in O(1). That is why swapping an array.includes() for a Set.has() turns a quadratic curve into a linear one.

The hidden O(n) behind an innocent line

The real skill is not reciting these classes, it is spotting them in your own code, often tucked behind innocent syntax:

array.unshift(x) and a mid-array array.splice(i, 0, x): O(n), everything shifts.
array.includes(x) or array.indexOf(x) inside a loop: O(n²). A Set or a Map brings it back to O(n).
An SQL query WHERE email = ? with no index on the column: the database does a full scan, O(n) over millions of rows. The index is its version of binary search, O(log n).
A .find() inside a .map() to "join" two lists: again a loop in a loop. Index one of the two lists into a Map first.

Conclusion

Nobody will ask you to rewrite a hash table, your language ships one. That is not what Big O is for. It is for reading a loop and seeing its future: this one will hold at a million elements, that one will freeze the page. It is a reading skill, not a writing one.

And the irony is that AI changes nothing here, quite the opposite. An assistant happily produces an O(n²) loop that passes every test on 50 rows and dies in prod. Recognizing the curve shape in generated code is something you cannot delegate. If the topic clicks, I wrote a whole reading note on Grokking Algorithms, the book that finally reconciled me with algorithms without a single formal proof.