DEV Community: Daniel Nwaneri

The Gap Andrej Karpathy Didn't Fill

Daniel Nwaneri — Tue, 21 Apr 2026 14:10:07 +0000

I was debugging a customer support issue and typed the question into Claude.

Perfect answer. Wrong company. The model told me what the general best practice was for the problem category — accurate, well-reasoned, completely useless for my situation. Because the actual answer was in our internal runbook. Three paragraphs written eight months ago by a contractor who's since left. Not in any training set. Not in any index. Just sitting in a Notion page nobody searched anymore.

That's the gap Karpathy didn't fill.

The Wikipedia Argument

Karpathy made a compelling point: LLMs are becoming the new Wikipedia. For general knowledge questions, just ask the model. Why build a retrieval pipeline to answer "what is gradient descent" when GPT-4 already knows it better than your docs ever will?

He's right, for that use case.

But most knowledge work isn't general knowledge questions. It's "what did we decide about the pricing model in Q3" and "which customer reported this exact error last month" and "what's the current state of the integration with Salesforce." None of that is in any model. None of it ever will be.

The moment your question is about your specific context — your decisions, your customers, your code, your history — you need retrieval. The LLM is still doing the reasoning. But it needs your data to reason over.

The Cheap/Expensive Pipeline Problem

The frustrating thing about most RAG tutorials is they hand you the expensive version by default.

Every query embeds. Every query hits the vector index. Every query reruns the full pipeline, even for questions it's already answered. Cache? Optional. Keyword search for exact matches? Not shown. A model worth $0.003/call handling routing decisions? Never comes up.

The result: hobby projects that work fine, production deployments that surprise you at month end.

The routing insight that changed how I think about this: not every query needs vector search. "Show me documents tagged 'finance' from last week" is a SQL query. "Find anything mentioning GPT-4o" is BM25. "What do we know about our churn patterns" is the full vector pipeline. Running everything through embeddings when the first two cases cover maybe 40% of real-world queries is just waste.

V4 of this project classifies query intent first — SQL / BM25 / VECTOR / GRAPH / VISION / OCR — then routes accordingly. In testing, that cuts average embedding cost by 71% compared to running everything through vectors. The expensive path runs when it actually needs to.

What's Actually Running

For anyone who wants the specific stack:

Layer	What's used
Runtime	Cloudflare Workers (TypeScript)
Vector store	Cloudflare Vectorize
Keyword + metadata store	D1 (SQLite at the edge)
Embedding (default)	`@cf/qwen/qwen3-embedding-0.6b` — 1024d
Reranker	`@cf/baai/bge-reranker-base`
Vision / OCR	`@cf/meta/llama-4-scout-17b-16e-instruct`
Knowledge synthesis	`@cf/moonshot/kimi-k2.5`
Query routing	`@cf/meta/llama-3.2-3b-instruct`
MCP transport	Streamable HTTP via Cloudflare Durable Objects

Everything on Cloudflare. No Pinecone account. No OpenAI bill for embeddings. No Redis for caching. The cache is the CF Cache API, which is global and free at reasonable volumes.

Rough cost at 1,000 queries/day with intelligent routing: ~$0.11/month. At 10,000/day: $1–5/month. The Workers free tier absorbs the first 100,000 requests/day with no compute charge.

The Part That Surprised Me

The reflection layer was the thing I didn't expect to matter as much as it does.

Standard RAG retrieves documents. It doesn't learn. Every query goes in cold — no memory of patterns across documents, no synthesis of what the knowledge base collectively knows, no growing sense of what questions remain unanswered.

After every ingest, this system does three things: finds the most semantically related documents already in the index, asks an LLM to synthesise what's new, how it connects to what exists, and what gap remains. That synthesis — one paragraph, structured — gets embedded and stored as doc_type=reflection, with a 1.5× ranking boost in search results.

After every 3 ingests, it consolidates the recent reflections into a doc_type=summary — a compressed view of what the knowledge base has learned across that batch.

The effect: your knowledge base builds a second layer of meaning on top of raw documents. Related concepts get explicitly linked. Contradictions get surfaced. A search that previously returned five independent chunks now might also return a reflection that already synthesised those chunks into one coherent insight.

It's not magic. It's just LLM synthesis run as a background job, stored where retrieval can find it. But the result feels different from a flat document store in a way that's hard to describe until you see it return the reflection instead of the source.

Kimi K2.5 handles the reflection and consolidation by default. It has noticeably better multi-document reasoning than smaller models — worth the slightly higher cost for synthesis quality. Drop in REFLECTION_MODEL=llama-3.2-3b in your env if you want to reduce cost at high volume.

Running It

git clone https://github.com/dannwaneri/vectorize-mcp-worker.git
cd vectorize-mcp-worker
npm install

# Create a 1024d Vectorize index (qwen3-0.6b default)
wrangler vectorize create mcp-knowledge-base --dimensions=1024 --metric=cosine

# Create D1 database
wrangler d1 create mcp-knowledge-db

# Configure, apply schema, deploy
cp wrangler.toml.example wrangler.toml
# paste your database_id into wrangler.toml
wrangler d1 execute mcp-knowledge-db --remote --file=./schema.sql
wrangler deploy

# Set API key
wrangler secret put API_KEY

Dashboard at https://your-worker.workers.dev/dashboard. OpenAPI spec at /openapi.json for Postman / Bruno / Insomnia.

Claude Desktop config:

{
  "mcpServers": {
    "vectorize": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-worker.workers.dev/mcp",
        "--header",
        "Authorization: Bearer YOUR_API_KEY"
      ]
    }
  }
}

Restart Claude Desktop. Six tools appear: search, ingest, ingest_image_url, find_similar_by_url, delete, stats.

What This Is For

This isn't trying to be better than LLMs at general knowledge. It's making LLMs useful on your data — the knowledge that doesn't exist anywhere else, the decisions your team made that aren't in any training set, the documents that answer the questions your customers actually ask.

Most RAG tutorials hand you a demo. This is what happens when you build the thing properly: hybrid search, cross-encoder reranking, intelligent routing, knowledge synthesis, multi-tenancy, rate limiting, caching, a native MCP server, batch ingestion, and a test suite. In one deployable Worker. At boring prices.

The model knows everything except what you know. That asymmetry is the whole problem. Filling it doesn't have to be expensive.

Full source: github.com/dannwaneri/vectorize-mcp-worker

AI is quietly making human experts invisible. I built a tool to stop it.

Daniel Nwaneri — Tue, 14 Apr 2026 17:01:10 +0000

Every time you ask an AI to write code, something disappears.

Not the code — the code shows up fine. What disappears is the trail. The GitHub discussion where someone spent two hours explaining why cursor-based pagination beats offset for live-updating datasets. The Stack Overflow answer from 2019 where one person, after a week of debugging, documented exactly why that approach fails under concurrent writes. The RFC your team wrote six months ago that established the pattern the AI just silently copied.

The AI consumed all of it. The humans who produced it got nothing.

And I don't mean "nothing" philosophically. I mean: no citation in the codebase. No way for a new developer to trace why the code is written the way it is. No signal to the person who wrote the original answer that their work mattered.

Over time, at scale, those people stop contributing. Why maintain a detailed GitHub discussion if AI will summarize it into oblivion and no one will read the original?

This is the quiet cost of AI-assisted development that nobody is measuring. I've been thinking about it for a while, and I built something to address it.

The scenario

A developer joins a team. Six months of AI-assisted codebase. They hit a bug in the pagination logic — cursor-based, unusual implementation, nobody on the team remembers why it was built that way. The original developer who designed it has left.

Old answer: two days of archaeology. git blame points to a commit message that says "fix pagination." The commit before that says "implement pagination." Dead end.

With poc.py trace src/utils/paginator.py, that same developer sees this in thirty seconds:

Provenance trace: src/utils/paginator.py
────────────────────────────────────────────────────────────
  [HIGH]  @tannerlinsley on github
          Cursor pagination discussion
          https://github.com/TanStack/query/discussions/123
          Insight: cursor beats offset for live-updating datasets

Knowledge gaps (AI-synthesized, no human source):
  • Error retry strategy — no human source cited
  • Concurrent write handling — AI chose this arbitrarily

They now know exactly where the pattern came from and — critically — which parts of the code have no traceable human source. That second section is what saves them. The concurrent write handling is where the bug lives. AI made a choice nobody reviewed.

That's what this tool does. Not enforcement first. Archaeology first.

What I built

proof-of-contribution is a Claude Code skill that keeps the human knowledge chain intact inside AI-assisted codebases.

The core idea is simple: every AI-generated artifact should stay tethered to the human knowledge that inspired it. Not as a comment at the top of a file that nobody reads. As a structured, queryable, enforceable record that lives next to the code.

When the skill is active, Claude automatically appends a Provenance Block to every generated output:

## PROOF OF CONTRIBUTION
Generated artifact: fetch_github_discussions()
Confidence: MEDIUM

## HUMAN SOURCES THAT INSPIRED THIS

[1] GitHub GraphQL API Documentation Team
    Source type: Official Docs
    URL: docs.github.com/en/graphql
    Contribution: cursor-based pagination pattern

[2] GitHub Community (multiple contributors)
    Source type: GitHub Discussions
    URL: github.com/community/community
    Contribution: "ghost" fallback for deleted accounts
                  surfaced in bug reports

## KNOWLEDGE GAPS (AI synthesized, no human cited)
- Error handling / retry logic
- Rate limit strategy

## RECOMMENDED HUMAN EXPERTS TO CONSULT
- github.com/octokit community for pagination

The section that matters most is Knowledge Gaps. That's where AI admits what it synthesized without a traceable human source. No other tool I know of produces this. It's the part that turns "the AI wrote it" from a shrug into an auditable fact.

How Knowledge Gaps actually get detected

This is the part worth explaining carefully, because the obvious assumption — that the AI just introspects and reports what it doesn't know — is wrong. LLMs hallucinate confidently. An AI that could reliably detect its own knowledge gaps wouldn't produce knowledge gaps in the first place.

The detection mechanism is different. It's a comparison, not introspection.

When you use spec-writer before building, it generates a structured spec with an explicit assumptions list — every decision the AI is making that you didn't specify, each one impact-rated. That list is the contract: here is every claim this feature rests on.

When the code ships, proof-of-contribution cross-checks the final implementation against that contract. Anything the code does that doesn't map to a spec assumption or a cited human source gets flagged as a Knowledge Gap. The AI isn't grading its own exam. The spec is the answer key.

The result is deterministic. If the retry logic wasn't specified and no human source covers it, the gap appears in the block regardless of how confident the model was when it wrote the code. The boundary holds because it comes from the spec, not from the model's confidence.

This is also why the confidence levels mean something. HIGH means the spec explicitly covered it or the user provided the source directly. MEDIUM means the pattern traces to recognized human-authored work but the exact source isn't pinned. LOW means the model synthesized it — human review strongly recommended before this code goes anywhere near production.

There's a second detection path that doesn't require spec-writer at all. poc.py verify runs Python's built-in ast module against the file and extracts every function definition, conditional branch, and return path. It cross-checks each one against the seeded claims. No API calls. No model confidence. Pure static analysis. When you run it on a file where import-spec was used first, only the assumptions with no resolved citation surface as gaps. When you run it cold, every uncited structural unit surfaces as a baseline. Either way, the AI's confidence at generation time is irrelevant — the boundary comes from the code's actual structure.

Three things the skill does

Provenance Blocks — attached automatically to any generated code, doc, or architecture output. You don't have to ask. It's always there.

Knowledge Graph schema — when you're building a system to track contributions at scale. Claude generates a complete graph schema for Neo4j, Postgres, or JSON-LD. Nodes for code artifacts, human sources, individual experts, AI sessions, and knowledge claims. Edges that let you ask: "who are the humans behind this module?" or "what did @username contribute to this codebase?"

Static analyser (poc.py verify) — runs after the agent builds. Parses the file's structure using Python's AST, cross-checks every function and branch against seeded claims, and reports deterministic Knowledge Gaps. Zero API calls. Exit code 0 means clean, 1 means gaps found — CI-compatible.

HITL Indexing architecture — when you want AI to surface human experts instead of summarizing them. The query interface returns Expert Cards:

Answer: Use cursor-based pagination with GraphQL endCursor.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
HUMAN EXPERTS ON THIS TOPIC
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
👤 @tannerlinsley  (GitHub)
   Expertise signal: 23 contributions on pagination patterns
   Key contribution: github.com/TanStack/query/discussions/123
   Quote: "Cursor beats offset when rows can be inserted mid-page"
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Not a summary. A pointer. The human expert stays visible.

Getting started takes one command

I didn't want this to be another tool that requires you to choose a database before you can do anything. The default is SQLite. It works immediately.

# Install the skill
mkdir -p ~/.claude/skills
git clone https://github.com/dannwaneri/proof-of-contribution.git ~/.claude/skills/proof-of-contribution

# Scaffold your project (run once, in your repo root)
python ~/.claude/skills/proof-of-contribution/assets/scripts/poc_init.py

That creates four things:

.poc/provenance.db — SQLite database, local only, gitignored
.poc/config.json — project config, committed
.github/PULL_REQUEST_TEMPLATE.md — PR template with an AI Provenance section
.github/workflows/poc-check.yml — GitHub Action that fails PRs missing attribution

Then you get a local CLI:

python poc.py add src/utils/parser.py    # record attribution interactively
python poc.py trace src/utils/parser.py  # show full human attribution chain
python poc.py report                     # repo-wide provenance health
python poc.py experts                    # top cited humans in your graph

poc.py verify is what catches gaps before they become incidents:

python poc.py verify src/utils/csv_exporter.py

Verify: src/utils/csv_exporter.py
────────────────────────────────────────────────────────────
  Structural units detected : 11
  Seeded claims             : 3
  Covered by cited source   : 2
  Deterministic gaps        : 1

Deterministic Knowledge Gaps (no human source):
  • function: handle_concurrent_writes (lines 47–61)
      Seeded assumption: concurrent write handling — AI chose this arbitrarily

  Resolve: python poc.py add src/utils/csv_exporter.py

poc.py trace is what I use the most for the full attribution picture. This is what it looks like on a real file:

Provenance trace: src/utils/csv_exporter.py
────────────────────────────────────────────────────────────
  [HIGH]  @juliandeangelis on github
          Spec Driven Development at MercadoLibre
          https://github.com/mercadolibre/sdd-docs
          Insight: separate functional from technical spec

  [MEDIUM] @tannerlinsley on github
           Cursor pagination discussion
           https://github.com/TanStack/query/discussions/123
           Insight: cursor beats offset for live-updating datasets

Knowledge gaps (AI-synthesized, no human source):
  • Error retry strategy — no human source cited
  • CSV column ordering — AI chose this arbitrarily

The GitHub Action is for teams that already find the trace valuable

Once you've used poc.py trace enough times that it's saved you real hours — that's when you push the GitHub Action. Not before.

git add .github/ .poc/config.json poc.py
git commit -m "chore: add proof-of-contribution"
git push

After that, every PR gets checked. If a developer submits AI-assisted code without an ## 🤖 AI Provenance section in the PR description, the action fails and posts a comment explaining what's needed.

The opt-out is simple: write 100% human-written anywhere in the PR body and the check skips.

The enforcement works because the tool already saved them hours before they turned it on. The PR check isn't introducing friction — it's standardizing something people already want to do. That's the only version of a mandate that doesn't get gamed.

It works with spec-writer

I built spec-writer first. It turns vague feature requests into structured specs, technical plans, and task breakdowns before the agent starts building. The problem spec-writer solves is ambiguity before the code exists.

proof-of-contribution solves attribution after the code exists.

They connect at the assumption layer. spec-writer generates an assumptions list — every implicit decision the AI made that you didn't specify, impact-rated, with guidance on when to correct it. Each correction can now carry a citation. Each citation becomes a node in the knowledge graph. By the time a developer runs poc.py trace on a finished module, the full chain is visible:

feature request → spec decision → human source → code artifact
                                       ↑
                              poc.py verify closes this loop
                              without asking the AI what it missed

That chain is what I mean when I say AI should be a pointer to human expertise. Not a replacement. A pointer.

Why 2026 is the right time to build this

The tools are mature. Coding agents are shipping code at scale. The question of "who is responsible for this output?" is becoming real — in teams, in code reviews, in enterprise audits.

The provenance infrastructure doesn't exist yet. git blame tells you who committed. It doesn't tell you what human knowledge shaped the decision. That gap is getting wider every month.

proof-of-contribution is one piece of the infrastructure. It's not the whole answer. But it's the piece I could build, and it's the piece I think matters most: keeping the humans whose knowledge powers AI visible in the artifacts AI produces.

Install

mkdir -p ~/.claude/skills
git clone https://github.com/dannwaneri/proof-of-contribution.git ~/.claude/skills/proof-of-contribution

Works with Claude Code, Cursor, Gemini CLI, and any agent that supports the Agent Skills standard.

Repo: github.com/dannwaneri/proof-of-contribution

Drilling boreholes taught me something AI keeps reminding me of.The formula can be perfect. The model can be correct. Yet the result is still dry.Because the assumption about the ground (or the environment) was wrong.

Daniel Nwaneri — Fri, 10 Apr 2026 15:43:30 +0000

Geology lessons on the limits of modeling

Daniel Nwaneri

Apr 10

The Formula Was Exact. The Assumption Was Wrong. That's Not an AI Problem.

#ai #webdev #career #python

Comments 9

5 min read

The Formula Was Exact. The Assumption Was Wrong. That's Not an AI Problem.

Daniel Nwaneri — Fri, 10 Apr 2026 15:07:48 +0000

Your geology will always govern your geophysics.

My lecturer said it once. I wrote it down. I didn't fully understand it yet.

I do now.

What He Meant

We were studying Vertical Electrical Sounding at the Federal University of Technology Owerri. VES is how you read the earth without drilling it — you send current into the ground, measure how it returns, and infer what's down there from the resistivity curves. Clean method. Decades of field use. Textbook technique.

But the method assumes something. It assumes the layers beneath you are horizontal, homogeneous, well-behaved. The formula works perfectly under those conditions. Run your numbers, get your model, trust the output.

Except Nigeria's basement complex isn't horizontal or homogeneous. It's fractured. Laterally variable. Full of structural surprises that don't announce themselves in your data. You can run perfect VES and still drill a dry borehole — not because the method failed, but because you trusted a reading without interrogating the ground it came from.

The geology is always prior. The geophysics only tells you what's there if you already understand the conditions under which it's operating. Skip that step and the output is confidently wrong.

I spent a semester learning this in a classroom. Then I spent six months at the Nigerian Geological Survey Agency watching it happen in the field — solid mineral surveys, real terrain, results that came back and either confirmed your model or told you your assumptions were off.

I didn't know I was learning how to work with AI.

The Same Failure, Different Surface

I've been building production systems in Port Harcourt for years now. Cloudflare Workers, RAG pipelines, MCP servers, edge infrastructure for users where bandwidth costs real money per request.

And I keep watching the same failure repeat, dressed in different code.

Developer gets AI-generated output. Output looks right. Tests pass. Ships to production. Fails — not catastrophically, but wrongly. Subtly. In ways that take days to trace.

The model wasn't broken. The formula was fine. The geology was different.

AI generates for the environment its training data came from — abundant compute, fast connections, forgiving infrastructure, users on fast networks in cities where the grid is reliable. That's the assumed geology. Most of the time, nobody states that assumption. Nobody interrogates it. The output arrives confident and gets treated as ground truth.

When I built a VPN service targeting Nigerian users, the AI-suggested architecture was technically correct and completely wrong. Correct for the assumed geology. Wrong for mine. The difference wasn't a bug you could find with a linter. It was a mismatch between what the model assumed about the world and what the world actually was.

That gap — between assumed geology and actual geology — is where production failures live.

The VES Lesson Nobody Teaches in CS

VES nearly died as a professional discipline in the 1980s and 1990s.

Not because the physics were wrong. The physics were exact. It died because practitioners kept getting bad results — boreholes drilled on confident readings that came back dry. Clients stopped trusting the method. The reputation collapsed.

The post-mortem was brutal in its simplicity: the formula was exact. The assumption was wrong. Geophysicists had been applying a method that required horizontal homogeneity to terrain that wasn't horizontally homogeneous. The model was rigorous. The geology was inconvenient.

They fixed it — better field protocols, more explicit assumption-checking, ground-truthing before committing to a reading. The method recovered. But only after the field admitted that confident output isn't the same as correct output.

We are at that moment with AI.

The models are rigorous. The outputs are confident. And we are shipping to production without interrogating the geology — the actual environment, the actual users, the actual constraints — that the output will have to survive in.

Ben Santora has been stress-testing LLMs with logic puzzles designed to expose reasoning failures. His finding: most models are solvers, not judges. They produce an answer. They don't flag when the assumed conditions don't match the actual problem.

"Knowledge collapse happens when solver output is recycled without a strong, independent judging layer to validate it."

The judging layer is the geologist's job. It always was.

What Field Work Actually Trains

I did my industrial training at NGSA in 2015. Solid mineral surveys. Real field conditions. Mineralogy in the lab, VES in the terrain.

The thing fieldwork does that coursework doesn't is this: it makes the gap between model and ground visible in real time. You take your reading. You record your resistivity curves. You run your interpretation. Then you go back the next day and find out if the borehole hit water or came back dry.

That feedback loop — model, prediction, ground truth, reckoning — is what builds the instinct to hold your interpretation lightly. Not to distrust the method. To distrust the assumption.

When I ran my SEO audit agent against my own published content this month — seven URLs, seven FAILs — I wasn't surprised. I'd built the agent, I knew what it was checking, and I ran it on myself first because that's the only version of a demo I trust. The agent was right. Three freeCodeCamp tutorials had broken meta descriptions. Two DEV.to article titles were too long for Google to render cleanly.

That reflex — interrogate the output before you trust it — isn't something I learned from a JavaScript tutorial. It came from standing in terrain that didn't match the model and having to explain why.

The same thing happened when I shipped The Foundation's clipboard capture in February. The workflow looked right. I documented it, wrote the article, shipped to GitHub. It was broken — capturing only user messages, missing every AI response, missing everything above the visible viewport. I'd reviewed it at the same speed I built it. The geology was inconvenient. I didn't check.

Five days later I wrote publicly: "I launched The Foundation with big plans. But I underestimated the scope." Not in a GitHub issue. On DEV.to. The well came back dry. You say so.

The Reframe

The conversation about AI in software development keeps getting stuck on the wrong question.

Not: is the model capable?

The model is capable. That's not the problem.

The question is: does the model know your geology?

AI-generated code is optimised for an assumed environment. Plenty of RAM. Reliable connectivity. Users on fast networks. Infrastructure that forgives. Most of the time, nobody states this assumption — it's baked into the training data, invisible until the output meets terrain it wasn't built for.

The developers who catch this aren't necessarily the most experienced. They're the ones who learned — somewhere, from something — to name the geology before trusting the reading.

In the field: name the geology before you trust the reading.

In production: name the environment before you trust the output.

Same question. Different surface.

What Non-CS Backgrounds Actually Transfer

The argument I keep hearing: your background doesn't matter, code is code.

It's wrong. And it misses the point.

What transfers from geophysics isn't syntax knowledge. It's the prior question. The one you ask before you trust the output.

CS tracks teach you to evaluate whether the code is correct. They don't train the instinct to ask whether the assumed conditions match the actual ones. That instinct comes from fields where the gap between model and ground is visible, expensive, and immediately yours to own.

The guts come from somewhere. For some people it's painful production failures. For some it's a good mentor. For me it was a lecturer in Owerri who said one sentence I've never stopped thinking about.

Your geology will always govern your geophysics.

The model doesn't know your terrain. That's not a limitation to wait out. It's a gap you have to close yourself — every time, before you ship.

I Ran My Own SEO Agent on My Two Domains — It Went from 0/4 to 4/4 PASS in One Afternoon

Daniel Nwaneri — Tue, 07 Apr 2026 15:12:57 +0000

invoice.naija-vpn.com was serving the Carter Efe $50K/month Twitch story as its meta description. That page is an invoice generator tool for Nigerian freelancers. Nothing about it has anything to do with Carter Efe.

The agent caught it on the first run. A scraper wouldn't have — it reads raw HTML before JavaScript executes. The agent uses Playwright, reads the rendered DOM, sees what a browser sees after all the scripts run. The homepage content was leaking in dynamically. The scraper sees an empty description. The agent sees the actual problem.

I own both domains — naija-vpn.com and naijavpn.com, a Virtual Payment Navigator for Nigerian freelancers and creators. I ran the agent on my own sites to see what it would find.

What the agent found

Four URLs. Four FAILs.

URL	Title	Description	Overall
naija-vpn.com/	FAIL — 65 chars	FAIL — 185 chars	FAIL
naijavpn.com/	FAIL — 66 chars	FAIL — 192 chars	FAIL
/cleva-vs-geegpay	FAIL — 63 chars	PASS	FAIL
invoice.naija-vpn.com	FAIL — no page-specific meta	FAIL — no page-specific meta	FAIL

The homepage title was NaijaVPN - Virtual Payment Navigator for Nigerian Freelancers — 65 characters when the display limit is 60. The description was 185 characters when the limit is 160.

The invoice.naija-vpn.com subdomain was the worst finding. It's a separate subdomain — Google treats it as its own site — but it had no page-specific metadata at all. The agent was reading Carter Efe makes $50K/month from Twitch — here's how he gets paid in Nigeria... as the meta description for an invoice generator tool. The subdomain is a React SPA and the static HTML <head> had no <meta name="description"> tag. Homepage content was leaking in dynamically after JavaScript executed.

A requests-based scraper would have missed this entirely. It reads the raw HTML before JavaScript executes and would have seen an empty description, not the leaking homepage copy. The agent uses Playwright — it reads the rendered DOM, the same page a browser sees after all the scripts run. That's the difference.

The cost curve routing on real pages

The audit ran in tiered mode. Here's what the routing looked like:

naija-vpn.com/ → Tier 1 — deterministic, zero API cost
naijavpn.com/ → Tier 1 — canonical pointing correctly to naija-vpn.com, clean
/cleva-vs-geegpay → Tier 1 — clear structure, no escalation needed
invoice.naija-vpn.com → Tier 2 (Haiku) — title on the boundary, needed a closer look

Three tiers, four pages, one run. Total API cost for the audit: under $0.05.

What I actually changed

The rewrite agent ran next — same cost curve applied to the suggestions. Tier 1 truncated the titles deterministically. Haiku generated description suggestions. Sonnet wrote the voice-matched copy for the invoice subdomain opening paragraph.

Three changes I deployed:

Homepage title: NaijaVPN - Get Paid Internationally in Nigeria — 46 characters. Cut the bloat, kept the value proposition.

Homepage description: Trimmed from 185 to 156 characters. The agent's suggestion preserved the Carter Efe reference — that's the hook that makes people click — but cut everything that was padding.

invoice.naija-vpn.com: Added a proper <meta name="description"> to the static HTML <head> of the React SPA — the fix lives in index.html, not in the JavaScript. One line of HTML. The agent's suggested copy: "Generate professional invoices instantly. Receive international payments in Nigeria with Geegpay, Payoneer and Cleva. Free invoice tool for Nigerian freelancers." — 158 characters, PASS.

The verification run

Reset state. Re-ran the audit.

URL	Title	Description	Tier	Overall
naija-vpn.com/	PASS — 46 chars	PASS — 156 chars	Tier 1	PASS
naijavpn.com/	PASS — 46 chars	PASS — 156 chars	Tier 1	PASS
/cleva-vs-geegpay	PASS — 52 chars	PASS — 156 chars	Tier 1	PASS
invoice.naija-vpn.com	PASS — 50 chars	PASS — 149 chars	Tier 2	PASS

4/4. Zero flags.

The verification run hit Tier 1 on every page — pure deterministic Python, zero API calls. That's the cost curve completing its own argument: the first run used Haiku and Sonnet because the issues were ambiguous enough to need judgment. The verification run used nothing because the fixes were mechanical and the checks are mechanical. The model cost dropped to zero not because the run was cheaper, but because the problems were gone.

The finding that mattered most

The invoice.naija-vpn.com subdomain inheriting homepage metadata is a serious SEO problem. Google treats subdomains as separate sites — so this wasn't "duplicate metadata on the same site." It was a standalone subdomain with no metadata of its own, rendering the homepage's Carter Efe story as the description for an invoice tool.

The agent caught it because it reads the rendered DOM. A scraper reads raw HTML — it would have seen an empty description and flagged the absence, not the leak. The agent saw what a real browser sees: the homepage content dynamically injected after JavaScript executed.

The agent found it automatically, on the first run, and proposed a fix.

That's the actual value. Not the character counts. The automated surface of a problem that was invisible to a quick look at the page.

Two full audit passes plus the rewrite run: under $0.15 total. Four pages, three runs, one afternoon.

The free core at dannwaneri/seo-agent handles the audit and the basic report. The PDF with per-page screenshots, severity-sorted issues, and the rewrite suggestions are in the Pro layer. The cost curve runs in both.

I Was Paying $0.006 Per URL for SEO Audits Until I Realized Most Needed $0

Daniel Nwaneri — Fri, 03 Apr 2026 14:24:02 +0000

Pascal CESCATO read my SEO audit agent piece and left this in the comments:

"You don't need an LLM for this. Everything you're sending to Claude can be done directly in Python — zero cost, fully deterministic, no hallucination risk."

He was right. And wrong. And the conversation that followed is the reason I rebuilt the entire thing.

What Pascal Actually Said

The audit agent I published checks title length, meta description length, H1 count, and canonical tags. Pascal's point: those are character counts and presence checks. A regex does that. You don't pay $0.006 per URL for a regex.

I pushed back. The flags array requires judgment — "title reads like a navigation label rather than a page description" isn't a character count. Pascal conceded, then reframed:

"Two-pass makes more sense. Deterministic Python for binary checks, model call only on pages that pass the mechanical audit but need a second look. You pay per genuinely ambiguous case, not per URL."

That's a better architecture than what I shipped. I said so publicly.

Then Julian Oczkowski extended it:

"Deterministic rules first, lightweight models for triage, larger models reserved for genuinely ambiguous edge cases. Keeps latency low, costs predictable, reduces unnecessary LLM dependency."

Three people in a comment thread had just designed something I hadn't thought to name. Pascal called it two-pass. Julian called it tiered. I called it the cost curve — a sliding scale from free to expensive, routed by what the task actually requires.

The Cost Curve

Tier 1 — Deterministic Python. Cost: $0.
Title >60 characters? FAIL. Description missing? FAIL. H1 count == 0? FAIL. These are not judgment calls. A model that can reason about Shakespeare does not need to be invoked to count to 60.

Tier 2 — Haiku. Cost: ~$0.0001 per URL.
Title present but 4 characters long. Description present but 30 characters. Status code is a redirect. These pass the mechanical audit but something is off. Haiku is cheap enough that calling it for ambiguous cases costs less than the time you'd spend debugging why the deterministic check missed something.

Tier 3 — Sonnet. Cost: ~$0.006 per URL.
Pages Haiku flags as needing semantic judgment. "This title passes length but reads like a navigation label." "This description duplicates the title verbatim." Sonnet earns its cost here. Not everywhere.

The insight is routing. Most pages on a typical agency site have mechanical issues — missing descriptions, long titles, no canonical. Those never need a model. The interesting cases — pages that pass every binary check but still feel wrong — are where the model earns its place.

On my last run of 50 URLs, 8 reached Sonnet. The rest resolved at Tier 1. Total cost dropped from ~$0.30 to ~$0.05. The 8 that hit Sonnet were the ones worth paying for.

What I Actually Built

I restructured the entire repo around this architecture.

core/ stays flat and MIT licensed. The original seven modules untouched. Anyone who cloned v1 still runs python core/index.py and gets identical behavior.

premium/ adds four modules. cost_curve.py handles the tier routing — audit_url(snapshot, tiered=True) runs Tier 1 first, escalates to Haiku if something fails, escalates to Sonnet only if Haiku flags semantic ambiguity. multi_client.py manages project folders — --project acme reads and writes from projects/acme/ with isolated state, input, and reports. enhanced_reporter.py generates WeasyPrint PDFs with per-URL screenshots, issues sorted by severity, and suggested fixes. rewrite_agent.py is the one Pascal didn't anticipate — after the audit, --rewrite generates improvement suggestions using the same cost curve: Tier 1 truncates titles deterministically, Haiku writes meta description suggestions, Sonnet rewrites opening paragraphs. Pass --voice-sample ./my-writing.txt and the prompt includes a sample of your writing. The suggestions sound like you, not like Claude.

main.py is the unified entry point. Free users run python main.py and get v1 behavior. Pro users add --pro, set SEO_AGENT_LICENSE, unlock the premium layer.

A full pro run looks like this:

python main.py --project client-x --pro --tiered --rewrite

That single command: reads from projects/client-x/input.csv, routes every URL through the cost curve, generates rewrite suggestions for failing pages, writes a PDF report with screenshots and severity levels, and appends a run record to the audit history.

The Architecture Decision That Matters

core/ imports nothing from premium/. Ever.

This isn't just clean code. It's a trust contract with anyone who forks the repo. The MIT-licensed core is the public good — auditable, forkable, accepts PRs. The premium layer is proprietary and closed, but it builds on a foundation anyone can inspect.

Mads Hansen in the comments named the right question: how do you prevent the auditor from developing blind spots on recurring patterns? The answer I didn't have then: run history in state.json. Each completed run appends a record — timestamps, pass counts, fail counts, report path. Over time, "this page has failed description length for six consecutive runs" is a different signal than "this page failed today." The audit becomes a monitor. Not just a snapshot.

What the Comment Thread Cost

Nothing. And produced a better architecture than I would have built alone.

Pascal's pushback separated the deterministic from the semantic. Julian's production framing gave me the three-tier structure. Apex Stack's 89K-page site showed me where the orphan detection problem lives. Mads Hansen named the blind spot question I hadn't asked.

None of that was in the original article. All of it is in the repo now.

The public comment thread is the architecture review I didn't schedule. That's what happens when you publish the honest version — the demo that fails on your own content — instead of the staged one.

The staged demo would have passed. The honest one compounded.

Full repo: dannwaneri/seo-agent. Core is MIT. Premium requires a license key. The freeCodeCamp tutorial covers the v1 build in detail: How to Build a Local SEO Audit Agent with Browser Use and Claude API.

Agents Don't Just Do Unauthorized Things. They Cause Humans to Do Unauthorized Things.

Daniel Nwaneri — Mon, 30 Mar 2026 14:36:52 +0000

A comment thread shouldn't produce original research. This one did.

Last week I published a piece about agent governance — the gap between what an agent is authorized to do and what it effectively becomes authorized to do through accumulated actions. I used a quant fund analogy: five independent strategies, each within its own risk limits, collectively overweight the same sector. No single decision was wrong. The aggregate outcome was unauthorized.

The comment section built something I hadn't anticipated.

Kalpaka,Vic Chen, Andre Cytryn, Stephen Lee, and Connor Gallic spent three days extending the argument in directions I hadn't gone. What follows is an attempt to assemble what they built — with attribution, because the thread earned it.

The Unit Problem

The first thing Kalpaka named was the hardest: what do you measure?

Actions taken is too noisy. Resources touched is closer but misses compounding. The unit that matters, they argued, is state delta — the diff between what the system could affect before and after a given action sequence.

A vendor approval doesn't just place an order. It creates a supply chain dependency. A database read doesn't just return rows. It establishes an access pattern the agent now relies on.

So the audit object isn't an action log. It's a capability graph — resources and permissions as nodes, actually-exercised access paths as edges. Reconciliation compares the declared graph against the exercised one. The delta is your behavioral exposure.

This is the frame that makes the quant fund analogy precise rather than decorative. A 13F filing is exactly this: a reconciliation between declared strategy and actual exposure, anchored to external cadence rather than internal computation speed. The quarterly filing forces the moment when someone has to look at the full graph, not just the individual positions.

Two Kinds of Edges

The capability graph has a shape problem I hadn't considered.

Direct edges are legible. The agent called the database, touched the file, invoked the API. These edges can be tracked. They decay naturally — an access pattern not exercised in N reconciliation cycles can be pruned. The agent hasn't used that path, so it drops from the exercised graph.

Induced edges are different. These are the edges created when an agent's output causes a human to take an action the agent itself didn't take. The Meta Sev 1 incident last week is the exact pattern: the agent didn't write anything unauthorized. It gave advice that caused an engineer to widen access. The exposure persisted for two hours. The agent's direct action log showed nothing unusual.

Induced edges don't decay the same way direct edges do. The human decision the agent caused doesn't un-happen when the agent stops referencing it. The widened access persists independently of the agent's continued activity. These edges have a much longer half-life — effectively permanent until someone explicitly reconciles them.

This is where the governance architecture splits. Direct edges decay on a usage clock. Induced edges require active reconciliation. The first can be automated. The second can't — which is exactly where the 13F analogy holds strongest. Quarterly isn't a technical choice. It's a regulatory one. Someone external decided that interval was often enough for fund positions. Agent capability graphs need the same external anchor.

The Irreversibility Problem

Andre Cytryn raised threshold drift: you calibrate materiality at deployment time, but the agent's decision space expands with use.

The per-strategy limits in the fund example weren't wrong at design time. They were wrong at failure time because the correlation structure changed. Continuous recalibration is the obvious fix. But continuous recalibration creates its own attack surface — a mechanism the agent can game structurally, not intentionally. Enough accumulated decisions that each looks within tolerance can shift the calibration baseline until the new thresholds permit what the original thresholds wouldn't.

The only way out Kalpaka identified: decouple recalibration authority from the agent's own execution context entirely. Thresholds reviewed by something with no stake in the agent's performance.

This requires knowing which actions are irreversible — but irreversibility is often only visible in retrospect. The Meta incident proves it. Nobody flagged the permission-widening action as irreversible-scope-changing while it was happening. The agent's advice looked like a routine technical suggestion. The irreversibility was only visible after the state had already changed.

Kalpatha's resolution was to invert the default assumption. Don't try to classify irreversibility upfront. Treat every induced edge as irreversible. Over-reconcile first, and let the reconciliation history generate the labeled data you need to build the upstream classifier later.

This is how financial compliance actually bootstrapped. Early fund compliance didn't start with sophisticated materiality filters. They reconciled everything quarterly and learned which position changes were material through decades of accumulated review history. The filters came from the data. The data came from over-reconciling.

We're in the over-reconcile phase. Expensive, noisy, generates false positives. But it's the only way to produce the labeled examples that make the classifier possible later. Trying to solve the detection problem at inception is trying to skip the generation of training data.

The Fatigue Problem

Over-reconciling creates a human cost. Every flagged induced state change needs a review decision. Volume in early cycles will be high by design.

The compliance history the 13F analogy draws on has a second chapter nobody likes to mention: the review process degrades under load. Humans start rubber-stamping. False positives stop being caught. The labeled data gets noisy before the classifier can be trained on it.

Kalpaka's answer was adaptive rather than prescribed: track reviewer consistency over time. Same reviewer, same flag type — does the approval rate shift as volume increases? That's your fatigue signal. Once you can detect it, you don't need a hard cap. You have evidence-based throttling.

The auditor rotation parallel holds here too. Financial auditors rotate precisely because of this problem. Fresh eyes are the simplest fatigue mitigation. The question for agent behavioral review is whether there are enough qualified reviewers to rotate through.

That's harder than it sounds. Financial auditors share a professional vocabulary — they all know what material means, what a restatement implies, what a concentration risk looks like. That shared language is what makes fresh eyes useful. Agent behavioral accounting doesn't have that vocabulary yet. The capability graph framing this thread built is an attempt to construct it. Until reviewers have a shared framework for what "consequential scope change" looks like in practice, rotating fresh eyes doesn't transfer the same way.

The qualified reviewer problem might be the bootstrapping constraint underneath the bootstrapping constraint.

The Enforcement Floor

Connor Gallic brought the piece back to earth.

Theory is one thing. What teams actually ship is another. The simplest version of enforcement is a write checkpoint: every agent action that changes state passes through a policy evaluation before it executes. Not token monitoring, not post-hoc audit. A deterministic gate between intent and action.

The aggregate authorization problem gets simpler when you centralize that policy layer. If every agent's writes flow through the same checkpoint, cross-agent scope becomes visible — because the governance layer has the view that individual agents don't.

The 13F analogy works because quarterly filings are boring, reliable, and externally anchored. Agent governance needs the same properties. The hard part isn't the theory. It's making enforcement boring enough that teams actually ship it.

The write checkpoint wins on that dimension. It's implementable today. It handles direct scope violations cleanly. It's the enforcement floor.

The capability graph is the ceiling. It handles induced state changes, threshold drift, cross-agent composition. It's more expensive, harder to build, requires the vocabulary that doesn't fully exist yet. It's also necessary for complete governance.

The right architecture is probably layered: checkpoint as the floor that catches direct violations cheaply, capability graph as the audit layer that catches induced drift over time. You ship the checkpoint first because it's boring enough to actually build. You develop the capability graph because the checkpoint leaves a class of failures uncovered.

What the Thread Built

None of this was in the original piece.

The two-clock distinction was there. The 13F analogy was there. The governance debt framing was there.

The capability graph, the direct/induced edge split, the over-reconcile bootstrap, the adaptive fatigue ceiling, the layered enforcement architecture — those came from Kalpaka, Andre, Vic, Stephen, and Connor over three days in a comment section.

That's worth naming directly. Not as a courtesy, but because it demonstrates the problem Foundation is designed to solve. This conversation happened in public, in a thread that will eventually scroll off everyone's feed, attributed to usernames rather than preserved as structured knowledge. The architecture it built is worth more than that.

The agent governance problem doesn't have a consensus solution yet. What it has is a comment thread that got further than most papers. The qualified reviewer problem is still open. The capability graph needs implementation. The adaptive ceiling needs tooling.

But the vocabulary exists now. That's what the thread produced. And vocabulary, as someone wiser than me wrote recently, turns vague frustration into specific, solvable problems.

The original piece: Your Agent Is Making Decisions Nobody Authorized

I Built a Local AI Agent That Audits My Own Articles. It Flagged Every Single One.

Daniel Nwaneri — Mon, 30 Mar 2026 14:33:56 +0000

Not as a gotcha. As a result.

Seven URLs. Seven FAILs.

My Hashnode profile is missing an H1. Three freeCodeCamp tutorials have meta descriptions that are either missing or over 160 characters. Two DEV.to articles have titles too long for Google to render cleanly.

I built the agent. I ran it on my own content first. That's the honest version of the demo.

The problem I was actually solving

Every digital marketing agency has someone whose job is basically this: open a spreadsheet, visit each client URL, check the title tag, check the description, check the H1, note broken links, paste everything into a report. Repeat weekly.

That person costs money. The work is deterministic. The only reason it's still manual is that nobody built the alternative.

I built it in a weekend.

The stack

Browser Use — Python-native browser automation. The agent navigates real pages in a visible Chromium window. Not a headless scraper. Persistent sessions, real rendering, the same page a human would see.
Claude API (Sonnet) — reads the page snapshot and returns structured JSON: title status, description status, H1 count, canonical tag, flags. One API call per URL.
httpx — async HEAD requests for broken link detection. Capped at 50 links per page, concurrent, 5-second timeout per request.
Flat JSON files — state.json tracks what's been audited. Interrupt mid-run, restart, it picks up exactly where it stopped. No database needed.

Seven Python files. 956 lines total. Runs on a Windows laptop.

The part most tutorials skip: HITL

The agent hits a login wall. Throws an exception. Run dies.

That's most automation tutorials.

This one doesn't work that way.

When the agent detects a non-200 status, a redirect to a login page, or a title containing "sign in" or "access denied", it pauses. In interactive mode: skip, retry, or quit. In --auto mode it skips automatically, logs the URL to needs_human[] in state, and continues.

An agent that knows its limits is more useful than one that fails silently. That's the design decision most people don't make because tutorials don't cover it.

What the audit actually found

I ran it against my own published content across three platforms:

URL	Failing fields
hashnode.com/@dannwaneri	H1 missing
freeCodeCamp — how-to-build-your-own-claude-code-skill	Meta description
freeCodeCamp — how-to-stop-letting-ai-agents-guess	Meta description
freeCodeCamp — build-a-production-rag-system	Title + meta description
freeCodeCamp — author/dannwaneri	Meta description
dev.to — the-gatekeeping-panic	Title too long
dev.to — i-built-a-production-rag-system	Title too long

The freeCodeCamp description issues are partly platform-level — freeCodeCamp controls the template and sometimes truncates or omits meta descriptions. The DEV.to title issues are mine. Article titles that read well as headlines often exceed 60 characters in the <title> tag.

The agent didn't care. It checked the standard and reported the result.

The schedule play

python index.py --auto

Add a .bat file that sets the API key and calls that command. Schedule it in Windows Task Scheduler for Monday 7am. Check report-summary.txt with your coffee.

That's the agency workflow. No babysitting. Edge cases in needs_human[] for human review. Everything else processed and reported automatically.

What this actually costs

One Sonnet API call per URL. Roughly $0.002 per page. A 20-URL weekly audit costs less than $0.05. The Playwright browser runs locally — no cloud browser fees, no Browserbase subscription.

The whole thing runs on a $5/month philosophy. Same one I use for everything else.

The code

GitHub: dannwaneri/seo-agent

Clone it, add your URLs to input.csv, set ANTHROPIC_API_KEY in your environment, run pip install -r requirements.txt, run playwright install chromium, then python index.py.

The freeCodeCamp tutorial walks through each module — browser integration, the Claude extraction prompt, the async link checker, the HITL logic. Link in the comments when it's live.

The shift worth naming

Browser automation has been a developer tool for a decade. Playwright, Selenium, Puppeteer — all powerful, all requiring someone to write and maintain selectors. The moment a button's class name changes, the script breaks.

This agent doesn't use selectors. It reads the page the way Claude reads it — semantically, through the accessibility tree. A "Submit" button is still a "Submit" button even if the CSS class changed.

The extraction logic is in the prompt, not in the code.

Old way: Automation breaks when the page changes.

New way: Reasoning adapts. The code doesn't need to.

That's the actual shift. Not "AI does the work" but "the brittleness moved." From selectors to prompts. From maintenance to reasoning. The failure modes are different. So is the recovery.

Built this as the first in a series on practical local AI agent setups for agency operations. The freeCodeCamp step-by-step tutorial is coming. Repo is live now.

Imposter Syndrome Didn't Go Away. It Got Quieter.

Daniel Nwaneri — Thu, 26 Mar 2026 13:05:44 +0000

I noticed something last year. The imposter syndrome posts disappeared.

Not gradually. They were everywhere — "I've been coding for three years and I still Google how to center a div," "just got promoted to senior and I have no idea what I'm doing," threads with thousands of likes, people in the replies saying me too, me too, me too. Then the LLMs arrived, and the posts stopped. I thought maybe the tools cured it. That we'd finally found the thing that made everyone feel competent.

I was wrong. The feeling didn't go away. It just changed shape.

The old imposter syndrome had a specific texture. You knew what you didn't know. You couldn't center a div, you'd never touched Kubernetes, you were faking it in standups about GraphQL. The gap was legible. You could name it, study it, fill it. That legibility is what made the posts shareable. "I don't know X" is a sentence you can say out loud.

The new version is harder to name. You shipped the feature. The tests pass. Your manager is happy. But when someone asks you to walk through the implementation, something is off. You can narrate what the code does. You can't always explain why it's structured the way it is, what the model assumed, where it would break under pressure. The code is yours the same way a house is yours when you hired the contractor. You own it. You don't know every decision that went into the walls.

Engineering culture has long tied ownership to authorship. You wrote the code, therefore you understood it. You understood it, therefore you were responsible for it. That chain held for decades. AI broke it — not dramatically, not all at once, but consistently enough that a new kind of doubt has moved in where the old one used to live.

The data is starting to catch up to what developers already feel.

METR previously published a paper which found the use of AI tools caused a 20% slowdown in completing tasks among experienced open-source developers — a finding strange enough that they ran a follow-up study. That follow-up ran into its own problem: developers refusing to participate because they did not wish to work without AI. 30% to 50% of developers told researchers they were choosing not to submit certain tasks because they didn't want to do them without AI.

Read that twice. Not "AI makes me faster." Not even "AI makes me better." Developers who cannot or will not attempt the work without the tool present. That's not productivity. That's dependency.

Luciano Nooijen noticed this before the research did. He used AI tools heavily at work, stopped for a side project, and hit a wall. "I was feeling so stupid because things that used to be instinct became manual, sometimes even cumbersome." The instincts didn't fail slowly. They went quiet.

AI coding tools can make you more productive. They can make you feel more confident. They can also produce developers who don't understand the context behind the code they've written or how to debug it.

Stack Overflow called this "the illusion of expertise." I'd call it something slightly different. It's not that the expertise is fake. It's that the path that usually builds expertise — the struggle, the failure, the iteration — got shortened. When AI generates code without the developer engaging deeply with the implementation, they skip over all of those learning iterations. The developer doesn't struggle with the problem, doesn't try multiple approaches, doesn't experience the failures that build intuition.

The old imposter syndrome was painful but self-correcting. You felt like a fraud, so you studied. You filled the gap. The new version doesn't have an obvious gap to fill. The code shipped. You're a senior developer with a good job and passing tests and no visible evidence that anything is wrong. The doubt is quieter. That's what makes it harder.

We're living in the most empowering time to be a developer. The barrier to building things has never been lower. And yet, I've never felt less sure of my own skills.

That's Pranav Reveendran, writing in December. He's not alone. A 2025 survey by Perceptyx found a "confidence gap" where 71% of employees use AI, but only 35% of individual contributors feel they understand it well enough. The adoption curve went up. The confidence curve didn't follow.

This is what the posts were about, when people still wrote them. Not "do I belong in tech?" but "do I understand what I'm building?" The first question had a community around it. Thousands of replies, conferences, entire career tracks built around addressing it. The second question doesn't have a community yet. It's the thing people say in DMs but not in threads. It's the thing I've heard from developers who've been building for years: I know how to use the tools. I'm not sure I know the work anymore.

I don't think this resolves neatly. The tools aren't going away and the productivity is real and I'm not arguing for anyone to stop using them. I use them. I built most of Foundation's evaluator with AI assistance and I'd do it again.

But I think the silence is worth naming. The imposter syndrome posts didn't stop because the feeling stopped. They stopped because the feeling changed into something that's harder to share. "I don't know how to center a div" is embarrassing but legible. "I shipped a feature I can't fully explain" is a different kind of statement. It implicates the work, not just the person. It's harder to say me too to.

The old imposter syndrome asked: am I good enough?

The new one asks: is the work mine?

That's a harder question. And so far, it's mostly going unasked.

The Future Is Not the Agent Using a Human Interface

Daniel Nwaneri — Mon, 23 Mar 2026 13:44:20 +0000

Carl Pei said it at SXSW last week. His company, Nothing, makes smartphones. He stood on stage and told the room: "The future is not the agent using a human interface. You need to create an interface for the agent to use."

A consumer hardware CEO publicly declaring that the product category he sells is the wrong shape for what's coming. That's not a hot take. That's a company repositioning before the floor disappears.

The room moved on. Most of the coverage focused on the "apps are dying" framing. That's the wrong thing to argue about. Apps are not dying next Tuesday. The question worth sitting with is quieter and more immediately useful: what does it mean that the thing we've been building — apps designed for human eyes, human fingers, human intuition — is increasingly being navigated by something that has none of those?

For thirty years, software design started with a user. A person with a screen, a mouse or finger, a working memory of roughly four things, limited patience, inconsistent behavior. Every design decision flowed from that starting point. Navigation was visual because users have eyes. Flows were linear because users lose context. Confirmation dialogs exist because users make mistakes and need to undo them.

Those constraints weren't arbitrary. They were load-bearing. The entire architecture of how software works was built around the specific limitations and capabilities of a human being sitting in front of it.

Agents don't have eyes. They don't navigate menus — they call functions. They don't get confused by non-linear flows — they parse structured outputs. They don't need confirmation dialogs — they need permission boundaries defined at initialization, not presented as popups mid-task.

When an agent tries to use an app designed for a human, it's doing something like what Pei described: hiring a genius employee and making them work using elevator buttons. The capability is real. The interface is friction. The agent scrapes what it can, simulates the clicks, and works around the design rather than with it.

This works. Barely. Temporarily.

The split is already visible in how developers describe their workflows.

Karpathy, in a March podcast, described moving from writing code to delegating to agents running 16 hours a day. His framing: macro actions over repositories, not line-by-line editing. The unit of work is no longer a file. It's a task.

Addy Osmani wrote about the same shift at the interface level: the control plane becoming the primary surface, the editor becoming one instrument underneath it. What used to be the center of developer work is becoming a specialized tool for specific moments — the deep inspection, the edge case, the thing the agent got almost right and subtly wrong.

These descriptions share a structure: something that was primary becomes secondary. Something that was implicit becomes explicit. The developer who used to navigate the editor now supervises agents. The app that used to be the product now needs to also be a legible interface for non-human callers.

Here's what that means practically, for anyone building software right now.

The apps built for human navigation will still work for humans. That's not going away. But increasingly, those apps will also be called by agents acting on behalf of humans — booking the flight, filing the form, triggering the workflow. And when the agent calls your app, it doesn't navigate. It looks for a contract: what can I call, what will you return, what happens when I'm wrong.

Most apps don't have that contract. They have a UI. They have an API if you're lucky. But the API was designed as a developer convenience, not as a primary interface for autonomous callers. The rate limits assume human usage patterns. The error responses assume a developer reading them. The authentication assumes a human with a session.

None of those assumptions hold for agents.

The developers who see this clearly are already building differently. Not abandoning the human interface — users still need screens, still need control surfaces, still need to understand what's happening on their behalf. But building the agent interface in parallel. Structured outputs. Explicit capability declarations. Error responses designed to be parsed, not read. Permission boundaries that don't require a human to click through them.

The spec is where this shows up first.

A product spec written for human implementation describes features. What the user sees. What they can do. How the flow works. A spec written for agent implementation describes contracts. What the system accepts. What it returns. What it guarantees. Where the boundaries are.

The [ASSUMPTION: ...] tags in spec-writer exist because that boundary — between what was specified and what the agent decided — is where agent implementations go wrong. Not in the happy path. In the assumptions that weren't stated because a human developer would have asked a clarifying question.

An agent doesn't ask. It fills the gap with whatever its training suggests is most plausible. If the assumption was wrong, you find out in production.

The spec that makes agent implementation reliable is the one that surfaces the assumptions before the agent starts. Not because agents are unreliable — they're remarkably capable within a well-defined contract. But because the contract has to be explicit in a way it never had to be when the implementer was human and could pick up the phone.

Carl Pei's argument is about device form factors. The smartphone built around apps and home screens doesn't fit a world where agents intermediate between intention and execution.

The same argument applies to every level of the stack.

The database schema built for human-readable queries. The API designed for developer convenience. The workflow tool that requires clicking through five screens. The SaaS product whose entire value lives in a visual interface with no programmatic equivalent.

None of these are broken today. They will accumulate friction as agent usage grows — the same way command-line tools accumulated friction when GUIs arrived, the same way desktop software accumulated friction when everything moved to the web.

The difference is pace. The GUI transition took a decade. The web transition took another. The agent transition is compressing.

The developers who will build the next layer are already asking a different question. Not "how does the user navigate this?" but "how does the agent call this?" Not "what does the confirmation dialog say?" but "what are the permission boundaries at initialization?" Not "how do we make the flow intuitive?" but "what does the contract guarantee?"

These are not new questions. They're the questions API designers have always asked. What's new is that they now apply to everything — not just the backend service, but the whole product. The human interface remains. It becomes one layer, not the only layer.

The future is not the agent using a human interface. The future is building interfaces designed for both — and knowing which decisions belong to which layer.

The developers who get that distinction early will have built the right foundation before it becomes mandatory. The ones who don't will spend the next three years retrofitting contracts onto systems that were never designed to have them.

That's the same pattern as every previous transition. The only thing that changes is how much runway you have before the friction becomes a crisis.

Right now, you still have some.

Your Agent Is Making Decisions Nobody Authorized

Daniel Nwaneri — Thu, 19 Mar 2026 18:02:23 +0000

A quant fund ran five independent strategies. Every one passed its individual risk limits. Every quarterly filing looked reasonable in isolation. But all five strategies were overweight the same sector.

Aggregate exposure exceeded anything anyone had authorized — because the complexity budget was scoped per-strategy, never cross-strategy. No single decision was wrong. The aggregate outcome was unauthorized. Nobody was watching the right scope.

This is governance debt. It accumulates invisibly. Each decision individually correct. Aggregate outcome unauthorized. The failure only surfaces when the sector moves against the fund and the concentration nobody explicitly built turns out to have been built anyway — one individually-reasonable decision at a time.

The token economy has no accounting entry for this. Nothing on the infrastructure bill reflects what happened. The cost appears later, in a different quarter, a different system, a different team's incident report.

Two Clocks

Every agent system has at least two clocks running simultaneously.

The execution clock measures computation — tokens consumed, API calls made, latency per response. This is what most monitoring systems track. It is visible, quantifiable, and entirely the wrong thing to govern.

The governance clock measures consequences — decisions made, thresholds crossed, exposures accumulated. This clock runs at a fundamentally different speed than execution. It is also running on a fundamentally different metric.

Execution counts tokens. Governance counts consequences.

Most agent architectures try to govern at execution layer granularity. They instrument every API call, set token budgets, alert on cost spikes. The result is a monitoring system that costs more attention than the decisions it is protecting. The governance layer becomes noise. Worse than useless — it actively degrades decision quality by demanding attention on non-material changes.

The fix is not better monitoring. It is a different master clock.

The Master Clock

Vic Chen builds institutional investor analysis tooling around quarterly SEC filing data. The production domain he works in — 13F analysis, the quarterly disclosures hedge funds file showing their equity positions — has solved the governance clock problem in a way most software systems haven't.

The expensive thing in 13F analysis is not parsing the filings. That part is mechanical. Run the filing through the pipeline, extract the positions, compare against the previous quarter. Cheap. Deterministic. Fast.

The expensive thing is deciding which signals actually warrant human attention. Every false positive costs analyst time. Every false negative costs trust in the system. That judgment call does not map cleanly to token costs. You cannot optimize it by switching to a cheaper model or batching the API calls. The bottleneck is not computation. It is consequence.

The master clock in Vic's system is anchored to SEC reporting cadence — filing deadlines, amendment windows, restatement periods. The quarterly 13F disclosure cycle is one of the few externally-anchored materiality signals in finance. It already encodes a judgment: this change was significant enough to report.

When a fund flips a position intra-quarter and back again, that event never surfaces in the filing. This is not a detection failure. The governance architecture is working correctly. An intra-quarter flip that reverses before the filing deadline was not a conviction change. The master clock — anchored to external cadence rather than internal computation — correctly filters it out.

This is filtering by design rather than detection by volume. The governance layer is not trying to catch everything. It is anchored to what the domain has already decided matters.

When the system detects an NT 13F — a late filing notification — or an amendment chain exceeding two revisions, the complexity budget automatically expands. Slower parsing. Deeper cross-referencing. Human-in-the-loop checkpoints. The external signal triggers the governance response because the external signal already encodes the materiality judgment.

The master clock is not a timer. It is a materiality filter.

The Over-Calibration Trap

The first failure mode most governance architectures hit is over-calibration.

Early 13F monitoring systems flagged every rounding discrepancy between a fund's 13F and their 13D as potential drift. The noise-to-signal ratio made the governance layer worse than useless. Analysts were spending attention on non-material changes. The system meant to improve decision quality was degrading it.

Vic's framing of the fix: governance cost should scale with expected loss from undetected drift, not with the volume of changes observed.

A $50M position shift in a mega-cap is noise. A $50M position shift in a micro-cap is a thesis change. Same signal magnitude. Completely different materiality. The governance architecture has to encode that domain knowledge or it cannot distinguish between them.

This is where the "significant drift threshold" becomes practical rather than theoretical. Without it, you are building a governance layer that is perpetually anxious — flagging everything, earning attention for nothing, training operators to ignore alerts. With it, the governance layer fires on what matters and stays quiet on what does not.

The threshold is not a technical parameter. It is a domain judgment encoded into architecture.

Governance Debt

Back to the five-strategy fund.

The token economy version of that failure is identical in structure. An agent that makes two expensive API calls but expands the decision space by introducing correlated hypotheses is under token budget and creating governance debt simultaneously. The cost does not appear on the infrastructure bill. It appears when the downstream decision fails in ways that trace back to the expanded hypothesis space nobody reviewed.

An agent that makes 100 cheap API calls but narrows a decision space from 5,000 options to 3 is adding value regardless of token cost. An agent that makes two expensive calls but introduces unreviewed complexity is accruing debt regardless of token efficiency.

The decision economy is the accounting system that captures the difference.

Three signals that matter in the decision economy and do not appear in token accounting:

Decision scope. How many downstream choices does this agent action constrain or enable? An action that narrows the decision space is value-generating. An action that expands the decision space without corresponding resolution is debt-generating. The token cost of both can be identical.

Consequence materiality. Not all decisions are equal. The governance clock runs faster when the expected loss from undetected drift is higher. A rounding discrepancy in a mega-cap position and a position reversal in a micro-cap both generate the same token cost to detect. Their materiality is orders of magnitude apart.

Authorization scope. Was this decision within the scope of what was explicitly authorized, or did it cross a threshold that required a decision nobody made? Governance debt accumulates at the boundary between authorized and implicitly permitted.

None of these signals are invisible. They require a different accounting system — one that tracks consequences rather than computation, materiality rather than volume, authorization scope rather than token spend.

The Rate Problem

Static agents accumulate governance debt slowly. An agent that makes the same decisions in the same scope every session creates predictable exposure. You can audit it. You can scope the complexity budget correctly once and leave it.

An agent with memory that promotes knowledge automatically accumulates governance debt at the rate the memory compounds. Each session, the promoted knowledge expands the hypothesis space the agent operates in. Each expansion is individually reasonable. The aggregate effect is an authorization scope that widens faster than anyone is reviewing it.

The governance layer has to keep pace with the learning rate or it falls further behind with every session — not linearly, but exponentially.

This is why the evaluator architecture in Foundation anchors promotion criteria to human judgment rather than automating it. Not because automation is wrong in principle. Because the governance debt from unchecked automatic promotion compounds at the same rate as the knowledge base — and the rate is the problem, not any individual promoted insight.

The master clock that works for 13F analysis works for agent memory for the same reason: it is anchored to external materiality judgment rather than internal computation speed. The filing cadence enforces a review interval that the domain has already validated. The human promotion gate enforces a review interval that the knowledge system needs.

Both are the same governance architecture. One is thirty years old. One is being built now.

What the Decision Economy Actually Measures

Token costs are visible on the infrastructure bill. Governance debt is not.

This asymmetry creates predictable incentives. Teams optimize for what they can measure. Token spend gets instrumented, budgeted, alerted. Governance debt accumulates until it manifests as a production failure, a trust breakdown, a concentration exposure nobody authorized across five individually-reasonable decisions.

The token economy prices execution correctly. It is the wrong accounting system for judgment costs because judgment costs do not appear until downstream consequences surface — often in a different quarter, a different system, a different team's incident report.

The precedent that prices judgment correctly is not a token count. It is a record of what decisions were made under what conditions, what thresholds were crossed, what downstream exposure was created, and whether any of it was explicitly authorized.

That record is what makes governance debt visible before it becomes a production problem.

Execution counts tokens. Governance counts consequences.

The decision economy is what you build when you understand the difference.

This is part of a series on what AI actually changes in software development. Previous pieces: The Gatekeeping Panic, The Meter Was Always Running, Who Said What to Whom, The Token Economy, Building the Evaluator, I Shipped Broken Code and Wrote an Article About It.

The governance debt examples and 13F production evidence in this piece draw from analysis by Vic Chen, who builds institutional investor analysis tooling around quarterly SEC filing data. The five-strategy concentration example is his.

I Built a Skill That Writes Your Specs For You

Daniel Nwaneri — Tue, 17 Mar 2026 11:35:53 +0000

Julián Deangelis published a piece this week that hit 194k+ views in days. The argument: AI coding agents don't fail because the model is weak. They fail because the instructions are ambiguous.

He called it Spec Driven Development. Four steps: specify what you want, plan how to build it technically, break it into tasks, implement one task at a time. Each step reduces ambiguity. By the time the agent starts writing code, it has everything it needs — what the feature does, what the edge cases are, what the tests should verify.

The piece is right. The problem is the workflow takes discipline most sessions don't have. Under deadline pressure, the spec step disappears and you're back to prompting directly.

So I built a skill that does the spec-writing for you.

The silent decisions problem

Julián's example stuck with me:

"Add a feature to manage items from the backoffice."

The agent reads the codebase, picks a pattern, writes the feature. At first it looks fine. Then you click "add item" again and it inserts the same item twice. All the assumptions you thought were obvious were never in the prompt.

Which backoffice — internal or seller-facing? Should the operation be idempotent? Admin-only or all users? Which storage layer? Which error handling strategy?

Each one is a silent decision. The agent guesses. Some guesses are right. Some are wrong. And you don't find out which until the feature is in production behaving in ways you didn't expect.

The spec is what makes those decisions visible before the agent guesses. But writing a spec from scratch, for every feature, before every session — that's the friction that kills the habit.

Generate first, flag assumptions inline

The standard approach to spec tools is Q&A: the tool asks clarifying questions before generating anything. What's the user role? What's the auth model? What should happen on error?

The problem with Q&A is you have to know what you don't know. If you knew exactly what questions to ask, you'd be close to having the spec already.

spec-writer takes a different approach. It generates the full spec immediately and marks every decision it made that you didn't specify:

Given an authenticated user requesting an export
When the export contains more than 1,000 rows [ASSUMPTION: async for large exports]
Then the export is generated asynchronously and the user is notified by email

At the end, every assumption is collected into a prioritized list:

## Assumptions to review

1. Async generation for exports over 1,000 rows — Impact: HIGH
   Correct this if: your order volumes are low and synchronous is fine

2. Date range filter is required — Impact: MEDIUM
   Correct this if: the first version should export all orders with no filtering

Correcting a draft is faster than answering questions cold. The [ASSUMPTION: ...] tags show you exactly where the agent would have guessed wrong — before it guesses. That's the value. Not the spec itself. The visible assumptions.

A real example

I ran it on something I'm actually building — CLI capture for Foundation, my knowledge commons project. Foundation currently captures Claude.ai browser conversations via a browser extension. Claude Code sessions live in ~/.claude/projects/ and disappear after 30 days. I needed to capture those too.

The prompt:

/spec-writer Add CLI capture for Claude Code sessions stored in ~/.claude/projects/

Here's a slice of what came back:

From the spec:

Given a developer with Claude Code sessions in ~/.claude/projects/
When they run the Foundation CLI capture command
Then a list of uncaptured sessions is displayed, sorted by most recent first

Given a session already in Foundation
When the developer runs capture again
Then that session does not appear in the review list

Given a malformed .jsonl file
When the capture command processes it
Then an error is logged for that file and processing continues on remaining sessions

From the plan:

CLI capture runs locally — it needs to read the local filesystem, which 
Cloudflare Workers cannot do. [ASSUMPTION: CLI capture is a local Node.js 
or Bun script that calls the Foundation API to insert sessions, rather 
than a Worker itself]

That assumption stopped me. I hadn't thought through the architecture split — Foundation runs on Cloudflare Workers, which can't read local filesystems. The skill surfaced it before I'd written a line of code.

The assumptions summary:

1. CLI capture is a local script calling the Foundation API, not a Worker
   Impact: HIGH
   Correct this if: you want a purely serverless approach

2. Manual curation before capture, not automatic bulk import
   Impact: HIGH
   Correct this if: you want automatic background capture

3. Session ID from .jsonl filename is the deduplication key
   Impact: MEDIUM
   Correct this if: session IDs are stored differently in your schema

4. No sensitive data scrubbing in v1
   Impact: MEDIUM
   Correct this if: your sessions contain credentials or keys

Four assumptions, two of them high-impact. The architecture one I would have hit mid-implementation. The sensitive data one I wouldn't have thought about until someone complained.

That's the value. Not the spec itself. The visible assumptions.

How it fits into SDD

spec-writer gets you to Spec-First immediately, with no ceremony. One command, full output, correct the assumptions, hand to the agent.

Julián describes two levels beyond that. Spec-Anchored: the spec lives in the repo and evolves with the code. Spec-as-Source: the spec is the primary artifact, code is regenerated to match. If you want to move toward Spec-Anchored, save the output to specs/feature-name.md in your repo. The skill produces something worth keeping.

The methodology is Julián's. The skill is the friction remover.

Install

mkdir -p ~/.claude/skills
git clone https://github.com/dannwaneri/spec-writer.git ~/.claude/skills/spec-writer

Then:

/spec-writer [your feature description]

Works across Claude Code, Cursor, Gemini CLI, and any agent that supports the Agent Skills standard. The same SKILL.md file works everywhere.

The repo is at github.com/dannwaneri/spec-writer. The README has the full output format and a worked example.

The agents are getting better at implementing. The bottleneck was always specification — knowing what to build precisely enough that the agent doesn't have to guess. spec-writer doesn't remove that requirement. It makes it faster to satisfy.

The spec isn't the output. The assumptions are.

Built on the Spec Driven Development methodology — operationalized by tools like GitHub Spec Kit and OpenSpec. Julián Deangelis's writing on SDD at MercadoLibre was the direct inspiration.

Other skills: voice-humanizer — checks your writing against your own voice, not generic AI patterns.