DEV Community: Abeera Lodhi

I capped extraction at 250 concepts, told the model to obey the cap, and let the app report the result as complete

Abeera Lodhi — Mon, 24 Aug 2026 02:31:28 +0000

This is a submission for DEV's Summer Bug Smash: Smash Stories.

TL;DR. I am building a study app whose entire premise is that it knows what you are about to forget. Extraction caps a source at 250 concepts, for good cost reasons, and I wrote that cap into the system prompt so the model would stop there. It does stop there. Which means a 300 page book comes back as exactly 250 concepts, the hard slice that would have told me something was dropped never fires, and the screen renders "250 concepts extracted." in the same neutral tone it uses for a two page note. The app was not losing your material by accident. It was losing it exactly as instructed, and then reporting a clean number over the top. The fix is one character, and the version almost everyone would write instead is the version that detects nothing.

The setup

Vesprit reads your study material and pulls out testable concepts, then tracks which ones are fading from your memory and puts those in front of you. The fade model only knows about concepts that exist in the database. That matters for what follows.

Extraction runs in a Cloudflare Worker against Claude, and it has a ceiling:

/**
 * A ceiling on concepts per source. This is the real cost lever: output tokens
 * cost 5x input, and output scales with concept count rather than source length.
 * Also keeps a single recall backlog from being unusable after one upload.
 */
export const MAX_CONCEPTS = 250;

That comment is mine, it is honest, and I still agree with every word of it. The cap is a deliberate design decision, not a bug. Two things follow from it that I did not think about together until much later: the system prompt tells the model to return at most 250, and the parser ends with a hard slice(0, MAX_CONCEPTS) as a backstop.

The assumption, stated plainly

A documented, intentional limit is a product constraint, not a defect. If it ever actually bites, the slice will be the thing that fires, and that is where I would put the detection.

I never wrote that sentence down. That is rather the point. It sat underneath the design as an unexamined belief, and it is wrong in a specific and interesting way.

Why it was wrong

The slice almost never fires.

The system prompt instructs the model to stop at 250. On a long source the model does what it is told. It returns exactly 250 concepts, parsed.length is exactly 250, and slice(0, 250) removes nothing at all. The backstop I was relying on to notice the problem is a backstop against the model disobeying me, which is the rare case. The common case, the model obeying, produces a response that is byte for byte indistinguishable from complete coverage of a short source.

So the boundary was invisible on both sides. The Worker had no idea it had hit a ceiling, because nothing was cut. The app had no idea, because the Worker only ever sent it a concepts array. The user had no idea, because the screen rendered a count, and a count with no qualifier reads as a total.

And in this product specifically, the consequence is not "a list is short." Material that never entered the system is invisible to the fade model, so the user gets a confident, well ranked revision queue built over a fraction of their syllabus, while every signal the app gives them says coverage is complete. The app's one job is to know what you are missing. It would have been the thing hiding it.

The fix, and the one character that carries it

-  return parsed.slice(0, MAX_CONCEPTS);
+  const truncated = parsed.length >= MAX_CONCEPTS;
+
+  return { concepts: parsed.slice(0, MAX_CONCEPTS), truncated };

>=, not >. That is the whole thing.

> is the version that looks correct in review. It asks "did the slice drop anything," which is the natural question, and it passes a test written by the same person who wrote the check, because that person reaches for the same mental model twice. It would have caught only the case where the model ignored its own instruction, and missed essentially every real truncation.

>= knowingly accepts a false positive. A source that genuinely yields exactly 250 concepts gets flagged as possibly incomplete when it is not. That trade is one sided and I took it on purpose: the cost is one hedged sentence on a rare exact hit, against silently handing someone a fifth of their material and letting them revise from it.

The reasoning is in the file rather than in a commit message nobody will read again, because the next person to look at this line will feel the same pull toward > that I did:

  // -------------------------------------------------------------------------
  // WHY `>=` AND NOT `>`
  //
  // This is the load-bearing line. The system prompt tells the model to return
  // at most MAX_CONCEPTS, so on a large source the model obeys and stops at
  // exactly MAX_CONCEPTS — the slice below never fires, and a `>` test would
  // report nothing. In other words `>` detects only the rare case where the
  // model ignored its own instruction, and misses essentially every real
  // truncation: a 300-page book comes back with 250 concepts, looking for all
  // the world like complete coverage.

The tests name the case rather than describing the mechanics, which is the only reason I trust them here:

it('flags a response that lands exactly on the ceiling', () => {
  // THE case this feature exists for, and the one a `>` comparison misses.
  // The system prompt tells the model to stop at MAX_CONCEPTS, so a large
  // source comes back at exactly the cap with nothing sliced off — which is
  // indistinguishable from complete coverage unless we say so here.
  expect(parseConcepts({ concepts: conceptList(MAX_CONCEPTS) })?.truncated).toBe(true);
});

it('counts survivors, not raw entries', () => {
  // Malformed entries are dropped before the count is taken, so a payload
  // that only reaches the ceiling by including junk is not a truncation.
  const withJunk = [...conceptList(MAX_CONCEPTS - 1), null, { prompt: '', expectedAnswer: 'x' }];

  expect(parseConcepts({ concepts: withJunk })?.truncated).toBe(false);
});

The first of those names is the whole argument. A > implementation passes every other test on this screen.

The part of the fix that nearly caused a worse bug

The flag has to persist. Intake navigates straight to the per source view on success, so a toast would be destroyed by the navigation on the exact path large sources arrive by. That meant a new field on the source document, and a new field means a parser change:

     createdAt,
     status,
+    // Deliberately NOT part of the validation block above. An older document has
+    // no `truncated` field and must still be a perfectly valid source — treating
+    // its absence as malformed would drop every pre-existing row and blank the
+    // timeline, which is precisely what this function's skip-one-row design
+    // exists to prevent.
+    truncated: data.truncated === true,

parseSource returns null for a malformed document and the list path skips nulls, by design, so one corrupt row cannot take down a timeline. Add truncated to the validation block above that line and every document written before this commit becomes malformed. Every row gets skipped. The user's timeline empties itself, silently, with no error anywhere, which is a considerably worse version of the bug I was in the middle of fixing.

It is pinned by a test that exists purely to stop someone tidying that comment away:

it('does NOT reject a document that lacks the field', () => {
  // The failure this guards against is severe and quiet: treating absence as
  // malformed would make parseSource return null for every pre-existing
  // source, and the list path skips nulls — so the user's timeline would
  // simply empty itself with no error anywhere.
  expect(parseSource('src_1', valid)).not.toBeNull();
});

What the user gets, finally, sits directly under the concept count, because that number is where the belief "this is my material" actually forms:

{source.truncated ? (
  <View className="mt-3 rounded-card border border-line bg-canvas-sunken p-gutter">
    <Text className="text-sm font-medium text-ink">Partial coverage</Text>
    <Text className="mt-1 text-sm leading-5 text-ink-muted">
      This source held more testable material than one extraction pass covers, so these{' '}
      {concepts.length} concepts are the most testable ones rather than all of them. Recall
      and fade tracking work normally on what is here.
    </Text>
  </View>
) : null}

It does not promise a fix. Complete coverage of a long source needs chunked extraction, which is scoped and not built, and offering a remedy that does not exist would be worse than the silence it replaces.

The honest note

This was caught by reading my own code while scoping chunked extraction on 2026-08-04, not by a user and not on a device. The app is pre launch, nobody was affected, there was no incident, and no source in the database has ever been long enough to trigger the flag, so the notice above has never rendered outside a fixture. The fix also does nothing until the Worker is redeployed, since the client reads a missing field as false.

What I take from it

An instruction to a model can hide the very boundary it creates. I asked for a limit and I got one, cleanly, every time. Obedience is what made this silent. If I had a sloppier model that overran the cap, my slice backstop would have fired and I would have found this on day one. The better the model followed instructions, the more invisible the problem became, and I do not think I would have predicted that.

The obvious implementation of a check is worth one minute of suspicion. Not the logic, which was fine, but the question it asks. > asks "did I cut anything." >= asks "am I at the edge." Those sound like the same question and they are not, and the difference is the entire feature.

A cap you documented is not a cap the user knows about. I had written the number down three times: in a constant, in a comment, in a system prompt. All three were facing me. None of them were facing them.

Silence is a claim. Rendering "250 concepts extracted." with no qualifier is not a neutral act. It asserts completeness by omission, and I would never have written that assertion out as a sentence.

One thing I have not solved, and would genuinely like to hear about.

When a model complies with your own constraint, how do you detect that you were at the boundary at all? The >= trick works here because my ceiling is a discrete count I control. It does not generalise to a token budget, a truncated context window, or a summarisation pass where the model quietly compresses instead of stopping. In all of those, obedience and completeness produce the same shaped output, and I do not have a general technique for telling them apart. Is there a real pattern for this, or is everyone hand rolling a sentinel per call site the way I just did?

I told my own agent the function was memoized. Twice. The device log said otherwise.

Abeera Lodhi — Mon, 24 Aug 2026 01:42:53 +0000

This is a submission for DEV's Summer Bug Smash: Clear the Lineup powered by Sentry.

TL;DR. My Clerk → Firebase auth bridge finished a full, successful sync and then immediately started over, twice a second, forever, on a real phone. Nothing threw. Every iteration worked. I was sure the cause was a remount, then I was sure getToken was memoized, and I had the library source open to prove it. I had the wrong library open. @clerk/clerk-expo wraps @clerk/clerk-react's correctly-memoized getToken to add an offline JWT cache, and drops the useCallback doing it. Every render, new identity. Every new identity, another effect run. Every effect run, a setState that caused the next render. The fix is nine lines. Finding it took building an instrument, because a re-run and a remount look identical in logs and have opposite fixes.

The setup

Vesprit is a study app. Clerk handles identity, Firestore holds the data, and Firestore's security rules need a Firebase auth.uid, which Clerk does not give you. So there's a bridge: take the Clerk session token, exchange it at a Cloudflare Worker for a Firebase custom token, sign in to Firebase with that. Three hops, one useEffect, one status the UI reads.

export function useFirebaseAuthBridge(): BridgeState {
  const { isLoaded, isSignedIn, userId, getToken } = useAuth();
  const [status, setSyncStatus] = useState<BridgeStatus>('signed-out');

  useEffect(() => {
    // … getToken() → exchangeForFirebaseToken() → signInWithCustomToken()
    // … setSyncStatus('syncing') … setSyncStatus('ready')
  }, [isLoaded, isSignedIn, userId, getToken, attempt]);

  return { status, error, retry };
}

getToken is in the dependency array because the lint rule says it should be, and because Clerk's own documentation shows getToken used inside effects. That is the entire bug, sitting in plain sight, looking like correct code.

Not a stall. This row is completing successfully and then starting again.

What was wrong

On device, the terminal read like this:

[firebase-bridge +2ms]   requesting Clerk session token
[firebase-bridge +6ms]   exchanging Clerk token for a Firebase custom token
[firebase-bridge +67ms]  signing in to Firebase with the custom token
[firebase-bridge +716ms] ready — Firestore rules will now see request.auth.uid
[firebase-bridge +2ms]   requesting Clerk session token          <- and again, forever

Read that last line carefully, because it's what made this hard. The sync succeeded. It reached ready. Then it did the whole thing again, roughly twice a second, indefinitely.

Every one of those cycles minted a real Firebase custom token: a network call to Clerk, an invocation of my Cloudflare Worker, and a Firebase sign-in. On a phone. On battery. There was no error state to find, no exception to catch, no failed request in the network log. The app was working perfectly, several times a second, forever.

This is the class of bug that error tracking cannot see.

The two things I was sure about, and why both were wrong

Wrong hypothesis #1: "The effect is re-running and cancelling its own result."

This was the first theory, and it was mine and my agent's together. It's the standard shape: an effect re-fires, the cleanup sets cancelled = true, and the in-flight result gets discarded before it can land.

Disproved by absence. The console.error in the bridge's catch block sits outside the cancelled guard, so it fires unconditionally whenever the catch is reached. It never fired. Nothing was throwing. Silence from that line was the whole diagnosis.

Wrong hypothesis #2: "getToken is memoized, so the dependency is stable."

This is the one worth writing the post about. I said this confidently. I had evidence. Here is the evidence I had, from @clerk/clerk-react:

const getToken = useCallback(createGetToken(isomorphicClerk), [isomorphicClerk]);

Memoized on a stable singleton. Stable identity. The effect runs once. Case closed. The loop must be a remount, which is a problem one layer above this hook, in how the provider is mounted.

I was reading the wrong package.

The app imports from @clerk/clerk-expo. That's a different package with its own useAuth, and I had generalised from the source of a library the app does not import.

The instrument, because logs couldn't answer it

Here's the thing that made this more than a lucky guess: a re-run and a remount produce identical logs, and they have opposite fixes. A changed dependency is fixed inside the hook. A remount is fixed above it. I had a 50/50 and no way to settle it by reading.

So before fixing anything, I built something to tell them apart:

// src/lib/dep-trace.ts
//
// `nextInstanceId` is module scope on purpose. Component-local state cannot
// distinguish "this instance ran twice" from "two instances each ran once",
// which is precisely the ambiguity in a paired log.

let nextInstanceId = 1;

export function claimInstanceId(): number {
  return nextInstanceId++;
}

export function diffDependencies(
  previous: readonly unknown[] | null,
  next: readonly unknown[],
  names: readonly string[],
): string {
  if (previous === null) {
    return 'FIRST RUN (fresh mount — if you see this repeatedly, the component is remounting)';
  }

  const changed = names.filter((name, index) => !Object.is(previous[index], next[index]));

  if (changed.length === 0) {
    return 'RE-RUN with NO changed dependency (double-invoke or Fast Refresh)';
  }

  return `RE-RUN — changed: ${changed.join(', ')}`;
}

Module scope is the entire point. If the counter lived in component state it would reset with the component, and "instance #1 ran twice" would be indistinguishable from "instance #1 and instance #1", which is exactly the question being asked.

Wired into the bridge:

+  const [instanceId] = useState(claimInstanceId);
+  const previousDepsRef = useRef<readonly unknown[] | null>(null);
+
+  useEffect(() => {
+    if (__DEV__) console.log(`[firebase-bridge #${instanceId}] MOUNTED`);
+    return () => {
+      if (__DEV__) console.log(`[firebase-bridge #${instanceId}] UNMOUNTED`);
+    };
+  }, [instanceId]);
+
   useEffect(() => {
+    if (__DEV__) {
+      const deps = [isLoaded, isSignedIn, userId, getToken, attempt];
+      console.log(
+        `[firebase-bridge #${instanceId}] effect: ` +
+          diffDependencies(previousDepsRef.current, deps, [
+            'isLoaded', 'isSignedIn', 'userId', 'getToken', 'attempt',
+          ]),
+      );
+      previousDepsRef.current = deps;
+    }

One detail I'd have got wrong a year ago: the instance id comes from a lazy useState, not a useRef. Reading a ref during render violates the Rules of React, and this component is compiled by React Compiler, which is entitled to assume those rules hold. A lazy initializer runs exactly once per instance and is safe to read while rendering.

One device run answered it. Every line read #1: the component never remounted, not once. And every effect run read:

[firebase-bridge #1] effect: RE-RUN — changed: getToken

The instrument naming the dependency I had just finished arguing was stable.

The root cause

@clerk/clerk-expo@2.19.31, dist/hooks/useAuth.js, verbatim, with only the bundler's CommonJS preamble stripped:

var import_clerk_react = require("@clerk/clerk-react");
var import_error = require("@clerk/shared/error");
var import_cache = require("../cache");

const useAuth = (initialAuthState) => {
  const { getToken: getTokenBase, ...rest } = (0, import_clerk_react.useAuth)(initialAuthState);
  const getToken = (opts) => getTokenBase(opts).then((token) => {
    if (!opts && import_cache.SessionJWTCache.checkInit()) {
      if (token) {
        void import_cache.SessionJWTCache.save(token);
      } else {
        void import_cache.SessionJWTCache.remove();
      }
    }
    return token;
  }).catch((error) => {
    if (!opts && import_cache.SessionJWTCache.checkInit() && (0, import_error.isNetworkError)(error)) {
      return import_cache.SessionJWTCache.load();
    }
    throw error;
  });
  return { ...rest, getToken };
};

That first line is the one I misread for days. It looks recursive (useAuth calling useAuth), but the one on the right is import_clerk_react.useAuth, a different package's hook pulled in under an internal name. In a post whose entire moral is "read the right source," it would be poor form to paraphrase this, so that's the literal file.

clerk-expo takes clerk-react's properly-memoized getToken, wraps it to add an offline JWT cache so tokens survive going offline (a genuinely good feature), and returns the wrapper. There is no useCallback around the wrapper. New function identity, every render.

The memoization still exists. It's just one layer down, wrapped in something that isn't memoized, which makes it worthless to anyone downstream.

And no, this isn't fixed, and I'm not the first to notice the ingredient. @clerk/clerk-expo is deprecated now (Clerk replaced it with @clerk/expo in Core 3), so a defect in it would be a fair thing to shrug at. I checked the replacement. @clerk/expo@4.5.2, dist/hooks/useAuth.js, as of 2026-08-24:

const useAuth = (options) => {
    const { getToken: getTokenBase, ...rest } = (0, _clerk_react.useAuth)(options);
    const getToken = (opts) => getTokenBase(opts).then(/* SessionJWTCache save/remove */)
        .catch(/* offline fallback */);
    return { ...rest, getToken };
};

New package, new build tooling, same wrapper, same missing useCallback. The file contains zero occurrences of useCallback or useMemo.

The un-memoized identity is also already corroborated in the wild, which I'd rather say than pretend I found it alone: get-convex/convex-js#176 (July 2026) ships an eslint-disable-next-line react-hooks/exhaustive-deps whose comment states it flatly: Clerk's Expo useAuth does not memoize getToken. So the fact is known. It's just known in a workaround comment inside somebody else's repository, not in an issue on Clerk's tracker, where I couldn't find it at all.

What I haven't seen written down anywhere is the part below: that when the effect also sets state, the missing memoization stops being a lint annoyance and becomes a self-sustaining loop that mints real credentials several times a second and never once looks like a failure. That consequence is my own diagnosis, and it's the reason a known-but-under-reported trap is worth a post.

And because the effect calls setSyncStatus, the loop needs nothing external to sustain it:

effect runs → setSyncStatus → re-render → new getToken identity → effect runs → …

It is a perpetual motion machine made of correct-looking code. Any useEffect that lists Clerk's Expo getToken in its dependencies and sets state has this, on the deprecated package and the current one alike. Clerk's docs show getToken used inside effects.

The fix

-  const { isLoaded, isSignedIn, userId, getToken } = useAuth();
+  // `getToken` is destructured under a different name and immediately stabilised.
+  // @clerk/clerk-expo rebuilds it on EVERY render (it wraps clerk-react's memoized
+  // version to add an offline JWT cache and does not re-memoize), so using it
+  // directly in the dependency array below re-runs the effect on every render —
+  // and since the effect calls setSyncStatus, it re-renders itself, forever.
+  const { isLoaded, isSignedIn, userId, getToken: getTokenUnstable } = useAuth();
+  const getToken = useStableCallback(getTokenUnstable);

And the hook itself, the "latest ref" pattern, which is React's own useEffectEvent proposal hand-rolled while that stays experimental:

export function useStableCallback<Args extends unknown[], Result>(
  callback: (...args: Args) => Result,
): (...args: Args) => Result {
  const latest = useRef(callback);

  // No dependency array on purpose: this must run after EVERY render, since the
  // whole premise is that `callback` changes identity every time.
  useEffect(() => {
    latest.current = callback;
  });

  // Empty deps, so the identity handed to callers never changes.
  return useCallback((...args: Args) => latest.current(...args), []);
}

Nine lines of body. Days of being confidently wrong.

The fix I didn't make, which is the interesting one

The obvious move is to delete getToken from the dependency array. The lint rule goes quiet, the loop stops, you move on.

That installs a worse bug than the one you fixed. The effect then closes over whichever getToken existed at mount and calls that one forever. After Clerk refreshes the session, the mount-time getToken is stale, so your bridge starts minting Firebase tokens from an expired Clerk session, and now you have an auth failure that only appears after the app has been open long enough to refresh. Good luck reproducing that.

The distinction is a test, not a comment:

it('calls the LATEST callback, not the one captured at mount', async () => {
  // The reason this is not just "delete the dependency". A frozen closure would
  // keep calling the mount-time getToken and hand back a stale session token
  // after Clerk refreshes.
  const { result, rerender } = await renderHook(
    ({ value }: { value: string }) => useStableCallback(() => value),
    { initialProps: { value: 'first' } },
  );

  expect(result.current()).toBe('first');
  await rerender({ value: 'second' });
  expect(result.current()).toBe('second');
});

Plus one for the loop itself, and one for a re-render arriving mid-flight while a token exchange is in the air:

it('keeps one identity even when the input changes on every render', async () => {
  // This is the exact shape of the bug.
  const { result, rerender } = await renderHook(() => useStableCallback(() => 'token'));
  const first = result.current;
  await rerender({});
  await rerender({});
  expect(result.current).toBe(first);
});

it('survives a re-render mid-flight, still resolving the original call', async () => {
  const { result, rerender } = await renderHook(
    ({ value }: { value: string }) => useStableCallback(async () => value),
    { initialProps: { value: 'first' } },
  );
  const pending = result.current();
  await rerender({ value: 'second' });
  await expect(pending).resolves.toBe('first');
});

There's one sharp edge worth documenting, and it's in the file: do not call the returned function during render. It reads a ref updated in an effect, so during render it hands back the previous render's callback. Effects, event handlers, and async work only.

The same screen after. The interesting part is the empty space underneath.

Honest scale

I want to be straight about how big this was, because the temptation to inflate it is real.

Nobody was affected. Vesprit is pre-launch: no users, no store listing yet. This was caught on my own device during development, on a build only I was running. Nothing leaked, nothing was corrupted, no one's battery died.

It was my bug too, not purely Clerk's. Clerk's wrapper is the defect, but I put getToken in a dependency array and then reasoned about it from the wrong package's source. The library made the trap; I walked into it and then argued the trap wasn't there.

The fix is a workaround, not a patch, and the trap is still open. I have an upstream report drafted against clerk/javascript, retargeted at @clerk/expo@4.5.2 now that I've confirmed the current package still ships it, and I haven't filed it yet. Until I do, this is still there for everyone else, which is the part that actually bothers me.

I did not discover the ingredient, only the consequence. The missing memoization is already documented, in passing, in an eslint-disable comment in convex-js#176. I'd rather say that than sell this as a lone discovery. What I contribute is the diagnosis of what it does when the effect sets state, the instrument that distinguishes it from a remount, and a fix that doesn't quietly swap it for a stale-token bug.

What's real: the loop was a full token mint several times a second on a mobile device, indefinitely, and it would have shipped. The pattern Clerk's own documentation shows still produces it in the current package, and the people who have it will not see it, because nothing about it looks or logs like a failure.

What I take from it

When two causes produce identical logs, build the instrument before you build the fix. I could have shipped a plausible guess in ten minutes and been wrong in a way I wouldn't have discovered for weeks. The instrument was thirty lines and settled it in one device run. It's still in the codebase.

Reading the source is evidence. Reading the right source is the evidence. I did the thing that feels most rigorous (go read the library), and it made me more confident and more wrong at the same time. @clerk/clerk-react and @clerk/clerk-expo are different packages, and my agent and I both generalised from the one that wasn't installed. Now I check node_modules for the package name in the import statement, not the package I assume is underneath.

Success is not a signal that things are fine. Every metric in this system was green. Every request returned 200. Every sync completed. The bug was that it completed again. I've since started thinking about "how often does this correct thing happen" as a first-class question, not just "does it work."

A memoization one layer down is not a memoization. If you wrap a stable callback, you own its stability now.

Two things I'd genuinely like answers to:

Has anyone found a way to catch this class of bug automatically? Not the loop itself: a render-count or effect-count budget in dev would catch that. I mean the general case: an operation that is individually correct and collectively pathological. Every tool I have is built around things going wrong, and this never went wrong.

And how do you handle the un-memoized-callback-from-a-library problem at scale? useStableCallback fixes one call site. There are dozens of hooks across the ecosystem returning fresh identities every render, and the honest answer for most of them is "wrap it and hope you noticed." Is there something better than a per-site workaround?

The Waiting Room: I generated a voice for eight shelter dogs from their own paperwork

Abeera Lodhi — Mon, 17 Aug 2026 06:40:02 +0000

This is a submission for Weekend Challenge: Dog Days Edition

"I really enjoy the company of my human friends. I may be shy at first, but once we get to know each other I will shower you with love! All I need is a soft warm place to lay, and to be told I am the goodest boy. I already know how to sit and I walk lovely on leash!"

That's Hart's entire adoption listing. Read it again and tell me one thing about him.

You can't. Not his age, not his size, not how long he has been sitting in a kennel. And here is the part that took me most of a day to notice: two of those four sentences are not about Hart at all. They also appear, word for word, in other dogs' listings at the same shelter.

Most listening projects would take that text and read it in a nicer voice. The Waiting Room reads it twice — once in the shelter's own upbeat register, and once in a voice generated from Hart's structured record — and the gap between the two is the whole argument.

What I Built

The Waiting Room is a single-page listening study of eight real, adoptable dogs. Every word on every card is verbatim from the shelter that published it. The only thing I added is the voice.

TL;DR

Eight real shelter listings, each read twice. The flat reading is a stock ElevenLabs voice. The second reading is a voice generated by ElevenLabs Voice Design from a prompt that a documented function computes out of that dog's record — age band, size, days waiting, returns, how it arrived. Flipping between the two readings preserves the playhead, so the same sentence changes voice mid-word. Not one word of the listing text is mine.

Demo

Live: https://waiting-room-ruby.vercel.app/

Repo: https://github.com/Abeera81/Waiting-room

60-second walkthrough — the audio swap is the thing to listen for.

The whole interaction fits in one screen:

One record at a time on a desk, with the rest of the deck showing underneath.

Press play. You hear the listing in a flat, upbeat listing voice.
Mid-sentence, hit DESIGNED. The words continue from exactly where they were, in a different voice.
Open How this voice was derived to see which attribute produced which part of the prompt.
On Yuji, drag the stay dial from Week 1 to Year 2 and listen to the same sentence get tired.
Any sentence with an amber underline is one the shelter also gave to another dog — click a name to hear that dog read the same words.
Arrow keys, drag, or the tabs at the bottom move through all eight records.

The finding: the template is louder than the dogs

I did not set out to write about templates. I set out to build a voice generator and needed eight real listings to feed it. Then I read them side by side.

Three of the eight dogs were given this sentence, character for character:

"I may be shy at first, but once we get to know each other I will shower you with love!"

Sterling is an 8-year-old Chihuahua. Ponyboy is a 3-year-old Anatolian Shepherd. Hart is a 9-year-old pit bull. One template, three animals with nothing in common but a shelter.

It isn't a one-off. The page detects the overlaps itself at load — exact string match after collapsing whitespace, six-word minimum, no fuzzy matching — and finds three shared sentences across five of the eight dogs:

Shared sentence	Appears in
"I may be shy at first, but once we get to know each other I will shower you with love!"	Sterling, Ponyboy, Hart
"I can be worried about new people, new surroundings and touch."	Sun Bear, Sterling, Ponyboy
"All I need is a soft warm place to lay, and to be told I am the goodest boy."	Ponyboy, Hart

Ponyboy comes off worst. Three of the four sentences in his listing belong to other dogs too.

The marks are drawn from the detector, not typed by me. The underlined sentences are the ones that are not his.

I want to be fair to the shelters here: a template is a rational response to being understaffed. Oregon Humane is moving hundreds of animals with a handful of people. But the effect is that the document cannot tell a 3-year-old Anatolian Shepherd from a 9-year-old pit bull, and the document is what an adopter reads.

That is not a claim I have to argue. It's in the source material, and the page checks it in front of you.

The thesis

Adoption is an emotional decision made from a bureaucratic artifact.

The listing text is 100% the shelter's — no additions, no paraphrase, no trimming for taste. The shelters write in the dog's first person, cheerfully, and that cheerfulness ships exactly as published. The only thing I contribute is the voice.

So when a worn, slow voice reads "I will shower you with love!", nothing has been editorialised. The cheerfulness is the institution's. The weariness is the record's. Both were already in the document; they were just never audible at the same time.

The shelter's reading.

The record's reading. Same words, same file length, same playhead.

Code

Abeera81 / Waiting-room

The Waiting Room

Shelter listings are documents. The Waiting Room makes them sound like the dogs they describe.

Built for the DEV Weekend Challenge: Dog Days Edition (Best Use of ElevenLabs) Repository created 2026-08-16, within the challenge window.

Run locally

node tools/serve.js 8124   # then open http://localhost:8124

Use this rather than python -m http.server: Chrome's media stack issues ranged requests for audio and stalls against a server that ignores them.

Tests

npm test

31 tests, no dependencies (node:test). They cover the mapping function, the shared-sentence detector, and the shipped data/dogs.json itself — that every audio file referenced exists, that all eight dogs derive distinct prompts, that no slider stop duplicates its neighbour, and that no placeholder text survived.

How it works

src/voicePrompt.js — the attribute → prompt mapping. Pure function buildVoicePrompt(attributes) returns the string handed to ElevenLabs Voice Design; derive() returns the same mapping with every rule's…

View on GitHub

No backend, no database, no build step. Four modules and a stylesheet: voicePrompt.js (the mapping), audioBus.js (the swap), sharedText.js (the template detector), app.js (the deck), and styles.css. Thirty-two tests under node --test, zero dependencies.

The swap is the demo

Two audio files, one <audio> element, and the playhead held across the source change. This is the moment I built first and everything else around:

// src/audioBus.js — the same sentence, in a different voice, mid-word
swapSource(src) {
  if (src === this.currentSrc) return;

  // Mid-drag the element has already been reset by an earlier swap, so trust
  // the held intent over what the element currently reports.
  const t = this.pending ? this.pending.t : this.position;
  const wasPlaying = this.pending ? this.pending.wasPlaying : this.playing;
  const token = ++this.swapToken;

  this.pending = { t, wasPlaying };
  this.currentSrc = src;
  this.el.src = src;

  const restore = () => {
    if (token !== this.swapToken) return; // a newer swap already won
    this.pending = null;
    this.el.currentTime = t;
    if (wasPlaying) this.play();
  };

  this.el.addEventListener('loadedmetadata', restore, { once: true });
  this.el.load();
}

Measured seek error across three consecutive flat↔designed swaps: 0.000 s, about 35 ms to load.

The pending and swapToken bookkeeping is not defensive decoration — it's two real bugs. Assigning .src immediately resets currentTime to zero, so a naive version reads that zero when a second swap arrives before the first has loaded, and the playhead is gone. That is exactly what dragging the stay dial does. The token exists because a stale loadedmetadata handler from a superseded swap will happily rewind you to a position you left three swaps ago. (There was also a third bug, which was mine and not the browser's: a hand-built silent placeholder MP3 with its channel-mode bits in the wrong byte, undecodable in Chrome and perfectly decodable everywhere I tested first.)

The hero dog: one variable moved

Yuji is a senior American Staffordshire Terrier and Labrador mix at Better World Rescue. He was hit by a car and surrendered by his family. His listing says he has been waiting "way too long".

His card carries a stay dial with four stops. Every stop calls the same function on the same record, with days_in_shelter as the only thing that changes:

Stop	`days_in_shelter`	What the function adds
Week 1	3	(nothing)
Month 1	30	a little flat
Month 4	120	quiet and tired
Year 2	730	flat, barely lifting, worn through

Dragging the dial swaps the audio through the same playhead-preserving function, so the voice ages mid-sentence. Four stops, four different weariness bands — chosen so that no drag is silent, and a test fails loudly if anyone changes the stops in a way that makes two of them collide.

The readout updates from the function, not from a lookup table.

Read the label on that dial before you read anything into it. It is a demonstration of what the mapping does with one variable. It is not a claim about Yuji's actual stay. More on that below, because it turned out to be the most interesting thing I found.

How I Built It

This is the intellectual core, so here it is in full. Five rules, applied in order, concatenated:

BASE       age_band     puppy  → "bright, very fast, unsteady, tumbling"
                        young  → "quick, energetic, eager"
                        adult  → "even, steady, measured"
                        senior → "low, slow, weary, patient"
PITCH      size         large  → "lower, resonant"     small → "higher, clipped"
                        medium → (nothing — the unmarked case)
WEARINESS  days         1-29   → (nothing)             30-119  → "a little flat"
                        120-179→ "quiet and tired"     180+    → "flat, barely lifting, worn through"
GUARD      returns      1      → "slightly hesitant"   2+      → "anxious, over-eager, trying too hard"
STRAIN     intake       stray  → "watchful"            owner_surrender → "resigned"
                        returned → "uncertain"         unknown → (nothing)

It's a real function, not a hardcoded lookup — derive() returns the same mapping with every rule's input and output, and the card renders that live:

// src/voicePrompt.js — pure, no I/O, no randomness, input not mutated
export function buildVoicePrompt(attributes) {
  return derive(attributes).fired.map((step) => step.value).join(', ');
}

export function derive(attributes) {
  const steps = RULES.map((rule) => {
    const input = attributes[rule.attribute];
    if (rule.required && (input === undefined || input === null)) {
      throw new Error(`buildVoicePrompt: attributes.${rule.attribute} is required`);
    }
    return { ...pick(rule, input), id: rule.id, label: rule.label,
             attribute: rule.attribute, input };
  });

  const fired = steps.filter((step) => step.fired);
  return { prompt: fired.map((s) => s.value).join(', '), steps, fired };
}

Every card shows its own working, including the rules that fired nothing — because a rule that stays silent because the shelter published nothing is a different thing from a rule that had nothing to say, and the panel labels which is which:

The record on the left, the prompt on the right, no step hidden.

Eight records in, eight distinct prompts out:

Dog	Record	Generated prompt
Yuji	senior, large, owner surrender	low, slow, weary, patient, lower, resonant, resigned
Paddington	adult, large, returned once	even, steady, measured, lower, resonant, slightly hesitant, uncertain
Sun Bear	puppy (3 mo), medium	bright, very fast, unsteady, tumbling
Sterling	senior, small	low, slow, weary, patient, higher, clipped
Buck	young, small	quick, energetic, eager, higher, clipped
Moose	young, large	quick, energetic, eager, lower, resonant
Ponyboy	adult, large	even, steady, measured, lower, resonant
Hart	senior, large	low, slow, weary, patient, lower, resonant

Sterling and Hart are both seniors. One is a Chihuahua and one is a pit bull, and the size rule is the only reason they don't sound the same. The shelter's copy could not tell them apart. The record could.

Why Voice Design, and not a preset voice with tuned parameters

Picking a preset is choosing from a menu. Voice Design generates a novel voice from a text description — which means the record can produce the voice, because the record can produce the description. That's the entire mechanism, and it's why this is a Voice Design project rather than a TTS project.

Now let me name the control honestly, because the obvious objection is a good one.

The flat reading is not a monotone robot. It's ElevenLabs' stock "Roger" — their own description is "Charismatic, positive and conversational" — on Eleven Multilingual v2, the same model as every designed voice. I deliberately did not sandbag the control. Roger is the upbeat register that shelter marketing is already written in, which makes the comparison one of tone, not expressiveness. If I'd used a flat robotic preset, the demo would be more dramatic and would prove nothing.

Nineteen clips, all generated on the free tier, which ended with 116 credits to spare.

Why the audio is pre-generated

Every clip is committed to the repo as an MP3. The browser makes no API calls and the repo holds no keys.

Three reasons, in order of how much I care: a judge opening this in six months hears exactly what I heard; there is no key to leak in a public repo; and no rate limit can decide whether my submission works during judging. The cost is that the demo can't voice arbitrary new text — which is the correct trade for a piece whose entire point is eight specific records.

The variable I could not get

Here is the part I did not expect.

No shelter publishes an intake date. Not one of the eight listings states how long the animal has been waiting. Not one shelter page, not the Petfinder record, nowhere. days_in_shelter is "unknown" for all eight dogs.

I could have estimated. It would have been easy and nobody would have checked. Instead unknown became a real value in the mapping — valid input, contributes nothing — and a genuinely missing value still throws, because "the shelter didn't say" and "I forgot to fill this in" must not look the same in a system that claims to derive things from records.

The consequence is uncomfortable and I think it's the most honest thing on the page: not one of the eight dogs carries a weariness modifier in its own voice. Weariness exists in exactly one place — Yuji's dial — where it is explicitly a demonstration of the function rather than a report about an animal.

So the honest sentence is: we can hear what waiting does to a voice; we cannot tell you how long any of these dogs has actually waited.

The absence is the finding. The one number that would turn this from an interpretation into a measurement is the one number the sector does not publish. Yuji's listing says "way too long". That is as precise as the record ever gets.

Limitations, plainly

The voices are an interpretation, not the dog. Nobody at these shelters signed off on how their animals sound here.
The mapping is authored, not learned. It encodes my reading of what a record implies about a voice. A different designer would write a different table and get different dogs.
Eight dogs is not a study. Three shared sentences across five records is a real, checkable observation about eight listings, and nothing more.
The degradation curve is a design choice. The four weariness bands are chosen, not measured. No one has established what 120 days does to anything.
The waveform is decorative. It's a progress bar drawn deterministically from the dog's id, not an analysis of the audio, and the page never claims otherwise.
These dogs may already be adopted. I hope so. Every card links to its source, captured 2026-08-16.

Prize Categories

Best Use of ElevenLabs

The API is not narrating this project — it's the visualisation layer. A documented pure function turns structured shelter data into a Voice Design prompt, and the generated voice is the output of that function, shown with its working on every card. The same function called four times with one variable moved produces the hero's stay dial, so the "one variable" claim holds by construction rather than by assertion. Nineteen clips, one stock control voice named openly, thirty-two tests, no keys, no backend, no live calls.

Built for the DEV Weekend Challenge: Dog Days Edition — repo created 2026-08-16, deployed and written inside the window, with Claude Code as co-author.

Eight dogs. One template. Two voices each. Go listen to Ponyboy, then click through to Hart and hear the same sentence again.

ZeroToRepo: I Built an AI Agent That Turns Notion Ideas Into GitHub Repos Before Your Coffee Cools

Abeera Lodhi — Sat, 28 Mar 2026 11:51:30 +0000

This is a submission for the Notion MCP Challenge

What I Built

I have a Notion database with 30+ startup ideas. Every single one followed the same pattern: get excited, write down the idea, tell myself "I'll start tomorrow"… and then spend the next 3 hours setting up a repo, googling competitors, creating GitHub issues, and losing all momentum before writing a single line of real code.

By idea #15, I realized the problem wasn't motivation. It was the Initialization Gap that dead time between having an idea and pushing a first commit. So I built the thing that would have saved me all those wasted hours.

ZeroToRepo is an autonomous AI agent. You check a single checkbox in Notion, and within 2 minutes, it has:

Researched your market : 5-8 live Brave Search queries, AI-analyzed to extract competitors, gaps, and trends ‎ ‎
Named your startup : AI-generated brand name + tagline grounded in the research
Written a Market Analysis : saved as a formatted Notion sub-page with proper headings and bold text
Built a 4-week strategy : every task maps to a competitive gap: "Competitors lack X → Week 2: Build Y"
Scaffolded a private GitHub repo : README with competitor table, package.json, src/index.js, all via ghost commits (zero local git)
Opened labeled GitHub Issues : each references the gap it addresses, with priority and owner
Synthesized a Project Brief : competitors, roadmap rationale, GitHub link, and timestamp, all back to Notion

Here's the thing that makes it actually interesting: the LLM decides what to do. This isn't a hardcoded script that runs step 1, step 2, step 3. It's a Groq-powered agent with 12 tools and function calling. The AI sees the tool descriptions, picks what to call next, and if something fails, it decides how to recover. The AI is the orchestrator.

Two commands. That's it.

npm run setup   # Interactive wizard: collects keys, tests all 4 connections
npm start       # Watches Notion. Check ☑️ Trigger. Done.

Demo

Show Us the Code

GitHub: https://github.com/Abeera81/zerotorepo

Architecture

The 4-Phase Pipeline

Agent Tool Registry (12 Tools)

Tool	Phase	What It Does
`update_notion_status`	All	Update Notion status via MCP
`deep_search`	Research	5-8 Brave searches (with fallback)
`analyze_market`	Research	AI → competitors, gaps, insights
`generate_startup_name`	Research	Creative name + tagline
`save_market_analysis`	Research	Write to Notion via MCP
`generate_strategy`	Strategy	4-week gap-targeting roadmap
`save_strategy_to_notion`	Strategy	Write to Notion via MCP
`create_github_repo`	Execution	Private repo + ghost commit
`set_github_url`	Execution	Store URL in Notion via MCP
`create_github_issues`	Execution	Labeled issues from roadmap
`write_project_brief`	Synthesis	Project Brief → Notion via MCP
`finalize_idea`	Synthesis	Mark Done, uncheck trigger

Project Structure

zerotorepo/
├── src/
│   ├── index.js            # CLI — polling loop, @clack/prompts TUI
│   ├── agent.js            # 🤖 LLM agent — Groq function calling, 12 tools
│   ├── stateMachine.js     # Routes: live → agent, mock → sequential
│   ├── mcp-client.js       # MCP client — spawns Notion MCP server (stdio)
│   ├── mcp-server.js       # ZeroToRepo AS MCP server — 7 tools for AI assistants
│   ├── notion.js           # Notion via MCP — markdown-to-blocks converter
│   ├── research.js         # Brave Search (5-8 queries) + Groq analysis
│   ├── scaffold.js         # GitHub ghost commits + rich README
│   ├── roadmap.js          # 4-week gap-targeting strategy
│   └── brief.js            # Project Brief synthesis
├── scripts/
│   ├── setup.js            # Interactive setup wizard
│   └── reset-db.js         # Reset Notion database
└── prompts/                # LLM system prompts

How I Used Notion MCP

Notion MCP is the central nervous system of ZeroToRepo. Every single Notion operation goes through MCP.

Consuming Notion MCP Server As MCP Client

ZeroToRepo spawns @notionhq/notion-mcp-server (v2.2.1) as a child process via stdio transport. All 22 MCP tools are available. We use 5:

MCP Tool	Where We Use It
`API-query-data-source`	Poll for triggered ideas every 5 seconds
`API-patch-page`	Update status (Researching → Planning → Building → Done)
`API-post-page`	Create Market Analysis, Strategy & Roadmap, Project Brief sub-pages
`API-get-block-children`	Idempotency checks — skip if sub-page already exists
`API-delete-a-block`	Database reset script

The MCP client handles connection lifecycle (lazy connect on first call, graceful disconnect on SIGINT/SIGTERM) and transparent JSON parsing of tool results.

Here's a problem I didn't expect: Notion doesn't render markdown. When you write research back to Notion, raw markdown appears as ugly plain text with literal **asterisks** everywhere. So I built a markdownToNotionBlocks() converter that transforms markdown into native Notion block types:

# Heading     → heading_1
## Subheading  → heading_2
- Bullet       → bulleted_list_item
1. Number      → numbered_list_item
> Quote        → quote
---            → divider
**bold**       → rich_text with bold annotation
[link](url)    → rich_text with link

Every sub-page (Market Analysis, Strategy & Roadmap, Project Brief) renders with proper headings, bold text, bullet lists, and links, just like hand-crafted Notion pages.

Exposing ZeroToRepo As an MCP Server

Here's where it gets interesting. ZeroToRepo isn't just an MCP client... it's also an MCP server. Any MCP-compatible AI assistant (Claude Desktop, Cursor, VS Code) can call ZeroToRepo's 7 tools directly:

Tool	Description
`process_idea`	Run the full 4-phase pipeline
`research_competitors`	Deep competitive research only
`generate_name`	Creative startup name from research
`scaffold_repo`	Create GitHub repo with scaffold
`generate_roadmap`	Generate & create roadmap issues
`generate_brief`	Synthesize project brief
`list_notion_ideas`	List all ideas from Notion database

This means Claude can say: "Hey ZeroToRepo, research 'AI pet care' and scaffold a repo" and it just works. The setup wizard even auto-generates the MCP config for VS Code or Claude Desktop so you don't have to write JSON by hand.

The Full MCP Data Flow

Total MCP calls per pipeline run: ~12-15 (status updates, sub-page creation, URL setting, trigger reset)

What Makes This Different

LLM-Driven Orchestration (Not Hardcoded)

Most hackathon projects chain API calls in a fixed sequence. ZeroToRepo's agent uses Groq function calling. The LLM receives 12 tool descriptions and decides which to call next. If deep_search fails, it sees the error and can retry with a different query or skip to analyze_market with fallback data. This is genuine AI agent behavior, not a script.

Dual MCP Architecture

We're not just consuming Notion MCP, we're also exposing ZeroToRepo as an MCP server. This creates a composable tool ecosystem where AI assistants can chain ZeroToRepo with other MCP servers.

Gap-Targeted Strategy

The roadmap isn't generic. Every task explicitly references a competitive gap: "Competitors lack real-time sync → Week 1: Build WebSocket infrastructure." Phase 2 reads Phase 1's gap analysis and generates tasks that directly target those gaps.

Ghost Commits (Zero Local Git)

Repos are created entirely via GitHub's Git Data API, blobs, trees, commits, refs, all remotely. No git clone, no local filesystem, no SSH keys.

$0 Total Cost

Groq free tier (100k tokens/day), Brave Search free tier (2k queries/month), GitHub API (free with PAT), Notion API (free integration). A full pipeline run uses ~20k tokens, you get ~5 runs per day for free.

Tech Stack

Technology	Role
Node.js v20+	Runtime
`@modelcontextprotocol/sdk`	MCP client + server framework
`@notionhq/notion-mcp-server`	Notion MCP integration (22 tools)
Groq API (Llama-3.3-70B)	LLM function calling, analysis, generation
Brave Search API	Real-time competitive intelligence
`@octokit/rest`	GitHub repo creation, ghost commits, issues
`@clack/prompts`	Beautiful interactive CLI