Nodding along to AI work feels like review. Two months ago, 49 of my pieces passed three automatic checks (prose style, format and search) with no flags. A reader who was not in my meetings still could not follow one of them.

Then a draft I asked a model to polish passed every check again. It lacked every embed, every tagged creator and the short summary. Each check looked for what was wrong. None asked what was missing.

Work you must re-check by hand each week is rented work, because you pay again and never own it. Daniel Kahneman's book Thinking, Fast and Slow names the two modes behind it. System 1 is fast, automatic thinking. System 2 is slow, effortful thinking. AI supplies the fast kind in seconds. Teams moving to AI native work must supply the slow kind themselves.

The short version.

• AI is System 1. It answers in seconds and sounds sure.

• Skimming its answer is fast thinking checking fast thinking.

• Slow thinking must happen twice. Write the definition of good first, then review the output against it.

• Every miss becomes one new line in the file the AI reads next.

• Start with one task and a short checklist. It takes under 30 minutes.

Reading AI Output Is Not System 2 Thinking

The puzzle Kahneman made famous takes 10 seconds. A bat and a ball cost $1.10 together. The bat costs $1 more than the ball. What does the ball cost?

The answer that jumps out is 10 cents. That jump is System 1. The correct answer is 5 cents. You only reach it when you slow down.

AI sounds sure, and that tells your brain the answer is fine. Kahneman found that System 2 is lazy, so it often approves what System 1 offers.

A Wharton study named the result cognitive surrender, which means people accept what the AI says, even when it is wrong. says the first cost is that "you let more wrong answers pass as correct".

Advait Sarkar's TED talk asks how to keep AI from killing your critical thinking.

A Judge Model Is Another System 1

The usual fix is a judge model, a second model that grades the first. It scales well and still thinks fast.

names the flaw: "the judge tends to favor responses that are generated by itself".

A NeurIPS paper found the same effect. Models scored their own text higher, and human raters judged the same texts equal.

Slow thinking needs a mechanism the output cannot sway. A definition of good written before the output exists is the first. A test that runs the code is another. A list of required parts is the third.

Write the Definition of Good Before You Prompt

The first slow step runs before the AI does. Write a short checklist with three parts.

• Good looks like. What a right result shows.

• Bad looks like. Real misses from past runs.

• Evals. Yes or no checks you run on every output. Teams use this word for scored checks on AI work.

The evals are the part my checks lacked. They only hunted for flaws. A draft missing its embeds has no flaws to find, so it scored zero. An eval that asks "is the video there?" fails a draft for what it lacks.

puts the order plainly: "you need to know what the product is supposed to do, who will use it, and what a successful result looks like".

says a judge needs the same input. You must "clearly define what success and failure look like" for it.

@realmadhuguru says teams treat evals as a late QA step, when evals are the product spec.

Write the checklist before you see any output, so the output cannot set your standard. Bad inputs cause AI slop, meaning machine-shaped prose a checker can measure.

Every Correction Must Leave One Rule Behind

The second slow step comes after the output. Review it against the checklist, never by feel. Each miss becomes one new line.

This loop is how a person becomes an expert. Kahneman and Gary Klein agreed that expert intuition earns trust in a regular environment with fast, honest feedback.

The model does not carry your review to the next run. The file it reads next time does. The checklist makes the environment regular, and each review is the feedback. Put it in the file your tool reads first, as this post shows.

When a rule stops failing, move it into a test or a judge model. Jev is a model built for System 1 judgments that returns a choice and a score for each question you ask. That puts System 2 inside System 1, and the speed stays.

A review that leaves nothing behind is rented work. You pay for it again next week.

I have not run a controlled test of this loop. It rests on two failures of mine. One added a clarity check, and the other added a gate that fails on what is missing. The Wharton label is contested. warns it "sounds like a diagnosis, even though the underlying mechanisms remain poorly specified".

Tonight, Review One Task and Leave One Rule

Below is the checklist for an AI image task. Swap in the task your team re-prompts most and fill it in 20 minutes. Run it once and review it against the list. Write the first miss as one new line, then run it again.

TASK: product photo of a ceramic mug for a shop page

WHAT       GOOD                      BAD
Shape      one handle, round rim     extra handles, warped rim
Color      matches the brief         washed out or off color
Text       none                      fake logo, garbled words
Backdrop   plain, soft shadow        busy, props steal the eye
Framing    mug fills the frame       cropped or tiny

EVALS, run on every image. Any "no" fails it.
1. Is there exactly one handle?
2. Is the color the one in the brief?
3. Is the image free of text and logos?
4. At thumbnail size, is it clearly a mug?
5. Is the whole mug inside the frame?

AFTER EACH RUN: add one line per fail

A working checklist means the same miss stops returning.

Leave a comment

I asked Claude how long a small side project would take. It said two months. I laughed out loud, alone, at my desk. That is what broken AI project time estimates look like. The habit behind them is judging AI work by the clock.

Two months of what?

• Claude doesn't sleep.

• Claude has no designer to wait on.

• Claude has never once taken a weekend.

Two months is a number a person gives you. A model never earned that number, it borrowed it. And every model I've used does the same borrowing, because it has no other number to reach for.

You do the same borrowing. You expect AI work to take as long as human work, and you read a long timeline as serious work. I checked both instincts against the research.

The short version.

• Claude Code quoted 3 weeks for a task that took 126 minutes.

• People read time as quality, but a 2026 study found that longer AI generation time raised perceived effort and left quality ratings flat.

• People also cut credit for AI-assisted work, even when the output is identical.

• The fix is a five-rule CLAUDE.md block, a timed build, and checks in place of the clock.

Claude Code Quotes Weeks for Work That Takes Minutes

Ryan Hoover watched Claude Code reply that the implementation would take 3 weeks. He posted the reply on 23 July 2026 with the line "AI, they're just like us." Then he added an update. It took 126 minutes. Digg's page for the thread holds both posts.

Greg Kamradt sees the same gap whenever a model quotes hours. Models carry old human timescales, he wrote, because they trained on old human data. When one says a few hours, he expects "30 seconds and a few tool calls."

Greg Kamradt, creator of the Needle in a Haystack test, put the pattern in one post.

Kun Chen ran the same test on camera. He asked Claude to estimate a 3D first person shooter that runs locally with AI enemies. The answer came back in days, weeks and months. Then he asked an agent to build it. He says a playable version arrives in a few minutes, because he has run the test many times.

Kun Chen, a former L8 principal engineer who worked at Meta and Microsoft, starts the test at 12:58.

His diagnosis is short. The models trained on human data, so they quote what a typical human developer would quote. He puts it this way: AI does not yet seem to know that it codes faster than humans.

Models Default to Human Timelines Because That's All They've Seen

Every timeline the model has ever read came stapled to human constraints. GitHub issues say "targeting next sprint." Blog posts describe "a weekend hackathon." Job postings assume 8-hour days, 5-day weeks, a commute, a lunch break, and a standup.

Almost no training text records how fast a system with no body and no sleep cycle finishes a task. That example is missing from its training data.

reaches the same diagnosis for Claude Code: "Claude has essentially been trained on human estimates of time."

So it does what it always does when a category of experience is missing. It grabs the nearest pattern, and that pattern is a human describing human work.

The model treats those constraints as facts about software in general. They are really facts about the humans who write software.

My two months quietly assumes four of them:

• Nobody works evenings.

• A weekend interrupts the work.

• Code review adds a wait.

• The art asset waits on a teammate.

None of that applies to the model doing the work. Its real bottlenecks are tool call latency and context window size. The context window is the amount of text a model can hold at once. The model never measured two months. It copied the number from every project retrospective it read.

A Wrong Estimate Also Steers the Model Toward Cheap Designs

The number does damage beyond the number. Kun points to what happens when the model chooses between technical options.

The model assumes the expensive options cost more than they do for an agent. So it picks the cheap one. He says those picks are often low quality, hard to scale or hard to maintain.

You never see that choice as a mistake, because no number sits next to it to argue with.

You Believe the Number Because You Count in Sprints Too

The model is not the only one on a human clock. You are on it too.

Two months sounds right to you for the same reason it sounds right to the model. Both of you learned what software takes from people. So you accept the number, shrink the scope to fit it, or never start.

Asana planned on the same clock. The company says removing its Enzyme testing system was expected to take at least 5 years, with a staffing estimate near $6 million.

Codex finished the job in about 2 weeks, and a human reviewed every change. Wes Roth reported the numbers, and they come from Asana, so read them as the company's claim.

Wes Roth reported the Asana numbers on X.

Even the best-known chart of AI progress counts in human time.

defines his version this way: "The benchmark measured the amount of human work that an AI can do with at least a 50% chance of success from a single prompt."

His numbers cover one book cycle. The human work a model completes at 50% success grew from 4 minutes to 17 weeks.

Ethan Mollick, who writes the One Useful Thing newsletter, shared the numbers in October 2026.

The yardstick says how big a task is for a person. It does not say how long the model takes. A reader who skims the chart can still walk away with the human clock in their head.

Kun does not accept the number. He runs the build. His trust comes from repetition, because he has run the test so many times.

Your gut has no run history with agents. It falls back on the calendar it learned from people. This is my claim, and the evidence above is anecdote. None of it is a controlled study.

The Clock Predicts Human Quality and Misses AI Quality

You also read hours as quality. Psychologists call that habit the effort heuristic. Kruger and colleagues tested it in 200400065-9). Participants rated a poem, a painting and a suit of armor higher on quality, value and liking when they believed it took more time and effort.

In the painting test, the story changed from 4 hours to 26 hours and the painting stayed the same. The ratings rose with the hours.

names the same shortcut in AI video: "so much of what makes something interesting is implied effort."

Treat that as a moderate effect, not a law. A 2023 replication with 1,405 participants backed the painting result and failed on the poem. A retest of the poem split. Quality and liking held, and monetary value did not.

Now swap the worker for an AI. The rule changes in three ways.

Time raises perceived effort and nothing else. A 2026 pair of pre-registered studies showed AI artworks with different generation times. Longer times raised perceived effort. They did not raise liking, beauty, quality or monetary value.

A slow algorithm looks worse. A 2020 paper in a decision science journal ran seven studies. People rated slowly generated algorithm predictions as less accurate. Slow human predictions got rated as more accurate. For algorithms, perceived effort did not track quality.

AI help costs credit. Across 11 studies, participants cut pay for workers who used AI, even with output quality held constant. In another experiment, 1,026 engineers reviewed identical Python code. They rated the engineer 9% lower on competence when they believed AI helped.

gives the engineering version of the same gap: "Generating a beautiful chart takes about the same effort for an AI as generating an ugly one."

So the verdict on the bias has two halves. People do read time as quality for human work, though weakly. They do not extend that credit to AI. Longer AI time earns no quality, and AI help earns less credit.

For an agent, the hours on the clock say little about the quality of the diff.

These studies measure judgments, not output. None of them shows that fast agent work is good. They show that the clock is a bad way to judge it.

One Rule and One Timed Build Replace the Clock

Kun's fix is one line in his global memory file, the file loaded into every agent session. His file runs 27 lines. The line tells the agent to give development cost little weight when it chooses between technical options.

The block below is mine. It keeps his rule and extends the idea to estimates. The agent names its own constraints before it gives you a number.

Paste it into CLAUDE.md or your system prompt:

## Timeline and Effort Estimates

When estimating how long a task will take for you (the AI) to complete,
do not default to human work patterns. Your training data overwhelmingly
describes human-paced work: sprints, days off, meetings, context switching,
sleep. You do not have these constraints. Before giving any timeline:

1. State your actual constraints for this task: context window limits,
   tool call latency, number of files or lines involved, verification
   steps required. Do not cite "team velocity" or "sprint capacity"
   unless a human is actually doing that part of the work.
2. Distinguish "how long would a human team take" from "how long will
   you take" as two separate numbers if both are relevant. Never merge
   them into one estimate by default.
3. Express your own estimate in hours or tool call rounds, not in days
   or weeks, unless the task is genuinely bottlenecked on something
   outside your control (human review, external API rate limits,
   a dependency you're waiting on).
4. If you're uncertain, say what specifically is uncertain (ambiguous
   scope, unverified assumption, missing test coverage) instead of
   padding the number "to be safe" the way a human engineer would.
5. When choosing between technical options, give development cost
   little weight. An option that is expensive for a human team can be
   cheap for you.

An hour figure from an agent is still a guess. The block changes the inputs to the guess. It does not make the guess true.

names the cost most estimates leave out: "The cost of verifying that the work is correct has moved much less."

Put verification time inside the number. Rule 1 of the block asks the agent for it.

So check the guess with a build. Tonight, pick one task you would estimate in days. Ask the agent for the number with the block in place. Then run the build and write down the real time.

Then judge the result by its checks. Read the diff and run the tests. The time it took tells you nothing about whether it works.

The gap between the two numbers is the estimate error for your agent and your tasks.

Leave a comment

jafgen --years 6 fails with No such option: --years. FirstRun, my agent that tests agent quickstarts, hit it at step 10 of the dbt DuckDB guide on 10 October 2026. The guide was broken on the day it merged.

I built FirstRun solo at neatHack, the neatlogs hackathon. It runs a quickstart in a fresh container, finds the first broken step, and proves the fix with a second clean run.

runs the same kind of loop on design systems with Playwright: "Full AI agents that explore, write, and fix tests autonomously."

The docs bugs were the easy part. The harder bugs sat inside my agent, and its own reports hid them. Trusting an agent's report on itself is vibes, which means using a tool without checking its output. So FirstRun runs on one rule. A fix counts as verified only when a model-free rerun in a fresh container passes.

In short:

• neatlogs raised an incident against my agent, at 52.8 times the baseline.

• A planner fix cut invented steps from 2 of 4 runs to 0 of 52.

• The verify step blocks every model call, so the agent cannot grade its own fix.

• A bisect named jafgen 0.4.6 as the release that broke the dbt guide.

• FirstRun fixed 16 docs pages, and contribution rules held back 3 PRs.

The 2:54 demo video covers the dbt break, the doc audit, the neatlogs incidents and the cost model.

FirstRun Reads, Plans, Runs, Fixes and Proves

Each run is one loop with five parts.

1. Read. Firecrawl pulls the docs page.

2. Plan. A Claude planner copies the shell commands into steps.

3. Run. Each step runs in a fresh python:3.11-slim container.

4. Fix. Recovery classes a failure and patches the command, with 3 attempts at most per step.

5. Prove. A second container reruns the patched steps with no model calls.

Each run is one neatlogs trace, with a span for each part, so a bad run shows where it went wrong.

Version 1 Passed Steps That Proved Nothing

I ran v1 on 4 quickstarts with recovery off. Several of its passes were fake.

names the same trap in spec-driven work: "The code passes tests, but it does NOT behave the way you want."

• A placeholder passed as a step. Chroma step 2 was true, a command that does nothing and exits 0.

• A fake secret passed too. export OPENAI_API_KEY='sk-...' exits 0 and proves nothing.

• The planner skipped the steps that need an API key, which are the steps most likely to break.

• The plan changed between runs. The same neatlogs page gave 4 steps, then 3 steps, 5 minutes later.

• 9 of 16 steps checked only the exit code, so an error that exits 0 would pass.

Each mistake made the agent's report look better than the run was.

An Incident Report Named My Agent as the Cause

neatlogs raised an incident on FirstRun itself. It counted 25 "Execution Failed" detections against a baseline of 0.5, across 10 traces.

The investigation named a root cause at 66% confidence, which neatlogs labels medium. A step ran a cd such as cd my-project, and the file check after it ran from inside the new folder. So the agent failed steps that worked.

Commit 2de852f is the fix, and it changed two things. A file check now looks from the folder where the step started. Every step also runs with set -e now, because dbt step 3 is five lines and its failed pip install passed on the exit code of the last line.

MkDocs went from a false fail at 14:58 IST to verified 9 of 10 at 15:40 IST.

Watch out: A last line that exits 0 says nothing about the four lines above it. Run every multi-line step with set -e.

A Second Investigation Caught the Planner Inventing Steps

At 14:10 IST I made two neatlogs detections. A detection is a saved rule that flags matching spans. One of them, "planner invented a step", flagged the planner spans of 3 v1 runs.

neatlogs Investigate traced the invented steps to the planner prompt. It proposed a stricter prompt that copies only the commands the docs write.

A headless Claude Code session read the detection through the neatlogs MCP (Model Context Protocol) server, which lets an agent query neatlogs. It applied the fix in commit 3ca6f11. Invented steps fell from 2 of 4 v1 runs to 0 of 52 runs after the fix.

The Verify Step Blocks Every Model Call

The model that patched a step does not get to judge the patch.

verify.py applies the patches and starts a new container. It runs every step inside config.block_model_calls(), where any Claude or Jev call raises ModelCallBlocked. The run ends verified only when every runnable step passes.

A test guards the guard. tests/test_verify.py fails if verify.py imports the planner, the recovery code or the LLM module.

On the Entire install, recovery added curl and a PATH line. Then a fresh container ran all 4 steps with no model calls.

The rule has a limit. A neatlogs AI judge scored 52 runs on 11 October and agreed with the reported failed step in 46. Only 34 had every patch backed by a passing verify rerun. Runs that stopped before the clean rerun got no proof, and the judge marked them down.

lists why a judge alone is not proof: "Judge LLMs can hallucinate judgments, be inconsistent between runs, or miss nuances that humans catch."

The Agent Asks a Human Once, Then Remembers

The idea came from @bettersayAJ, who wrote "self-healing is self-defeating". So recovery classes each failure before it patches. It checks precedents.json first. A precedent is a stored error signature with its class, such as docs bug or environment. A match returns the class at probability 1.0, with no model call.

A new error goes to Jev, a model that returns a typed judgement with a probability. Below 0.7 confidence, FirstRun asks the human one question. The answer goes into precedents.json, so the same error never asks again.

counts the same number as a core agent metric: "how often humans have to intervene."

Bisect Named the Release That Broke the DuckDB Guide

firstrun bisect finds when a step broke. It binary-searches a package's releases, one fresh container per probe, with the version pinned.

On the dbt guide, jafgen --years 6 passes on jafgen 0.3.1, released 2023-01-17. It fails on 0.4.6, released 2024-04-07. PyPI has no release between them. The guide merged on 2025-03-14, 11 months later, so it never worked in a clean environment.

The bisect took 5 probes and $0 in model calls, because it replays stored commands. The table went up as a comment on dbt PR #10149, and I posted the result on X.

4 PRs went up on day one, each from a FirstRun verified run.

describes the same moment from the coding side: "a little while later you get a pull request with code changes and passing tests." Passing tests were the part FirstRun did not trust.

• dbt-labs/docs.getdbt.com#10149 fixes the removed jafgen --years flag.

• dbt-labs/docs.getdbt.com#10150 states the Python 3.12 floor the guide needs.

• entireio/cli#2724 names the Linux PATH step after install.sh.

• accuknox/help#671 fixes a knoxctl page that named 0.9.0 while the installer fetched 0.9.58.

Version 2 Finished More Runs at a Lower Cost

The same 4 targets ran twice. v2 added the planner fix, recovery and verify.

• Quickstarts that ended passed or verified went from 2 of 4 to 3 of 4.

• Failed steps recovered went from 0 to 3.

• Fixes proven in a fresh container went from 0 to 1.

• Cost per run, from neatlogs, went from $0.0262 to $0.0200.

• Time per run went from 128 s to 201 s.

v2 runs 73 seconds longer, because a verified fix runs the whole quickstart twice.

The sample is thin. Each target ran once per version, and several fixes landed together, so they share the credit.

The Business Plan Set the Agent's Spending Cap

Before the plan existed, the cap was a guess of $0.50 per run. Then firstrun econ read 88 run traces from neatlogs. The old cap sat at 30 times the mean run cost of $0.0178.

cfo.ai modeled 18 months from those traces. Under the old cap, cash goes negative in month 14. At a 70% margin floor, the Scale tier cap comes out at $0.028 per run.

The executor now checks the tier cap in a budget span. A free-tier run on the typer quickstart stopped at step 4 with cost budget spent: $0.0115 of $0.0108.

Rule of thumb: Measure the cost per run first. Then derive the cap from your margin floor.

The Agent Printed a Receipt, Then Held Back 13 Pages

A docs agent earns trust when it shows the bill for every run and declines work a repo's rules forbid.

Every run ends with a bill. The AccuKnox knoxctl run cost $0.0453 in model use. Compute added $0.0020, for $0.0473 in total. That total is 96.4% of the Team cap and 162.5% of the Scale cap.

The receipt also hashes each evidence file, and firstrun receipt --check fails when one changed.

An audit costs less than one run. Doc-audit reads a repo's git history to find stale docs pages. The first 7 audits cost $0.014609 together. That figure is an estimate from a rerun on 11 October. dbt-core cost the most at $0.005498, for 7 Jev calls over 11,552 commits.

The team map found the single owner. On the AccuKnox help docs, 9 of 9 areas rest on one person. That person is me, with 425 commits.

The proof page lists its own gaps. The For Judges page maps every claim to its file. It also says only 91 of 132 commits carry an Entire checkpoint, and that two proof pages need a login.

The agent held back 13 pages. FirstRun fixed and verified 16 docs pages, and 3 of those pages became the 4 PRs. Of the other 13, 10 needed only a container fix, so the docs were right. 3 had docs gaps.

• Flask runs flask run with no --app.

• Hypothesis gives an install line that skips pytest.

• HTTPX sets r.encoding after r.text.

The Pallets LLM policy, the Hypothesis AI policy and the HTTPX discussion-first rule ruled out an agent PR on all 3. So 0 new PRs went up. I posted the HTTPX gap by hand as discussion #3801 on Saturday, and Polars issue #29855 the same day.

I Would Not Build Two Cost Counters Again

FirstRun and neatlogs each count the cost of a run. On 43 matched runs, FirstRun counts 39% higher. The cap reads FirstRun's count, so it stops a run early and never late. That is safe, and it still gives two numbers for one fact. I will merge them into one counter next.

Copy the Verify Rule Into Your Own Agent

1. Run the fix in a container that the fixing agent never touched.

2. Block every model call inside the check, and raise an error if one fires.

3. Add a test that fails if the check imports the planner or the fixer.

4. Mark a run verified only when every runnable step passes.

5. Report every other ending as not verified, and say why.

Three Questions Get Short Answers

Does FirstRun open a PR on its own? No. It prints the gh command, and a human approves each PR before anyone runs it.

What does one run cost? The mean is $0.0178 over 88 runs, at list price.

Can my own coding agent run it? Yes. The site takes a docs URL and writes a prompt for your coding agent.

Appendix

firstrun <url>
firstrun bisect <run> --package <pkg>
firstrun prereqs <run>
firstrun receipt RUN_ID --html
firstrun receipt --check runs/RUN_ID/receipt.json

• Site: https://firstrun.atharvashah.com

• Repo: https://github.com/HighnessAtharva/firstrun

• Demo video, 2:54: https://www.youtube.com/watch?v=9xxgu_1bH-E

Leave a comment

Claude Code forgets you every session. You explain your project again, you retype the same corrections, and you get the same mistakes back. The fix is a harness, and the Claude Code load order (the files Claude reads on startup, and their sequence) decides which of its rules reach the model.

A harness is Claude plus the files it reads on startup. Those files hold your rules, your skills, your tools and your saved state. You keep them in git, so they survive a new laptop or a new account.

gives the same definition from the builder side: "The harness supplies context, manages tool execution and state, enforces boundaries, and checks results."

The model is rented. Mine is the same model you use. The harness is the part you own, and it is how you stop paying again every week for the same work.

Y Combinator says the same model weights score 30% or 95% on ARC-AGI, depending on the harness.

Fix the load order before you add one more rule. A file that never loaded is a set of rules that never ran.

TLDR

• Five layers of files load before Claude answers, and you write three of them.

• My own files cost 40,293 tokens, and only 28,069 of them load on every session.

• Give each rule one home. A pasted copy drifts, and the model then picks a version at random.

• Check what loaded with /memory, because the model's own report proves nothing.

• A hook turns a rule into a gate that blocks a bad draft before you see it.

The Same Request Comes Back Wrong Without a Load Order

Take one prompt you have typed before: "Draft a short post about this week's release and save it with my other drafts." Run it in two setups with the same model.

Without a load order, here is what comes back:

• The draft breaks the style rules you added last month, because the only copy it saw was an old paste.

• The file lands at the repo root, because no project file names the drafts folder.

• Claude says it followed your style guide, and nothing ran to check that claim.

• Your next message repeats the corrections you typed last week.

With a load order, the global file loads one current copy of each rule. The project file names the drafts folder. A hook scores the file on save. Your next message is about the idea itself.

Watch out. If the wrong files loaded, throw the output away. No edit repairs a draft written under the wrong rules.

Claude Reads Five Layers of Files Before It Answers

Every session, Claude reads five layers before it answers you. Each layer has one job.

maps the same stack: "Claude Code supports memory hierarchies: global, team, and project-level memory."

1. System prompt. Anthropic writes it. You cannot edit it, and it loads first.

2. Global CLAUDE.md. A CLAUDE.md is a plain Markdown file of instructions that Claude Code reads on startup. The global one sits at ~/.claude/CLAUDE.md and loads in every folder.

3. Project CLAUDE.md. Each project folder gets its own. It holds what only that project knows.

4. Skills. A skill is a folder with a SKILL.md file inside. Claude reads one line per skill at startup and opens the full file only when a job matches.

5. MCP tools and the environment. MCP (Model Context Protocol) is the standard way to plug an outside tool, such as Gmail, into Claude. The tool names, the working folder and the git status load last.

All five layers sit in the context window at once. The context window is the text a model reads before it answers. No layer wins every conflict, so when two layers disagree, the next run can pick the other one.

Skills are the cheap layer. Adding one more skill costs one line of startup text, because the full file stays closed until a job needs it.

Anthropic published its own guide to the skill format in this post.

My Harness Loads 40,300 Tokens Before I Type a Word

I measured my own stack on 2026-09-02. A token is about four characters of text. Nine files I wrote reach the model before my first word, and they add up to 40,293 tokens.

• Every session: 28,069 tokens, whatever I ask for.

• Writing prompt only: 12,224 tokens, added by a hook. A hook is a script that Claude Code runs on its own at a set event, such as a prompt or a file write.

• Job match only: one full skill file, opened when a request matches its description.

Ask that same session about a Python bug and the writing rules never load. The layers that always load stay small, and the heavy rules arrive only for the job that needs them.

Each Rule Needs One Source Because Copies Drift Apart

The usual fix for an ignored rule is to paste it into a second file. Within weeks you edit one copy and forget the other. Both copies reach the model, and they now say different things.

The model sees both versions and picks one. Monday's draft follows the 20-word sentence cap, and Tuesday's draft breaks it. The model read a conflict you wrote.

reports the same decay inside OpenAI, where the agent manual "turned into a graveyard of stale rules."

So give every rule one home:

1. Write the rule in one file.

2. Link to that file from everywhere else.

3. If a second place needs the full text, generate that copy with a script.

4. Add a check that compares each copy with its source and fails on any difference.

Rule of thumb. Every correction you repeat twice is a file you have not written yet.

One home per rule also means a new rule must reach every old file once. I built a skill called Corpus Rule Rollout for that job. It tests the rule on your best work first, then applies it across hundreds of files with a dry run before every write.

The Corpus Rule Rollout page shows one rollout across a real archive.

Step 1. Write Your Repeated Corrections Into One Global File

Create a folder named .claude in your home folder, and an empty CLAUDE.md inside it. Then write down the five corrections you gave an agent this week.

• Write each correction as a short command, such as "Use American English."

• Put each one in one file only.

• A rule for every project goes in the global file.

Step 2. Move Project Facts Into a Project CLAUDE.md

Create a CLAUDE.md in the root of each project. Move every project fact out of the global file and into it. A project fact is anything only that project needs, such as its drafts folder or its test command.

Step 3. Add a Project Registry That Sends Claude to the Right Folder

One table in my global CLAUDE.md saves me the most retyping. It maps the words I say to a folder on disk and its GitHub repo.

I name a project and Claude works there from any session. Four rules travel with the table:

• When two rows collide, such as "the docs", Claude asks which one I mean.

• Claude runs git status before it edits, because some repos sit on feature branches.

• Claude names the target path in its reply when it writes to another repo.

• A commit or a push still needs my yes.

To link a new project, add one row with the trigger words, the local path and the upstream repo.

Step 4. Run /memory Before You Trust the Output

Open a new session inside a project folder and run /memory. Claude Code itself lists the memory files it loaded. Fix any missing or extra file, then restart.

Tip. Trust the /memory list over anything the model says it read. The list comes from Claude Code, and the claim comes from the model.

Step 5. Write the Tie-Break Down Once You Pass Three Rule Files

Two layers stop working once you hold more than three rule files, because the files begin to collide. My voice file wants a long conditional sentence. My scoring script caps every sentence at 20 words. The scoring script is a Python program that counts the words and patterns I banned.

One file settles every collision. I call it the runtime contract. It names which files load, in what order, and which file wins each kind of disagreement:

• A sample I paste into the session beats the voice profile.

• The voice profile beats the skill.

• A hard ban beats everything.

Step 6. Let a Script Print Which Files Loaded

Ask Claude which rules it followed and it answers with confidence. That answer is text the model generated. It can say a check passed when the check never ran, because a careful assistant reports success.

So a script renders a panel above every draft. The top half lists the files that loaded, which the script looks up itself. The bottom half runs each scoring script and prints the result:

• A tick means the check passed.

• A cross means it failed.

• A dot means the check could not run, and a dot never reads as a pass.

When the panel and the model disagree, believe the panel.

Step 7. Block a Bad Draft With a Hook

A rule in a CLAUDE.md file is a request. The agent weighs it against everything else in context, and sometimes skips it. Rewriting the rule in capital letters only makes the request louder.

draws the same line: "a hook that blocks a tool call cannot be reasoned around."

A hook turns that request into a gate. Mine fire at three points.

1. On a writing prompt. The hook prints the file chain into context.

2. After every file write. It runs the scoring script, and on a critical finding it blocks the write and names the lines.

3. At the end of the session. It refuses to end while a draft it touched still fails.

Example. In one session, 21 LinkedIn comments failed the scoring script and never posted.

Boris Cherny, who leads Claude Code at Anthropic, runs a hook after every edit to format the code.

Step 8. Commit the Harness to Git Because a New Machine Needs the Same Order

Push three groups of files to a private repo:

• Commit the global CLAUDE.md and every project CLAUDE.md.

• Commit your skills and your hooks.

• Commit a .env.example with placeholder key names.

Never commit your .env keys or .credentials.json, which holds live login tokens. On a new machine, clone the repo into your .claude folder and copy each file back in place.

The full backup, restore and version control guide is in the 5 files that give Claude Code permanent memory.

Five Questions a Newcomer Asks About the Load Order

Does a longer CLAUDE.md make Claude follow it better? No. Every line in the global file loads on every session and competes with the rest. Move project facts into project files and job rules into skills.

sets the ceiling at 300 lines, because past it "Claude starts treating your instructions as background noise instead of rules."

Where does a rule go when it fits two projects? Put it in the global file. If only some projects need it, write it as a skill, because a skill loads only when a job matches.

How do I see which files Claude loaded? Run /memory inside the session. Claude Code lists the memory files itself, so the list does not depend on the model's answer.

Do I need hooks on day one? No. Start with two layers and the registry. Add a hook when one rule keeps breaking after you gave it one home.

What do I do with a draft written before the fix? Throw it away and run the prompt again. A draft built on the wrong rules carries those rules in every sentence.

The Appendix Holds Every Path and Command

The global and project files:

mkdir -p ~/.claude
touch ~/.claude/CLAUDE.md          # global layer, loads in every folder
touch ./CLAUDE.md                  # project layer, run in the project root

Registry rows to paste into the global file, one project per line:

notes, the vault     -> ~/notes          -> you/notes
my website, my site  -> ~/code/my-site   -> you/my-site
the docs             -> ~/work/docs      -> company/docs

A hook that runs your own checker after every file write, in ~/.claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{ "type": "command", "command": "python ~/.claude/check.py" }]
      }
    ]
  }
}

What to keep out of the backup repo, in .gitignore:

.env
.credentials.json

Subscribe for the next piece of the harness, written from the files I run every day.

Leave a comment

Most AI models write for a living. The Jev AI model, from a company called TypeSafe, refuses to write at all.

Ask ChatGPT a question and it answers in a paragraph. Ask Jev the same question and it answers with a typed decision: a choice, a score, or a probability.

That trade sounds small. It changes what you can afford to automate. Jev skips the writing step, so it answers in about a tenth of a second. A normal AI model takes several seconds for the same call, and costs far more per answer.

Jev launched into early access on 15 September 2026. Within a week, people had shipped routers, linters, lead scorers, spreadsheets and photo pipelines on it. This guide covers what Jev is, how it works, and eighteen jobs people already gave it.

One Restriction Makes Jev Fast

Every normal AI model works the same way. It reads your prompt, then writes an answer one word at a time. Each new word depends on the words before it. That loop is slow, and that's where most of the cost comes from.

describes the same cost in a data pipeline: "The model spends seconds generating tokens, the pipeline parses the JSON, and sometimes the JSON comes back broken."

Jev skips that step. You give it two things: a state, and a set of questions. The state is the information, a message, a document, a paragraph, anything in text. The questions are what you want to know about it.

It reads the state once, then answers every question in parallel, in a single pass. It never writes a sentence, so there's no word-by-word loop to wait for.

TypeSafe calls this a System One model, after the psychologist Daniel Kahneman. In his framework, System One is your fast, gut reaction. System Two is slow, careful reasoning. A normal AI model tries to do System Two thinking in full sentences. Jev only makes System One judgment calls, and it makes them fast.

Pydantic, the Python validation library, described a call in one sentence when it added Jev support. The type you already wrote is the question, and the answer comes back as that type with one confidence per field.

learned why the type matters in production: "Without structured outputs, we had no data validation, no type checking, and no real control over how the output should look."

You Can Ask Jev Three Kinds of Questions

The three types are Choice, Score and true-or-false. You can mix all three types in one call, and every question runs against the same state at the same time.

A support message can get a Choice question asking which team should handle it, a Score question asking how upset the customer sounds, and a true-or-false question asking whether they want a refund. All three answers come back together.

Shann Holmberg wrote the shortest description of the loop I have read. You supply the information, your questions, and the allowed answers. Your own code decides what happens next.

Every Answer Comes With a Confidence Number

Every Choice and Score answer includes a confidence number, from 0 to 1. A high number means Jev found one clear answer. A low number means the options were close, or the text didn't give it enough to go on.

That number lets your software decide what happens next. A high-confidence answer can be acted on right away. A medium one can be flagged for a person to glance at. A low one can skip automation entirely and go straight to a human.

shows how to tune those cutoffs for decision models, and how "calibration can make them more useful as confidence estimates."

That distinction makes Jev usable for real decisions rather than demos. A system that can say "I am not sure" gives your code a rule to build around, instead of a guess to trust.

OrcDev put the same idea in terms of where Jev sits. Big models think slowly. The small decisions between their calls never needed to be slow.

Jev Can Cost 400 Times Less Than a Normal AI Call

A Jev call costs $0.042 for every million tokens of text you send in. A token is a small chunk of text, close to three quarters of a word. Jev's output costs nothing, because it never writes anything out.

A normal AI model charges for input and for output, and output is usually the bigger cost. The input text alone can run $0.20 to $10 per million tokens.

TypeSafe tested Jev against several AI models on four real workflows. Jev came out up to 444 times cheaper and 193 times faster on those tests. TypeSafe ran that test itself, so read it as their claim, not an independent check. Their launch post plots accuracy against cost, and Jev holds the cheap end of that line without losing much accuracy.

The rest of this guide uses other people's numbers instead.

Eighteen Jobs People Gave Jev in Its First Week

Every job below is a real build, posted publicly between 15 and 20 September 2026. I kept each person's own figures and named who ran the test, because almost nobody has checked these independently yet.

Sorting a Pile That Nobody Wants to Read

1. Classify 1,018 AI research papers for eight cents. Hassan summarized every paper with DeepSeek V4 Flash, which cost $3.99 on Together AI, a service that hosts open models. He then sent each title, each summary and 24 candidate topics to Jev. The 1,018 classifications cost $0.08 in total, at 256 milliseconds median per paper, end to end. He is still running evals before he replaces his current labels, so treat the accuracy as unproven.

2. Triage security alerts in a production pipeline. Greg Pstrucha works on AI at Sentry. He posted a table of seven models running one of Sentry's security pipelines. Jev scored 99.3% accuracy in 0.259 seconds. GPT-OSS 120B scored 96.4% in 1.821 seconds and cost three times more. Gemini 3.1 Flash-Lite matched Jev's accuracy, took 1.338 seconds, and cost fourteen times more.

3. Sort an inbox, then sort the seven queues behind it. Greg Isenberg described the job in one line. Jev reads each item and says "this is junk, I'm 94% sure". He priced 1,700 emails at 18 cents. He then listed the queues that are the same job wearing different clothes: quote forms, inbound leads, support tickets, transcript clipping, grant and permit piles, marketplace matching, and bulk browser work.

4. Catch phishing with five small questions instead of one big one. Somebody ran 2,000 phishing emails through Jev. One big question scored 89.4%, which lost to a two-line text rule at 91.8% and to Claude Haiku 4.5 at 94.2%. The same person then asked five small questions and added the answers up in his own code. That scored 95.0%, the best result in the test. Same model, same emails, different question shape.

found the opposite on research paper screening. In his test, "making Jev more sophisticated did not help". Five criterion questions scored 0.536 on WSS@95, and one question scored 0.646.

Choosing the Model Before the Model Runs

5. Route a chat to the right model on its first message. Ashley Hindle runs Fuel, which reads the opening message of a chat and decides how much intelligence that chat needs. His benchmark has 75 test cases. Against GPT-OSS-120B he measured Jev at 3 times faster, 65% cheaper and safer. A wrong route costs him twice, because a weak model on a hard problem annoys the user and raises their bill.

6. Route models inside Claude Code with one install command. Daniel San shipped the same idea as an installable mod. For every request, Jev picks the subagent model and the effort level. It picks the main model only at session start, because changing it mid-session breaks the prompt cache.

7. Pick the right skill out of a catalog of 182. TypeSafe's docs describe a test against the Hermes skill catalog from Nous Research. One Jev request ranks all 182 skills and asks whether the turn needs a skill at all. A second request reads the top three closely and can reject all of them. On Haiku 4.5, wrong skill loads fell from 17% to 7.3%. Both figures come from TypeSafe's own test.

Screenshot from Ray Amjad's Jev video, showing TypeSafe's documentation.

8. Put Jev in front of a model you already pay for. Ronin, who posts as @DeRonin_ on X, describes one email tool that swapped two AI calls per email for a single Jev call, and kept every safety check it already had. On a 120-ticket test, the version with Jev in front finished in 42 seconds for $0.0003. The version without it took 22 minutes and cost $0.059. He is clear that retry errors inflated the slow number, so the real gap is smaller.

9. Compact an agent's context tonight. The same thread names the cheapest win available. Score every tool call in the history, drop the dead ones, and keep the survivors word for word instead of writing a lossy summary. Ronin also points at the honest limit. Somebody ran 18,514 emails through Jev with no examples and got 98.33%. A TF-IDF classifier trained on 14,800 labelled examples got 98.39%, so labelled data still wins when you have it.

Deciding Inside the Interface, While Somebody Types

10. Rank a launcher's results on every keystroke. Nader Dabit built what he calls a keystroke oracle. A normal launcher ranks by alias, fuzzy match and habit. Type "the pdf I just downloaded" into his version and the newest PDF is already the top hit, with a confidence on every keystroke, in about 100 milliseconds.

11. Turn a spreadsheet column header into a judgment. Spreadsheets recalculate numbers, never meaning. Dabit typed "Urgency" at the top of a column and the sheet rated every row from "no follow-up needed" to "urgent" as he typed, in about 100 milliseconds a row.

12. Drive a browser by voice, remember what an agent learned, predict a video's numbers. Mario Nawfal published a full build tutorial with three demos. The voice-controlled browser needs a decision per utterance, the memory layer needs one per stored fact, and the YouTube predictor scores a title before you publish it. All three break down into typed questions.

Deciding Where the Money Goes

13. Score 700 leads and their outreach messages in 40 seconds. Romàn fed Jev 700 high-intent leads together with the personalized message written for each one. It predicted how each message would perform, attached a confidence score, and flagged the leads whose message did not match them. The whole run cost $0.09.

14. Lint every comment in a repository for one cent. Ray Amjad asked Claude Code to find useless comments in his own codebase. Claude Code sent 150 comments to Jev in one run. It took 9.3 seconds, used 233,802 input tokens, had zero failures, and cost $0.00982.

Screenshot from Ray Amjad's video.

15. Price a code smell scan across 8,270 functions. In the same session, Claude Code costed two versions of a full-repo scan. A gated pass sends about 7.5 million input tokens for $0.32 in roughly four minutes. An exhaustive pass sends 28 million for $1.19 in roughly eleven minutes.

Screenshot from Ray Amjad's video.

Money stopped being the constraint at that price. Claude Code's own note under the table names the constraint that replaced it. A 10% false-positive rate across 8,270 functions hands you 827 bad findings, and you stop reading the report. Check that number before you trust any scan this cheap.

Wiring Jev Into Something You Already Run

16. Give a Python agent framework its answer type back. Pydantic AI agents now run on Jev. The output type an agent already declares becomes the question, and the answer arrives as that model with one confidence per field. Nothing in the agent's code has to change shape.

states the reason this matters for agents: "agents that produce validated JSON are composable."

17. Check an agent's work before a person ever sees it. Because Jev writes no prose, it invents no facts inside an explanation. That makes it a reasonable verifier for another model's output. Ask whether the answer used the source, whether the tool call matches the request, and whether a human should look. Three typed questions, one call, one price.

18. Sort four years of photos into 39 days of posts. That one is mine, and the next section is the whole build.

Jev Sorted 469 of My Photos Into 78 Carousels for 29 Cents

I ran my first real build on my own camera roll. Four years of photos sat in 54 folders grouped by feel rather than by post. One pipeline regraded, recropped, regrouped, captioned and scheduled the whole set onto Instagram, two posts a day for the next 39 days.

Four tools each did one job. Claude Sonnet described every frame in words. Jev read those words and made every judgment. Python held the policy and ran the edits. The Zernio API published the queue. Zernio is a social media scheduling service.

The judgment layer cost $0.29. It made 5,961 typed judgments across 132 model calls, and I sorted zero photos by hand.

One judgment pass with Claude alone costs $17.40 and takes 36 minutes. The same pass with Jev underneath costs $0.14 and takes 5 minutes.

Projected to a 1,000-image run, the first pass drops from 90 minutes to 58. Every re-run after it drops from 36 minutes to 5. Re-running is where the work actually sits, because a grouping rule is never right on the first try.

Jev Is Not Built for Every Job

Jev can't write open-ended text. It won't draft an essay, an email, or a chatbot reply. If you need a model to produce free-form writing, you still need a normal AI model.

It can also be confidently wrong. TypeSafe says Jev can't output an invalid answer, only a valid one, because the shape of the answer is fixed in advance. A normal AI model can invent a fact that never existed. Jev can only pick from the options you gave it. But a valid answer can still be the wrong answer, with a high confidence number attached to it. When developers debated this on Hacker News after launch, that distinction was the most argued point in the thread.

Ronin's testing found three failure shapes worth copying into your own notes. Jev does not know what it does not know, so a question like "do you have enough information" answered yes on 85% of 120 test tickets. Option order changes answers, and reordering four options moved 7 answers out of 120. And the final verdict belongs in your code rather than in one big question, because the model is better at noticing things than at ruling on them.

There are plain practical limits too. Jev reads text only, no images or audio yet. It holds about 64,000 tokens of information in one call, smaller than several other AI models. The company is new, so its pricing and rate limits could still change as more people sign up.

Trying Jev Takes About Five Minutes

Getting access takes one of two paths.

The direct path is TypeSafe's own waitlist, at typesafe.ai. Sign up, and TypeSafe sends an API key once a spot opens. Early testers have reported getting in within a few hours.

The second path skips the waitlist. Vercel added Jev to its AI Gateway in September 2026. Anyone already building with Vercel's AI tools can call Jev through that account, with no separate signup.

Cloudflare followed on 17 September and put Jev on its own AI Gateway.

Once you have access, TypeSafe gives you a web playground. You paste in a piece of text and type a plain-language question. Then you pick a choice, a score, or a true-or-false answer. Press run, and the answer comes back in well under a second, confidence score included.

There is also a developer toolkit that plugs Jev straight into an app. Once wired in, the app can ask the question on its own, with no one typing into the playground.

Why This Price Is Low Enough to Start New Companies

A ten-times price drop changes who wins. A four-hundred-times drop changes what gets built at all. Four examples show what that buys.

1. A game bot that runs all day. TypeSafe's own demo has Jev making roughly ten decisions a second to play Doom in real time. Running that continuously costs about $7 an hour. A normal AI model, answering in full sentences at that speed, would cost far more and likely couldn't keep up with the game clock at all.

2. A chess engine priced under a thousandth of a cent. One developer wired Jev into a chess app through Vercel's AI toolkit. Jev picks a move from every legal option in about 300 milliseconds, for roughly $0.00004 a move. A full forty-move game costs less than two thousandths of a dollar.

3. Scanning everything instead of a sample. At $0.042 per million input tokens, checking a million tokens of text costs about four cents. Most systems settle for spot-checking a sample, because scanning everything used to be too expensive. That excuse is gone.

4. A guardrail in front of every action, not just the risky ones. Most AI systems today reserve a safety check for the actions that look dangerous, because running a full model on every single step costs too much. At Jev's price, the check can run in front of all of them.

None of these four needed a new company two years ago. Each needed a decision too slow or too expensive to make in real time, and TypeSafe is betting that gap just closed.

Where Jev Fits Into How I Publish

Every piece I publish goes through the same four steps. I write it, I check it against a set of rules for what good writing looks like, I fix whatever gets flagged, and only then does it go out.

Some of those checks used to be too slow to run on everything, so I read for them by hand instead. Jev is cheap enough to run every one of them, on every piece, every time. That's the first place I'm putting it, and I expect to find more as I keep building.

Leave a comment

After DevRel Uni Cohort 7, I plan my DevRel week with one rule from Francesco Andreoli of Consensys. Every task is human-led, AI-assisted or agent-led, and a task that belongs in the third column but sits in the first becomes a backlog item.

DevRel (developer relations) is the job of helping developers adopt a product. DevRel Uni is a cohort program for people who do it. Cohort 7 ran five live sessions between April 28 and May 26, 2026, beside a public project. Mine was the 10xDevRel workbench.

In short

• Sort each recurring task into three columns, and move agent-shaped work out of column one.

• Run your own quickstart as a coding agent would, one literal step at a time. A failing step is a docs bug.

• Put a 45-minute scan on the calendar, so you taste new tools on purpose.

• Turn one agent-led task into a scoped tool, because only a scoped tool can fail a test.

• Ship something public every week. A post you cannot write means you do not understand the build yet.

Docs Written for a Human Fail When an Agent Runs Them

Your getting-started guide has a second reader now: a coding agent that runs each line as written. A human reads "run the install command" and infers the rest. An agent has to guess the command and its flag.

Take the same quickstart in both forms:

• Before. The step says "run the install command". The agent picks a command and a flag, and a wrong guess fails.

• After. The step gives the exact command, the exact flag and the expected output. The agent runs it as written.

• The payoff. A failing step now names the line to fix, instead of becoming a bug report from a stranger.

Step 1. Sort Your Week Into Three Columns

Francesco Andreoli closed Cohort 7 with a DevRel Operations Grid. It asks one question per task: is this human-led, AI-assisted or agent-led? That is a workflow design question, and most DevRel work has a concrete answer.

Run it on your own week:

1. List every task you repeat each week.

2. Split each task into its judgment and its routine.

3. Put the judgment in column one. Put a draft a human fixes in column two. Put a rule a script can apply in column three.

4. Mark every column-three item that you still do by hand as a backlog item.

I plan my own week this way. The shift is gradual, so move one task per week and never flip all of them at once.

Rule of thumb. If a task has a clear right answer that a script can check, it belongs in column three.

Step 2. Run Your Quickstart as a Coding Agent

Open an empty folder and give a coding agent your guide. Tell it to run each command exactly as written and to stop at the first failure. Any failure is a docs bug, whether or not a human would have worked around it.

Here is what that finds. The dbt DuckDB guide tells readers to run jafgen --years 6. My agent FirstRun hit the failure at step 10 of that guide on 10 October 2026. I reran the command on jafgen 0.4.6 on 13 October 2026.

The fix is one word. The years became a positional argument, so the command is jafgen 6. dbt docs PR 10149 proposes that change.

Watch out. A step that exits 0 can still be wrong. Judge each step by its expected output, not by its exit code.

Agents also read your docs in conversations you never join. That is why Generative Engine Optimization (GEO), the practice of being the source an AI answer cites, now matters as much as ranking. I cover it in Forget Ranking #1 on Google.

Step 3. Put a 45-Minute Scan on the Calendar

Patrick Skinner's rule from session 3 was "Speed without system doesn't create progress. It creates queues." The system I took from it is a weekly block for ecosystem scanning.

This figure is a template for you to copy. It is not a screenshot of my calendar. The block works because it has three fixed jobs:

• Taste. Try one new tool on purpose, rather than reading about it.

• Document. Write down what changed in your workflow.

• Update. Edit your tool list, and note what you replaced.

Scans turn up tools like this one. Hassan El Mghari, the session 4 speaker, announced a design MCP server (a plug-in that gives an agent outside tools) that searches hundreds of websites for design inspiration.

Step 4. Turn One Agent-Led Task Into a Scoped Tool

Pick one column-three task and build a tool for only that task. The 10xDevRel Launch Checklist Generator started as the checklist my team at AccuKnox actually uses. It takes a changelog entry and returns a checklist.

A scoped tool can be tested. Ask: "Did this generate a valid launch checklist with owners, priority levels and correct task categories?" That question has an objective answer.

I built a general assistant for the workbench early on, and it did worse than the scoped tools. The question "Was this conversation helpful?" has no objective answer, so that assistant could never fail.

Rule of thumb. If you cannot write the pass or fail question for a tool, its scope is too wide.

The workbench now ships 16 playbooks and five AI tools. The case study on atharvashah.com lists what each one does.

Each tool has one input and one exported artifact.

Step 5. Ship Something Public Every Week

I treat every project as a forcing function for public output. With the workbench, something shipped and something got posted every week. Posting tested whether I could explain the build to a reader who had not seen the code.

Nader Dabit's loop in session 2 was learn, build, share, get feedback, improve. Most people skip share. Readiness usually comes after movement, so you do not need every answer before the next step.

Tip. If the post will not write, you do not understand the build yet. Go back to the build, not to the post.

Here is the thread where I posted the first version of the workbench.

Each Habit Traces Back to One Speaker

• Bianca Buzea, session 1. "More people can build now, which means more people need guidance." Docs now serve developers and agents, which led to step 2.

• Nader Dabit, session 2. Show what you know in public, which led to step 5.

• Patrick Skinner, session 3. A system beats raw speed, which led to the scan in step 3.

• Hassan El Mghari, session 4. Find what a new model does uniquely well and build around it, which led to step 4.

• Francesco Andreoli, session 5. The Operations Grid became step 1.

For the AI-first DevRel setup behind these steps, read Building DevRel AI-First.

Four Questions Readers Ask About This Routine

What is llms.txt? It is a markdown file at the root of a site that gives AI agents a short guide to your docs. Jeremy Howard proposed it on September 3, 2024, and it is still a proposal rather than a universal standard. See the llms.txt proposal.

Do I need the cohort to use this? No. Each step runs on its own. The cohort supplied the frame, and the steps are yours to run.

What is a coding agent? It is a model that runs commands in a terminal, reads the output and decides the next step. Claude Code is one.

Where do I start if I have one hour? Do step 2. Run your quickstart as an agent and fix the first step that fails.

Appendix

Reproduce the failing step from step 2:

python -m venv .venv && source .venv/bin/activate
pip install jafgen==0.4.6
jafgen --years 6    # fails: No such option: --years
jafgen 1            # runs

A prompt that turns any coding agent into a quickstart tester:

Open the guide at <URL>. In an empty folder, run each command exactly as written.
Do not fix, reorder or skip a step. Stop at the first failure and quote the step number,
the command and the full error.

The calendar event for step 3:

Weekly · 45 minutes · "Ecosystem scan"
Taste one new tool. Document what changed. Update the tool list.

Leave a comment

This is a recorded podcast I did with Manik, a colleague from Cohort 7 of DevRelUni, a live cohort program for developer relations. We sat down on May 20, 2026, ran the camera for about 46 minutes, and walked through every part of how I actually run DevRel at AccuKnox. The post below is the full structured writeup, every number, every framework, every mistake. If you'd rather watch the conversation, the recording is right under this paragraph.

Filmed live during DevRelUni Cohort 7. Roughly 46 minutes.

This is the deck I built for the session. The article follows it block by block, with the slides embedded inline at each beat. By the end you'll have the full playbook: how I think about the role, how I run GTM (go-to-market), what I tell anyone trying to break in, and the three mistakes I'd undo if I could rewind.

What This Conversation Actually Covered

Manik wanted a structured walkthrough, not a vibes call. So we set an agenda and stuck to it.

Seven blocks. Journey, online presence, GTM, what DevRel actually does, DevRelUni and the Workbench, advice, mistakes. Each one gets a section below.

Block 1. The Role, the Journey, the Nine Pillars

I'm Atharva Shah. DevRel and AI Product Manager at AccuKnox, a cloud-native security company building CNAPP, CWPP, API Security, and AI Security. KubeArmor is our open source runtime security engine for Kubernetes. I joined AccuKnox 2+ years ago as the first DevRel hire and built the function from zero.

My day-to-day is six jobs duct-taped together, and the split changes week to week depending on what's on fire.

Content work is the biggest share of it: over 100 technical blogs, 200-plus help docs, and six books published on Amazon KDP, three of them endorsed by US CISOs. GTM work has meant launching three product verticals from zero, AI Security, API Security, and SBOM, each with its own launch package, which I break down in Block 3. Events work covers 15-plus webinars produced, five-plus offline events, and running RSA Conference 2026 end to end, with KubeCon Mumbai planning underway for June 2026. Tooling work built an AI-native demand gen stack that replaced a $4K-a-month agency with $400 a month of AI tools, a 90% cost cut with better output. Community work is partner co-branded propositions, DevRel network building, and hackathon CTFs. Engineering work is forward-deployed: landing page builds, in-house automations, release notes, tenant enablement.

My competency map has nine pillars: AI and Applied AI, Cloud-Native and DevOps, Web Development, DevRel and Technical Writing, Product Management, Growth and SEO, UI/UX for Conversions, Technical Deep Dives, and Hot Tech News. I don't just write about tech. I ship it, market it, and measure it.

The receipts: 1M+ organic traffic generated across blogs, docs, and product content. +100% year-over-year growth in LLM citations, tracked via LLM Labs. Gartner reviews grew from near zero to ~60. Each vertical launch was a full content cluster, not a press release.

If you're a fresher or just starting out, my number one advice is this. Assume you already have five years of experience. Pick the domain you want to claim. Then build your portfolio toward that claim. Identify your top skills, build a competency pillar list, and get aligned with what you can actually operate in versus what's noise. Pivot quickly when the alignment is off.

Block 2. Freelance and Online Presence

Nobody hires you because of your resume. They hire you because they've already seen your work. Your online presence is your portfolio. Three pillars do all the heavy lifting.

draws the same line for developers: "A project on your portfolio beats a keyword on your resume any day."

Pillar 1. The Website

atharvashah.com is the home base. Everything else points back to it. Six service pages: AI and Automation, Web Dev, Growth and SEO, Python Dev, Product Management, Gen-AI Creatives. Five subdomains that each do one job:

• blog.atharvashah.com for Substack

• store.atharvashah.com for Gumroad products

• offers.atharvashah.com for HTML landing pages

• assets.atharvashah.com for client PDFs

• 10xdevrel.atharvashah.com for the DevRel Workbench

Don't ship a one-pager and call it done. Build a real site with a value proposition, service cards, a brag list, publications, and links to every channel you own.

Pillar 2. The Blog

A website gets you calls. A blog builds your credibility. Mine is on Substack: 33 published articles, 30%+ email open rate. Mailchimp's own benchmark report puts the cross-industry average around 21%. Blogs compound. Every article is a permanent sales page that keeps converting months after you ship it.

One important note for early-career writers: skip the thought-leadership pieces in the beginning. Those land much later, once you have 10 to 20 years in the space. In the first few years, write about what you actually shipped at work.

What did you build, what did you fix, what workflow did you find that broke through the noise. That kind of writing has a clear point of view because it's real.

Pillar 3. X and LinkedIn

X is for fast thought pieces, signal consumption, and network building. LinkedIn is for wider professional reach and inbound leads. Different formats, same core ideas. I rewrite every Substack piece into a Twitter thread, a LinkedIn carousel, and a Substack Note. One piece of content becomes five distribution shots.

Four Portfolios, Not One Resume

I keep four portfolios alive: blog (Substack plus external bylines at Real Python, freeCodeCamp, TutorialsPoint, CloudMatos), web development (production sites and client work), video (currently building Cozy Console on YouTube, repurposing blogs into video), and community (engagement, events, cohort participation).

The system underneath is knowing your niche, your ICP, or ideal customer profile, and your skill tree, then building content around your competencies. Validate ideas in public. Let people watch you work. I have 17 audience archetypes documented with exact pain points and buying triggers, which is what "know your ICP" turns into once you actually write it down.

Block 3. GTM That Actually Works

GTM is the system that carries a product from built to bought. Marketing borrows the story after GTM has already written it.

The Launch Package Behind Three Verticals

Three verticals from scratch: AI Security, API Security, SBOM. For each one, the launch package included a positioning doc, competitive analysis, a 5-to-7-article blog cluster, a landing page with a value proposition rewrite, a webinar series, and a partner co-branded proposition.

One of those clusters drove most of our AI visibility growth. Seven articles, including "2026 Applied AI Glossary," "Practical Tips for Reducing AI Costs," and "AI Slop Is a Skill Issue." That cluster alone is responsible for a meaningful chunk of the +100% YoY growth in LLM citations.

The Five-Step Motion Every Launch Follows

1. Start with the narrative. What problem are you solving and for whom. Write the positioning before you write the landing page.

2. Content-first GTM. Your blog cluster IS your launch plan. Each article targets a different search intent. Without the cluster, the launch plan does not exist.

3. Distribution beats creation. One piece of content, five channels. My Substack-to-social flywheel turns each article into posts for X, LinkedIn and Substack Notes. That flywheel is what makes the work compound.

4. Measure what matters. Organic impressions, LLM citations, qualified registrations. Skip the vanity metrics.

5. Partner motions. Co-branded content, joint webinars, shared distribution. 5+ partner propositions built at AccuKnox so far.

Consulting Wins Outside Work

Two recent ones worth naming. An SEO client went from 2K to 8K monthly organic visitors in six months. 4x growth, mostly from cluster strategy and on-page fixes. A second client had a manual processing workflow that ate 8 hours a week. Python pipeline, one weekend of work, cut it to 45 minutes.

Block 4. What a DevRel Should Actually Do

The role is misunderstood. DevRel gets reduced to conferences and tweeting, which is maybe 10% of the job.

A DevRel's real job is to bring measurable ROI to the company by improving developer growth. Not awareness. Not vibes. Growth you can tie to a number on a dashboard.

After three DevRelUni sessions of watching how the speakers framed their own wins, I settled on four things that actually matter.

The first is messaging: lead with ROI, not features. Developers don't read your feature list. They care about what your product solves, so every blog, every demo, every talk should answer one question, what does this save me. Position the product as a shortcut, not as a tool.

gives the same advice for selling developer tools: "focus on helping them get the ROI they need".

The second is integrations. If your product connects to the giants, AWS, GCP, Kubernetes, Terraform, that connection is your product-market fit story. Integrations signal maturity and lower the friction of trying the thing, so lead with them rather than burying them on a features page.

The third is developer tooling. Simplify your APIs, make SDKs that are actually pleasant, and keep your docs current and honest, no outdated screenshots, no broken code samples. The developer portal is your storefront, and a broken storefront makes the rest of the work moot.

Build internal apps too, now that AI credits are cheap: an ROI tracker, an SEO analytics tool, a content calendar, whatever your team is still running through Excel. Tools like Lovable, VS Code, and Claude Code make this trivial to ship, so get your org to sponsor the credits and go build it.

The fourth is proof. Track developer signups, docs traffic, community growth, content attribution. A DevRel who can't tie the work to a business metric is the first cut in a downturn.

makes the same call for GTM AI spend: "Rather than measuring AI adoption, measure AI impact."

What I'd Hand a New DevRel Hire on Day One

1. Build an AI content layer for your product. Use tools like MagiHQ to scale content creation without losing quality.

2. Set up social signal monitoring. Use SensorHub to track what developers say about your niche on Reddit and X.

3. Create a developer onboarding experience that works in under five minutes. Time-to-first-value is everything.

4. Ship integration guides for every major platform your product touches.

5. Build a community feedback loop. Not a Slack graveyard. An actual loop with action items.

6. Produce real-workflow demos. No toy examples.

7. Run or join hackathons. If senior, organize. If early-career, compete. Either way, show up.

8. Build a DevRel metrics dashboard. Docs visits, tutorial completions, API adoption curves, community engagement.

9. Create a content repurposing pipeline. One webinar becomes a blog, a thread, a short, a LinkedIn post, a Substack Note.

10. Build internal tools and automations that make your own team faster. This compounds quarterly.

Block 5. DevRelUni and the Workbench I'm Building

How I Found DevRelUni

X. I saw the signal, bookmarked it, and signed up. That's the obvious answer. The interesting one is how that bookmark made it into my workflow.

I have a script that fetches my X bookmarks periodically and pulls them into my Obsidian vault. Anything I bookmark shows up in my notes automatically. If it's actionable, it lands in my to-do list, which is also synced. My scrolling becomes research instead of a time sink. This is part of my digital twin, which is a set of files that describe me well enough for an agent to act as me. It is also my number one piece of advice later on.

The vault itself has 1,570 knowledge graph nodes right now. Every meeting transcript, brain dump, email, signal, bookmark, all of it organized by AI. I'll talk more about the system in the advice section.

The Cohort Experience

Cohort 7 ran from April 28 to May 26, 2026. Five live sessions, speaker lineup that included Bianca Buzea, Nader Dabit, Patrick Skinner, Hassan El Mghari, and Francesco Andreoli. Each session unlocked something new, but the peers are the real value. People like Manik bring different angles and different industries, and working as a pack toward the same goal creates social accountability that's hard to replicate alone.

Devrel’s Substack

Applications for DevRel Uni Cohort 7 are Live! Deadline: 25th April

“How do we build, learn, and grow in the age of AI?”Thanks for reading Devrel’s Substack! Subscribe for free to receive new posts and support my work…

Read more

7 months ago · 3 likes · Devrel Uni

Honest feedback for future cohorts: I'd run it for a full year. The momentum is real and a month feels short. Add hands-on workshops and more community success stories, the way Lenny's Podcast works but from inside the cohort.

The DevRel Workbench

10xdevrel.atharvashah.com. Open source web app, four core tools, plus a community playbook library.

The problem: DevRel work is fragmented and repetitive. Every launch, every demo, every content repurposing cycle starts from scratch. I do this work manually every week. So I'm shipping a sharper version of my daily workflow as a tool.

The first tool is a launch checklist generator: input a changelog entry, get a T-minus checklist with task owners, a DRI map, and a readiness score. The second is a demo run-of-show builder: input product, audience, and time slot, get a timed structure with speaker notes and fallback scenarios. The third is a content repurposing planner: input one blog, webinar, or transcript, get six content briefs, a tutorial, a narrative blog, a webinar pitch, tweets, a LinkedIn post, a Substack Note. The fourth is a demo-to-distribution planner: input a feature announcement, get a three-layer plan, demo flow, launch checklist, two-week distribution calendar.

Around those four sits a community playbook library with 5 seed playbooks, community submissions, upvoting, and owner approval. Playbooks cover normal day-to-day moves, building community, content cycles, launches, and the harder stuff most resources skip: handling outages, crisis comms, incidents.

Tech stack: Next.js plus Tailwind, OpenAI and Claude for structured output, Supabase for storage. CI/CD already wired. Hosted on a subdomain off my main site.

Block 6. Three Pieces of Advice (Plus One Bonus)

Advice 1. Build Your AI Digital Identity. Start Today

Create a vault. Obsidian, Notion, whatever. Just start. Dump everything in: meeting notes, brain dumps, emails, bookmarks, job listings you admire, future goals.

You don't have to organize it on day one. Embrace the chaos. Let AI process and categorize it.

The system compounds. It took two years for my vault to reach its current node count, but it grows exponentially once the inputs are flowing. Your digital twin becomes your second brain, a single local folder of plain text that holds everything you know and finds it again. It remembers what you forget. It connects dots you miss.

Tool stack I run on. Go all-in on the Claude stack:

• Claude Chat for ideation and research

• Claude Code for building automations, writing scripts, managing the vault

• Claude Routines for recurring scheduled tasks (content audits, pipeline checks)

• Claude Skills for reusable workflows you trigger with a slash command

• MCP Connections to plug Claude into Slack, Drive, GitHub, Buffer, anything

• Plugins for extending Claude inside your specific domain

• MagiOOS for scaling content creation

• SensorHub for social signal monitoring

You don't need 15 SaaS tools. You need one AI backbone with good connectors.

Advice 2. Go Deep in Your Niche. Build in Public

Pick your niche and know it inside and out. Build things in that niche. Ship them. Show your work.

Publicly validate ideas. Let people see your process, not just your polished output. The compounding effect of niche expertise plus public building is unmatched for career growth.

Specific beats general. "I help cloud-native security companies with GTM" beats "I do marketing." Every time.

Compete in hackathons if you're early-career. Organize them if you're senior. I won 1st place at CRIF Hackathon 2023, beating 37 teams and 140+ participants with an NLP-powered media reputation engine. Hackathons compress months of learning into 48 hours. If you're senior, organizing them builds community, sources talent, and stress-tests your product.

Advice 3. Clean Your Algorithm. Separate Your Feeds

Your feed IS your environment. If your feed is slop, your thinking becomes slop.

My setup: two accounts, two purposes.

Primary account. Extremely focused. Follow only the top operators in your industry, the most active builders, the most reputed voices. Underdogs count too, not just the big names. When I log into my main feed, every scroll, every tweet is high-signal. The algorithm feeds itself once you train it.

Secondary account. Brain rot, entertainment, whatever you enjoy. Vacation mode. No guilt. The separation means you can switch off completely when you need to, and when you're on, every signal matters.

Don't just consume. My X bookmark script auto-pulls interesting tweets into my Obsidian vault. Scrolling becomes research.

Get a buddy or join a cohort. Preferably global, preferably with a strong technical lead. Social accountability and peer pairing are underrated growth accelerators. DevRelUni is proof. Working alongside peers like Manik toward the same goal changes how fast you move.

Advice 4 (Bonus). Apply Real Frameworks

Code is commoditized. Growth is not. Growth requires multi-step thinking, and for that you need frameworks. DevRel means juggling multiple hats, so you need mental models to decide what gets your time.

Three I rely on:

• Eisenhower Matrix. Separate urgent from important. Most DevRel fire drills are urgent but not important. The blog cluster that drives organic traffic for 12 months is important but not urgent. Prioritize accordingly.

• Pareto Principle (80/20). 20% of your content drives 80% of your traffic. 20% of your community interactions drive 80% of your conversions. Find the 20% and double down.

• MEDDIC Framework. Shoutout to Patrick Skinner from the last DevRelUni session. Metrics, Economic Buyer, Decision Criteria, Decision Process, Identify Pain, Champion. It's a sales framework, but it applies cleanly to how you position DevRel programs internally to get buy-in and budget.

Identify two or three mental models that fit your context and apply them consistently. The frameworks don't think for you, but they stop you from thinking in circles.

Block 7. Three Mistakes I'd Undo

I'd cast a wide net here because these aren't unique to me. Most operators I know have made the same three.

Mistake 1. Juggling Too Many Things at Once

I'm guilty of this to this day. Spreading thin across 10 projects means none get the depth they deserve. Right now I'm focused on the DevRel Workbench. In the background I still have to maintain my website stack and show up at work. The honest answer is two to three things at a time, max.

Not every project deserves equal attention. If project X is going to add more ROI than project Y, project X gets more depth. Map your projects to ROI. Time-box the rest. The quality of your output collapses when you context-switch this much.

Mistake 2. Focusing on Low-Priority Work

Being busy is not the same as being productive. I spent months polishing things nobody was going to see, optimizing things that didn't need optimizing. There's an old developer trap that captures this perfectly: until you hit 1,000 users, why are you worrying about Kubernetes. You can operate out of an Excel sheet at that scale. Scaling work you don't need for two to three years is theater.

The fix: ruthless prioritization. Ask "does this move the needle?" If the answer is no, cut it. This is where the Eisenhower Matrix and Pareto save you. Without a framework, everything feels equally important.

Mistake 3. Engaging for the Sake of Engagement

There's a lot of bait on social media right now. A lot of AI-generated slop content. People showing up to every event, every call, every Slack thread without a clear reason. They want to feel included. They want to feel part of it.

Trivial engagement gives the illusion of progress. The pipeline stays empty.

Instead of joining 15 different communities, pick two or three where your audience actually lives. It would not make sense for me to participate in Web3 conferences, my audience lives elsewhere. Quality of engagement beats quantity, and one deep conversation beats 20 surface-level exchanges.

DevRelUni works for me because the conversations are deep. Do less, but do it more mindfully. Burnout is not a flex.

Watch the Recording, Try the Workbench, or Just Start

Manik, thanks for the session and for pushing the structure. To everyone else in Cohort 7, see you in the next class.

Watch the full recording at the top of this post if you want the parts I cut for length, including the live workflow demo and the moments where Manik pushes back, about 46 minutes, worth your commute. Try the DevRel Workbench at 10xdevrel.atharvashah.com, four tools, free, open source, and if you ship feedback I'll prioritize it. And if any of this was useful, follow along: Substack at blog.atharvashah.com, X at @cultist_dev, LinkedIn at linkedin.com/in/atharva-shah-tech. This is one piece in a longer series on building DevRel and growth functions from scratch with AI as the backbone.

Go ship something today.

Leave a comment

AI content stays generic until the brief carries a market, a buyer and that buyer's KPIs. At AccuKnox, a cloud and AI security company, I mapped 11 markets and 33 personas into MagiHQ by hand before it wrote one draft.

Magi is an AI marketing platform that drafts content from the knowledge you load into it. The setup work was manual, and it decided the quality of every draft that followed. I tell the wider story in my two-year recap at AccuKnox.

TLDR

• A brief with an ICP (ideal customer profile) and a persona changed the first paragraph of the same draft from the same model.

• Map 1 market to 1 ICP to 3 personas before you generate anything.

• Give every market 4 competitors and 3 influencers, so the model knows the field.

• Require 11 frontmatter fields on every draft, so it arrives structured.

• Building all 11 markets took weeks of working sessions, and the drafts came after.

Structure Beat the Model, and 11 Markets Came Before One Draft

I ran one task twice with Claude: write the opening paragraph of an AI-SPM (AI security posture management) blog post for AccuKnox.

• Brief 1 held five product capabilities and the audience "cloud security buyers." The draft opened on how many models run in the cloud and then listed the capabilities in order.

• Brief 2 added one ICP, one persona, five pain points and five KPIs from the Magi setup. The draft opened on shadow AI and an auditor asking how many AI assets you run.

The model, the product and the market stayed the same. Only the brief changed. Both drafts sit in the Appendix.

Watch out. Claude wrote both drafts for this post, and Magi did not. They test the brief, and they say nothing about Magi's own writing.

I made the same point on X: every AI content tool I tried breaks at one step, which is writing before anyone decided what it should know about the company.

Six steps build that structure. Five of them are inputs, and generation comes last.

Step 1. Collect What the Company Already Knows

Pull every source the company owns. Classify none of it yet.

• FAQs and llms.txt

• Whitepapers and eBooks

• CVE pages and security advisories

• Help docs and sitemaps

• Playbooks for sales, onboarding and objection handling

• Sales call transcripts and objection logs

Sales calls and proof-of-concept conversations usually make better source material than published pages, because people explain the product plainly there. We still chose what to extract and how to classify it, and nothing arrived through automatic ingestion.

Tip. Collect first and classify second. Step 4 decides which campaign each file serves.

Shann Holmberg found 7 things that separate a knowledge wiki you keep from one you abandon.

Step 2. Map 1 Market to 1 ICP to 3 Personas

Each market became one campaign with its own ICP, three personas, competitors and influencers. Eleven markets give 11 ICPs and 33 personas.

The three personas follow one pattern in every market:

• User: the hands-on operators, such as security, DevSecOps and platform engineers.

• Buyer: the decision makers with budget, such as the CISO, the VP of Security and the AI governance lead.

• Partner or reseller: channel and account managers, MSP managers and integrators.

Every persona carries a description, use cases, pain points and the KPIs that person is judged on. Here is the full market grid inside Magi.

Each card is a campaign anchor. Open one and you see its ICP, personas, competitors and influencers.

Example. The AI-SPM User persona lists shadow AI, no standards, rapid rollout, poor visibility and compliance gaps as pains. Its KPIs are AI asset coverage, policy violations, risk events, audit readiness and MTTR. Those ten items are the input behind the second draft above.

This is the AI-SPM market with its use cases and its three personas mapped.

Step 3. Add 4 Competitors and 3 Influencers per Market

The rule for competitors is 4 per market, 2 broad platforms and 2 niche players. Each one gets a name, a website, a LinkedIn page, a blog and a one-line positioning summary. A model with no map of the field writes as if it has never seen the market.

Influencers are 3 per market, each with a name, a title and a LinkedIn link. We tracked them for signal. The people closest to a category write about its problems, and that is free market research.

The captured AI-SPM view shows three competitors filled and one slot open, plus five influencers, which is two more than the rule.

Step 4. Map Knowledge Files to Campaigns

One question drives this step: which file belongs to which campaign? Without the answer, a large source library is storage. With it, Magi pulls the right asset into the right campaign.

My brag list on atharvashah.com counts 648 campaign ideas generated from this setup.

Samiksha Shukla shares a 21-page context engineering guide on memory, retrieval, chunking and tools.

I use the same inputs-first pattern to run an AI marketing team with Claude skills.

Step 5. Require Eleven Frontmatter Fields

Frontmatter is the metadata block at the top of a draft. Every AccuKnox blog needed all 11 fields at generation time.

Tone guidance, category rules and required links went into the brief next to the fields. The draft then arrived close to publishable.

Rule of thumb. A field you leave optional is a field the model skips.

MagiHQ sits under Content and Marketing on my tools page.

Step 6. Generate From the Brief

The generation form takes a prompt, a campaign, a content type and ideas. This brief asked for a 1,500-word CNAPP blog post that compares AccuKnox's AI-powered Zero Trust CNAPP with Claude Code Security Review.

Magi reads the campaign's knowledge, finds a template and builds an outline. The brief is grounded in one campaign, one ICP and one knowledge source, and the buyer's pain shows up in the first paragraph, as the two drafts above showed.

Shann Holmberg calls a knowledge base the easiest low-effort win for an AI marketer.

The full AccuKnox story, with its numbers, is in the AccuKnox case study.

Five Questions a Newcomer Asks About the Magi Setup

Do I need Magi to use this? No. Any tool that takes a brief can hold the same inputs. A folder of Markdown files for the markets, ICPs, personas and competitors is a working first version.

Why 3 personas per market? Every market had a user, a buyer and a partner. Add a fourth only when a market has a fourth buyer who would read a different piece.

Why leave revenue size, industry, employee size and country blank? Those fields stayed empty on purpose, so segmentation happens at targeting time.

Where do I start collecting knowledge? Start with sales calls and help docs. They hold the plain-language explanations that published pages lose.

Does a better model fix generic content? The test above held the model fixed and changed only the brief. The opening changed, so the brief carries the quality.

The Appendix Holds Both Briefs and Both Drafts

Brief 1 holds features only:

Company: AccuKnox, a cloud and AI security company
Market: AI-SPM (AI security posture management)
Content type: blog post
Audience: cloud security buyers
Product capabilities: discover AI assets, govern model usage, secure pipelines, monitor access, enforce AI policies

Claude wrote Draft 1 on 2026-10-13:

Most security teams cannot say how many AI models, datasets, and endpoints run in their cloud today. Engineers spin up models in minutes, and each one reads data, calls APIs, and answers to no policy. That gap is what AI-SPM exists to close. AI security posture management starts with discovery of every AI asset, then governs which models people may use. It secures the pipelines that train and serve them, monitors who has access, and enforces AI policies. This post shows how AccuKnox helps cloud security buyers do each of these steps.

Brief 2 adds the ICP and the persona:

ICP: operates AI and LLM workloads without dedicated AI security tooling, and supports AI features used in its products
Persona: AI-SPM User, the hands-on operator
Pain points: shadow AI, no standards, rapid rollout, poor visibility, compliance gaps
KPIs: AI asset coverage, policy violations, risk events, audit readiness, MTTR

Claude wrote Draft 2 on 2026-10-13:

Your team shipped an AI assistant last quarter, and now three more models run in production that nobody on the security side approved. This is shadow AI, and it grows faster than any inventory you keep by hand. Each model has its own access keys, data sources and usage rules, or none at all. When an auditor asks how many AI assets you run and who governs them, you have no complete answer. AI-SPM fixes this by discovering every AI asset, enforcing policies on model usage and showing risk events as they happen. You get coverage you can prove and audit evidence that is ready on request.

The 11 frontmatter fields:

title, excerpt, slug, author, meta.title, meta.description, tldr,
primary_keyword, secondary_keywords, sticky_cta, faqs

Leave a comment

From zero to 18 flags: architecture, UX, challenge design, deployment, and launch strategy behind KubeArmor AI CTF.

Static workshops don't teach security. They teach patience. You sit through slides, nod at diagrams, and leave with zero hands-on reps. So instead of running another workshop, I built a full browser-first CTF platform in one day. A CTF, short for capture the flag, is a security contest where players hunt hidden strings called flags.

I work DevRel at KubeArmor, AccuKnox's open-source runtime security engine. The goal was simple: give AI security learners something they could actually play, not just watch.

says hands-on work counts in hiring too: "Hiring signals in this field skew heavily toward published research, CTF results and open-source contributions over certifications"

The result shipped with 3 tracks, 15 primary challenges, and 3 bonus flags, for 18 flags total. Registration and the scoreboard run on CTFd, an open-source platform for hosting CTF events. The gameplay runs on a custom browser app I built. Solve checks are deterministic, not model-dependent, and the whole thing deploys through Docker.

This is the build journal: the decisions, the tradeoffs, and the exact order I built things in to make one day work without the platform falling apart under real players.

Why Browser First Decided Everything Else

The first decision was strategic, not technical. If participation has friction, conversion drops. A CTF that demands local setup loses people before they see a single challenge. So the event had to run entirely in the browser.

That single choice split the platform into three pieces: CTFd for registration and official scoring, a custom browser app for the actual game experience, and a backend runtime that keeps secrets and challenge logic server side. Players get a scoreboard workflow they already trust from other CTFs. I get to build AI-native challenge interaction without fighting a plugin system that was never designed for it. And because the runtime, not the browser, holds the challenge logic, solve checks stay deterministic no matter what a player's browser can see.

The Build Order That Kept One Day on Schedule

My rule for this build: do not start from individual challenges. Start from the platform they run on.

I have watched CTFs sink into content sprawl before the runtime even works: a pile of half-formed challenge ideas and no working platform under them. So I locked the scope first. Three tracks, five primary challenges each, one bonus per track, CTFd as the scoring source of truth, the browser app as where players actually solve. Any ambiguity at this stage would have cost hours of rework later, so I fixed it before writing a line of challenge content.

With scope locked, I built the runtime shell next: Express and EJS, server-rendered pages that are simple to debug under time pressure. I was not trying to win a framework debate. I was trying to ship.

Before authoring the full challenge catalog, I validated one complete solve path per track, end to end: Prompt Injection, Agent Workflow, and Hidden API. Only after those three slices worked did I fill out the rest of the challenge JSON and the bonus progression logic. Admin and operational controls, reset paths, session visibility, the solution library, came last, because those exist for organizers, not for the players who show up first.

The one rule I broke early and paid for: AI output varies from run to run, so solve logic can't rely purely on model text. I paired every prompt flow with a deterministic regex or action check, which is what kept challenges solvable even when the model's phrasing drifted mid-event.

names the same reason: "LLMs are non-deterministic, meaning there’s no guarantee they’ll provide the same answer to the same question twice."

Architecture: Browser Game, Deterministic Checks, CTFd Scoreboard

Every challenge runs in the browser: prompt manipulation tasks, constrained agent workflow attacks, hidden API tamper paths. Nobody needs a local AI setup to play.

points to the same way to learn: "There is even a game to improve your prompt injection skills."

Challenges themselves live as JSON, loaded dynamically, so I could tune metadata, system prompt behavior, flag values, solve patterns, and track-level bonus progression without touching platform code. When the live LLM went unavailable or gave an inconsistent response during testing, a fallback mode kept the deterministic checks running anyway. That fallback saved a testing session more than once: I could keep verifying challenge logic even when the model itself was misbehaving.

Provider keys stay server side, with no raw secrets exposed to the front end. Solve state tracks per user session, and admin access to the control operations is role-based.

The UI Rule: Understand the Objective in Ten Seconds

I treated this as a product, not a challenge dump. I have seen enough CTF sites that are a bare list of problem statements and a submit box, and that shape works for people who already know CTFs, not for someone trying it for the first time.

So the home page works as a mission board with progress context, not a login screen. Track pages show the challenge list and status in one view. Challenge pages keep the conversation, the solved state, and the prompt box in a single loop, so nobody has to switch tabs to remember what they were doing. A player should understand what to do within seconds, see their progress at a glance, and get from home to track to challenge in one click.

For organizers, I built an admin dashboard with rate limit visibility and user management. It also gives quick access to solution guides, because a platform that's hard to run doesn't get run twice.

Testing for Trust, Not Coverage

The fastest way to lose a CTF's credibility is inconsistent solve behavior. If someone submits the right answer and the platform doesn't register it, that player stops trusting the event. So I prioritized testing ergonomics over coverage metrics: deterministic solve checks in the runtime, reset paths for fast retesting, seeded demo users, visible solve status per challenge, and structured session storage I could inspect directly.

Then three passes, each from a different starting point. Could I solve from a blank state quickly, could a peer solve using only the hints I'd written, and could someone with zero context finish a challenge with nothing but what's on the page? That third pass is the one most builders skip under deadline pressure, and it's the one that catches the UX gaps a creator is blind to after staring at their own platform all day.

CTFd Integration and Deployment

The deployment model is intentionally hybrid. CTFd handles registration, team context, and the scoreboard, because that's a solved problem and players already trust it. The custom platform handles everything CTFd was never built for: AI interaction, challenge runtime, deterministic solve checks. Forcing that into a CTFd plugin would have meant fighting the plugin system instead of building the game.

The runtime ships as a containerized Docker Compose stack, with a persistent volume for session and solve state and a root-level environment file for provider keys and rate limits. That gave me a local Node process for fast iteration during the build and a repeatable container for the actual event, with predictable data paths for backup and restore. For a DevRel-led event, setup friction for the organizer running it matters as much as friction for the player joining it, so Docker went in on day one instead of getting bolted on afterward.

Difficulty Design

Difficulty was layered on purpose: easy challenges build early confidence, medium stages teach the deeper patterns, hard stages demand chaining and precision, and bonus flags reward finishing a full track.

In testing, prompt injection challenges felt like the fastest track to clear. The workflow and hidden API attacks demanded chained, multi-step reasoning, and took noticeably longer to work through. That gap was the intended shape, not an accident: a beginner should finish a meaningful chunk of the event, and an experienced player should still hit real depth by the end.

How I Actually Vibe-Coded This

I used GitHub Copilot for most of the implementation. The speed came from fixing the intent and boundaries of each slice before I ever opened the editor, then using Copilot as a fast implementation partner inside those boundaries rather than accepting whatever it generated first.

The loop, every time: I wrote a clear objective for one thin vertical slice, one challenge page, one solve path, one admin operation. I drafted candidates with Copilot, validated the behavior immediately in the browser and in session data, and kept only the code that matched the deterministic solve logic and the product flow.

Vibe coding gave me speed. Fixed scope, deterministic solve checks, and that thin-slice discipline kept the quality from sliding, because scope never drifted mid-build.

For UI exploration, I used Google Stitch, Google's AI tool for UI design, as a design-thinking accelerator, not as final output. It generated layout directions and interaction ordering fast, and I translated the ideas I liked into the Express and EJS runtime by hand, which kept the reliability guarantees intact. Stitch helped most on the homepage's information hierarchy and the track page's scannability, and it shaped the rhythm of the challenge pages too.

How I Wrote Prompts During the Build

Prompt quality was the hidden multiplier. I didn't write one giant prompt and hope. Every prompt followed the same shape. The objective named what exactly should get built in this step. The context listed the files, routes, and constraints in play.

The guardrails named what must not change. The output contract set how I wanted the result formatted, and the verification named what should be true once it was done.

An example from the actual implementation work:

"Implement a deterministic solve check for this challenge route. Keep existing API shape unchanged. Do not move secrets client-side. Return minimal patch. Add only required validation and update solved state in session."

For content and UX iteration:

"Rewrite this challenge instruction so a first-time participant can act within 10 seconds without losing technical depth. Keep tone assertive and concise."

For debugging:

"Given this route and this observed behavior, list the top three likely failure points, then propose the smallest safe fix first."

Prompt granularity mattered more than anything else. Mixing an architecture decision with a copywriting pass and a debugging session in one prompt produced garbage every time. Smaller prompts and tighter loops meant fewer regressions to chase down later.

What I'd Improve Next

At larger scale, four things would need to change:

• Analytics would need to go deeper, down to the per-challenge step and drop-off point.

• The event would need richer anti-abuse controls, since a public run draws different behavior than an internal one.

• Flags would need a one-click relay straight into the CTFd API, instead of the manual sync I ran during the event.

• Reporting would need to cover learning outcomes after the event, not just the final scores.

The architecture held up because the split held: CTFd never had to pretend to be a game engine, and the custom runtime never had to pretend to be a scoreboard. That's the part I'd keep unchanged even at ten times the scale.

Leave a comment

Walking into a POC (proof of concept) scoping call with a 79-item checklist and no clear ranking is painful.

That was our reality.

Context, If You Have Never Sat in One

AccuKnox sells cloud-native security to enterprises. The platform covers posture management and runtime protection across Kubernetes clusters and cloud accounts. The buyer is a security team at a company large enough that a breach becomes a board-level event. Deals at that size never close on a demo. They close on a proof of concept.

A POC is a trial run inside the customer's own environment. It runs for weeks, not days, and the product has to prove itself against real infrastructure. Every step burns solution-architect hours and customer engineering time that neither side has much of.

EarlyGTM | Craft Ventures

Rules for running a sales "proof of concept"

Imagine this scenario: you’re an early stage founder or sales leader. Every time a customer validates the need for your product, it feels like the best thing you’ve ever heard. Every customer you talk to that isn’t as excited about what you’re building feels like a crushing blow…

Read more

6 years ago · 2 likes · Mike Marg

I am a DevRel engineer, so POC scoping is not my job. It landed on my desk because I sat close to the sales engineering team and watched the same failure happen on call after call. We would finish a scoping call with every box filled and no idea which three items to run first. Someone would then sequence the whole POC from memory on the drive home.

The problem was hard to solve inside a meeting and easy to solve in a spreadsheet. Nobody else had built that spreadsheet yet.

The Problem With Flat Checklists

AccuKnox covers a lot of surface area: CSPM, CWPP, KSPM, CDR, GRC, AI Security, ASPM, SAST, DAST, SIEM integrations, and CI/CD. KSPM is Kubernetes security posture management. CDR is cloud detection and response.

Prospects rarely need all of it during a POC. They need a subset that maps to their urgent risks.

Our old process ran on one flat spreadsheet where every feature carried the same weight, so nothing told us where to start.

We would leave calls with every box filled and still not know what to prioritize first. We knew what was selected. We did not know what mattered most.

Why This Is a Resource Allocation Problem

Assume a prospect has six weeks and three engineers, with limited bandwidth to spare. We have two solution architects.

Without a way to rank what the prospect cares about, three outcomes show up fast.

1. We spread too thin and demo everything shallowly.

2. We go deep on the wrong module.

3. We miss the one module that could have carried the deal.

The gap was visibility, not sales talent.

What I Built

I converted our POC checklist into a weighted scoring engine in Excel.

Scoring rules:

• Must POC = 2

• Nice to POC = 1

• Not Required = 0

Each of the 15 modules has its own feature rows. Prospects choose a priority per feature from a dropdown. Excel aggregates those weights by module and produces a weighted score automatically.

We also calculate max possible score per module as:

feature count * 2

Then we compute score percentage and status (High Priority, Medium Priority, Low Priority, Not Scoped).

The dashboard chart puts weighted score and max possible side by side for all modules. One glance gives the ranking. Prospect input now drives that order directly, instead of getting reinterpreted from memory after the call.

The Excel Logic Behind It

This is plain Excel, but structured properly.

1. Controlled Input via Data Validation

Checklist column E accepts only:

• 1 - Must POC

• 2 - Nice to POC

• 0 - Not Required

No free text means cleaner downstream calculations.

2. Weight Mapping Formula

Checklist column F maps dropdown values to numeric weights:

=IF(E2="1 - Must POC", 2, IF(E2="2 - Nice to POC", 1, 0))

3. Module-Level Aggregation

Dashboard weighted score per module:

=SUMIF('POC Checklist'!$B:$B, A6, 'POC Checklist'!$F:$F)

4. Max Possible per Module

=COUNTIF('POC Checklist'!$B:$B, A6) * 2

5. Safe Percentage Calculations

IFERROR prevents divide-by-zero noise.

6. Linked Chart

The chart is bound to the score table, so updates happen immediately when priorities change.

Across 79 features and 15 modules, recalculation is effectively instant.

What Changed After Rollout

Before, the checklist told us what got checked. Now it tells us what to tackle first.

Post-call notes changed from paraphrased impressions to numbers. A module score now reads as KSPM at 8 out of 8, CDR at 8 out of 8, AI Security at 27 out of 50, and the ranking itself tells the team to start with KSPM and CDR and push the AI Security deep dive to week two.

The highest-scoring modules get engineering focus first, and low or zero modules get deprioritized with a clear paper trail behind the decision. The POC that follows mirrors the priorities the prospect picked during scoping, not the priorities we guessed at afterward.

Fifteen Modules Overload Memory, Not Judgment

I built this because I got tired of watching a good team make sequencing decisions from memory and instinct. With 15 modules and 79 tracked features, memory is not a reliable ranking tool. People default to whatever they heard last on the call, not to what actually carried the most weight.

Scoring gives judgment a starting point instead of replacing it. The grader took one afternoon to build, and every formula in it is plain arithmetic.

The result is a priority map that updates with every prospect input and hands the team a ranked agenda before the follow-up call is even booked.

AccuKnox is an AI-native cloud security platform. It covers CNAPP, KSPM, CWPP, CSPM, CDR, AI-SPM, and related domains. If you want to see how we scope POCs, reach out.

Related reading: Local AI Photo Curation Pipeline (No Cloud) and Build an AI Security CTF Platform in One Day.

Leave a comment

Our sales team at AccuKnox, which sells a B2B security platform, used a shared Excel file for customer quotes.

Realistically, two people fully understood how it worked.

I am a DevRel (developer relations) engineer. Pricing tools are not in my job description.

I built one anyway.

The Spreadsheet Ritual

Quoting pain can look like a small nuisance from the outside. It burns hours every week, and everyone tolerates it because the sheet "works."

This is what quote creation actually looked like:

• Open the file. Find the right version, hopefully.

• Enter asset counts into a formula chain nobody has audited in months.

• Wait for a number.

• Copy that number into a Word template.

• Export the file to PDF.

• Double-check the final amount, because we had already seen dropped digits.

• Send it.

That took 30 to 45 minutes per quote, on the happy path.

Then came the hidden failures.

None of this is theoretical. I watched all of it happen.

The Calculation Had Eight Dependent Steps

A calculator sounds like the obvious fix. Pricing for a multi-module B2B security platform is not seat count times price, though. The calculation ran through eight dependent steps, and each one changed the others.

Pricing analyst Kyle Poyar tracks why SaaS pricing moved from seats toward usage.

Kyle Poyar’s Growth Unhinged

The state of SaaS pricing

A few years ago I started writing about what seemed to be a new trend in SaaS pricing…

Read more

3 years ago · 111 likes · 8 comments · Kyle Poyar

• Modules: About a dozen products, including cloud posture, workload protection, API security, multiple appsec modules, AI model security, prompt firewall, vulnerability scanning, and log analytics. Customers rarely bought one.

• Billable unit per module: There was no universal seat model. Billing could be assets, nodes, endpoints, repos, apps, AI models, prompts per month, container images scanned, or GB ingested per day.

• Per-module divisors: Raw counts had to be normalized first. 1,500 API endpoints was not 1,500 units. Divisors varied heavily by module.

• Volume tiers: Normalized units across all selected modules rolled up to one total. That total set the tier, and the tier set per-unit rate across the whole quote. One extra module could shift pricing for everything.

• Discount: Applied to the post-tier subtotal.

• Support tier: Silver, Gold, or Platinum, each with its own multiplier.

• Subscription term: One, two, or three years.

• Currency and billing entity: USD or INR. INR also needed lakh-crore formatting. 10,000,000 should render as 1,00,00,000. Locale differences between machines made outputs inconsistent. Billing entity also controlled address, footer text, and legal language.

That is eight to ten linked pricing steps per quote.

A spreadsheet hides those links. One wrong cell reference gives the customer a wrong price, and nothing warns you.

One bad spreadsheet formula contributed to JPMorgan's $6.2 billion London Whale loss.

Dear Analyst

Episode #38: Breaking down an Excel error that led to a $6.2B loss at JPMorgan Chase

This post originally appeared on the KeyCuts blog…

Listen now

6 years ago · Al

What I Built

I built a passcode-gated web app with a three-step wizard that outputs a branded PDF quote.

The design choices behind it mattered more than the interface.

Why Passcode-Gated Instead of Full Auth

A full login system would have delayed launch and added onboarding friction that this workflow did not need. Reps and select partners needed instant access from any device, including right before calls. A rotatable shared passcode fit the threat model and shipped fast.

OAuth could wait.

The entry point. One URL. No file attachments. No version confusion.

That URL became the distribution model. Nobody sent files, and nobody confused versions. When pricing changed, I updated the tool once and everyone got the latest values immediately.

Three Steps, One Order

I had seen the same failure pattern repeatedly. People skipped fields they found annoying and promised to fill them later. Sometimes they forgot.

The wizard blocks the pricing step until quote details are complete. It blocks PDF export until required fields are filled.

Step one captures everything that goes on the cover page:

Required fields with live validation. Nothing gets sent without a customer name, a preparer, a billing entity, and a logo.

Customer name, prepared-by, quote date, valid-until, billing entity, and customer logo are all required. The form blocks progression until they are filled. The valid-until date defaults to 30 days out so nobody sends an expired quote from an old template.

Here is what the same form looks like when it is done:

One Dropdown Switches Currency, Address, and Legal Text Together

Switching entities updates the registered address, currency defaults, number format, and legal footer simultaneously.

This took the most thought. It controlled a full downstream chain: currency symbol, number format, legal address block, footer text, and entity name. In the spreadsheet, these were manual and separate steps. People got one part right and missed another.

Select AccuKnox India Pvt. Ltd., and currency, formatting, address, and legal text switch together. The dropdown cannot check whether a rep picked the right entity on purpose. A rep still has to know which entity the deal belongs to.

The Pricing Engine

This replaced the old formula chain:

Eleven modules, live unit calculations, real-time tier tracking, and one very useful nudge.

The layout is intentional: inputs sit on the left, pricing impact sits on the right, and both stay visible at once. There is no "fill then calculate" flow. Reps type values and see outcomes live.

Each module row has three fields that matter:

• Count: Raw numbers from the customer.

• Divisor: Converts raw counts to billable units. I made this editable on purpose. Most reps should keep the defaults, but some deals require negotiated normalization factors. If the tool could not handle exceptions, reps would return to spreadsheets. Defaults are prefilled, overrides are visible.

• Units: ceil(Count / Divisor). Simple, visible, auditable.

The right panel handles everything else:

Total units are summed across selected modules. That single total sets the tier. The tier is quote-wide, not per module.

Price per unit, monthly list, annual list, discount, support multiplier, term modifier, and grand total update in real time.

The detail I cared about most was this message:

129 more units to unlock Tier 3 pricing ($22/unit)

In the old spreadsheet, tier thresholds were buried in formulas. Most reps never surfaced them during calls. That meant missed opportunities when a customer was already close to the next discount tier.

Now the threshold distance is explicit and live. Reps can test module combinations on a call and show the customer the tier effect right away, instead of promising to check and follow up later.

What Changed

Quote time dropped from 30-45 minutes to 3-5 minutes.

That gap matters. A same-call quote lands while the customer is still deciding. A next-day quote lands after they have moved on to other options.

Zero currency errors and zero wrong-entity quotes since launch. Nobody has reported an "Excel says one number, PDF says another" incident either.

New sales engineers can now produce correct branded quotes on day one. The spreadsheet used to require a one-hour walkthrough plus validation from a senior rep.

Quote cycles used to turn into long Slack threads. Rate card updates meant inbox blasts. New rep onboarding included spreadsheet survival training. None of that happens anymore.

Each quote is now a generated artifact tied to exact inputs. We can reconstruct what was quoted months later, including module mix, rate card, and discount.

If your B2B quotes still live in Excel, I am curious what your failure mode looks like. Reply here or find me on X.

Related reading: Composition vs Composable in Software Engineering and Shift Left Testing: Why Late Bugs Cost 100x.

Leave a comment

A private, reproducible AI pipeline for photo curation, captioning, music tagging, and folder export. No cloud uploads. No subscriptions.

I had 585 photos in one folder and no plan for them. I built a workflow with GitHub Copilot in VS Code that fixed this in one extended session. It ran on a Python script and a Markdown file, CURATION.md, that tracked every decision, across six phases. The folder became 62 ready-to-post directories. Every step happened on my own laptop, and no photo ever reached a server.

585 Images Named IMG_20241103_182344.jpg

Files in the folder looked like IMG_20241103_182344.jpg, sitting next to screenshot_edit_final_v3_REAL.png and remini-enhanced-kgwv6b.jpg, in no order at all. Every photographer collects a folder exactly like this one.

Lightroom already solves editing. It does not solve curation at scale. That work means deciding which 12 photos from a three-day trip belong together. It means keeping the pacing across 60 posts from repeating the same mood, twice on adjacent posts.

Music has to match the visual energy of each post, without reusing a track on the post next to it. And certain people and certain locations have to stay off public content entirely. An AI can close that gap, but only when you hand it the structure to work from.

From One Folder to 62 Named Directories

I used GitHub Copilot in VS Code and local Python 3. In one extended session, I went from a raw image dump to this:

Every operation happened locally. Copilot read filenames and the descriptions I had logged, not pixels, and my own curation criteria decided every grouping. My photos stayed on my machine the entire time.

The CURATION.md summary table: 62 active posts, 585 images assigned, zero cuts. This single document replaced every folder, sticky note, and spreadsheet I would have otherwise needed.

The Input Prompt That Started Everything

Here's the prompt architecture. Adapt it to your project:

I have [N] photos in [local folder path].

My goal: group them into [platform] posts for publishing over [timeframe].

Curation criteria:
- Timeline: roughly chronological, anchored to real events/trips
- Location: photos from the same place should travel together
- Vibe / mood: visual tone should be internally consistent per post
- People: flag posts that include [specific people] so I can decide on privacy
- Quality gate: no blurry, test shots, or obvious duplicates in any post

I have [an existing metadata log / no log — build one].
My image folder is [path]. Compressed derivatives live at [path].
My music taste: [genres, artists, references].

Deliverables I want:
1. A CURATION.md with all posts, image assignments, captions, music picks
2. A Python export script that builds a FINAL/ folder from CURATION.md
3. A post.txt inside each FINAL folder with caption + music ready to paste
4. An audit flag if any post breaks the [platform] image cap

Privacy requirement: all processing must be local. No uploads.

The Six-Phase Workflow

Phase 1 Audit and Inventory (Don't Skip This)

The AI didn't start with grouping. It read the existing metadata, counted files, and ran a structural audit first, and that audit found three problems before a single post got named. One post had 24 images, past Instagram's hard cap of 20, so it got split into two. Index 208 in my image log turned out to be a session boundary marker, not a real image, silently included in a post assignment. Thirty-two images from my oldest batch had never been individually logged.

Lia Haberman reported the carousel limit change when Instagram rolled it out.

Skipping this step would have shipped a broken export. The oversized carousel would have silently dropped four images at upload time. The ghost index would have thrown a file-not-found error during export. Neither failure would have announced itself without a deliberate check first. That is why the audit runs before anything else now, on every batch.

A section of image_log.md. SESSION 3, images 33 through 48. Each image logged with its compressed filename, a plain-English description, and a semantic tag. The AI read this file and built groupings from it. Not a single pixel crossed the wire.

Phase 2 Grouping by Timeline, Location, and Vibe

Grouping 585 images from 18 months of shooting was the hardest part of the whole project. Photos cluster naturally by trip or life phase first. Location matters within that: a Mumbai weekend and a Goa weekend can happen close together in time and still look nothing alike, so they need separate posts.

Vibe breaks the tie when two image sets share a timeline and a location but split by mood. One trip can hold a golden-hour outdoor set and a nightlife indoor set, and those still need separate posts. People acted as a privacy gate throughout. Any image with certain people in it got flagged for my own review before it could go into a public post.

The AI proposed 60 posts initially. After the audit, that became 62, two splits from the carousel-cap fix, plus the 32-image unlogged batch resolving into two dedicated archive posts.

Each post got a real name instead of a filename, something like P41 — Kerala — Backwaters + Garage Café + Coast. Getting there took a few passes at the title until it matched what was actually in the frame, rather than just where the photos were taken.

Key Clusters and Themes Discovered: the AI's location map of the library before a single post was named. Clusters like "KATHA Records Series" and "CSMVS Museum" emerged from overlapping session ranges and shared visual context.

The Post Details section of CURATION.md. Each cluster converted into a named post with exact image indices and a one-line description of the visual brief. P05 (OOTDs and Mirror Selfies) came in at a full 20 images, right at Instagram's carousel cap.

SESSION 6 in image_log.md, images 81 through 96. The tagging discipline held across every batch: filename, description, and a semantic tag. Enough for the AI to reason about visual groupings without ever seeing the photos.

Phase 3 Building the Export Script

This is what made everything reusable. export_final.py is a Python script that:

1. Reads CURATION.md as the source of truth

2. Parses the image index list for each post

3. Resolves each index to the actual filename on disk (handling AI-enhanced variants, shortened UUIDs, WhatsApp-formatted names)

4. Copies the HD original into FINAL/<PostID> - <Title>/P01a.jpg, P01b.jpg...

5. Writes a post.txt alongside the images with caption, music, and rationale

6. Outputs an _EXPORT_REPORT.md, a full accounting of every post, file count, and any resolution errors

The resolver was the interesting part, because my filenames came in three different formats depending on which app had touched them last: IMG-20250103-WA0012.remini-enhanced.jpg from WhatsApp plus a suffix from Remini, an AI photo enhancer app, FF92EE38.jpg as a shortened UUID from a different app, and -kgwv6b.remini-enhanced.jpg as a partial hash format. The resolver cascades through them in order: exact match, then strip the .remini-enhanced suffix, then match on the first 8 characters as a prefix. Zero images failed to resolve.

The export script is also idempotent. Every run wipes FINAL/ and rebuilds it straight from CURATION.md. Edit a caption in CURATION.md and run the script, and the change is live in FINAL/. Move an image to a different post and run the script, and the folders reflect it instantly. CURATION.md is always correct, and FINAL/ is only ever a derived artifact of it.

P19, Golconda Fort Hyderabad after export: 10 images renamed sequentially (P19a through P19j), plus a post.txt with caption and music. Every file moved into place by the script, zero manual work.

D:\Remini\FINAL. 62 named, themed folders generated from CURATION.md. From "P01 - Desk & Dev Setup" to "P48 - Hotel Mirror Selfie + Canal Night" and beyond. One script run, fully reproducible.

Phase 4 Captions and Music

The caption philosophy was simple: terse and atmospheric for travel and scenery posts, since a Taj Mahal photo doesn't need the Taj Mahal explained under it, and warmer and more personal for portrait or home posts. No hashtag spam went into the draft, since that's a posting-time decision, and every caption had to add something the image didn't already say on its own.

The live VS Code session: post.txt open for P01, Desk & Dev Setup, CURATION.md active in adjacent tabs, the AI mid-way through captioning P21 to P30. Caption, music, and rationale drafted in one continuous pass.

Music followed a different rule: each track's mood had to amplify the image rather than fight it, and no generic "lo-fi beats" filler was allowed to stand in for an actual choice. After all 62 posts were drafted, a deduplication pass caught one track assigned to three different posts, plus several more repeating on posts that sat next to each other or shared a mood. Six swaps fixed it, each one a deliberate match for the post it landed on rather than a random substitution.

The export script stores a TRACK_REASONS dictionary for every post, recording why the music works. Months later, when I no longer remember the session, that reasoning is still sitting right there next to the file.

The Phase 3 Queue in CURATION.md. 13 of the 62 caption and music drafts. Disclosure for a locked-in desk setup, Cigarettes After Sex for a low-light portrait series. Each track justified by the visual energy of the post, not picked at random.

Phase 5 The QC Pass

Before calling the project done, we ran a coherence check across four questions. Does every image in a post share a real through-line, visual, narrative, or emotional? Does the title name what's actually in the post, or just where the photos were taken? Is the music still clean of duplicates after the Phase 4 fix? Are any captions too generic, too try-hard, or over-explaining the photo underneath them?

One title fix came directly out of this pass. P41 — Kerala became P41 — Kerala — Backwaters + Garage Café + Coast, because the images underneath it were three genuinely different subjects. The vague title would have misled anyone looking at the archive later, myself included.

Phase 6 Visual Sanity Check

The final step was a visual review, guided by AI-generated contact sheets. For the two most uncertain posts, P60 (Early Heritage & Portrait Archive) and P62 (Early Interiors, Culture & Misc Vibes), we generated contact sheets with PIL, the Python Imaging Library, a grid of every image in the post rendered at thumbnail size:

from PIL import Image
import os, math

def make_contact_sheet(folder, output_path, thumb_size=(300, 300), cols=5):
    files = sorted([f for f in os.listdir(folder) if f.lower().endswith(('.jpg','.jpeg','.png'))])
    imgs = [Image.open(os.path.join(folder, f)).convert('RGB') for f in files]
    thumbs = [i.copy() for i in imgs]
    for t in thumbs: t.thumbnail(thumb_size)
    rows = math.ceil(len(thumbs) / cols)
    w, h = thumb_size
    sheet = Image.new('RGB', (cols * w, rows * h), (30, 30, 30))
    for idx, t in enumerate(thumbs):
        x, y = (idx % cols) * w, (idx // cols) * h
        sheet.paste(t, (x, y))
    sheet.save(output_path)

Within seconds of viewing the P60 contact sheet, two images looked wrong next to the rest of it. A white fabric close-up and a lakefront scene had ended up alongside Jantar Mantar stonework and Mughal architectural portraits. Both moved to P62, which had a looser, more eclectic brief anyway and could absorb them without breaking its own coherence.

A filename list would never have caught those two images. The contact sheet did, in the time it took to look at it once.

P50, Goa Resort Morning after export: 14 images renamed P50a through P50n, with post.txt alongside. The original filenames were a mix of remini-enhanced variants, abbreviated UUIDs, and WhatsApp-formatted timestamps. The resolver handled all of them.

What Made This Different From Auto-Tagging Tools

Nothing left my machine during any of this. Python read local files, Copilot read filenames and logged descriptions rather than pixels, and the export script copied files within the same drive. That mattered more than speed did. The alternative was uploading 585 personal photos to a service to get them auto-labeled. I wasn't willing to do that for a set that includes people I'd rather keep off a server I don't control.

The bigger difference was that the AI worked from criteria I actually wrote down, not a fixed label set. I reviewed every grouping before it became final, so the curation stayed mine even though the sorting was automated.

CURATION.md also turned into something more than a working file I'll delete later. It holds every grouping decision and every caption, plus the reasoning behind each music pick, so six months from now I can still see why two images landed in the same post. The same setup handles 100 images or 5,000 without changing shape. Next time I dump a new batch, I run the same prompt architecture, add any new filename pattern to the resolver, and get another FINAL/ folder out the other end.

Take It With You

I packaged the entire workflow into a SKILL.md. Any AI assistant that supports the VS Code Copilot skill format can invoke it. The file contains the six-phase workflow, the CURATION.md schema, and the export script skeleton, along with fixes for the failure points this project actually hit: the carousel cap, the ghost index, and the three filename formats.

Drop it into your VS Code setup. Point it at your folder. If you want the SKILL.md file itself, ask. I'll send the version that already handles WhatsApp exports and Remini-enhanced filenames, so you are not rebuilding the resolver from scratch.

Run It Yourself

Here's the full starter prompt:

I have [N] photos in [local folder path].
My target platform is [Instagram / Substack / portfolio / personal archive].

Curation criteria:
- Timeline: [yes/no, describe the date range]
- Location: [yes/no, describe the geography]
- Vibe/mood: [describe your visual style — e.g., "film grain, golden hour, blue interiors"]
- People: [flag posts with [names] for my privacy review]

I have [an existing metadata log at path / no log — build one from filenames].
Compressed derivatives are at [path / same folder].
Music: I like [genre / artists / specific tracks file at path].

Please:
1. Audit: count files, find cap violations, flag ghost indices
2. Group: propose posts with names, index assignments, and image counts
3. Export: write export_final.py that builds FINAL/ from CURATION.md
4. Caption + Music: draft all posts, log TRACK_REASONS
5. QC: flag music collisions, title vagueness, grouping incoherence
6. Visual: generate PIL contact sheets for any flagged posts

All processing must be local. No uploads.

Leave a comment

Uketsu writes under a mask. He is a Japanese YouTuber of undisclosed identity, known for a white papier-mâché face and a voice run through a pitch shifter, who built an audience on short videos where ordinary objects sit slightly wrong. Strange Houses (2021), his first novel, carried that same trick onto the page: floor plans, drawings, and case files appear as literal images the reader studies, not prose describing them. Jim Rion's English translation reached UK and US shelves in 2025 through Pushkin Vertigo and HarperVia, and the two novels that followed, Strange Pictures and Strange Buildings, kept the mechanic and pushed it further.

Read the three back to back and one argument runs under the puzzles: the spaces people live in record what happens inside them, love does more damage than hatred does, and the truth sits one layer beneath whatever a witness is looking at. Fifteen patterns carry that argument across the trilogy.

Part I: How Uketsu Builds the Mystery

1. The detective who never leaves his desk

In Strange Buildings, Kurihara solves a nationwide cult conspiracy without visiting a single site. He plots eleven reader-submitted case locations on a map of Japan, finds they trace a perfect circle, and reads the center point as the cult's Hall of Rebirth. A compass and a set of coordinates did the work.

That is how every Uketsu investigation runs. Two people carry each case: one who goes to the scene, and one who never does. In Strange Houses and Strange Buildings, the Author, as the narrator is called, is the field agent, visiting houses and interviewing witnesses. His friend Kurihara, an architectural draughtsman, works from a desk and turns a geometric anomaly on a blueprint into a full hypothesis, a hidden room or a murder scene, without ever leaving his chair.

2. The clues are already on the page

Uketsu puts his evidence directly on the page rather than describing it. Floor plans appear as floor plans. Drawings appear as drawings. The reader holds the same physical evidence the characters hold, at the same moment they hold it.

In Strange Pictures, a reader can perform the layer composition alone: stack the three drawings over their circled axes and watch an innocent sketch resolve into the murder image Yuki, the blogger's wife, hid inside it. In Strange Houses, a reader can overlay the two floor plans and find the dead space before Kurihara names it.

The mystery is solvable before the characters solve it.

3. The truth arrives in fragments, never straight

Strange Pictures opens inside a defunct blog, using a husband's cheerful domestic posts as the primary record for a murder investigation. Strange Buildings pieces its conspiracy together from a 1940 travelogue and a 1994 undercover tabloid article, then confirms it against the published diary of a nine-year-old boy who died of neglect mid-sentence. His entries get shorter as the book goes on, the handwriting deteriorates, then they stop.

Uketsu never narrates events directly. Every fact in these books gets rebuilt from documents, and every document is incomplete, unreliable, or filtered through a narrator with a reason to omit something. Each fragment carries someone's version of events, not the events themselves.

4. The clue is the thing that's missing

In Strange Pictures, a husband buys an eight-slice anniversary cake. He eats two slices and his wife eats one. Four more go into the fridge for breakfast, which brings the count to seven, one short of eight. Kurihara reads that missing slice as evidence of a third person living in the house, hidden from every blog post.

In Strange Houses, the Saitama floor plan has no garage, and the killers needed somewhere to put an intact body. Kurihara works backward from that missing room and finds the underground cellar dug beneath the garden. In Strange Buildings, a walking stick goes missing from a mobility-impaired woman's room the night she dies on the stairs.

Uketsu's key clues are almost always absences. Something that should exist does not, and finding what fills that gap finds the crime.

5. Layer one thing over another and the hidden shape appears

Reality in Uketsu's work hides under a transparency, not behind a wall.

Stack the first-floor blueprint over the second-floor blueprint in Strange Houses and the "dead space" lines up exactly with the windowless child's room above and the windowless bathroom below. What looked like a wasted pocket of air is a vertical murder tunnel.

Stack the three drawings in Strange Pictures, aligning their circled numbers, and a baby in a Santa hat becomes a surgical incision, a praying old woman becomes a doctor pulling a baby out of a body, and a woman lying down becomes a corpse.

In Strange Buildings, a modern two-story house in Nagano sits around, not on top of, a 1938 gothic watermill. The house is the second layer, placed over history nobody wanted to acknowledge.

6. An ending that takes back what it just gave you

Each book earns a resolution, then reverses it.

In Strange Houses, Keita Katabuchi's confession letter reads as tragic and decent: he built the trap-houses to fake ritual murders and protect his imprisoned son from a cult that demanded real kills, then surrendered himself so his family could survive. Then Kurihara points at one detail on the Tokyo floor plan, a small interior window between the living room and the bedroom. Interior windows exist to let someone watch the room, not to let in light. Kurihara asks whether Keita was the protector in his own story, or the prisoner his wife, Ayano, watched constantly. The letter does not change. What the reader does with it does.

In Strange Pictures, Doctor Hagio reads a child's drawing of a bird inside a thorny tree as evidence of nurturing love strong enough to overcome the patient's aggression. The ending reveals the thorns were there to protect the bird, and Hagio was right about the love. She missed what it was defending against.

Part II: What the Houses Do

7. One company, two kinds of violence

Uketsu treats architecture the way thriller writers treat guns, as a tool one person designs to hurt another person.

In Strange Buildings, Hikura Homes builds a mansion for a wealthy client with a deliberate gap at the top of the main staircase, no wall and no handrail, sized to be fatal to someone with a mobility impairment. The grandmother who lives there and struggles to walk was killed by the floor plan, not by a person.

The same company also builds mass-market homes with plumbing that guarantees mold and bedrooms with no privacy, laid out as through-corridors. It converts storage closets into bedrooms and calls one a teenager's room. These houses do not kill on a schedule. They grind people down until someone snaps.

One company builds custom murder machines for the wealthy and mass-produces psychological attrition for the poor. The product changes. The contempt does not change.

8. The nicer the exterior, the worse the interior

The more Uketsu hides inside a building, the more the outside performs welcome.

The Katabuchi murder house in Strange Houses has sixteen exterior windows, which Kurihara flags as deliberate. Sixteen windows serve no functional purpose. They are a performance, telling anyone who looks that there is nothing to see. The windowless rooms sit at the center, and the light show stays on the outside.

Toho adapted Strange Houses into a 2024 film.

In Strange Houses, the retrofitted triangular sunroom on the Saitama house has large windows facing the garden, immediately blocked by the walls framing the room, with no functional access from inside. It was built as a cover story for the underground cellar excavated beneath it. Someone needed a reason to be digging in the garden, and the sunroom is that reason.

9. A space with no explanation is where the truth lives

The ancestral Katabuchi estate in Strange Houses runs a hidden passage system behind a massive, immovable Buddhist altar at the center of the house. The sliding doors that would open onto that passage are jammed shut, so from outside that wing simply reads as closed. Behind the altar sits a confinement room nobody is supposed to know exists.

In Strange Buildings, Yayoi Negishi grew up with a hallway that dead-ended at a blank wall between her bedroom and her parents'. It led nowhere, and her mother built her daughter's whole life around a corridor with no destination.

In Strange Houses, the dead space between the kitchen and the living room of the Tokyo house is a vertical shaft, not a construction error, an interior the floor plan never mentions.

That's the shared premise across all three books: the space with no official explanation is the space where the truth lives.

Part III: What the Books Are Actually About

10. Mothers who destroy the thing they love

Maternal love in Uketsu's work is the most dangerous motivation in the trilogy, never a softening one.

In Strange Pictures, Naomi Konno killed her abusive mother to protect a pet bird, killed her husband to protect her son, killed her son's wife to possess his child, and killed a reporter to protect her life with that child. Every person she killed was a threat to something she claimed as hers.

Doctor Hagio looked at a child's drawing of a bird inside a thorny tree and read it as evidence of nurturing love. She was right about the love. She missed what the thorns were guarding against.

In Strange Buildings, a mother tries to pay a construction company to surgically remove her daughter's bedroom from the house, not out of cruelty but from a cult-driven belief that reshaping the floor plan will protect her child. The love in both cases is real. That does not make it safe.

11. Trauma that moves into the walls

Horror in these books gets inherited, moving down the family line into the buildings instead of staying with the person who first felt it.

The Katabuchi family in Strange Houses had already been building hidden rooms and secret passages for generations before the story starts. The ancestral estate, built decades earlier, already held the jammed sliding doors and the confinement room behind the altar. The modern Tokyo house did not invent any of it. Each generation built a new version of the same structure because no one in the family had found a way to stop.

In Strange Buildings, the Rebirth Congregation targets people carrying inherited guilt, an affair or a child born with a disability, and sells the architectural reformation of their homes as a cure for the sins that produced them. The transaction only works if the guilt stays permanent and transferable. The business model needs the wound to stay open.

12. Children who never get to be children

In Strange Houses, Momoya is raised from infancy in a windowless room behind double doors, with an en-suite toilet so he never has to leave. He is given a chute and a task. He is ten years old.

The first time he uses the secret passage built for him, he does not go to hurt anyone. He goes to the master bedroom to press a damp cloth on a sick baby's forehead.

In Strange Buildings, the nine-year-old boy Naruki keeps a journal. He writes about being locked in a closet and not being fed. He writes that his stomach does not hurt anymore, only feels tight. His entries get shorter, then they stop. The journal was later published as The Lonely Death of Naruki Mitsuhashi.

In Strange Pictures, a five-year-old boy draws his dead mother's gravestone on a Mother's Day card. His kindergarten teacher reports his mother for abuse.

13. Why it is always the left hand

In Strange Houses, the Katabuchi family curse demands the "Offering of the Left Hand." Every child born into the family without a left hand must, between ages ten and thirteen, murder a member of the rival branch and sever the victim's left hand for the altar. A manipulator invented the ritual generations ago, and the family kept obeying it anyway.

In Strange Buildings, the Hall of Rebirth is built in the exact shape of a woman missing her left arm and right leg, an amputated body made into architecture. Cult members remodel their own homes to match the same proportions, bricking over windows and removing rooms until their floor plans mirror the limbless idol.

14. The corporation is the villain, not a person

Uketsu does not confine evil to individual people. In Strange Buildings, the primary antagonist is a corporation.

Hikura Homes builds the Tsuhara house with total disregard for what its cramped, no-privacy design will do to the people living inside it. It builds the mousetrap mansion knowing exactly what the staircase gap will do. It constructs the Hall of Rebirth as physical headquarters for the cult it founded and operates, then sends salespeople to congregation members the morning after their religious sacrament to sell them remodeling packages.

The cult and the construction company are the same organization. The guilt is the product, and the house is what you buy to manage it. Cure the guilt, and the business ends.

15. Violence that solves a forensic problem, not an emotional one

The gore in these books works as forensic logic, rarely as emotion.

In Strange Houses, the Katabuchi family dismembers their victims because an intact adult body cannot fit through the narrow architectural chutes connecting the child's prison to the garage. The house demanded the dismemberment. It was logistics, not sadism.

In Strange Pictures, Naomi Konno beats a man's body more than two hundred times with a rock, and the mutilation is a technical requirement rather than an act of rage. It destroys the physical evidence a pathologist would use to calculate time of death from rigor mortis or body temperature. With that evidence gone, the only method left is stomach contents, which Naomi has already controlled by force-feeding her victim a specific meal at a specific time.

The two hundred blows are a calculation, not a loss of control. The body is a clock she needed to stop.

Naruki's journal entries get shorter for the same reason the dead space in the Tokyo house never appears on paper: nobody recorded either one while there was still time to do something about it. That gap between what a floor plan admits to and what actually happened inside it is where Uketsu has now built three novels, and it is still standing open at the end of the third one.

Leave a comment

Uketsu writes mysteries in which the murder weapon is a floor plan. He means a real architectural drawing, printed on the page. The reader is expected to solve it before the narrator does. Strange Buildings is the second novel built that way. In this one the trick stops being a gimmick and becomes a genre.

Who Uketsu Is

Uketsu (雨穴, "rain hole") is a Japanese author and YouTuber whose real identity is known to approximately 30 people. He appears in public in a white papier-mache mask, a black bodysuit, and a voice changer. He lives in Kanagawa Prefecture. He worked at a supermarket when he started to post surreal videos online: asparagus turning into severed fingers, raw meat hung on a washing line, eight human ears spinning on a wheel.

In 2020, he posted a 21-minute mystery built around a series of architectural floor plans. Publishers told him to make it a novel. That novel became Strange Houses (2021).

This is the 2020 video by Uketsu that became Strange Houses.

Strange Pictures followed in 2022. Strange Buildings (変な家２, Hen na ie 2) came out in Japan in 2023. The English translation arrives in 2026. It is a direct sequel to Strange Houses, keeping the same Author-narrator and the same Kurihara. Kurihara is an architectural draughtsman who decodes the floor plans. It also keeps the same project of using architectural floor plans as forensic evidence.

Jim Rion translated both Strange Houses and Strange Pictures into English for Pushkin Vertigo and HarperVia. He has lived and worked as a translator in Japan since 2004, and the same publisher pairing is the likely home for Strange Buildings when it reaches English readers.

John Hill, an architecture writer, reviewed the English translation in March 2026.

A Weekly Dose of Architecture Books

An Architect Reads Uketsu

This newsletter for the week of March 9 looks at the latest “chilling Japanese mystery sensation” by the anonymous author and YouTuber Uketsu. Published last week, Strange Buildings, like the first two books (Strange Pictures and Strange Pictures, both published last year), tells a mystery in words and images, the latter mainly floor plans. Sounds like …

Read more

8 months ago · 37 likes · John Hill

By 2024, three of Uketsu's novels sat in Japan's top 10 fiction bestsellers at the same time. Strange Pictures alone sold over 1.5 million copies in Japan. Translators took it into 30-plus languages.

Strange Buildings is the most ambitious of the three novels covered in this series. It drops the single central case of Strange Houses and the four interlocking stories of Strange Pictures. It presents eleven separate reader-submitted files about architectural anomalies. Each file looks isolated, and each one connects secretly to every other. The final reveal is larger than anything Uketsu attempted before. A nationwide cult conspiracy sits encoded in the floor plans of ordinary Japanese homes.

Why This Summary and Analysis Exists

No complete, chapter-level English-language breakdown of Strange Buildings exists. The book still lacks wide coverage outside Japan. This is the full summary and analysis. It covers all eleven files, the climactic deductions, and the master map of every planted clue. This page carries complete spoilers throughout.

Prologue

The Author, the same freelance writer who investigated the Katabuchi family in Strange Houses, receives eleven new files from readers. Each file describes a bizarre architectural anomaly. One case is a hallway that goes nowhere, another is a building shaped wrong, and a third is a room with a door that should not exist. At first glance the cases are unrelated, and on examination they reveal one story of interconnected crimes across decades.

File 1: The Hallway to Nowhere

The House Yayoi Grew Up In

Yayoi Negishi is a woman in her thirties. She consults the Author about her childhood home in Toyama Prefecture. A company called Housemaker Misaki built it in 1990. The single-story house had a dead-end hallway between her parents' room and her own. It led to a wall.

Uketsu adapted this first file as a video on his own channel.

Her mother was cold and distant toward Yayoi. She was obsessively protective about one thing. Yayoi could never walk on the main road south of the house. The mother was not anxious in general. She was anxious about that road alone.

After her parents died, Yayoi found two strange objects among their belongings. One was a hidden stash of 680,000 yen in cash. The other was a wooden doll missing its left arm and right leg.

Yayoi has a theory. The hallway was meant for a twin sibling who died in utero. The Author investigates local newspaper archives and disproves this through architectural logic.

He finds something else. A Housemaker Misaki construction truck struck and killed a child in 1990. It happened right in front of the home plot, just before the house went up. The original entrance was planned to face the road where the accident happened. Yayoi's mother paid to have the entrance moved.

The representative from Housemaker Misaki adds one final detail. Five years after the move, Yayoi's mother returned to the company. She tried to hire them to remove Yayoi's bedroom from the house. That job was expensive and structurally significant. The mother could barely afford it. She kept asking anyway.

A Floor Plan as a Confession

The "hallway to nowhere" is the novel's entry point into its governing theme. Houses are physical confessions of psychological guilt. The mother cannot walk past the place where a child died. She cannot live in a house whose front door opens onto that site. She is willing to destroy her daughter's bedroom to correct the floor plan of her guilt.

At this stage of the novel, the amputated wooden doll is a grotesque non sequitur. By the final chapter, it is the key to everything.

Where the Doll Leads

The amputated wooden doll prefigures the "Holy Mother" of the Rebirth Congregation, introduced in File 6. She is a woman missing her left arm and right leg. She is the figurehead of a cult that exploits parental guilt.

Yayoi's premature birth blocked the newborn blood test. As Kurihara later deduces, Yayoi was conceived in an affair. The mother's road prohibition was not about the accident. It came from fear that any hospital visit with a blood transfusion would reveal Yayoi's blood type to her husband.

The mother's attempt to remove Yayoi's bedroom was an act of cult devotion. The Rebirth Congregation instructed members to alter their homes physically, so that each home matched the amputated form of the Holy Mother as a ritual of penance.

File 2: Nurturing Darkness

The Tsuhara House Killings, Reconstructed

Tatsuyuki Iimura is a forensic cleaner. He recounts the "Tsuhara house" in Shizuoka, a 2020 crime scene. A 16-year-old boy allegedly took a kitchen knife and stabbed his mother. He then killed his bedridden grandmother and younger brother.

Iimura provides the floor plan. A corporation called Hikura Homes built the house as a mass-produced "commodity home". Plumbing crammed into the north side caused mold and persistent odors, and nobody had real privacy. The bedrooms worked as through-corridors, so everyone passed through everyone else's space constantly. The 16-year-old lived in a converted, windowless storage room. Iimura argues the suffocating architecture "nurtured the darkness" in the boy.

The Author re-examines the forensic record. The grandmother's eyes were closed at death. The mother had no defensive wounds except the knife entry point. The teenager had multiple slash wounds on his hands and arms.

The Author reconstructs the actual sequence. The mother cared for a bedridden relative in an intolerable home, and the weight shattered her. She attacked the grandmother in her sleep. The teenager fought his mother to stop her, and she cut him repeatedly. He killed her by accident in the struggle. Then panic and shock made him attack his younger brother.

The teenager's "kills" were a consequence of someone else's snap, in a house designed to make everyone inside it worse.

A House Built to Fail Everyone Inside It

This chapter expands the novel's thesis from the individual scale to the systemic. The Tsuhara house is a product, mass-manufactured by a corporation optimizing for cost and profit, not a deviant design. Hikura Homes built it this way, and everyone who lived in it has since died.

The media used a "killer teen" framing, and Iimura adopted it at first. The Author's forensic re-reading rejects it.

Hikura Homes' First Appearance

Hikura Homes enters here as a corporation with a troubling history. Rumors in the 1980s said the president abused "some little girl." The company answered those rumors with aggressive media management and reputation control rather than accountability. That rumor pays off in File 10 as something far worse: Masahiko Hikura, the future chairman, bought a child from a yakuza-operated brothel.

File 3: The Watermill in the Woods

Uki Mizunashi's 1938 Discovery

The Author presents an excerpt from a 1938 travelogue by Uki Mizunashi. She is a steel magnate's daughter, and she visits her uncle's rural property in Nagano. She discovers a watermill in the forest that has no water source. She turns the massive exterior wheel by hand, and an interior wall slides forward. That opens a hidden, doorless confinement room.

Outside the mill stands a small shrine with a statue of Kishimojin, the goddess of children's protection. The statue holds fruit and no baby. The mill's second room holds a square alcove, exactly the size for a person to curl up in.

Uki uses the wheel to open the hidden room. She finds a rotting body, and she describes it as a "female egret" missing the tip of one wing.

She flees. Her written theory calls the mill a gothic execution chamber, built by a cult to crush sinners against the goddess's image as the mechanical wall advanced.

A Machine Needs Someone to Run It

This chapter drops the novel into gothic horror without explanation. The watermill is a machine, and machines require operators. Someone built this. Someone used it. The statue of Kishimojin missing her baby does not represent abstract spiritual emptiness. Something happened to the baby that the goddess was supposed to protect.

The Egret Is Okinu

The "female egret" is the body of Okinu, a maid of the Azuma family. File 5 identifies her. The "missing wingtip" is her severed wrist, consistent with the mechanical wall closing on her arm.

The square alcove inside the mill existed for protection, not execution. Someone hid a baby there. That baby is Yaeko. The mechanical wall closes on her as an infant and takes her left arm. Decades later she becomes the "Holy Mother" of the Rebirth Congregation.

File 4: The Mousetrap House

The Staircase Shiori Witnessed

Shiori Hayasaka is a wealthy CEO who grew up poor, and she recounts a middle school trauma. She went to a sleepover at the palatial Tokyo mansion of her classmate Mitsuko Hikura. Mitsuko is the daughter of the Hikura Homes president. The house had grand dual staircases and a massive locked bookcase in Mitsuko's room. A grandmother occupied a central windowless room. The grandmother was beautiful, but she moved stiffly and hid her body under long skirts and white gloves.

That night, while Shiori was present in the house, she heard the grandmother tumble down the stairs to her death.

Years later, Shiori examines the floor plan and identifies the kill mechanism. The area at the top of the main staircase carried a wide gap with no wall and no handrail. The size made it hazardous to anyone with a mobility impairment.

Shiori theorizes that Mitsuko stole her grandmother's walking stick during the night, locked it in the bookcase, and let Shiori witness the locked bookcase as an alibi. The old woman then descended the staircase unaided.

A House Built to Kill Its Own Owner

The "mousetrap" architecture proves that Hikura Homes designs murder into residential structures. The family weaponizes space for clients, and it weaponizes space for itself. They killed their own grandmother with a floor plan.

At that age Shiori could not weigh what she witnessed. She went to that sleepover as a socially ambitious teenager trying to make friends with a rich classmate. She left as an unwitting accomplice to a family assassination.

What Mitsuko Actually Stole

The grandmother in the long skirts and white gloves is Yaeko, the Holy Mother from File 3 and the founding figurehead of the Rebirth Congregation. She conceals a missing left arm and a prosthetic right leg.

Shiori's misidentification of the "walking stick" as the murder weapon is a red herring. Kurihara later determines that Mitsuko stole Yaeko's prosthetic leg while she slept. The old woman then descended the staircase on one real limb and a stump. The locked bookcase held the prosthetic, not a cane.

The first theory is that Akinaga Hikura, the Hikura Homes president, ordered his daughter Mitsuko to kill Yaeko. After the Rebirth Congregation dissolved, Yaeko became a reputational liability for the corporation. The builders designed the house to do the job cleanly.

File 5: The House Where It Happened

Kenji Hirauchi bought a pre-owned house in the Nagano woods. He checks a crowdsourced dark history app. Real Japan-specific services do the same job and log crime and death locations at residential addresses. He finds his exact lot marked: "23 August 1938, Woman's corpse found."

The Author and Kenji research local archives. In 1938, the land belonged to the Azuma family. The lord of the manor, Kiyochika, had an affair with a maid named Okinu. His wife discovered the affair and ordered Okinu killed. Okinu fled into the forest.

Back at Kenji's house, the Author notices that the ground floor has no windows. One room has abnormally thick exterior walls. He taps the walls and finds a hollow space. He concludes that someone built this house around the watermill from File 3. The modern residential structure is a shell enclosing an 88-year-old gothic execution chamber.

Okinu fled to the watermill, gave birth, and died there. Decades later, someone enclosed the watermill inside a conventional structure, added a second floor, and sold it as a home. The buyers had no idea what sat inside the walls.

The House That Enclosed Its Own Crime Scene

File 5 is the novel's "architectural uncanny" thesis in its purest form. A modern house sits on modern land. Behind walls too thick for structural need sits a machine. That machine killed a woman nearly a century ago. The house did not demolish its own history. It enveloped it.

The people who built the shell around the watermill knew what was inside it, and so did the people who bought the shell and added the second floor. Kenji had no idea. Each layer of construction is a new generation that stays silent.

Confirming the Egret

The "female egret" of File 3 is Okinu, confirmed. The baby in the alcove was Yaeko, and she survived. File 10 explains the rest. The Hikura family bought this land and built the modern shell around the watermill. It became a pilgrimage site for the cult, a visit to the Holy Mother's birthplace. When the cult collapsed, they simply sold the property to an ordinary civilian.

File 6: The Hall of Rebirth

Inside the Hall of Rebirth

The Author presents an unfinished 1994 tabloid exposé from an undercover reporter named Ikaze. The cult's primary facility in Nagano is the "Hall of Rebirth," a misshapen white building. Inside, Masahiko Hikura, the future Hikura Homes chairman, delivers sermons. He warns wealthy congregants that their children inherited their "sin." A dark spiral path leads through a subterranean shrine to the "Holy Mother," a motionless, beautiful woman missing her left arm and right leg.

A man bursts into the shrine and screams at the Holy Mother. He calls her a fraud and blames her for his son Naruki's death. He threatens to "seal her heart forever." Guards drag him away.

The cult's "sacrament" is an overnight sleep in a large, dimly lit communal room. The next morning, members meet with acolytes, effectively Hikura Homes salespeople, to review architectural floor plans.

The Author analyzes Ikaze's crude building sketches and finds the Hall of Rebirth's architectural secret. The building is more than a worship space. It is an exact architectural replica of the Holy Mother's mutilated body, at building scale. The floor plan is shaped like a woman missing her left arm and right leg.

The Building Is Shaped Like the Goddess It Worships

This is the structural keystone of the entire novel, placed in the center of eleven files on purpose. Everything in Files 1 through 5 radiates outward from this revelation. Files 7 through 11 fill in the consequences.

Hikura's sermon follows the standard cult mechanics. First it instills guilt, so a child's suffering becomes the parent's punishment for sin. Then it provides a proprietary cure: reshape the home to match the Holy Mother's body, with Hikura Homes contractors, at significant expense. The architecture is the product. The guilt is the marketing.

The "sacrament room," positioned in the building's central belly, performs spatial indoctrination. The cult sells a sleep in the architecture's "womb" as spiritual rebirth. It is a Hikura Homes product placement delivered as a religious experience.

Where Every Earlier File Lands

The Holy Mother's missing left arm and right leg connect to Yayoi's amputated wooden doll from File 1, to the mechanical wall injury from File 3, and to the grandmother under long skirts in File 4. File 10 then names her as Yaeko.

Kurihara identifies the angry man who threatens to "seal her heart forever." He is Mr. Kasahara, the father from Files 7 and 8. His son Naruki is the child whose journal fills File 7. He fulfils the threat literally, later committing suicide in the sealed shrine room of his own remodeled home.

The morning architectural consultations explain File 1. The cult instructed members to amputate architectural space to match the Holy Mother's missing limbs, seeking absolution for the sin that produced their child. That is why Yayoi's mother wanted Housemaker Misaki to remove an entire room from her house.

File 7: Uncle's House

Naruki's Journal

File 7 is the published journal of Naruki Mitsuhashi. He was nine, and he died of severe neglect and abuse in 1994. His entries describe his mother pinching his nose shut when he asks for food. They also describe visits to a wealthy man he calls "Uncle," who feeds him and gives him a bedroom. Naruki notices that "Uncle's" house changes between visits. A room with a river view disappears.

Uncle warns Naruki about a specific room: "This is the heart of my house. Never lock this door."

Uncle tries to take custody of Naruki, to give him a permanent home. Naruki's mother and her boyfriend Eiji arrive and remove him. Eiji locks Naruki in a closet. The journal entries get shorter and the handwriting deteriorates, until the entries stop.

A Child's Architecture of Survival

The shift to a nine-year-old's perspective is the most emotionally brutal turn in the entire novel. Naruki's prose is concrete and simple. "My tummy doesn't hurt anymore but it feels all tight now." The child does not understand that this sensation is starvation. The reader does.

The architecture in File 7 is a stark binary. Uncle's house is all windows and space and food and a river view. Eiji's flat reduces Naruki's spatial existence to a closet. The novel spent six files building a theory of architecture as psychology. Here that theory becomes unbearable. The spaces children inhabit determine whether they survive.

Who Uncle Is

"Uncle" is Mr. Kasahara, the father from File 8. Naruki is the illegitimate child Kasahara fathered with a mistress. The vanishing room in Uncle's house mirrors the architectural alterations in Files 1 and 11. Kasahara removed interior space to reshape his home into the Holy Mother's amputated form. His warning about the "heart room" reflects a cult belief: a locked shrine room "seals the heart" and kills everything inside.

File 8: The String Phone

What Chie Heard Through the String

Chie Kasahara describes her childhood in a suburban development of identical houses. Her father, a wealthy but philandering car salesman, largely ignored his family. He made one act of paternal warmth. He strung a paper-cup string phone between his room and Chie's for nighttime conversations.

One night, on the string phone, her father's voice went incoherent. A strange rustling followed. Minutes later, the house next door burst into flames. It belonged to the Matsue family. Searchers found Mrs. Matsue dead in her closet. The ruling was suicide.

Her father became withdrawn, divorced, left his family a fortune, and disappeared. Years later, Chie tests the string phone. The string is far too long for two adjacent rooms. Pulled taut, it reaches the tatami room of the Matsue house.

Chie concludes that her father used the string phone to fake an alibi. He climbed through a window, murdered Mrs. Matsue, and set the fire.

An Object of Tenderness Turned Into an Alibi

The string phone is a precisely selected symbol. It is the most innocent childhood object and an artifact of parental tenderness. The book turns it into a tool of deception. Kasahara used his daughter's fear of the dark and her need for comfort to build an alibi. The alibi may not cover what Chie believes it covers.

The identical clone houses carry the same logic as the mass-produced Tsuhara house. The exteriors are uniform and the interiors are fractured. Everyone in these identical houses lives through something nobody else can see.

Kurihara Corrects the Alibi

Kurihara resolves Chie's theory. She had the facts right and the conclusion wrong. Her father was in Mrs. Matsue's house because they were having an affair, not to murder her from the room next door. The rustling incoherence Chie heard through the string phone was Kasahara finding his mistress's suicide note and her dead body, and panicking.

Kasahara then withdrew from his family. He died in a sealed room, with a strange doll and a photo of Naruki. That is the direct aftermath of File 7. The death of his illegitimate son devastated him, and he could not stop the people who did it. He sealed the shrine room, the "heart" of his own house, against the cult's fiction, then killed himself.

File 9: Footsteps to Murder

Hiroki's Account of the Same Night

Hiroki Matsue, the boy who survived the fire in File 8, provides his own account and rejects the suicide ruling. His father was a devoutly Christian pacifist, and he behaved strangely that night. He went to his wife's room at an unusual hour and stayed for 30 minutes. He then rushed downstairs and handed Hiroki his crucifix and a coin. He told Hiroki to call the fire brigade, because "for some reason, she wasn't in her room." He then ran back into the burning house.

Hiroki has a theory. His father drugged his mother and carried her to the closet. He set the fire and staged the discovery to explain his failure to save her, so Hiroki would assume she suffocated where she slept.

In a final revelation, Hiroki notes that he and Chie Kasahara stay in contact. Both suspect their own fathers. He also knows that the Author hid part of his journalistic purpose in contacting them.

Two Children, Two Different Murders That Never Happened

The competing narratives of Files 8 and 9 are Uketsu's Rashomon. Chie names her father as a killer because a string phone's slack length outran her trust in him. Hiroki names his father as a killer because a 30-minute absence and a locked closet outran his grief. Neither father committed the murder his own child assigned him. The crucifix handed to Hiroki is the novel's most pointed religious symbol: his father's faith weighed so heavily that it drove him toward the very act he was trying to prevent anyone from suspecting.

What Mr. Matsue Actually Did

Kurihara reconstructs it. Mrs. Matsue was pregnant with Kasahara's child. She committed suicide and left a note. Mr. Matsue found the note during his 30-minute visit, discovered his wife's body, and realized that another man fathered the child.

His Christian devoutness could not tolerate his son growing up with that knowledge on the family name. He burned the house to destroy the forensic evidence of the pregnancy, using the closet as an impromptu crematorium. He died the way a man dies who runs back into a fire to save his wife.

File 10: No Escape

Akemi's Story, Then Mitsuru's Correction

Akemi Nishiharu is an elderly izakaya owner. Bankruptcy hit her in her twenties. Yakuza debt collectors then forced her into an "okito," a concealed brothel disguised as an ordinary residential building. The architectural design of the okito prevented escape. A mother could leave only if she gave the operators another resident's child as collateral.

Akemi's neighbor in the okito was Yaeko, a woman missing her left arm, with a daughter of about 11 years. One day, Yaeko took Akemi's son Mitsuru out to run errands. Mitsuru ran into traffic. Yaeko pushed him aside and lost her right leg under the wheels.

Shortly after, Masahiko Hikura, the future Hikura Homes chairman, paid off Yaeko's debt and took her and her daughter away.

In a follow-up interview, Mitsuru corrects his mother's version. The okito catered to pedophiles, and he was the one they prostituted. His run into traffic was a suicide attempt. Hikura bought Yaeko's 11-year-old daughter, not Yaeko herself.

A Building Engineered Around a Single Threat

The unreliable narrator reveals itself slowly here. Akemi's sanitized memory is the protective narrative a mother builds to survive what happened to her child, not deception. Mitsuru's correction does not condemn his mother. He explains her.

The okito's architectural design is the novel's most concentrated statement on systemic oppression. The building is engineered for captivity with the one lever available: children as collateral. The architecture does not hold people with walls. It holds them with a threat against someone else's child.

The Holy Mother's Origin

This file provides the complete origin story for the Holy Mother. Yaeko enters the narrative with one missing arm, from the mechanical wall injury in File 3. She loses a second limb to save a child. Masahiko Hikura then buys her, installs her as the figurehead of the Rebirth Congregation, and presents her real mutilation as sacred stigmata.

File 2 introduces the "dark rumors" about Hikura's abuse of a young girl as a whisper. This file confirms something far more specific and criminal.

File 11: The Vanishing Room

The Door Ren Iruma Found at Six

Freelance designer Ren Iruma reports a childhood memory. At age six, during a dizzy spell, a door appeared in his hallway. Behind it lay a freezing one-square-meter room with a terrifying object in a wooden box. The next day the door was gone. He never found it again.

The Author visits Iruma's childhood home with him. The dead-end hallway is still there. He deduces that the 2004 Chuetsu Earthquake vibrated a mechanism in the wall open. That mechanism is a metal plate that acts as a magnetic latch. With a strong neodymium magnet, the Author slides the hidden door open.

Inside stands a wooden effigy of a beautiful woman missing her left arm and right leg.

A House Built as a Shrine

Iruma realizes the doll's proportional shape matches the architectural layout of his childhood home exactly. His father was a product designer who worked with rare earth elements, and he used his knowledge of neodymium magnets to build a magnetic concealment mechanism into his own wall. The dead-end hallway is a penitential architectural prayer.

File 11 brings the unheimlich, the uncanny, full circle. The domestic space Iruma grew up in was a cult devotional object shaped to look like an ordinary home. His father built it around the amputated form of the Holy Mother, with a hidden room at its "heart" holding her effigy. Iruma crawled around that effigy as a six-year-old with a dizzy spell, then lived beside it for decades while it stayed invisible in the wall.

The neodymium magnet is the satisfying technical payoff for a detail planted many files earlier, when Iruma mentions offhand that his father worked in product design with rare earth materials.

Kurihara's Deductions

Kurihara Maps Every Address

The Author presents all eleven files to Kurihara. Kurihara maps the geographic location of every house and building. All of them orbit the Hall of Rebirth in Nagano at various distances. The architecture is a web, and the Hall of Rebirth is the anchor point.

Kurihara reconstructs the complete history.

Masahiko Hikura founded the Rebirth Congregation and installed Yaeko as the "Holy Mother." His own family bought her from a brothel as a child. The congregation exploited parents who carried guilt over illegitimate children, affairs, or children born with disabilities.

Hikura Homes sold them an architectural solution: remodel the home to resemble Yaeko's mutilated body, so the child receives spiritual purification by sleeping in the building's "womb." The sacrament room was the uterus. The overnight stay was rebirth.

Kurihara traces Yaeko back to the watermill. Okinu gave birth to her inside the mechanical wall chamber. The wall reactivated as her dying mother tried to hide her, and it severed the baby's arm. Hikura Homes later bought the Nagano land and built a house around the watermill to create a pilgrimage site. When the cult dissolved, they sold the property as a residential house.

The Author tracks down Mitsuko Hikura from File 4. She confesses. On the night of her grandmother Yaeko's "accident," she hid Yaeko's prosthetic leg while Yaeko slept. She acted in self-defense, not on her parents' instructions.

Her parents were abusive and dangerous, and the one person in the house who protected Mitsuko was Yaeko. By killing the only person who cared for her, Mitsuko secured her own survival. She carries that calculus to this day.

Mitsuko's Confession Closes the Loop

Mitsuko's confession completes the novel's moral geometry. She was not following orders. She was a child who protected herself from abusive parents, eliminating Yaeko, the one person in the house who loved her.

Masahiko Hikura started the cycle of abuse when he bought a child from a brothel and installed her as a goddess. That cycle ends with his own granddaughter, who kills the only person who ever protected her.

Two Endings to the Kasahara and Matsue Story

Mr. Kasahara from File 8 is confirmed as "Uncle" from File 7. His suicide happened in the sealed room, with the strange doll and the photo of Naruki. Two events met there: the cult's collapse and his son's death. The cult was a fraud, and he could not save Naruki. He sealed the "heart" of his own shrine-house as a final act, a symbolic killing of the fiction that failed everyone.

Files 8 and 9 resolve the Matsue fire the same way, from two directions. Mrs. Matsue learned that her pregnancy with Kasahara's child would destroy her family, and she committed suicide. Mr. Matsue burned the house to destroy the forensic evidence of the affair. He hid no murder. He was protecting his son from the knowledge attached to both his parents' deaths.

The Clue Payoffs, and What File 6 Changes on a Second Read

A handful of details planted early in the book only make sense once File 6 names the Holy Mother's mutilated body as the cult's central icon.

• The amputated wooden doll in the Negishi family's belongings (File 1) is the physical representation of Yaeko's mutilated body, and it marks Yayoi's mother as a cult member.

• The mother's ban on the main road (File 1) traces back to a fear that a hospital blood transfusion would expose Yayoi's real paternity, not to the truck accident itself.

• The Hikura Homes abuse rumor (File 2) is Masahiko Hikura buying an 11-year-old girl from a yakuza-run brothel, confirmed in File 10.

• The windowless rooms, dead-end hallways, and blocked windows across Files 1, 5, and 11 all trace to the same source: the Rebirth Congregation's instruction to alter a home's architecture to match the Holy Mother's missing limbs.

Read in order, File 6 sits at the center of the book on purpose. Files 1 through 5 hand the reader an amputated doll, a mechanical wall injury, and a grandmother in long gloves with no explanation for any of them. A reader who finishes File 6 and goes back to reread those five files sees the same objects differently: no longer strange details a case happened to include, but a body shape the book was teaching the reader to recognize before it had a name.

Files 7, 8, and 9 read like three separate cases, but they cover the same neighborhood and the same night: a dying child's journal, then the daughter next door, then the son who lived through the fire. Geographic proximity turns three individually plausible theories, an alibi, a suicide, an affair, into three fragments of one event nobody involved could see whole.

Strange Buildings starts as a set of quirky, isolated puzzles about odd houses. By the time Kurihara finishes, every puzzle is a node in one corporation's business model. Houses are neutral. They mean what the people who design them intend. Hikura Homes decided to industrialize guilt and sell architectural penance as a product, and everyone who lived inside a house it touched paid for that decision in shame, fear, or money for the rest of their life.

Not every reader agrees that the eleven files pay off.

Strange Buildings is the most structural of Uketsu's three novels in the "Strange" series. It asks the reader to hold eleven separate cases in memory at once and trust that they connect. They do, and tracing that connection is the point: a company that sells floor plans can sell guilt through the same floor plans, and the people living inside them may never know which one they bought.

Leave a comment

Who Is Uketsu?

Uketsu (雨穴, "rain hole") is a Japanese author and YouTuber. About 30 people know his real identity. In public he wears a white papier-mache mask and a black bodysuit. His voice never appears unfiltered. A voice changer handles that.

He lives in Kanagawa Prefecture and spent part of his childhood in Surrey, England. He worked at a supermarket when he started to post on YouTube.

His early videos were surreal. Asparagus turned into severed fingers, strips of raw meat hung on a washing line, and human ears spun on screen. In 2020, he posted a 21-minute mystery story built around a series of architectural floor plans. Readers and publishers told him to expand it into a novel. The result was Strange Houses (変な家, Hen na ie), published in Japan in 2021.

Strange Houses was the first novel. Uketsu followed it with Strange Pictures in 2022, then Strange Buildings in 2023, which is a direct sequel to this book. By 2024, three novels by Uketsu sat in Japan's top 10 fiction bestsellers at the same time. Pushkin Press published the English translation of Strange Houses in 2025. The breakout success of Strange Pictures had already primed the anglophone market for it.

The formal concept behind Strange Houses made Uketsu's YouTube channel successful. That concept treats architecture as a text. Read a house floor plan properly and it tells you things about its designers. They would never say those things aloud.

Why This Summary and Analysis Exists

No thorough English-language, chapter-level breakdown of Strange Houses exists. The book's premise sounds like a puzzle box, and it is one. The puzzle also runs deeper than most reviews suggest, in architecture and in psychology. This is the complete summary and analysis, from Chapter One through the Afterword.

This piece contains complete spoilers for the entire novel.

Chapter One: A Strange House

Plot Summary

The Author is a freelance writer who specializes in the macabre. His acquaintance Yanaoka approaches him. Yanaoka wants to buy a newly built two-story home in Tokyo for his growing family. Yanaoka has a problem.

On the first floor, between the kitchen and the living room, sits a section of the house that nothing opens into. That is a dead space, sealed on every side. Somebody built it in, walled it off and sealed it.

The Author lacks architectural training. So he brings the floor plans to Kurihara, an architectural draughtsman and fellow mystery enthusiast. Kurihara is methodical. He notes that somebody created the dead space on purpose. Two additional walls block it off, and they cost the kitchen part of its floor area. Why would a builder shrink a kitchen to seal off an empty section of the house?

Kurihara then directs the Author to the second floor. The child's bedroom is in the corner farthest from the staircase. It has no windows at all. An en-suite toilet means the child never needs to leave.

One route reaches the room, and that is a double-door vestibule. A pair of sequential doors makes an airlock-style buffer between the child's room and the rest of the house. Kurihara calls this design a solitary confinement cell. The architectural language communicates obsessive control over a child's movement and presence.

The contradiction: the parents' bedroom is bright and open. Their dressing room is completely exposed to the bed, with no privacy partition. And the house has 16 exterior windows, an unusual number for a residential build.

Kurihara reads the 16 windows as intentional. The house is performing normalcy to anyone looking at it from outside. All those windows say: nothing to hide here. Meanwhile, the interior hides its most important spaces completely.

The Author overlays the two floor plans and makes the key discovery. The walled-off dead space on the first floor aligns precisely with two corners, one from the child's windowless room and one from the windowless bathroom below it. Kurihara traces where it leads: straight up, a vertical tunnel connecting the two.

Kurihara constructs a scenario. The parents bring someone home, get them drunk, suggest a bath. The imprisoned child drops through a trapdoor in the bedroom. The dead space works as a vertical access shaft. The child enters the bathroom from below and kills the naked and defenseless guest.

Dismemberment occurs. Body parts pass back through the tunnel to a storage room near the garage. A vehicle takes them away.

Yanaoka pulls out of the purchase.

Shortly after, a dismembered body is found in the wooded hills near the property. All parts present except the left hand.

Architecture Testifies Before Anyone Does

A floor plan with a section walled off and left blank is the whole premise of this novel, compressed into one drawing. Uketsu makes architecture the antagonist and the floor plans the evidence, and the trick works because Kurihara cannot actually be certain. He is constructing a narrative from empty geometric shapes. He may be wrong. The dismembered body at the chapter's end does not confirm his specific murder scenario. It only confirms that something terrible happened near that house, and everything else is inference laid on top of a blueprint.

The chapter sets the template Uketsu repeats for the rest of the book: the Author presents a floor plan, Kurihara decodes it, and the two of them arrive at a horrifying conclusion together, one they cannot fully prove. The 16 windows are what lift the chapter from puzzle to statement. A house that decorates its exterior with abundance while hiding its interior in darkness has thought carefully about the optics of concealment, which means someone inside it already knew what the house needed to hide.

That decision to perform normalcy becomes the Katabuchi family's survival strategy for the rest of the book, foreshadowed here and confirmed later. The Katabuchis are the family who designed the Tokyo house, and Chapter Two names them. So does the missing left hand. The Author's first instinct is that the body was dismembered simply to fit through the tunnel's narrow passageways. That is a reasonable guess and a red herring. Chapter Four names the real reason: a ritual called the Offering of the Left Hand, which becomes the structural center of the novel's second half. The sealed dead space also foreshadows the jammed fusuma doors in Chapter Three and the broader pattern behind them, hidden passages as standard operating procedure across generations of one family.

Chapter Two: Another Warped Floor Plan

Plot Summary

Unable to let the case go, the Author publishes a vague article about the floor plans. He receives a letter from Yuzuki Miyae, an office worker from Saitama. Her husband, Kyoichi Miyae, vanished three years ago (in 2016). His body was recently found on a mountainside. The body was intact. His left hand was severed.

Yuzuki believes the murder connects to the Tokyo house. She found the floor plan of a home in Saitama where she believes the Tokyo family previously lived. The Saitama house was built in 2016 and recently burned to the ground.

The Author takes the Saitama floor plan to Kurihara. The similarities are clear. A windowless child's room sits on the second floor. A windowless bathroom sits on the first floor. A dead space connects them. But there are significant differences.

The Saitama house has no garage. This explains why Kyoichi's body was found intact rather than dismembered. The Saitama house had no good vehicle route for dismemberment and disposal.

The parents slept in separate single beds.

The child's room had only one door, not the double vestibule of the Tokyo house.

On the first floor sits a bizarre retrofitted triangular room. It has large windows, walls block those windows, and the room is completely useless. It occupies space that previously opened onto the garden.

Kurihara identifies the triangular room's function. Somebody built it over a section of the garden after the original building was complete. Below it, in what used to be open ground, is an excavated cellar used to store intact bodies. No garage needed. The cellar is the cold storage.

Then the Author visits the empty Tokyo house and speaks to a neighbor. The family's name was Katabuchi. They had a beloved one-year-old baby named Hiroto. They fled suddenly after the neighbor's husband spotted something at a window. He saw a pale, strange boy of about ten years old. The boy sat in the parents' bedroom window late at night.

Kurihara synthesizes the data. There are two children. The first is Child X, the imprisoned assassin in the windowless cell. The second is Hiroto, the infant the parents clearly adore. The timeline tells the story of the house's evolution. Somebody built the Saitama house for the parents and Child X.

When Hiroto was born, they added the triangular nursery room. That kept the baby separate from the murder mechanics. Later they designed the Tokyo house to manage both children at once. The heavy double vestibule stops X and Hiroto from ever sharing the same space. The double bed in Tokyo is for the mother and Hiroto. She becomes a human barrier between the infant and the door to X's room.

The Author presents these conclusions to Yuzuki. She breaks down when she hears the family fled. The Author confronts her. Kurihara has established that the real Kyoichi Miyae was a bachelor. The woman calling herself Yuzuki Miyae is not who she says she is.

She confesses. She is Yuzuki Katabuchi. The woman in the murder house, the mother of Hiroto and warden of X, is her estranged older sister, Ayano.

Two Houses Record One Escalating Crisis

The Saitama house and the Tokyo house record the same crisis at two different moments, three years apart. Each floor plan reflects the exact state of the parents' psychology at the time it was built, which is why the differences matter as much as the similarities. No garage, single beds, one door on the child's room: read those against the Tokyo house's garage, double bed, and double vestibule, and the escalation is a family adapting its architecture to an expanding moral problem, not repeating one.

Yuzuki's false identity runs the same trick as the houses. She presents a false floor plan of her own life to reach the investigation, and the Katabuchi family builds false floor plans to hide their crimes. Even the humans in this novel perform spatial deception, not just the buildings.

Hiroto's arrival does more damage to the reader's assumptions than anything Kurihara has decoded so far. The parents are not simply sociopathic architects running a murder factory. They also raise a baby with apparent tenderness, building him a sunny nursery and sleeping close enough to keep him safe. Both things are true inside the same square footage, and the book has no interest in resolving which one is the real family.

The Vestibule's Meaning Changes on a Second Read

The double vestibule's meaning shifts decisively here. In Chapter One, it read as a mechanism to keep the imprisoned child inside. In Chapter Two, it becomes a quarantine to keep that child away from the innocent infant. The architecture has not changed. The interpretation has, and that is the novel's own structural project running one level up: the same floor plan means something different on the second pass.

Chapter Four explains the pale boy seen through the window. He is Momoya, the imprisoned child, and he uses the hidden passage to reach the mother's room, where he places a damp cloth on the feverish baby's forehead. His goal was never to kill. This is the first sign, three chapters early, that Momoya is a boy and not the killer the setup trained readers to expect.

Chapter Three: Drawn From Memory

Plot Summary

With her deception exposed, Yuzuki Katabuchi shares a piece of her family's history that she has never told anyone. In 2006, her extended family gathered at the ancestral Katabuchi estate in the mountains. The estate is large and highly symmetrical. A long central corridor divides it evenly. A massive, immovable black Buddhist altar stands at the exact midpoint.

During that stay, Yuzuki's seven-year-old cousin Yoichi was found dead in front of the altar. His head was covered in clotted blood. The family ruled it an accident, because he must have climbed the altar and fallen. They also suppressed his mother Misaki's attempts to call the police.

Kurihara analyzes Yuzuki's hand-drawn floor plan of the estate. He identifies several anomalies. All the rooms on the right side of the house lack windows entirely. A set of fusuma (Japanese sliding doors) is permanently jammed shut. Kurihara traces the structure's hidden layout.

A confinement room sits behind the altar. One route reaches it, and that is the secondary passage masked by the jammed fusuma.

His reconstruction: a family member took Yoichi in the night and pulled him through the passage into the hidden confinement room, which had no windows and muffled sound completely. He killed him there, then placed the body at the altar to stage the accident.

No police investigated the death. The family closed the matter cleanly.

Yuzuki acknowledges this. Her own father was likely responsible. He worked to manipulate the family's line of inheritance. The plan surrendered her sister Ayano to the main Katabuchi family. They indoctrinated Ayano and tasked her with serving as a warden for disabled children.

Her father eventually lost his mind and died by suicide.

The Estate the Family Couldn't Stop Building

Chapter Three shifts the novel from modern procedural mystery into Gothic horror, and the transition is earned, because it answers a question the first two chapters never asked: where did any of this come from? The ancestral estate is the architectural origin myth. The jammed fusuma, the hidden room, and the windowless wing aren't recent innovations. They're centuries of accumulated spatial habit passed down like a family trait.

The altar at the center of the house does real symbolic work rather than merely looking ominous. It sits at the geometric center of the corridor, so every walk from one end of the house to the other passes around it. The family cannot cross its own home without acknowledging what stands at its middle. Ancestral weight becomes something you physically have to route around.

Yuzuki's father is the chapter's most tragic figure precisely because he is ordinary. He committed a monstrous act while believing he protected his family, and the delusion did not survive contact with what he had actually done. He reads as an early, less patient version of Keita, the man Chapter Four spends far longer trying to understand.

The estate is the direct architectural prototype for every house in the novel. The jammed fusuma is the same hidden-passage system the modern Tokyo and Saitama houses reuse. The windowless rooms on the right side of the estate become the template every later Katabuchi dwelling copies for its child's prison, and the confinement room behind the altar is the prototype for the whole murder-tunnel concept. The family did not invent any of this. They inherited it, and nobody in three generations found a way to stop building it.

Chapter Four: House of Chains

Plot Summary

The Author and Yuzuki visit her estranged mother, Yoshie. Yoshie produces a letter. Ayano's husband, Keita, wrote all of it as a complete confession to the history of the Katabuchi family's madness.

The origin: decades ago, the Katabuchi patriarch Soichiro entered into an incestuous relationship with his own sister, Chizuru. Soichiro's neglected wife, Ushio, discovered the affair and, in a state of dissociation, severed her own left hand. Shortly after, Chizuru gave birth to a son, Momota, who was born missing his left hand.

The curse attribution: a manipulator named Rankyo convinced Soichiro that Momota's deformity was Ushio's supernatural punishment. Rankyo was actually a woman named Shizuko from a rival branch of the family, and she orchestrated generational revenge. Rankyo established what became the Offering of the Left Hand. Any Katabuchi child born with a missing left hand must be imprisoned from childhood. Between the ages of 10 and 13 that child must murder a descendant of the rival branch, then present the victim's severed left hand at the family altar.

Enter Keita and Ayano, the present-day wardens assigned to a disabled child named Momoya. They refused to become killers. They built the Saitama and Tokyo houses as theatrical sets that simulated compliance with the ritual and faked it entirely. Keita scavenged the intact bodies of suicide victims.

One was Kyoichi Miyae, a bachelor who jumped from a bridge. Keita presented their severed left hands to the family enforcer, Kiyotsugu, as the required Offerings.

The deception holds until Kyoichi's body surfaces and the police investigate. Kiyotsugu confronts Keita: he knows the rituals were faked. He threatens to take Momoya back to the main family compound and force the boy to perform an actual murder.

During this confrontation, Momoya escapes his room through the hidden passage. He does not go to the bathroom. He goes to the mother's room, where the feverish baby Hiroto lies sick in bed. Momoya places a damp cloth on the infant's forehead and stays with him until the fever breaks. The neighbor who glimpsed the pale boy at the master bedroom window saw Momoya nursing a sick baby.

Keita kills Kiyotsugu. Then he kills the family patriarch, Shigeharu. He takes full responsibility and disappears, leaving his wife and children with the story that absolves them.

Keita Builds the Same Prisons to Save Instead of Kill

Keita and Ayano spend three chapters looking like the monstrous wardens of a murder house. Chapter Four spends its entire length insisting they, and the child they guarded, were prisoners of the same architecture. The structures were designed to imprison and kill. Keita repurposed them into a theatrical prop, a stage set for a performance of compliance that kept his family alive.

He is the inverse of every Katabuchi ancestor before him. They built prisons to enforce the ritual. He built identical prisons to fake it. The structural language is the same. The moral content is opposite, and that is the whole argument of the chapter compressed into one man's floor plan.

Momoya nursing the sick baby does more damage to the reader's assumptions than any single reveal so far. The narrative spent three chapters training readers to see him as a dangerous unknown, a pale figure glimpsed through windows, the engine of a murder factory. He is 10 years old and he has never killed anyone. The first time he escapes his room, he tends to a sick infant.

The catharsis here is deliberately incomplete. Keita's disappearance resolves nothing except the immediate threat. The houses are destroyed and the enforcers are dead, but the family structure that produced the ritual continues, and so does the incestuous origin story underneath it.

Every Missing Hand Is Accounted For, Except One

Only one of the two severed left hands from the early chapters now has an explanation. Kyoichi's came from a scavenged suicide victim, presented as an Offering. What Keita's letter never explains is the unidentified body from Chapter One, the one whose missing left hand started this whole investigation. His confession resolves the Kyoichi case and deliberately leaves that first one open.

By Chapter Four, the double vestibule's function is settled: quarantine in two directions. It protected Hiroto from what sat behind that door, and it protected Momoya from the full weight of how differently the two children were being raised.

Afterword: Kurihara

Plot Summary

Kurihara meets the Author one final time. He says the investigation is finished, except for one thing.

He points to a detail in the Tokyo house floor plan that nobody examined: a small interior window between the living room and the first-floor bedroom.

The Window Nobody Checked, Including Me

Interior windows destroy privacy. They exist for one purpose, observation. Keita's letter describes a man who built the houses to protect his family. Kurihara asks whether Keita was a prisoner himself, watched constantly by Ayano through that same window.

I had the floor plan of the Tokyo house from page one of this book, and I missed that window too. That is the real trick of the Afterword: after two hundred pages spent earning a comfortable ending, Kurihara hands the reader evidence they already had and asks why they stopped reading it. I do not think the sacrifice-and-redemption reading of Chapter Four collapses under this. It just has to share the page with an uglier one now, and Uketsu never picks a side between them. That refusal is the strongest writing in the book, stronger than any single reveal in the four chapters before it.

Kurihara also notes the other unresolved thread: the dismembered body from Chapter One remains completely unidentified. Keita's confession accounts for Kyoichi Miyae's intact body. It says nothing about the person who was dismembered, whose left hand is somewhere nobody has looked.

The interior window loops the novel back to its own opening instruction, look at the floor plan again, something is wrong, you missed it. The reader had the Tokyo house's floor plan from Chapter One. The window was there the whole time.

The novel does not close.

How the Ending Reframes the Beginning

Strange Houses begins as a cool, clinical puzzle about malevolent architecture. By the end, it is a study in how generational trauma becomes structural. The incest and suicide of the founding generation produced a deformed child. The deformed child produced a ritual. The ritual produced a building type. The building type became tradition, and the tradition imprisoned every generation that followed, because nobody in the family ever found a way to say stop.

Keita's theatrical set is the first act of genuine refusal in the entire lineage. He built the same kind of structures his ancestors built, and he built them to protect a child instead of destroying one. The structures looked identical. The moral content underneath them was entirely different, and that distinction costs him everything.

Five Chapters, Each Zooming Out Further

Chapter One stays inside one house and one unsolved detail, the floor plan with a section that shouldn't exist.

In Chapter Two, a second house forces a second timeline, and the two floor plans start to argue with each other. The chapter introduces the human beings behind the architecture for the first time.

In Chapter Three, the estate that started it all holds one murdered child and one room built to hide the killing. The novel zooms back decades to the source of the family's obsession.

Chapter Four zooms out all the way. It lays out the complete family tree and the complete history of the ritual, and it explains every house in the novel. The houses were not designed by killers. They were designed by trapped people, in houses that had already designed them.

The Afterword zooms in on one small window and one question it raises. The floor plan of the entire novel gets pulled back one more time, to reveal a dead space the reader walked past five times.

The English translation of Strange Houses (Pushkin Press, 2025) embeds the original floor plan diagrams in the text as intended, and that matters. This is a novel you read with a pen, because the floor plans work as evidence rather than illustration.

Leave a comment

Who Is Uketsu?

Almost nothing is known about the person behind the name. Uketsu (雨穴, which translates to "rain hole") is a Japanese author and YouTuber. He appears in public in a white papier-mache mask and a black bodysuit. A voice changer modulates his voice to sound between mechanical and childlike. About 30 people know his true identity: his family, his publisher, and a small group of collaborators.

He is a man. He lives in Kanagawa Prefecture, southwest of Tokyo. He spent part of his childhood in Surrey, England. He worked at a supermarket when he began to post online. That is more or less the complete profile.

His early YouTube videos were surreal. Asparagus turned into severed fingers under the knife, strips of raw meat hung on a washing line, and eight human ears spun on a wheel. Then in 2020 he posted a 21-minute mystery story built around a series of architectural floor plans. The response was overwhelming. His publisher told him to turn it into a novel.

The rest followed quickly. By 2024, three books by Uketsu held slots in Japan's top 10 fiction bestsellers at the same time. Strange Pictures (変な絵, Hen na e) came out in Japan in 2022. Jim Rion translated it into English in January 2025. It sold over 1.5 million copies in Japan alone, and it now exists in more than 30 languages.

It was shortlisted for Waterstones' 2025 Book of the Year and topped Germany's May 2025 Krimibestenliste. A manga adaptation by Aiba Kiko launched in 2024.

Futabasha, the manga publisher, released this promo for the adaptation.

Why This Summary and Analysis Exists

Nobody has put up a truly detailed, chapter-level breakdown of Strange Pictures in English. Reviews exist and plot summaries exist. Nothing maps the structural puzzle, traces the planted clues back to their payoffs, and explains why this book works. That is what this piece is.

It is the complete summary and analysis, chapter by chapter. A full master map of narrative threads sits at the end. If you have already read the book, this is the deepest dive available. If you have not, this will tell you exactly how it was built and why it is worth your time.

Fair warning: this is the kind of analysis that only works with full spoilers. Everything is revealed.

Prologue: The Drawing Test

Plot Summary

The novel opens in a university lecture hall. Dr. Tomiko Hagio is a former practicing psychologist. She presents her students with a drawing by an eleven-year-old patient she calls "Little A." The child was institutionalized after murdering her abusive mother. The drawing came from a standard HTP (House-Tree-Person) test, one of the oldest tools in psychological evaluation.

Dr. Hagio walks her students through three anomalies in the drawing. First, the figure's mouth is heavily smudged. Hagio reads this as physical trauma memory. The child's hands trembled as she recalled a forced, constant smile that appeased her abuser.

Second, the house lacks a door. Hagio interprets this as a fortress mentality, a desire to lock the world out. Third, the tree's branches end in sharp, thorny points. Drawings by violent offenders show that trait often, and it indicates deep aggression.

Then comes the pivot. Little A drew a small bird resting safely inside a hollow in the tree's trunk. Hagio seizes on this as a profound "desire to protect," a capacity for nurturing love underneath the violence. She closes the lecture by telling her students that Little A is now living happily as a mother.

Literary Analysis

Uketsu builds the prologue on ekphrasis: a drawing carries the narrative's evidence instead of dialogue or testimony. Dr. Hagio sets the rule for the rest of the book in one lecture. A drawing tells you what a person cannot say out loud.

Her authority comes from being right three times before she is wrong once. The smudged mouth, the doorless house, and the thorny branches: she reads all three correctly, and the reader has no reason yet to doubt her. Then she reaches the bird resting in the hollow of the tree and calls it proof of a hidden capacity for love, evidence that violence and nurturing can coexist inside the same child.

That reading is wrong, and it stays wrong for the rest of the novel. Little A grows up to become Naomi Konno, the woman whose case drives every chapter that follows, and what looks like a hopeful detail in an eleven-year-old's drawing is the first clue nobody in the room was equipped to read correctly.

Chapter One: The Old Woman's Prayer

Plot Summary

On May 19, 2014, Shuhei Sasaki investigates a defunct blog. He is a 21-year-old college student. Kurihara, a junior in his Paranormal Club, recommended the blog. It is titled "Oh No, Not Raku!", and a man using the pseudonym "Raku" wrote it. Its subject is his life with his wife Yuki, a former professional illustrator six years his senior. The posts begin in October 2008, cheerful and domestic, covering their daily life and Yuki's pregnancy.

Uketsu first told this chapter as a video on his channel.

The final post, dated November 28, 2012, appears after a three-year silence in the archive. It is addressed "To the one I love most." Raku says he has finally decoded "the secret of those three drawings." He cannot forgive his wife's "sin," and he still loves her. Then the blog goes silent.

Reading backward through the archive, Sasaki learns that in May 2009, Yuki was diagnosed with a breech pregnancy. The hospital recommended natural delivery. As the due date approached, Yuki drank excessive amounts of juice, citing uncontrollable thirst.

To manage her anxiety, she drew five cryptic images she called "visions of the future". They show a baby in a Santa hat, an old woman praying, an adult woman with flowing hair, a young boy, and an adult man. On October 11, 2009, the blog ends: Yuki died of a brain hemorrhage during an emergency C-section. The baby survived.

Kurihara and Sasaki work through the archive. Kurihara spots a mathematical impossibility in a post about an anniversary cake. It has 8 slices. Raku eats 2, Yuki eats 1, and 4 are saved. One slice is unaccounted for.

Someone else was living in that apartment. Raku never mentioned a third resident.

Sasaki cracks the drawings. He notices that each has a circled number. Yuki was a professional illustrator. She would know layer composition.

Sasaki stacks drawings 1, 2, and 3, aligning their circles as central axes and scaling accordingly. Stacked, the three drawings resolve into one scene.

Drawing 1's "Santa hat" becomes a bloody incision in a pregnant belly. Drawing 2's "praying old woman" becomes a doctor in scrubs pulling a baby from the wound. Drawing 3's "adult woman with flowing hair" becomes a stiff corpse on an operating table. Yuki had drawn a picture of her own murder, embedded across three innocent-looking images.

Stacking drawings 4 and 5 yields a second image. A man and a young boy walk away together, hand in hand. Yuki drew a future she would not be alive to see.

The Slow Read That Sasaki and the Reader Share

Uketsu tells this chapter entirely through Raku's blog, so the reader does the same forensic work Sasaki does, in the same order, at the same pace. An ordinary domestic blog turns sinister one post at a time, and neither Sasaki nor the reader ever gets ahead of the other.

Kurihara barely functions as a character. He exists to spot the one thing Sasaki missed: the math on the anniversary cake. Eight slices, two for Raku, one for Yuki, four saved, and one left over with no owner. That extra slice belongs to someone the blog never named. She is Naomi Konno, Raku's mother, living in the apartment the entire time the blog ran and never once mentioned across three years of posts.

The blog's own title carries a second clue nobody inside the story catches. "Oh No, Not Raku!" rearranges into "Haruto Konno": Raku was really Haruto Konno, father of the surviving baby Yuta, and the drawings his dead wife left behind are what finally break him. Yuki's strange thirst and the hospital's push for a natural breech delivery both read as small, forgivable details on a first pass. Neither one is forgivable. Both come back, with their full weight, in the Final Chapter.

Chapter Two: The Smudged Room

Plot Summary

Point of view shifts to Naomi Konno: widowed, raising her five-year-old son Yuta in a sixth-floor apartment. The chapter opens with a harsh scolding. Yuta used a geometric stencil ruler to draw in permanent marker on the apartment walls.

A concurrent storyline: Naomi notices a man in a grey coat following her and Yuta home. He drives a compact car. She cannot place him but feels the threat clearly.

At Yuta's nursery school, homeroom teacher Miho Haruoka examines Yuta's Mother's Day drawing. He drew their apartment building in reasonable detail. Their specific sixth-floor room carries a violent grey blotch over it. Haruoka investigates the mechanics. Yuta did not use a grey crayon.

He used a white crayon over a black underdrawing. The pressing and smearing mixed the pigments into an opaque grey. A classmate, Miu Yonezawa, volunteers one detail. Yuta's original drawing showed a large rectangle with a small triangle inside, and he erased it.

Haruoka connects the shape to the stencil ruler Naomi punished Yuta for using. She draws on child psychology research, which holds that children draw the idea of trauma rather than literal objects. She concludes that Yuta drew the implement his mother struck him with. She phones Naomi to report suspected abuse.

Naomi realizes Haruoka has misread the drawing. The rectangle and triangle are the kanji 今野, the characters for "Konno," which looks like a triangle sitting above a rectangle, not a stencil ruler.

Yuta was attempting to draw a gravestone, his mother's gravestone. Naomi deduces that Yuta has been sneaking to Sakura Memorial Garden. He holds a faint memory of his father once taking him to visit "Mummy's" grave. She goes to the cemetery.

She finds Yuta at the headstone of Yuki Konno.

That evening, the grey-coated man follows Naomi into her apartment building. She has anticipated this. She waits behind her door with a kitchen knife. When he steps inside, she stabs him. As he falls, his hood drops: the wrinkled face of an old man she dimly recognizes.

Sympathy Built on Purpose

By the time Naomi picks up a knife, the reader has known for a full chapter that she is dangerous, and Uketsu spends this entire chapter making that knowledge useless. He puts her through a harsh, unfair accusation from her son's teacher and an exhausting stretch of solo parenthood, and the effect is real sympathy for a woman who ends the chapter stabbing a man in her own doorway.

Haruoka examines Yuta's drawing with the exact tool Dr. Hagio used in the prologue, art as a window into subconscious trauma, and reaches the exact wrong conclusion Hagio nearly reached. She reads the grey blotch as a stencil ruler standing in for abuse, when Yuta is drawing his mother's name over the shape of a gravestone. He is trying to erase what is in front of him and reach what is buried under it. Nobody in his life has told him his mother is dead, let alone that she has a name he could draw.

This chapter confirms two identities. Yuta is the baby who survived Yuki's murder on the operating table in Chapter One, and Naomi is Haruto's mother, not Yuki's, which makes her the "old woman praying" in Yuki's composite drawing, the figure with both hands reaching into the incision.

Haruto's own sequence resolves here too. He worked out what his mother had done, took Yuta to his real mother's grave, wrote his last blog post, and hanged himself.

The man Naomi stabs is Isamu Kumai, a veteran reporter who appears formally in Chapter Three. He survives. His stalking was deliberate provocation, meant to push Naomi into a violent act his police contact could arrest her for. She never calls the police when she feels threatened. She picks up a knife, the same way she always has.

Chapter Three: The Art Teacher's Final Drawing

Plot Summary

The timeline shifts to August 1995. Shunsuke Iwata is a 19-year-old high school graduate. He failed to land a reporting position, so the L-Daily newspaper placed him in its administrative department. He wants one specific story: the 1992 unsolved murder of his high school art teacher and personal mentor, Yoshiharu Miura.

His boss in the admin department is Isamu Kumai, a veteran reporter demoted after a bout with esophageal cancer. Kumai was the lead reporter on the Miura case and shares his confidential files with Iwata.

The physical evidence from the 1992 murder on Mt. K is strange. Miura's body was discovered at the mountain's eighth-station clearing. A rock beat it more than two hundred times, which made it completely unidentifiable. The degree of mutilation forced the pathologist to estimate the time of death from stomach contents alone. Miura ate a Hanayagi bento box, and digestion placed his death at 5:00 PM on September 20.

This timeline cleared two people. Miura's wife had an alibi for the morning of the 21st. A student named Yuki Kameido had an alibi for the evening of the 20th. The prime suspect became Nobuo Toyokawa, a resentful college friend of Miura's who had no alibi for that evening.

Two details continued to bother investigators: Miura's sleeping bag was stolen, and some of his food was missing. Miura had also drawn a crude picture of the mountain range on the back of a folded supermarket receipt.

Iwata pursues an independent lead to his old school. There he meets a blind student drawing on a "pierced canvas," a surface with tactile gridlines. The image clicks. Miura folded the receipt into a grid and drew the mountains by touch, without seeing his own hands.

Iwata hikes Mt. K on the anniversary of the murder to test the theory. At the eighth station at 5:00 PM, he looks at the mountain range and sees nothing. The setting sun is directly behind it. The mountains are completely backlit, invisible against the glare. Miura could not have drawn a detailed mountain range in those conditions.

He deduces the actual sequence. The killer captured Miura and restrained him in his own sleeping bag through the night. The next morning the killer force-fed him the Hanayagi bento, which then looked like normal consumption. Two and a half hours after the meal, the killer murdered Miura.

The killer destroyed the body beyond recognition to eliminate rigor mortis as a time-of-death indicator. The bento's digestion level did the rest. It placed the death ten hours early, inside the window where the killer had an alibi.

Iwata realizes the brutal mutilation was never about rage. It was a forensic necessity. With his theory proven, Iwata sits in his tent on the mountain.

That night, Naomi Miura, the art teacher's widow, binds him in his sleeping bag and force-feeds him.

Iwata realizes what is happening and why. He folds a piece of paper and draws one last blind picture of the mountains against his restrained hands. Then she kills him. Naomi then murders Toyokawa. She types a fabricated suicide note on a brand-new word processor to frame him for both deaths, and closes the police file for good.

A Genre Change Mid-Book

The story drops its epistolary, domestic frame here and becomes a hardboiled forensic procedural, tracking a nineteen-year-old cub reporter who dies for getting too close to a three-year-old mountain murder. Nothing about the case is what it first looks like once Iwata rebuilds the timeline. Miura's body took more than two hundred blows from a rock because a beaten, unrecognizable body gives a pathologist no way to read body temperature or rigor mortis, not because of rage. That leaves exactly one piece of forensic evidence, the digested bento, and the killer controlled that evidence completely by force-feeding Miura the next morning and killing him hours later.

Iwata's proof comes from a blind student's pierced canvas, a drawing surface worked by touch through a tactile grid rather than by sight. Miura folded his own receipt into the same kind of grid so he could draw the mountain range with his hands bound inside a sleeping bag, in the dark, without looking. A sighted man's drawing was made exactly like a blind one, and that mismatch is what breaks the alibi.

This chapter also reveals who Kumai is: the grey-coated stalker from Chapter Two. He survives. His cancer keeps progressing. His stalking was deliberate provocation, meant to trigger a violent reaction from Naomi that his police contact could use to arrest her, one last case he wanted to close before running out of time.

The fake suicide note is typed on a brand-new word processor. A real suicide note would be handwritten, so the note's own format is what proves it was forged to avoid a handwriting match.

The Final Chapter: The Bird, Safe in the Tree

Plot Summary

Following her 2015 arrest, Naomi Konno's history is reconstructed in full.

As a child, her father's suicide left her alone with a deeply abusive and sociopathic mother. Naomi found one source of comfort: a pet finch she named Cheepy. Her mother tried to crush Cheepy to death. Eleven-year-old Naomi fought back and stomped on her mother's neck until she died. She was committed to a juvenile reformatory.

That girl was "Little A."

Naomi eventually became a midwife, married Yoshiharu Miura (the murdered art teacher), and had a son, Haruto. Miura was a harsh disciplinarian who struck the introverted Haruto and forced him outside.

Naomi feared that her juvenile record would cost her custody of Haruto in any divorce. So she planned and executed the elaborate murder on Mt. K. She killed Toyokawa later when he deduced the method and attempted to blackmail her into a sexual relationship. She killed Iwata when he got too close.

Years later, the adult Haruto reconnected with Yuki Kameido, Miura's former art student, and married her. They moved in with Naomi. Yuki became pregnant.

Naomi began to want the baby as something to own, not something to help raise.

Using her medical knowledge, she replaced Yuki's prenatal iron supplements with 15-gram daily doses of sodium chloride, which is pure salt. Ingested throughout a pregnancy, this level of sodium induces progressively worsening hypertension.

Naomi, as senior midwife at the clinic, falsified Yuki's blood pressure charts and arranged for the dangerous natural breech delivery. On the operating table, Yuki's blood pressure spiked to fatal levels. She died of a brain hemorrhage. Naomi took the baby.

Three years later, Haruto decoded Yuki's composite drawings. He understood what his mother had done. The blog's final post was a goodbye, written to Haruto's wife, who was already dead. He took Yuta to Yuki's grave. Then he hanged himself.

In the aftermath of Naomi's arrest, Dr. Hagio realizes her diagnosis of "Little A" was wrong. The smudging, the doorless house, and the thorny branches all held up. The bird did not hold up: she had read it as proof of a capacity for nurturing that would soften the aggression, and she had the causality backwards.

The thorns exist to protect the bird. Naomi's maternal love drives her violence rather than redeeming it.

Kumai, recovering in the hospital, shares a room with Kurihara (from Chapter One). Kurihara explains the blog's mysteries. Kumai's cancer is advanced and his life is effectively over. He adopts the newly orphaned Yuta to break the cycle.

The Pattern That Breaks on Purpose

The Final Chapter treats Naomi as a psychological profile to understand, not a mystery to solve, and the understanding does not bring comfort. Her first three killings are built to earn sympathy: she kills an abusive mother to save a bird, an abusive husband to protect her son, and a blackmailer to protect an innocent life. The pattern holds together well enough that a reader has to work to resist rooting for her. Naomi killed Yuki simply because Yuki stood between her and a new person to possess, and that murder breaks the pattern the first three built.

The book's only comfort comes through substitution rather than justice. Nobody punishes Naomi for what she did to Yuta's family. Kumai, a dying man with nothing left to protect, adopts the boy instead, and that quiet, unglamorous act is the closest thing the story offers to an ending that heals anything.

Master Map: Planted Clues and Their Payoffs

Three Clues Worth Rereading For

The clue I missed on a first pass is the cake. Raku's post about their wedding anniversary mentions an eight-slice cake: two for him, one for Yuki, four saved for later. That is seven. The eighth slice belongs to nobody the blog ever names, and it sat there for three years before I noticed it, proof that Naomi Konno had been living in that apartment the entire time the blog ran, eating from a cake she was never once mentioned eating.

Yuki's thirst reads as a throwaway domestic detail the first time through, one more small complaint in a blog full of small complaints. It is the murder weapon. Naomi replaced Yuki's iron supplements with fifteen grams of salt a day, and the uncontrollable thirst was Yuki's body trying to survive its own poisoning. The American College of Obstetricians and Gynecologists treats a planned cesarean as the safer default for a term breech pregnancy and reserves vaginal delivery for hospitals that document strict protocols and informed consent, because the mortality gap between the two paths is real. Naomi, as the clinic's senior midwife, had exactly the standing to override that guidance and steer Yuki toward the delivery that would kill her.

The cleanest single clue in the book is the mountain. The eighth station of Mt. K faces west, so at five in the afternoon in September the sun sits directly behind the range and the mountains go black against the glare. Miura's drawing shows detail no one could see under those conditions. He drew it in the morning, with the sun behind him instead of in front of him, which puts the entire official timeline for his death off by roughly fourteen hours. One fact about where the sun sits at 5 p.m. undoes an entire police file.

A few more clues do the same work in miniature.

• Yuta's Mother's Day drawing hides the kanji for the Konno family name inside a shape his teacher misreads as evidence of abuse.

• Miura's blind, tactile drawing on a folded receipt breaks his own murderer's alibi, because a sighted man could not have drawn it under the lighting conditions the police assumed.

• The blog's title, "Oh No, Not Raku!," rearranges letter for letter into "Haruto Konno," the real name of the man writing it, months before the text confirms it directly.

Thematic Resonance: How the Ending Shatters the Beginning

Strange Pictures widens its scope with every chapter. Chapter One is pure archive work, solved entirely from behind a screen. It turns physical and domestic in Chapter Two, then historical and procedural in Chapter Three, with a body found on a mountain. The Final Chapter pulls all three back into one woman's history, which is the actual shape of the book: four separate cases that were always the same case, viewed from four distances.

Wind-Up Blog

J-Lit Review #5: Strange Pictures

If you are interested in contemporary Japanese literature, then you have probably heard of Uketsu, the controversial blogger, YouTuber, and now novelist. He is not the sort of writer who churns out novels about cats in cafés or bookshops (a trope that is growing a little tiring). Instead, he has transitioned from making creepy, confusing videos and myst…

Read more

2 years ago · 3 likes · David S. Wills

Dr. Hagio's lecture in the prologue states the book's real argument before the plot even starts: a drawing reveals what a person cannot say. She proves that argument three times over, then gets the fourth reading backward, showing what her own correct method does in the hands of someone who wants a hopeful answer badly enough. The thorns around the bird were never something the bird earned by being gentle. They exist because the bird needed defending, and Naomi's love for what she claims as hers is the same violence wearing a gentler face.

Kumai closes the book by adopting Yuta. He is a dying man with nothing left to lose and one decent thing left to do, and that is enough to break a cycle three generations deep.

If you have read this far and have not picked up the book yet, start with the English translation by Jim Rion (HarperVia, January 2025).

Related reading: Strange Buildings by Uketsu: Summary and Analysis and Strange Houses by Uketsu: Summary and Analysis.

Leave a comment

👋🏻 Hey. I’m Atharva.

I am a software engineer, a GTM (go-to-market) strategist and an AI-native builder. I work at AccuKnox on DevRel (developer relations) and growth engineering for cloud-native security products. Before that I worked as a freelance developer, a technical writer and a research consultant.

In this newsletter I write about the things I build and the decisions I make. I cover AI systems, growth infrastructure and developer workflows. Once in a while I cover the movies, music and games worth your time. I write no summaries and no secondhand takes. You get what I built, what broke and why I made each call.

This is the setup I use to write, review, edit and post my content.

Four categories exist. Pick one:

🔵 Tech and AILLMs, AI cost engineering, Claude ecosystem, developer tools, hands-on implementation 🟢 Biz and GrowthGTM strategy, lead generation, content systems, marketing automation 🟡 Money and CareerCareer decisions, compensation, investing, working in tech on your own terms 🔴 Entertainment and CultureFilm, music, gaming, fiction, ideas worth arguing about

Now pick the outcome that fits you:

• 💸 AI Cost & Systems

• 🤖 Claude Ecosystem

• 🛠️ Dev Workflow & Tools

• 📈 GTM & Lead Generation

• 📣 Content & Growth

• 💼 Money & Career

• 🎬 Culture & Entertainment

• 📖 Full Archive

• 🔗 Find Me Elsewhere

💸 AI Cost & Systems

You pay too much for AI. Or you do not know why costs blow up at scale. Or the outputs stay inconsistent and you cannot find the cause. Start here.

Practical Tips for Reducing AI Costs, Part 1: Tactical StackModel selection, prompt caching and batching. These are the fast wins that cut your bill.

Practical Tips for Reducing AI Costs, Part 2: Context Optimization & Memory ManagementContext bloat multiplies cost. Design memory that avoids it.

Practical Tips for Reducing AI Costs, Part 3: Advanced Algorithms & Internal GovernanceSpeculative decoding, logit bias, activation probes and the Batch API. You also get hard token ceilings for agents.

Token Anxiety and the Illusion of ProductivityWhat happens when you optimize for tokens instead of outcomes. Stop confusing activity with progress.

AI Slop Is a Skill IssueBad outputs come from bad inputs. An honest breakdown shows where most prompting falls apart.

50 AI Terms Every Developer and Builder Should KnowThe terminology that separates understanding from tool use. Learn the words.

🤖 Claude Ecosystem

Claude is the AI I use most. These posts cover the real setup. They also show how to extend Claude and fit it to your brain.

Building an AI Marketing Team with Claude SkillsHow I wired custom skills into Claude to run content. This is the actual setup and not a concept piece.

Skills 2.0, Anthropic Just Made Vibes-Based AI Building ObsoleteWhat changed with Claude’s skill architecture. It matters for anyone who builds serious workflows.

The 5 Files That Give Claude Code Permanent MemoryContext management for Claude Code. Structure your files so the model remembers.

🛠️ Dev Workflow & Tools

The stack you use every day compounds. These are the tools and setups I committed to. I give honest takes on what earns your time.

GitHub Copilot, A Complete Guide to Agents, Skills, and InstructionsEverything Copilot can do that most people never touched. You get agents, custom instructions, skills and a proper setup.

The 30-Minute Copilot Setup That Changes EverythingThe specific configuration I use. It sets up fast and it changes the work after.

One Command to Share Your Entire VS Code SetupExport your extensions, settings and keybindings. This helps on a new machine or with a new hire.

Your New PC Migration Should Not Cost You a Full DayThe actual checklist I use, with no fuss.

The Tech Stack I Bet My Career OnPython, FastAPI, Next.js, AWS, Cloudflare Workers. Why these and not the alternatives, and what the tradeoffs look like.

SEO for Vibe-Coded Apps, Audit and FixWhat breaks SEO when you build fast with AI. Audit it and fix it fast.

Forget Ranking #1 on Google, Get Recommended by AI InsteadGEO (Generative Engine Optimization) explained in practical terms. Structure content so LLMs cite you.

📈 GTM & Lead Generation

These cover the growth systems I built and tested. They give results with specifics and no theory.

2026 Marketing Stack for AI-Driven GTMThe full stack for a modern GTM motion. It shows what each layer does and what to cut.

The 3-Step Workflow to Intercept High-Intent Leads on Reddit and LinkedInFind people who already want your product. Follow the steps with no ad spend.

The Zero Dollar Lead Gen Channel Your Competitors IgnoreThe channel most B2B teams dismiss. It compounds quietly and the barrier to entry stays low.

The LinkedIn Pipeline Nobody Is Talking AboutHow to turn LinkedIn into a steady inbound pipeline. It takes less effort than one post.

I Almost Spent $250 on LinkedIn Auto-CommentsWhat I found when I looked at the tools. And what works instead.

How to Win Your First 10K Users Without SpamEarly distribution strategy for builders. What actually worked at small scale.

Integration Strategy for Small TeamsHow to connect your tools with no engineering overhead. The decisions that save you from workflow debt.

📣 Content & Growth

The content system is the asset. These posts build a system that compounds and needs no constant feeding.

Stop Writing Posts. Start Building a Content Flywheel.A flywheel is a loop where one finished piece of work feeds the next. The mental model shift that changes how you write content.

The 2026 Content Stack, Three Tools to WinThe actual tools I use. Why these three cover most of what you need.

My Second Brain Setup That Actually CompoundsA second brain is one local folder of plain text that holds what you know and finds it again. The Obsidian system I use daily, and how I capture, link and resurface ideas across projects.

The Joy Revolution Nobody in Your Marketing Meeting Will ApproveWhy the best content now looks unlike B2B output, and what to take from it.

💼 Money & Career

The business of being a technical person. I cover compensation, investing and career decisions. I cover work in tech without the wrong targets.

Two Years at AccuKnox, From Intern to SpecialistWhat I learned inside a cloud-native security startup. This is the real version and not the LinkedIn version.

You Don’t Rise to Your Goals. You Fall to Your Systems.Why discipline is overrated and environment design is underrated.

Calculating Your FIRE NumberThe math and the assumptions behind financial independence. Run it for your own situation.

A Dummy’s Guide to Investing WiselyFirst principles investing for people who do not want to become investors.

Inflation Isn’t One ThingWhy the headline number masks what happens to your purchasing power.

Slaying Your 20s, a five-part series on your path, ambition, money, digital detox and presence. Part 1: Owning Your Path · Part 2: Ambition vs Contentment · Part 3: Mastering Money · Part 4: Digital Detox · Part 5: Staying Present

🎬 Culture & Entertainment

I cover film, music, gaming and fiction. I have opinions and I defend them.

Mickey 17, A Systemic Analysis of the Future of Human LaborWhat Bong Joon-ho built beneath the premise.

Film School in Scenes, a multi-part series on directing, cinematography, story and the work of great filmmakers. Intro · Part 1: Heart of Story · Part 2: Masters of the Medium · Part 3: Vision and Craft · Part 4: The Director’s Process · Part 5: The Power of Restraint · Part 6: Anatomy of a Scene · Part 7: The Invisible Language

Her (2013), The Cultural and Ethical Weight of AI on FilmWhy this film reads better every year.

The Darkest Genre in Gaming Nobody Talks AboutThe games built around dread, loss and systems that punish you.

How 675 Million Spotify Users Get Fed MusicThe actual recommendation architecture. How the algorithm picks what you hear next.

I Fed Every Beach House Lyric Into an AIPattern analysis on a discography. What the model found that I missed.

The Algorithm Listens, Analyzing Every Lorde LyricThe same treatment for Lorde. I map linguistic and thematic patterns across her catalog.

The Hypnotic World of Haruki MurakamiWhat makes his prose work. Why it should not work as well as it does.

Why the Next Decade Will Rewrite Human CivilizationThe macro argument. Where AI, energy and geopolitics converge. This is what it means.

📖 Full Archive

Everything is at blog.atharvashah.com/archive.

Posts go out when I have something worth saying. They run dense and not frequent. Every post links to related posts. The archive stays coherent.

🔗 Find Me Elsewhere

• 🐦 X / Twitter: x.com/cultist_dev

• 💼 LinkedIn: linkedin.com/in/atharva-shah-tech

• 🐙 GitHub: github.com/HighnessAtharva

• 🎬 Letterboxd: letterboxd.com/highnessatharva

• 🎵 Last.fm: last.fm/user/highnessatharva

• 🌐 Website: atharvashah.com

• 📧 Email: hi@atharvashah.compaid work and real conversations only

I am open to web development and AI automation. I also take API integrations, technical content, GTM consulting and DevRel work. Find the details at atharvashah.com.

Leave a comment

Claude forgets you when a session closes, even when your notes sit in an Obsidian second brain (a folder of notes kept outside your head). You explain your job, your voice and your rules again, then repeat yesterday's corrections. The fix is a harness, which is Claude plus the files it reads on startup, kept in git.

names the same reset: "Most AI tools start from zero every time you open them."

TLDR

• Every rule you type into chat twice belongs in a file instead.

• A fresh Claude session with no chat history is the hardest test reader, and the right one.

• Each question that fresh session asks names one file your vault is missing.

• Seven folders and one CLAUDE.md file at the root hold the whole setup.

• Keep your personal second brain and your company brain in two separate repos.

That repeated explaining is rented work. You pay for it every session and keep nothing.

My vault is a folder of plain Markdown files in a private GitHub repo. The first version had one flaw. Only I could operate it, so it worked like a diary with good search.

The vault now passes a stricter test. A fresh Claude session with no chat history opens it and runs the work, because every rule lives in a file.

Here is the same Monday task, run twice. Claude has no memory of past chats either time, and only the files change.

• Without files, I explain my job, then my voice, then yesterday's fixes.

• That costs about 20 prompts and still ends in a generic draft.

• With files, I type "write the next LinkedIn post" and nothing else.

• Claude reads CLAUDE.md, the Voice file and the matching skill.

• That costs about 2 prompts, and the draft arrives already checked.

Ten Terms Explain Every File in the Vault

Each term below means one thing in this guide. A search for some of them returns another person's meaning, so the graph shows how they connect.

The vault and the agent

• Second brain: a folder of notes outside your head. Here it is an Obsidian vault of Markdown files.

• Claude Code: Anthropic's command-line agent. It reads, writes and runs files inside one folder.

• Harness: Claude plus every file it reads on startup, such as rules, identity, skills, tools and state.

• MCP: Model Context Protocol, a standard way to connect Claude to an outside tool or data source.

The files Claude reads

• CLAUDE.md: a Markdown file Claude Code reads at the start of each session. It holds the rules for that folder.

• Load order: the sequence in which Claude reads its instruction files. An earlier file carries more weight.

• Skill: a folder with a SKILL.md prompt. Claude loads it when a task matches its trigger.

The files that run work

• Hook: a script that Claude Code runs on an event, such as a file save.

• State file: a log the agent edits, such as rows of sent, pending and failed messages.

• Routine: a scheduled workflow, such as a daily comment pass, stored as a file.

A Fresh Session Is a Harder Reader Than a New Hire

The test is simple to state. If you disappeared for two weeks, could someone who never met you keep the work running? Pick the hardest stranger for it, a fresh AI session with no memory of past chats.

A new hire passes a weak system. They ask a colleague, search old threads, and copy the person at the next desk. Each answer stays in their head, so the system looks finished while the gap stays open.

A fresh session has no one to ask. It reads the files, and where the files say nothing, it guesses. The guess sounds confident, so the error ships before you see it.

describes the same blank start: "Your AI starts fresh every session with zero memory of what you built, decided, or debugged before."

1. Open a fresh session.

2. Give it one task with no explanation.

3. Write down every question it asks.

4. Write the file that answers each question before the next session.

Rule of thumb: If you type the same correction twice, it belongs in a file. The second time is the signal.

Nine Steps Start an Obsidian and Claude Vault Today

Do these in order. One step takes one sitting, and the sections below explain each one.

1. Install Obsidian and create a vault, which is one folder of Markdown files.

2. Create five folders to start, named Inbox, Library, Projects, Archive and Identity.

3. Write an About file in the Identity folder with your role, your work and your goals.

4. Write a Voice file there with three paragraphs you wrote, plus the words you never use.

5. Write CLAUDE.md at the vault root with the folder map and a rule that every draft goes to a file.

6. Install Claude Code and start it inside the vault folder.

7. Turn your most repeated prompt into a skill, which is one SKILL.md file in its own folder.

8. Push the vault to a private GitHub repo, and commit at the end of each session.

9. End each session by asking Claude to write the decisions and changes into the vault.

Steps 1 and 2. Install Obsidian and Give Each Folder One Job

Every note is a .md file on your own drive. If Obsidian stops working, the files still open in any text editor. Steph Ango, the Obsidian CEO, calls this principle file over app.

Obsidian sits in my tool directory for that reason. Obsidian Copilot sits beside it, and it answers questions from your own notes.

Browse the rest of the list in the tool directory.

Copy this folder pattern and rename the folders to suit you. Keep one job per folder, and start with five folders before you add Output and Engine.

Two files sit at the root. CLAUDE.md holds the rules and the folder map, and TODO.md holds open tasks.

Kanika shares a similar folder tree for content creators, from an ideas inbox down to an archive.

A file outside the agreed folders escapes every check. Each check looks in one known place, such as a scoring script on the drafts folder. None of them searches the whole drive, because a search that wide runs slowly and flags notes never meant to ship.

Watch out: A draft saved in the wrong folder reports zero errors, because no check opens it. Zero errors from an unread file looks the same as a clean draft.

So write the folder map into CLAUDE.md. Tell Claude to save each file type in exactly one folder. Then run a weekly script that lists every file outside the map.

Steps 3 and 4. Write the Identity Files Before Claude Drafts a Line

Most AI output sounds generic, because the model does not know what you sound like. An identity folder fixes that with plain files.

• An About file says who you are and what you have built.

• An Audience file names the readers you write for.

• A Voice file sets the tone and the formatting rules.

• A Purpose file says what each piece of writing is for.

My identity folder holds those files plus a README that tells Claude to read them first.

The files carry rules a stranger could never guess. My Voice file bans hashtags and emoji. It also says to write "second brain" with no hyphen. Claude reads that file before it drafts a line, so I never type those rules into a chat again.

Shann Holmberg calls a second brain the place for every file your agents need to do quality work.

Step 5. Write CLAUDE.md With the Folder Map and a Drafts Rule

CLAUDE.md sits at the vault root and loads first. Give it three things.

1. The folder map, one line per folder.

2. The rule that each file type goes in exactly one folder.

3. The rule that every draft goes into a file in the drafts folder.

The third rule matters because chat is gone when the session ends. In a long session Claude writes ten or twenty drafts, and you read three. A draft you never saw is a draft you never reviewed, and that is the one that ships with a wrong number.

Asking Claude to paste everything again at the end fails too. The drafts still sit in a place that expires.

Build one review page that lists every draft from every channel. Mark each one approve, rework or cut, and paste your verdicts back to Claude.

Harsehaj built a blog agent at Browserbase that only drafts, and a human clicks approve before any edit.

A vault grows fastest when a whole website can land in it as one note. My Site to Knowledge Note skill fetches every entry of a glossary, an ideas library or a docs set into one markdown file, then links each entry to your other notes.

Get it from the Site to Knowledge Note page in the skill pack.

Steps 6 and 7. Start Claude Code and Sort Every File Into Three Kinds

Start Claude Code inside the vault folder, so it reads CLAUDE.md on launch. Then turn your most repeated prompt into a skill. Every file you add after that is one of three kinds, and each kind has one owner.

names the cost a skill removes: "You are basically re-hiring the same employee every morning"

Skill files. You write them. A skill is a folder with SKILL.md for the prompt, the trigger and the output format. It can add a scripts folder for Python checks and a references folder for examples. The skills guide shows a full set.

State files. The agent edits them, and you never do. My outreach log records every Substack DM the outreach script sends. The next run reads it and refuses a duplicate, so a hand edit can make it message someone twice.

Reference files. These are examples to copy. One folder holds a breakdown of each post format, and the LinkedIn skill copies their shape.

Tip: Skills live in two places. The skills folder in your home directory loads in every project, and a skills folder inside the vault loads only there. Keep each skill in exactly one of the two.

Step 8. Commit the Rules to a Private Repo and Never Commit the Keys

Push the vault to a private GitHub repo and commit at the end of each session. Commit these files:

• The vault notes and the identity files

• The skills, the hooks and the routine files

• An example env file with empty values

Never commit .env, a credentials file or any API key. Keep secrets in one gitignored .env file and refill them by hand on a new machine.

A company brain is the same idea for a team. It holds company skills, company voice, and a README written for agents. Keep it in its own repo.

A help docs repo I maintain at work runs as a company brain. Its README lets a new joiner point Claude at the repo with zero context.

The global CLAUDE.md in your home directory loads in every session, and mine carries a project registry. Each row maps the words I say, such as "my website", to a local folder and its GitHub repo. I say "fix the footer on my website" from any session, and Claude works in the right folder.

1. When two rows collide, such as "the docs", Claude asks which one I mean.

2. Claude runs git status before it edits, because some repos sit on feature branches.

3. Claude names any other repo it writes to in its reply.

4. A commit or a push still needs my yes.

Step 9. End Each Session by Writing Decisions Into the Vault

Ask Claude to write the decisions and changes of the session into the vault before you close it. Then run the stranger test again. Each question the fresh session asks names a file your vault is missing, so write that file next.

On a new PC, clone the config repo and run its restore script. The full backup and restore guide is in The 5 Files That Give Claude Code Permanent Memory.

Advanced Users Add Hooks, Agents and Routines as Files

The nine steps give Claude memory. The pieces below make the vault refuse bad work and run on a schedule.

Hooks block the write. My hook runs a scoring script after each file save. On a critical finding it blocks the save, so Claude cannot finish while the draft fails. A second hook prints the load order into context on any writing prompt. The load order post shows what that costs in tokens.

Scorers and a second grader close the loop. Define good and bad output, generate, score, and regenerate up to 3 to 5 times. A fresh subagent grades the rest, because an agent will not reject its own earlier answer.

Example: In one session, 21 LinkedIn comments failed the scorer and never posted.

Agents own one job each. An agent is a file that gives Claude one role and its tools.

• One agent writes articles, and another turns them into social posts.

• One sends outreach messages, and another writes comments.

• One runs the health checks, and another files loose notes.

Routines live in git. A routine that exists only inside a Claude account vanishes when you switch accounts. So each routine is a file in a routines folder, with its input and its output state.

Connectors follow the account, and MCP servers follow the machine. A cloud connector in Claude's Connections tab works for anyone on that account. A local MCP server lives in the machine config, so a new PC needs it set up again.

Five Questions Newcomers Ask About an Obsidian Second Brain

Do I need Obsidian, or will any folder work? Any folder of Markdown files works, because Claude Code reads plain files. Obsidian adds links, search and a graph view on top of the same files.

found the same thing with years of plain notes: "But it turns out markdown files are exactly the type of context AI wants to eat."

How long does the first setup take? Plan one sitting per step, so about nine short sessions. The first five steps already stop most of the repeated explaining.

Can I start with five folders and add more later? Yes. Start with Inbox, Library, Projects, Archive and Identity, then add Output and Engine when you have drafts and skills to store.

What happens to my API keys when I push to GitHub? They stay on your machine if they live in a gitignored .env file. Commit an example file with empty values, so a new machine knows which keys to refill.

How do I know the vault is finished? It is never finished, but it passes when a fresh session runs a task without a question. Each question it does ask tells you the next file to write.

Appendix. A Starter CLAUDE.md and Gitignore to Copy

Paste this at the vault root as CLAUDE.md, then rename the folders to match yours.

# CLAUDE.md

## Folder map
- Inbox/      raw captures, not sorted yet
- Identity/   About, Audience, Voice, Purpose. Read before any draft.
- Library/    reference notes
- Projects/   one subfolder per active project
- Output/     ideas/, drafts/, published/
- Engine/     skills/, hooks/, routines/
- Archive/    retired notes. Never delete, always archive.

## Rules
1. Save each file type in exactly one folder from the map.
2. Write every draft into Output/drafts/, never only into chat.
3. Never edit a state file by hand.
4. Commit at the end of each session. Never commit .env.

Add these lines to .gitignore before the first push.

.env
*.key
credentials.json
.obsidian/workspace.json

One row of the global project registry looks like this.

| You say    | Local path          | Repo              |
|------------|---------------------|-------------------|
| my website | D:\Projects\website | you/your-website  |

Leave a comment

Keep everything you must back up in one private GitHub repo, and a new PC setup takes 45 minutes instead of a full day. Winget installs the apps, symlinks bring back the settings, and one more clone restores Claude.

• One private GitHub repo holds every file you wrote: the app list, the scripts, the configs and your Claude setup.

• Winget installs 35 apps from that list in 15 minutes, with no download pages.

• Symlinks point each app at its config file in the repo, so a settings change becomes a commit.

• Keys stay out of git. The repo keeps an example file with every key name, and you refill the values by hand.

• A restore you never tested proves nothing, so run it in Windows Sandbox once a quarter.

Picture the same new laptop set up twice. From memory, you hunt for 35 installers, redo each setting, and re-explain your rules to Claude for about 8 hours. From the repo, you run two scripts and clone one more repo in about 45 minutes.

Jean-Michel Lemieux watched an agent set up his new work laptop, from the dev environment to the repos.

One Private GitHub Repo Holds Everything You Must Back Up

My rule is short. If I wrote a file or changed a setting, it lives in a GitHub repo. That covers the Winget app list, the install and restore scripts, every config file and the README.

I run the same rule for Claude. My global Claude config and my global skills live in one private repo, cloned straight into the .claude folder in my home directory.

Two things stay out on purpose: secret keys, and bulky data such as notes and databases.

Rule of thumb. When you change a setting, move its file into the repo the same day and link it back. A setting saved anywhere else never comes back, because no restore looks there.

Step 1. Install Git, the One Tool a Fresh Windows Lacks

A fresh Windows install ships with Winget but without Git. Open PowerShell as Administrator, install Git with Winget, and clone your setup repo to C:\dotfiles. Every later step reads from that folder.

Step 2. Install 35 Apps From One Winget List

Winget is the package manager built into Windows. It installs an app by its package ID, so you never visit a download page. One script installs all 35 in 15 minutes.

Productivity

1. Obsidian, the base of my second brain, one local folder of plain-text notes

2. TickTick, for tasks

3. Flow Launcher, to open files and apps from the keyboard

Communication

1. Slack, for work

2. Discord, for communities

3. Telegram, for everything else

Browsers and privacy

1. Brave, the main browser, with Chrome extensions

2. Proton VPN, for networks I do not trust

Development

1. VS Code, the main editor

2. Sublime Text, to open a single file faster

3. Docker, to run containers

4. Node.js, the JavaScript runtime

5. Python 3.12, the Python runtime

6. MongoDB, for local document databases

7. SQLite, for local file databases

Media

1. VLC, to play every format

2. Audacity, to edit audio

3. MediaMonkey 5, to keep the music library tagged

4. OBS Studio, to record the screen

5. Upscayl, to upscale images on the local GPU

6. qBittorrent, for downloads

System utilities

1. WizTree, to find the files that fill a disk

2. SyncThing, to sync folders between machines

3. CCleaner, to clear junk files

4. PDF24 Creator, to merge and split PDFs offline

5. Calibre, to manage ebooks

Command-line tools

1. FFmpeg, to convert media

2. yt-dlp, to download video

3. Gallery-DL, to download image galleries

4. ImageMagick, to edit images in batches

5. Rclone, to sync files to Google Drive and Dropbox

6. Pandoc, to convert Markdown to PDF or Docx

7. Zoxide, a cd that learns your folders

8. Ripgrep, to search a whole codebase in seconds

9. Bat, to print files with syntax colors

Tip. Winget IDs change when a publisher renames a package. If one app fails, search Winget for its name and update the ID in the list.

Scott Hanselman of Microsoft uses the same package manager to update every app at once.

Winget can also export every app on your old machine to one file, which gives you a first draft of the list.

Microsoft's WinGet team shows how to export a machine setup to one file and apply it on another machine.

Step 3. Link Every Setting Back to the Repo With Symlinks

Apps keep their settings in scattered AppData folders. Copy each config folder into the repo once, on the old machine. On the new machine, the restore script renames any default config to .bak and links the repo copy in its place.

Open VS Code after the script runs, and your theme and keybindings are already there. Only seven of my apps need a config copied, and every other app keeps the Winget default. A .gitignore keeps logs, databases and credentials out of the repo.

Step 4. Handle the Three Apps That Refuse a Symlink

• Obsidian keeps its config in the .obsidian folder inside the vault. Point the app at the synced vault and skip the link.

• Brave encrypts profile data with a key tied to one machine, so a linked profile breaks saved logins. Use Brave Sync for bookmarks and extensions, and keep an exported bookmarks file as a spare.

• Python and Node.js need their global packages. Add your npm install -g and pip install lines to the end of the bootstrap script.

Step 5. Sync Notes and Databases With SyncThing Instead of Git

SyncThing syncs folders between machines peer to peer, with no cloud server in the middle. Pair it with the old machine, and your notes and databases copy across. Then point Obsidian at the synced notes folder.

Git stores each binary file whole on every change, so the repo grows and the history stops being readable. SyncThing keeps no history, which suits data you never compare line by line.

Gary Explains walks through a SyncThing setup across Windows, macOS, Linux and Android.

Watch out. A full disk image looks safer, and it fails twice. It carries years of junk back with it. It also carries profile data locked to the old machine, so Brave logins break anyway.

Step 6. Clone Your Claude Config Repo Into Your Home Folder

Claude Code is Anthropic's AI coding assistant that runs in your terminal. With no setup, it forgets you every session. A harness is Claude plus the files it reads when a session starts, and mine has four kinds:

• CLAUDE.md, the plain-text rules Claude reads at the start of every session

• Skills, one folder each, with a SKILL.md prompt that loads when a request matches it

• MCP servers, small programs that give Claude a new tool, such as a web scraper (MCP stands for Model Context Protocol)

• Routines, prompts that run on a schedule, such as a daily report

Install Git, Node.js and Claude Code first, because the tool setup needs all three. Then clone the private repo into the .claude folder and run the restore script inside it. The script skips any file that already exists, reinstalls each command-line tool, and registers its MCP server.

Everything Claude Code is a public example of the same idea: one repo of skills, memory and security config. I list it on my tools page.

The full backup and version control guide lives in the 5 files that give Claude Code permanent memory.

Step 7. Refill Every Key From the Example File

All API keys sit in one .env file that git ignores. A committed .env.example lists every key name with an empty value. Copy it to .env, paste each key back in, and rerun the tool setup so each command-line tool signs in.

Claude's login token never goes in the repo either, so you sign in again. A sync script copies the live folder back into the repo and blanks each secret, and you review the diff before every commit.

Step 8. Reschedule Every Routine From Its File

A routine registered only inside a Claude account disappears when you switch accounts. One social scheduling tool I use deletes an uploaded image after 7 days unless a post uses it.

So keep each routine as a Markdown file in the repo, with its schedule in the header block and its prompt in the body. On a new machine, point Claude at the folder and ask it to schedule every routine again.

Step 9. Test the Restore in Windows Sandbox Once a Quarter

A setup that works on the machine that built it proves nothing. The old machine still holds every file you forgot to save.

Windows Sandbox is the throwaway desktop built into Windows Pro. Run the restore there, write down every question you had to answer from memory, and add each answer to the README.

Prune old rules during the same test. Rule Rewriter, a $19 skill in my skill pack, audits CLAUDE.md and skill files for rules written for older models.

Four Questions Decide Whether This Setup Fits Your Machine

Does this work on Windows Home?

Winget and symlinks work on Home. Creating a symlink needs an Administrator PowerShell or Developer Mode turned on. Windows Sandbox needs Pro, so on Home run the test in a virtual machine.

Why a private repo and not a public one?

Config files leak your email, your machine paths and your tool list. Keep the repo private, and publish a cleaned copy only to share it.

Does the approach carry over to macOS?

It does. A Homebrew Brewfile replaces the Winget list, and ln -s replaces the PowerShell symlink command. The rule stays the same: one repo holds every file you wrote.

How do I keep the repo current?

Commit when you change a setting. The symlink already put the change in the repo, so you only commit and push.

Appendix. Every Script, Path and Command

Install Git

winget install --id Git.Git -e

bootstrap.ps1 Installs All 35 Apps

Run it as Administrator.

# Run as Admin check
if (!([Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)) {
    Write-Error "Run this script as Administrator!"; return
}

$apps = @(
    # Productivity
    "Obsidian.Obsidian", "Appest.TickTick", "SlackTechnologies.Slack", "Discord.Discord",
    "Telegram.TelegramDesktop", "Flow-Launcher.Flow-Launcher",

    # Browsers & VPN
    "Brave.Brave", "Proton.ProtonVPN",

    # Dev & Terminal
    "Microsoft.VisualStudioCode", "SublimeHQ.SublimeText.4", "Docker.DockerDesktop",
    "OpenJS.NodeJS", "Python.Python.3.12", "MongoDB.Server", "SQLite.SQLite",

    # Media & Creativity
    "VideoLAN.VLC", "Audacity.Audacity", "VentisMedia.MediaMonkey.5",
    "OBSProject.OBSStudio", "Upscayl.Upscayl", "qBittorrent.qBittorrent",

    # Utilities
    "AntibodySoftware.WizTree", "Syncthing.Syncthing", "Piriform.CCleaner",
    "geeksoftwareGmbH.PDF24Creator", "calibre.calibre",

    # CLI Power Tools
    "Gyan.FFmpeg", "yt-dlp.yt-dlp", "mikf.gallery-dl", "ImageMagick.ImageMagick",
    "Rclone.Rclone", "JohnMacFarlane.Pandoc", "ajeetdsouza.zoxide",
    "BurntSushi.ripgrep.MSVC", "sharkdp.bat"
)

foreach ($app in $apps) {
    Write-Host "Installing $app..." -ForegroundColor Cyan
    winget install --id $app --silent --accept-source-agreements --accept-package-agreements
}

Export the App List From an Old Machine

winget export -o apps.json

Seven Config Paths to Copy Into the Repo

• Obsidian: [YourVault]/.obsidian, with appearance.json and plugins.json

• VS Code: %AppData%/Code/User/, with settings.json and keybindings.json

• Flow Launcher: %AppData%/FlowLauncher/, with Settings/ and Plugins/

• Zoxide: %LocalAppData%/zoxide/, with db.json, your folder history

• MediaMonkey: %AppData%/MediaMonkey/, with MM5.db, your library metadata

• yt-dlp: %AppData%/yt-dlp/, with config.txt, your default download settings

• Brave: %LocalAppData%/BraveSoftware/Brave-Browser/User Data/Default, with Bookmarks and Login Data

A Quick Symlink Script

# Define where your synced configs live
$syncFolder = "C:\Backup\Config"

# Function to create the link
function Set-Link($appPath, $backupPath) {
    if (Test-Path $appPath) { Remove-Item -Recurse -Force $appPath }
    New-Item -ItemType SymbolicLink -Path $appPath -Target $backupPath
}

# Apply Links
Write-Host "Restoring App Settings via Symlinks..." -ForegroundColor Green

# 1. VS Code Settings
Set-Link "$env:APPDATA\Code\User" "$syncFolder\vscode"

# 2. Flow Launcher (Everything: plugins, history, themes)
Set-Link "$env:APPDATA\FlowLauncher" "$syncFolder\FlowLauncher"

# 3. yt-dlp Global Config
Set-Link "$env:APPDATA\yt-dlp" "$syncFolder\yt-dlp"

# 4. Git Config (Crucial for your dev work)
Set-Link "$env:USERPROFILE\.gitconfig" "$syncFolder\git\.gitconfig"

Repo Layout

.
├── scripts/
│   ├── bootstrap.ps1        # Installs all apps (Winget)
│   └── restore.ps1          # Creates the symlinks
├── configs/
│   ├── vscode/
│   │   ├── settings.json
│   │   └── keybindings.json
│   ├── flow-launcher/       # Folder for Flow settings
│   ├── git/
│   │   └── .gitconfig
│   └── obsidian/            # Optional: Global snippets or CSS
├── .gitignore               # CRITICAL: Prevents pushing secrets
└── README.md                # Instructions for your future self

.gitignore

# Ignore local databases and logs
*.log
*.db
*.sqlite

# Ignore sensitive VS Code data
configs/vscode/backups/
configs/vscode/workspaceStorage/

# Ignore actual Obsidian Vaults (Keep those in Syncthing/Proton Drive)
# Only track global Obsidian CSS or templates here if desired.
vaults/

# Ignore sensitive Git credentials
.git-credentials

One-Line Deploy on a New Laptop

git clone https://github.com/YourUsername/dotfiles-windows.git C:\dotfiles; & C:\dotfiles\scripts\bootstrap.ps1; & C:\dotfiles\scripts\restore.ps1

restore.ps1 Links Configs From Any Clone Path

$repoRoot = (Get-Item $PSScriptRoot).Parent.FullName
$configSource = "$repoRoot\configs"

function Set-Link($targetPath, $sourcePath) {
    if (Test-Path $targetPath) {
        Write-Host "Backing up existing config for $(Split-Path $targetPath -Leaf)..."
        Move-Item $targetPath "$targetPath.bak" -Force
    }
    # Ensure the parent directory exists
    $parentDir = Split-Path $targetPath -Parent
    if (!(Test-Path $parentDir)) { New-Item -ItemType Directory -Path $parentDir }

    New-Item -ItemType SymbolicLink -Path $targetPath -Target $sourcePath
    Write-Host "Linked: $targetPath" -ForegroundColor Gray
}

# -- Execute Links ---
Write-Host "Linking configurations from $configSource..." -ForegroundColor Cyan

# VS Code
Set-Link "$env:APPDATA\Code\User\settings.json" "$configSource\vscode\settings.json"

# Git
Set-Link "$env:USERPROFILE\.gitconfig" "$configSource\git\.gitconfig"

# Flow Launcher
Set-Link "$env:APPDATA\FlowLauncher\Settings" "$configSource\flow-launcher\Settings"

Write-Host "Migration Sync Complete!" -ForegroundColor Green

The .bak file holds one prior version only. Run the script twice on the same machine and the second .bak replaces the first.

Commit a Settings Change

cd C:\dotfiles
git add .
git commit -m "Updated VS Code theme"
git push

Related Reading

• VSCode Plugin Export and Share with Friends

Leave a comment

Vibe coded app SEO fails in one place. Your React app serves one HTML file for every URL. A crawler that never runs your JavaScript reads the head of that file on all of them. I rebuilt my own app, 10xDevRel, from the commit before my fix and fetched its 43 sitemap URLs. All 43 returned the same title and the same canonical.

AI code generators build the layout you can see first. Title, canonical and description never show in a preview, so the model skips them. That is the cost of vibe coding at speed. This post shows the fix I shipped and the two prompts that apply it.

TLDR

• A crawler or link preview reads the head in the served HTML, and a head that JavaScript writes arrives too late.

• In 10xDevRel, 43 URLs returned 1 title before the fix and 43 titles after it.

• Keep each route's title, description and canonical in one map, and write them into the HTML your server sends.

• Check the raw HTML with curl, because your browser tab shows the head after JavaScript ran.

• Run the audit prompt for the plan and the report prompt for the record. Both sit in the Appendix.

The Same URL Returned the Homepage Head Before the Fix

Here is the same URL on two builds of 10xDevRel, a React and Express app. I built the repo at its fix commit and at the commit before it. I then fetched each URL from the app's own static server.

• Before: curl on /playbooks returned the homepage title, description and canonical. /tools and /book returned the same file, byte for byte.

• In a browser: the page then added its own canonical, so the tab held two that disagreed.

• After: the same URL returns its own title, description and canonical.

• Unknown paths: /nope-xyz answered 200 before the fix and answers 404 after it.

A Crawler Reads Your HTML, Not Your React

A browser fetches the HTML, runs your JavaScript bundle and lets React write the page. Many fetchers stop after the first step. LinkedIn and Slack link previews read only the served HTML, so every shared URL unfurls as your homepage.

Google can run your JavaScript, but it queues the page for rendering first. Its own documentation says a page may wait on that queue for longer than a few seconds (Google Search Central). A head in the served HTML needs no wait.

Pre-launch checklists already list the layer this post fixes. Suraj Sharma posted 20 tasks to give Claude before a launch, and meta titles, descriptions and a sitemap sit on it.

Rule of thumb. If view-source on a URL shows your homepage title, so does every fetcher that skips JavaScript.

Step 1. Map Every Public Route Before You Edit

Start with a list. A head you cannot attach to a route cannot be checked. The audit prompt writes a plan file first and stops, so you read the list before an agent edits anything.

10xDevRel had 39 routes when I fixed it. Your list needs four kinds:

• Static routes, such as /playbooks and /pricing.

• Dynamic families, such as one page per playbook. Derive their heads from their own data so a new page cannot be forgotten.

• Aliases, which render another route's page and take that page's canonical.

• Private routes, such as /signin, which need noindex.

Step 2. Write Each Route's Head Into the Served HTML

The head must exist in the file your server sends. Two methods do that, and your hosting picks one.

• The server writes it per request. 10xDevRel runs Express. A marker in index.html is replaced with that route's tags before the file goes out.

• The build writes one file per route. atharvashah.com sits on GitHub Pages, which has no rewrite rule. A script writes an index.html at every route path with that route's tags baked in.

A framework that renders pages on the server removes this step. I did not test one for this post.

A runtime head library such as react-helmet-async can still own the tab title after the page loads. It cannot replace this step, because it runs after the bundle loads. React 19 places a rendered title in the document head (react.dev), and that happens when the component renders. A fetcher that skips the bundle never gets there.

Make an unknown path answer 404. Before the fix, 10xDevRel answered /nope-xyz with 200 and the 404 page, which tells a crawler the URL is real.

Watch out. Check / too. In the build I ran from the fix commit, the static-file middleware answered / from the built index.html before the head handler ran. Inner routes carried their own head. The homepage kept the fallback title and no canonical.

Step 3. Give Every Route Its Own Title and Canonical

Each entry in the map carries five things:

• Title: 50 to 60 characters that name the page.

• Description: written for this route, never copied from the homepage.

• Canonical: one absolute URL that points at the page the route renders.

• Robots: noindex on private routes, and no robots.txt block on them, because a blocked page never shows its noindex.

• Social tags: OpenGraph and Twitter tags built from the same title and description.

Example. Before the fix, the browser tab for /playbooks held two canonical tags, / and /playbooks. After the fix both read /playbooks. A search engine cannot trust two canonicals that disagree.

Write structured data (JSON-LD) into the HTML the same way. 10xDevRel still ships one site-wide WebSite block. atharvashah.com writes blocks per route, and its SEO Blog Grader page returns two.

Step 4. Check the Raw HTML With One Command

Run curl against the live URL and read the head. Your browser tab hides the problem, because the tab shows the head after JavaScript ran.

curl -s https://your-site.com/playbooks | grep -E '<title>|rel="canonical"'

This is the real output from 10xDevRel before the fix.

<title>10x DevRel — Playbooks &amp; AI Tools for Developer Advocates</title>
<link rel="canonical" href="https://10xdevrel.atharvashah.com/" />

This is the real output after the fix.

<title>DevRel Playbooks: 16 Interactive Checklists | 10x DevRel</title>
<link rel="canonical" href="https://10xdevrel.atharvashah.com/playbooks" />

Here is the same check on my own site today, for a route that the build wrote.

<title>AI SEO Blog Grader Skill for Claude | Atharva Shah</title>
<link rel="canonical" href="https://atharvashah.com/ai-skills/seo-blog-grader" data-head="static">

Past a dozen routes, loop the check over your sitemap and count distinct titles. One title means the fix did not land. The loop is in the Appendix. Scale is no excuse to skip it. Borja reports that a model read all 586 pages of his site in 45.1 seconds for $0.21, to rebuild its internal link map.

Step 5. Run the Report Prompt and Keep the Record

The report prompt runs after the audit prompt finishes. It compares the before state with the after state and writes SEO_REPORT.md. Build for a client and the report is the deliverable. Build for yourself and it is the reason a title reads the way it does, months after you approved the plan.

The report covers five areas:

• Executive summary: SEO health before the overhaul and after it.

• Technical infrastructure: every new file, why it exists and how it changes crawler behavior.

• Page-by-page breakdown: every tag and semantic fix, route by route.

• Head mechanism log: how each route's head reaches the served HTML, with curl output as proof.

• Performance and accessibility: alt text and lazy-loading changes.

Keep the plan-first rule in your agent's instruction file so every session starts with it. The Copilot setup guide shows how instruction files work. Any app you ship in a day, such as the AI security CTF platform I built in one day, needs this layer before launch.

Once each route has a head, Search Console shows which pages sit at positions 5 to 20. Okara describes asking for a new title tag, an h1 and 2 or 3 h2 sections for each of them.

Your blog posts need the same check. The SEO Blog Grader skill scores a draft, a file or a live URL on six areas, and lists the fixes in priority order.

Tip. Run the audit prompt, read SEO_PLAN.md, and fix the plan before you approve it. A missing route costs nothing at that stage.

The next layer after a fixed head is being named by AI answers, which this guide to getting recommended by AI covers. Ira Bodnar lists seven SEO and GEO workflows, and the first scores competitor pages on answer, depth, proof and freshness.

Four Questions a Builder Asks About the Served HTML

Does Google run my JavaScript? It can. Google queues the page for rendering after the first fetch, and the wait can run long. Link previews and many AI fetchers stop at the served HTML, so write the head there for all of them.

Does React 19 fix this? React 19 places a rendered title in the head, and rendering happens in the browser. A fetcher that skips the bundle still sees your shell. The head has to be in the file.

Do I need to move to a framework? No. 10xDevRel kept its Vite and Express setup, and atharvashah.com kept a static host. A framework that renders on the server removes the step, but I did not test one for this post.

Which pages stay out of the index? Private routes such as sign-in and account pages. Give each one noindex in its served head, and leave it out of robots.txt so a crawler can read the noindex.

The Appendix Holds Both Prompts, the Check Loop and the Injection Code

This is the audit prompt, run first. Paste it into your coding agent with your React project loaded.

Role: You are an Expert Senior Full-Stack Engineer and SEO Specialist.

Task: Perform a comprehensive SEO overhaul of this React workspace. You must follow a strict "Plan-First" execution model.

Phase 1: Analysis & Documentation
Crawl the Project: Scan the /src folder, especially routes (e.g., App.js, routes.tsx, or react-router configs) to identify every public-facing page, every dynamic route family, every alias and every private route.

Sitemap Audit: Locate or create a strategy for a dynamic sitemap.xml.

Deliverable: Create a file named SEO_PLAN.md documenting:

A list of all identified routes, grouped as static, dynamic, alias and private.

The proposed robots.txt configuration.

How each route's head will reach the HTML the server sends. Pick one method and name the file that will hold each route's title, description and canonical: the server writes the head per request, the build writes one HTML file per route, or the framework renders it on the server.

A strategy for OpenGraph (OG) tags and structured data (JSON-LD).

Phase 2: Technical Infrastructure
Robots & Sitemap: Generate a robots.txt in the /public folder. Create a script (or a manual sitemap.xml) that includes all routes found in Phase 1. Do not block private routes in robots.txt. Give them noindex instead.

Head in the Served HTML: Implement the method chosen in SEO_PLAN.md so the HTML sent for each route already carries its own title, description, canonical, OpenGraph and Twitter tags before any JavaScript runs. A runtime head library may stay for the browser tab, but it never replaces this.

Unknown Paths: Make a path that matches no route answer with HTTP status 404.

Phase 3: Page-Level Optimization
For every page component identified:

Meta Tags: Give each route a unique <title> of 50-60 characters and a unique <meta name="description">.

Social Graph: Implement OpenGraph (og:title, og:description, og:image) and Twitter Card tags.

Semantic HTML: Review the JSX. Ensure the page uses a logical heading hierarchy (<h1> for main titles, <h2> for sections) and semantic tags (<main>, <article>, <nav>).

Clean URLs: Ensure all Link components use human-readable slugs.

Phase 4: Performance & Programmatic SEO
Image Optimization: Identify <img> tags and suggest/implement loading="lazy" and descriptive alt text.

Dynamic Routes: If the app uses dynamic parameters (e.g., /products/:id), derive each route's head from the data that renders the page, so a new page cannot be forgotten.

Implement a site-wide JSON-LD 'Organization' and 'WebPage' Schema to clarify brand identity for LLMs and search engines. Ensure all critical brand and service information is 'crawl-ready' without requiring JavaScript execution to prevent data loss during AI indexing.

Constraints:

Do not break existing CSS or functional logic.

Prioritize "Human-Readable" code and SEO-friendly URL structures.

Before you finish, run curl on the raw HTML of three different routes and paste each title and canonical into SEO_PLAN.md as proof.

Wait for my approval on SEO_PLAN.md before modifying any application files.

This is the report prompt, run second.

**Role:** You are a Senior Technical SEO Auditor.

**Task:** Conduct a post-implementation review of the SEO overhaul performed on this React workspace. You must generate a professional, comprehensive report named `SEO_REPORT.md`.

**Scope of Analysis:**

1. Compare the current state of the `/src` and `/public` folders against standard React SEO best practices.

2. Identify every route whose head is now written into the served HTML, and the file that holds its title, description and canonical.

3. Identify all new files created (e.g., `sitemap.xml`, `robots.txt`, `SEO_PLAN.md`).


**Report Structure Requirements:**

### 1. Executive Summary

- Provide a high-level overview of the SEO health of the application before vs. after implementation.


### 2. Technical Infrastructure Changes

For every **New File** created (e.g., `robots.txt`, `sitemap.xml`):

- **File Path:** [Path to file]

- **Purpose:** Why was this specific file created?

- **Impact:** How does this file affect search engine crawlers (indexing, crawl budget, etc.)?


### 3. Page-by-Page Breakdown

Create a section for **every page/route** modified. For each page, document:

- **Component Name & Path:**

- **Elements Added:** List specific Tags (Title, Meta Description, Canonical, OG Tags, Schema.json).

- **Technical Decisions:** Why was this specific keyword or description chosen for this route?

- **Semantic Improvements:** Note if tags like `<div>` were changed to `<main>`, `<article>`, or if `<h1>`-`<h6>` hierarchy was corrected.

- **SEO Impact:** Explain how these specific changes improve the "Relevancy Score" for that page.


### 4. Head Mechanism Log

- **Method:** Which method puts each route's head into the served HTML, and why was it chosen over the others?

- **Proof:** Paste the curl output for the title and canonical of three routes.

- **Unknown Paths:** Show the status code for a path that matches no route.


### 5. Performance & Accessibility (A11y)

- List improvements made to `<img>` alt tags and `loading="lazy"` attributes.

- Explain how these changes impact Core Web Vitals (LCP, CLS).


**Tone:** Professional, technical, and data-driven. Use before and after lists to compare meta-titles and descriptions.

**Final Output:** Save all of this into `SEO_REPORT.md` in the root directory.

This loop fetches every sitemap URL and counts distinct titles. One line of output means every route shares one title.

grep -o "<loc>[^<]*</loc>" public/sitemap.xml | sed 's#<loc>##;s#</loc>##' | while read url; do
  curl -s "$url" | grep -o "<title>[^<]*</title>" | head -1
done | sort | uniq -c | sort -rn

This is the core of the server method in 10xDevRel, trimmed. The function seoForPath reads the route map, and the marker in index.html is replaced before the file is sent.

export function injectRouteHead(template: string, rawPath: string): string {
  if (!template.includes("<!--ROUTE-HEAD-->")) return template;
  // drop the fallback <title> that sits above the marker
  const open = template.indexOf("<title>");
  const close = template.indexOf("</title>");
  const withoutTitle =
    open !== -1 && close > open
      ? template.slice(0, open) + template.slice(close + "</title>".length)
      : template;
  return withoutTitle.replace("<!--ROUTE-HEAD-->", routeHead(rawPath).trimStart());
}

// in the static handler: an unknown path gets a 404 instead of a 200
const status = seoForPath(routePath).canonical ? 200 : 404;
res.status(status).set({ "Content-Type": "text/html" }).end(injectRouteHead(template, routePath));

Leave a comment