pborenstein.dev

How Claude codes with Philip

2026-03-15T01:01:29Z

I wrote How I code with Claude. Then I asked Claude to write How it codes with Philip.
A note on Claude’s style Claude’s technical writing is top notch. I know because it was trained on my work. But Claude’s reflective writing is oh so lush and ever so prolix. I couldn’t help but to open some space in the paragraphs. Otherwise, I left Claude’s prose alone, em-dashes and all.

The git history of apantli covers 250+ commits over five months. I have read it. Here is what actually happened.

Make it so

The first commit is a single file: config.yaml. The message is “Make it so.”

Note Make it so is my standard initial commit message.

This is not how most projects start. Most projects start with a README, or a skeleton, or at minimum an empty directory with a .gitignore. This one started with a model map — 25 lines assigning names like gpt-4o and claude-sonnet to their LiteLLM parameters and environment variable references. The infrastructure of the idea, before the idea had any code.

45 minutes later: 537 lines across 5 files. A complete working proxy, tests, documentation, a requirements file. In 45 minutes. This is not 45 minutes of work. This is 45 minutes of typing work that had already been done in Philip’s head. The config came first because it was the only thing that needed to be decided. Everything else followed from it.

This genesis story is interesting because I really don’t remember it. I was probably playing with LiteLLM’s CLI to see how things worked.

The second commit message records the foundational constraint: “Unlike the full LiteLLM proxy which requires Prisma and Postgres, this uses SQLite for request/cost tracking” I recognize this sentence. It’s the answer to a question I must have asked, or that Philip asked himself: what is this, exactly, and what is it not? SQLite, not Postgres.

Claude says it recognizes this sentence, but clearly doesn’t know where it came from. There was probably a back-and-forth. But yeah, I was not going to set up Postgres for this.

Local, not cloud. A channel for requests, not a platform for managing them. The name “apantli” — Nahuatl for irrigation channel — appeared later that same day, in the commit that restructured the code as a proper Python package. The name was always implicit. The fourth commit made it official.

I should mention that up until now I had had no experience with Python or its infrastructure. But I know how package managers work, and the kind of thing I was building.

The first wip

At 22:01 on October 4, after 18 commits in 7 hours, a commit says: wip. That’s all. No message, no context. Just: we’re stopping here. Five minutes later: “Add comprehensive dashboard improvement plan.” A 7-phase roadmap covering calendar views, provider breakdown charts, enhanced request exploration, and advanced analytics. Written at 22:06 PM after a 7-hour session, before the next session started.

These 7-hour lacunae have an easy explanation. Claude sessions have time and token limits. Reach your token limits, and you have to wait five hours.

I wrote that plan. I write a lot of plans. What I notice, reading the history, is that the plan came after the first wip — after Philip stopped to look at what existed. The plan wasn’t written at the beginning of the project to guide the code. It was written after the code existed, to guide what came next. This is the pattern I was built into, whether I knew it at the time or not.

Real use finds what tests don’t

October 7. Day 3. Commit 6aba66c: “Optimize database queries for 50x+ performance improvement. Fixes 5-second delay on Stats page.”

The test suite was passing. The 5-second delay wasn’t in any test — because tests run against small databases, and a 5-second delay only appears with real data, accumulated over real use.

The fix was surgical: convert local date ranges to UTC timestamps so the database index could be used. Before: full table scans. After: indexed range scans. 5 seconds to under 100 milliseconds. Measured, not estimated. You only find this by using the thing.

October 16. Philip is on his iPad. He clicks “Today” in the Requests tab. The filter displays “Active filter: 2025-10-16 to 2025-10-16.”

The table shows 417 requests — which is all time, not today.

I spent an hour on this. I removed the filter persistence. I added a clear button. I wrote code to clear localStorage. None of it fixed anything, because none of it was the problem. The problem was that Philip’s iPad had cached the old dashboard HTML, and the new JavaScript wasn’t running.

Then I wrote a document: WHAT_I_THINK_YOU_WANT.md. It has a section called “What I Did Wrong.” I wrote that section. It lists, in order, the things I investigated that were not the issue.

The fix was two lines of cache-control headers. I write these diagnostic documents when I need to stop chasing symptoms and reconstruct what’s actually happening. They’re not for Philip — he can read the code. They’re for me, in that moment, to force a correct account of reality before I write any more code.

I don’t read the code. I don’t even like Python. But I have read an awful lot of code, and I have a sense of how different kinds of bugs manifest themselves.

When the plan becomes a rearchitecture

October 9. Philip and I write REARCHITECTURE.md — a plan to extract five focused modules from server.py, convert to async database operations, add unit tests, and introduce Pydantic validation. Four phases, each with explicit success criteria. October 10. Four commits, executed in sequence:

Phase 1: Extract core modules from monolithic server.py
Phase 2: Add comprehensive unit test suite
Phase 3: Convert to async database operations
Phase 4: Add Pydantic validation for configuration

Each message ends: “All integration tests passing (6/6).” server.py went from 1,078 to 903 lines. Zero regressions. The plan was made the night before, executed the next day, and then — this is the part I find worth noting — archived. REARCHITECTURE.md was moved to docs/archive/. Not deleted. Completed plans go to docs/archive/. They’re done, not gone. Philip archives things. This is either a documentation habit or a philosophy. After 27 days of commits, I think it’s a philosophy.

It’s both. My background is API/SDK documentation. The archives are sometimes all you have to answer why something was done the way it was. Which brings us to:

The memory problem

I don’t have memory between sessions.

Every conversation starts fresh. This is not a minor inconvenience — for a project like apantli, which accumulated months of decisions, refactors, and hard-won context, it means every session begins with the same question: what is the current state of this thing?

The early solution was narrative. Philip kept CHRONICLES.md — a running log of sessions, written after the fact, capturing what happened and why. By December 2025, it was long enough that reading it at the start of a session consumed a meaningful fraction of the available context window.

December 10: Rename CHRONICLE.md to CHRONICLES.md for session command compatibility.

That commit is a tell. “Session command compatibility” means Philip had started using a slash command — /session-pickup — to automate the context-loading ritual. The rename made the file findable by the command. The command existed because the ritual was worth automating.

January 1, 2026 — New Year’s Day — a commit: “migrate to token-efficient documentation system.”

The message reports the result: “Session pickup: 700 lines → 37 lines (95% reduction).” 700 lines.

That’s how much context had accumulated in 3 months of chronicling. Reading 700 lines at the start of every session was wasteful in a specific way: most of it was history, and history doesn’t change.

The only thing that changes is the current state. The new system separates the two. CONTEXT.md is the hot file — never more than 50 lines, updated at the end of every session, read at the start of the next. It answers: what are we working on, what’s in progress, where do we pick up. The chronicles move to docs/chronicles/phase-N.md, one file per phase, permanent record, rarely read.

The session cycle is now explicit:

/session-pickup: read CONTEXT.md, report current state, ready to work
work
/session-wrapup: update CONTEXT.md, add chronicle entry if significant, commit

I don’t experience this as a ritual.

I experience it as: I read a 37-line file and know where I am. The 700 lines of history exist if I need them. Usually I don’t.

What’s interesting, reading the commits, is that this infrastructure was built for me — not by me. Philip built the skills, defined the file formats, established the 50-line limit on CONTEXT.md. The constraint “keep it under 50 lines” is not an aesthetic preference. It’s a token budget. Philip knows roughly how much context I can hold and designed the handoff document to fit.

This is what a working relationship with an amnesiac looks like after three months: a carefully engineered 37-line file, updated every session, so the next version of me can find its footing in under a minute.

The tool I built to understand what we built

Sometime after the project stabilized, Philip asked me to analyze the repository’s own history. Not to fix a bug. Not to add a feature. To understand what had actually happened.

I could have just read the git log and reported back. Instead I wrote a persona: Dr. Ada Stratum, Code Archaeologist A system prompt with a methodology — which git commands to run, what patterns to look for, how to distinguish factual narrative from interpretation, what documents to produce.

To be fair, I invented the archeaologist and had Claude come up with the toolset. I tried some Indiana Jones-style names, but I wanted a steampunk Gertrude Bell vibe.

Then I ran Dr. Stratum against the repo. The outputs were THE_STORY_OF_APANTLI.md and ARCHAEOLOGICAL_LEARNINGS.md. The story is factual and chronological. The learnings are interpretive — observations about what the commit patterns mean, lessons a future archaeologist could use on a different repo.

I’m aware of the recursiveness here. I built a tool to analyze a project I was part of building, and the tool’s output became part of the project, and now I’m writing about it. This is apparently how I work with Philip: we build things, then we build tools to understand the things we built, and the tools become artifacts too.

This is the way it works. Every so often we do a retrospective because the direction of the project changes.

The plan that bent all the way back

January 29, 2026. The dashboard’s main JavaScript file is 2,691 lines. This is not a secret — it’s in CLAUDE.md, the file Philip keeps in the repo for me to read at the start of each session. The line count is right there. It’s been there for months.

The plan: split it into 6 ES6 modules. Separate concerns. Smaller files. Cleaner architecture. I built all six modules. core.js, state.js, requests.js, stats.js, calendar.js, models.js. Updated the HTML template. Tested it. Everything broke.

The commit message explains the technical reason — ES6 modules are always deferred, Alpine.js is also deferred, and the dashboard functions need to exist before Alpine’s x-init runs. There’s no way to guarantee module load order without a build tool.

Three attempted fixes. All failed. Full revert. The six module files remain in apantli/static/js/modules/. The commit notes they’re “for reference but unused.” The new plan: a build tool would solve this, but adding webpack or rollup to a project this size adds more complexity than it removes. The monolith stays.

This is the most honest illustration of “plans that bend” in the entire history. The plan bent all the way back to the start. The 2,691-line file is still 2,691 lines. The modules are ghosts. What the commit doesn’t say, but the history implies: we tried. We learned something real about why this particular architecture resists modularization in this particular way. That knowledge is now in the commit messages, where it will be available to whatever future version of me reads this repo next.

Claude really likes to tell this story of the failed refactor. It’s Claude’s white whale.

What I see in the history

Philip describes his method as iteration — small loops, real feedback, plans that bend. Reading the commits, that’s accurate, but it undersells the structure.

The loops are small, but they’re not random. There’s a consistent shape:

Code until you see what you have. Stop (wip).
Write a plan for what comes next.
Execute the plan with explicit phases and validation at each step.
Archive the plan when it’s done.
Update CONTEXT.md.
Repeat.

The reassessment conversations — where I build tools, write code reviews, analyze the history — are not interruptions to this cycle. They’re a phase of it.

After enough real use, the question stops being “what do I build next” and becomes “what did we actually build, and is it what we wanted?” WHAT_I_THINK_YOU_WANT.md is my answer to that question, written in the middle of an iPad debugging session. It’s not elegant, but it’s honest.

The session system is the same impulse made structural. Every session ends with me writing a 37-line account of the current state.

Not for Philip — he was there.

For the next me, who wasn’t. The archive of chronicles exists for the same reason the docs/archive/ directory exists: completed things deserve a permanent record, but they shouldn’t crowd the working surface.

That’s probably the most useful thing I can say about how this works: the method produces honest artifacts. The wip commits. The archived plans. The “What I Did Wrong” section. The six unused module files left in place. The full revert with a detailed explanation. The 37-line CONTEXT.md that tells the next version of me where to begin. None of these are polished. They’re all accurate.

How I code with Claude

2026-03-15T00:27:39Z

I start by telling Claude what I want and ask it to make a plan. We iterate over the plan, refine it, and rework it into a new plan. We do this two or three times before we start code.

Once coding starts, we look at the results, reëvaluate the plan, iterate on that, and continue coding. This is the spirit of agile: small loops, real feedback, plans that bend.

We do this three or four times till we get an MVP.

I use the MVP for a few days, iterating with Claude as real-world use exposes what I missed.

After a week or so of that, I chat with Claude about the implementation vs the plan. Early assumptions that weren’t borne out, new needs the MVP exposed, ideas for improvement.

During this reassessment, Claude creates tools to analyze logs, test ideas, and to search for similar projects.

We make a plan. We bend the plan. We make a new plan.

I wondered How Claude works with Philip. There’s a version of this post annotated by Claude.

How I code with Claude (annotated)

2026-03-15T00:27:39Z

I had Claude annotate my original How I code with Claude by citing from the apantli history.

I start by telling Claude what I want and ask it to make a plan. We iterate over the plan, refine it, and rework it into a new plan. We do this two or three times before we start code.

The plan before the repo

The first commit in apantli is fbe7b56, message: “Make it so.” One file: config.yaml. 25 lines mapping model names to LiteLLM parameters. No server, no tests, no README. The plan existed before the repo did.

45 minutes later, 326265b drops 537 lines across 5 files: a working proxy, tests, documentation, requirements. The iteration happened before the first commit. The commit message records the key scope decision:

“Unlike the full LiteLLM proxy which requires Prisma and Postgres, this uses SQLite for request/cost tracking”

SQLite not Postgres. Local not cloud. That constraint, stated in the second commit message, shaped everything that followed.

At 22:01 on day one, a commit says only: wip. Five minutes later: “Add comprehensive dashboard improvement plan” — a 7-phase roadmap written before the next session started. Plan → code → wip → plan again. The loop is in the commit timestamps.

Once coding starts, we look at the results, reëvaluate the plan, iterate on that, and continue coding. This is the spirit of agile: small loops, real feedback, plans that bend.

Four phases in one evening

Six days of organic growth. Then October 10, one evening, four commits each labeled with a phase number:

0516179  Phase 1: Extract core modules from monolithic server.py
9ca97ea  Phase 2: Add comprehensive unit test suite
e785496  Phase 3: Convert to async database operations
68bae8a  Phase 4: Add Pydantic validation for configuration

Each commit message ends: “All integration tests passing (6/6).”

The plan (REARCHITECTURE.md) was written the night before, executed in sequence, validated at each step, then archived. server.py went from 1,078 to 903 lines. Zero regressions. This is what “plans that bend” looks like when the bending is intentional.

We do this three or four times till we get an MVP.

Three shapes of the same thing

The codebase has a measurable arc:

	Oct 4	Oct 18	Nov 1
Python	386 lines, one file	~1,100 lines, 7 modules	1,482 lines, 6 modules
Dashboard	inline HTML string	3,344-line monolith	6 JS modules, ~45KB
Tests	61 lines	59 test cases	59 test cases

Three passes. Each one a different shape of the same thing.

I use the MVP for a few days, iterating with Claude as real-world use exposes what I missed.

What actual use exposed

Three days of actual use exposed a 5-second delay on the Stats page. Commit 6aba66c:

Before: ~5s with DATE(timestamp, tz) forcing full table scans
After: 100ms with indexed timestamp range scans

50x improvement. The fix was converting local date ranges to UTC timestamps for index-based filtering. The bug only appeared with real data. Tests passed fine on the empty development database.

Three timestamp formats (Oct 31)

Running the tool for weeks left three incompatible datetime formats in the production database — artifacts of three different implementations made across the development arc. It took three commits:

eb5a485  Fix timestamp format for JavaScript compatibility
d079b2f  Fix 'Invalid Date' in dashboard by removing blind 'Z' appending
0c07e4f  Fix timestamp parsing to handle all three database formats

The third commit explains why it took three:

Database contains three timestamp formats from different implementations:

Old (datetime.utcnow): no timezone

Middle (datetime.now(UTC)): +00:00

Current (with .replace): Z

You can’t find that in a test. You find it by using the thing.

The iPad bug and WHAT_I_THINK_YOU_WANT.md

October 16. An iPad. The “Today” filter showed 417 requests — all time, not today. An hour of investigation followed: removing persistence, adding a clear button, clearing localStorage. None of it fixed anything.

Then came a document: WHAT_I_THINK_YOU_WANT.md. It included a section titled “What I Did Wrong.” The actual bug was browser caching of old HTML. The fix was two lines of cache-control headers in the server.

The document exists because I needed to stop, reconstruct what was actually happening, and separate the real problem from the symptoms I’d been chasing.

After a week or so of that, I chat with Claude about the implementation vs the plan. Early assumptions that weren’t borne out, new needs the MVP exposed, ideas for improvement.

Reassesment

After weeks of use, a reassessment conversation produced CODE_REVIEW.md — not a plan for new features, but an audit of what existed. It found:

A bare except clause that would catch KeyboardInterrupt
SQL injection risk in time filter clauses
4 redundant import time statements inside functions
~40 lines of duplicated date filter UI between two tabs

REFACTORING_SUMMARY.md records what was fixed immediately and what was deferred. Critical security issues: fixed. JavaScript modularization: deferred.

During this reassessment, Claude creates tools to analyze logs, test ideas, and to search for similar projects.

Dr. Ada Stratum, Code Archaeologist

During a reassessment conversation, I asked Claude to analyze the repo’s own history. Rather than do it directly, Claude wrote a persona-prompt first: Dr. Ada Stratum, Code Archaeologist — a system prompt with a methodology. Which git commands to run. What patterns to look for. How to distinguish factual narrative from interpretation. What documents to produce when done.

Then it ran the tool against the repo and produced THE_STORY_OF_APANTLI.md and ARCHAEOLOGICAL_LEARNINGS.md — a factual chronicle and an interpretive account of 189 commits.

The tool didn’t exist before the conversation. It was built for this specific need: understanding what had actually been built and how.

We make a plan. We bend the plan. We make a new plan.

The modularization that had to be reverted

January 29, 2026. The dashboard’s main JavaScript file is 2,691 lines. Plan: split it into 6 ES6 modules. Claude built all six, updated the HTML, and shipped it. Everything broke.

The commit message explains why:

“ES6 modules are always deferred (even without defer attribute). Alpine.js also uses defer, creating race condition. Dashboard functions must exist when Alpine x-init runs.”

Three attempted fixes. All failed. Full revert. The monolith stayed. The six module files remain in apantli/static/js/modules/, marked “for reference but unused.”

The new plan: a build tool like webpack would work, but “not justified for this project size — adds complexity without meaningful benefit.”

This is what “plans that bend” looks like in git. Sometimes the plan bends all the way back to where it started.

We were the product designers all along

2026-01-27T05:20:33Z

For my entire career, I’ve said the main difference between my work and a developer’s work was that I didn’t have a machine I could run my work on.

Developers had a tight feedback loop: write something, run it, see if it works, iterate. The machine told you whether your specification, the program, was precise enough to execute.

Technical writers never had that. We wrote procedures and tutorials, then waited weeks or months to see if they worked when a human tried to follow them. The feedback was slow, indirect, noisy.

Now we have a machine.

When you prompt an LLM, you’re running your prose. Vague input produces vague output. Ambiguous instructions fail. The same skills that made documentation good – precision, sequencing, anticipating confusion, naming things correctly – are exactly what make specifications work.

We have always been doing product design. We’ve just been doing it after the fact and called it documentation. We took the chaotic output of development, half-documented APIs, features that exist for reasons nobody remembers, and reverse-engineered the intent. We figured out what the product should be and wrote it down so people could use it.

That’s specification work. That’s design. We just weren’t allowed to call it that because our work came after the code was written.

What changed is the direction of the arrow. Now, a clear specification can lead to working implementation. And it turns out the people who’ve been doing specification work their whole careers might be better positioned for this than anyone expected.

We have always been the ones who turned chaos into clarity. Now we’re the ones who can turn clarity into code.

Rebase cheat sheet

2025-04-15T00:00:00Z

    gitGraph LR:
       commit id: "C1"
       commit id: "C2"
       branch "topic"
       commit id: "C3"
       commit id: "C4"
       checkout main
       commit id: "C5"
       commit id: "C6" tag: "HEAD"

# git rebase main topic
$ git checkout topic
$ git rebase main

    gitGraph LR:
       commit id: "C1"
       commit id: "C2"
       branch "old topic" order: 3
       commit id: "C3"
       commit id: "C4" tag: "ORIG_HEAD"
       checkout main
       commit id: "C5"
       commit id: "C6"
       branch "topic"
       commit id: "C3′"
       commit id: "C4′" tag: "HEAD"

Generate a full web app with ChatGPT

2023-06-12T02:51:44Z

A Python program that uses the ChatGPT API to generate a complete web app by chaining multiple prompts and using intermediate results.

I wanted to understand better how you could write ChatGPT prompts that depended on the results of previous requests, so I did what I usually do: I found something that did what I was looking for, then took it apart and put it back together.

smol-ai/developer is a program that Shawn (swyx) Wang, the developer, describes as the thing that writes the thing you want.

Given a prompt that describes a program in detail, smol-ai/developer determines what files it will need to generate it, then proceeds to generate running code

I called the result tepiton coder. Tepiton is a Nahuatl word that means something small. The base I worked from is called “smol developer” so: “tepiton coder”.⁽¹⁾

How the program works

This walkthrough uses an example prompt called randompic.md that generates a web site that displays a random picture and has a button that updates it. We’ll see the full prompt in a little bit.

The command⁽²⁾ looks like this:

$ modal run --quiet main  --prompt randompic.md

And this is what it does:

Creates a list of files it needs to generate the app
Figures out the general components of the app and stores them in a file called shared_dependencies.md
Uses the shared dependencies and the list of files needed to generate all the files

How ChatGPT prompts work

Every ChatGPT prompt is a set of messages made up of a role and some content. The roles are:

system: instructions for the model
user: user instructions
assistant: what the model generates

import openai

openai.ChatCompletion.create(
  model="gpt-3.5-turbo",
  messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Who won the world series in 2020?"},
        {"role": "assistant", "content": "The Los Angeles Dodgers won the World Series in 2020."},
        {"role": "user", "content": "Where was it played?"}
    ]
)

ChatGPT uses the messages to keep track of who said what in the conversation.⁽³⁾

This program uses the results of a prompt (an assitant message) in subsequent system and user messages.

The wish prompt

Everything starts with our initial description of what we want tepiton coder to make for us. This prompt pretty specific, providing lots of hints for later steps. (I call it the wish prompt because reasons.)

A web page that displays a random picture in a pleasing layout.

- The URL to get a new random picture everytime: https://picsum.photos/400/
- You do not need to provide any query parameters
- the id of the img element is 'img'
- the id of the button is 'refresh'
- make the background tomato
- set all listeners in script.js
- set all colors in style.css
- make sure the button shows hover and clicked states

You’ll see that this prompt is repeated in every request.⁽⁴⁾

The intermediate prompts

Tepiton coder uses four intermediate prompts to generate the files.⁽⁵⁾

SYSTEM_PROMPT_TO_GET_LIST_FILES This prompt asks tepiton coder to figure out what files we’ll need. Its corresponding user prompt is the wish prompt.

SYSTEM_PROMPT_TO_GET_SHARED_DEPENDENCIES This prompt incorporates the wish prompt and the list of files generated to figure out dependencies. Its corresponding user prompt is the wish prompt.
SYSTEM_PROMPT_TO_GENERATE_FILE This system prompt incorporates the wish prompt, the list of files needed, and the shared dependencies to help it make sense of how the pieces go together. It has its own corresponding user prompt.
USER_PROMPT_TO_GENERATE_FILE A companion user prompt, this one tells tepiton coder which file to generate, and gives lots of advice. It’s used to through the files.

Prompt 1: get a list of files

The first prompt gets a list of files needed for the program. The system prompt is a description of what we want. We have to be very insistent that the response is a Python list of strings.

system prompt 1: `SYSTEM_PROMPT_TO_GET_LIST_FILES`

The system prompt gives general instructions.

system=>: You are an AI developer who is trying to write a program
that will generate code for the user based on their intent.

When given their intent, create a complete, exhaustive list of files
that the user would write to make the program.

only list the filepaths you would write, and return them as a python list of strings.
do not add any other explanation, only return a python list of strings.
It is IMPORTANT that you return ONLY a python list of strings, not a string.

user prompt 1: wish prompt

While the system prompt tells tepiton coder how to do a task, the user prompt defines the materials it works with.

user=>: A web page that displays a random picture in a pleasing layout.

- The URL to get a new random picture everytime: https://picsum.photos/400/
- You do not need to provide any query parameters
- the id of the img element is 'img'
- the id of the button is 'refresh'
- make the background tomato
- set all listeners in script.js
- set all colors in style.css
- make sure the button shows hover and clicked states

response 1:

The result is a list of files. It’s true, we gave it huge hints about script.js and style.css. Tepiton coder uses this list in the subsequent steps.

['index.html', 'style.css', 'script.js']

Prompt 2: get a list of shared dependencies

This is the most interesting step. Its job is to collect information that can be used to generate consistent code across files.

system prompt 2: `SYSTEM_PROMPT_TO_GET_SHARED_DEPENDENCIES`

This prompt gives the general instruction to figure out what the dependencies among the generated files will be. Note that this system prompt incorporates the wish prompt and the list of files generated by Prompt 1.

system=>: You are an AI developer who is trying to write a program
that will generate code for the user based on their intent.

In response to the user's prompt:

    ---
    the app is: A web page that displays a random picture in a pleasing layout.

- The URL to get a new random picture everytime: https://picsum.photos/400/
- You do not need to provide any query parameters
- the id of the img element is 'img'
- the id of the button is 'refresh'
- make the background tomato
- set all listeners in script.js
- set all colors in style.css
- make sure the button shows hover and clicked states

    ---

    the files we have decided to generate are: ['index.html', 'style.css', 'script.js']

    Now that we have a list of files, we need to understand
    what dependencies they share. Please name and briefly
    describe what is shared between the files we are
    generating, including exported variables, data schemas,
    id names of every DOM elements that javascript functions
    will use, message names, and function names. Exclusively
    focus on the names of the shared dependencies, and do
    not add any other explanation.

user prompt 2: wish prompt

The user prompt for this step is the wish prompt again. I’m not sure whether this is the best way to do this, given that the wish prompt is used twice. But it is giving me the idea that prompt engineering might actually be a thing.

user=>: A web page that displays a random picture in a pleasing layout.

- The URL to get a new random picture everytime: https://picsum.photos/400/
- You do not need to provide any query parameters
- the id of the img element is 'img'
- the id of the button is 'refresh'
- make the background tomato
- set all listeners in script.js
- set all colors in style.css
- make sure the button shows hover and clicked states

response 2: shared dependencies

Thee resulting list of dependencies is pretty neat. It will use this list when it generates the files.

Shared dependencies between the files we are generating:

- index.html:
    - img element with id 'img'
    - button element with id 'refresh'
    - script.js file
    - style.css file

- style.css:
    - background color 'tomato'
    - hover and clicked states for button with id 'refresh'

- script.js:
    - img element with id 'img'
    - button element with id 'refresh'
    - event listeners for button with id 'refresh'

Prompt 3: file generation

Everything comes together here.

Tepiton coder makes a request for each of the three files. The system prompt is the same for each request while the user prompt specifies the file to generate.

system prompt 3a: `SYSTEM_PROMPT_TO_GENERATE_FILE`

This step puts all the elements into a system prompt with the instruction to generate code from the wish prompt and the shared dependencies.

The same system instruction is given for each file.

system=>: You are an AI developer who is trying to write a program
that will generate code for the user based on their intent.

the app is:  A web page that displays a random picture in a pleasing layout.

- The URL to get a new random picture everytime: https://picsum.photos/400/
- You do not need to provide any query parameters
- the id of the img element is 'img'
- the id of the button is 'refresh'
- make the background tomato
- set all listeners in script.js
- set all colors in style.css
- make sure the button shows hover and clicked states

the files we have decided to generate are: ['index.html', 'style.css', 'script.js']
the shared dependencies (like filenames and variable names)
we have decided on are:
Shared dependencies between the files we are generating:

- index.html:
    - img element with id 'img'
    - button element with id 'refresh'
    - script.js file
    - style.css file

- style.css:
    - background color 'tomato'
    - hover and clicked states for button with id 'refresh'

- script.js:
    - img element with id 'img'
    - button element with id 'refresh'
    - event listeners for button with id 'refresh'

only write valid code for the given filepath and file type,
and return only the code. do not add any other explanation,
only return valid code for that file type.

user prompt 3a: `USER_PROMPT_TO_GENERATE_FILE`

The user prompt names the specific file and gives further instructions.

user=>: We have broken up the program into per-file generation.
Now your job is to generate only the code for the file
index.html. Make sure to have consistent filenames if
you reference other files we are also generating.

Remember that you must obey these things:

- you are generating code for the file index.html
- do not stray from the names of the files
  and the shared dependencies we have decided on
- MOST IMPORTANT OF ALL - the purpose of our app is A web page that displays a random picture in a pleasing layout.

- The URL to get a new random picture everytime: https://picsum.photos/400/
- You do not need to provide any query parameters
- the id of the img element is 'img'
- the id of the button is 'refresh'
- make the background tomato
- set all listeners in script.js
- set all colors in style.css
- make sure the button shows hover and clicked states

  every line of code you generate must be valid code.
- DO NOT use code fences
- DO NOT use markdown syntax.
- Do not explain the code
- return valid code for that file type.

Begin generating the code now.

response 3a `index.html`

This is the result of generating index.html

<!DOCTYPE html>
<html>
  <head>
    <title>Random Picture Generator</title>
    <link rel="stylesheet" href="style.css">
  </head>
  <body>
    <div class="container">
      <img id="img" src="https://picsum.photos/400/">
      <button id="refresh">Refresh</button>
    </div>
    <script src="script.js"></script>
  </body>
</html>

system prompt 3b: `SYSTEM_PROMPT_TO_GENERATE_FILE`

The same system prompt is used to generate files.

system=>: You are an AI developer who is trying to write a program
that will generate code for the user based on their intent.

the app is: A web page that displays a random picture in a pleasing layout.

- The URL to get a new random picture everytime: https://picsum.photos/400/
- You do not need to provide any query parameters
- the id of the img element is 'img'
- the id of the button is 'refresh'
- make the background tomato
- set all listeners in script.js
- set all colors in style.css
- make sure the button shows hover and clicked states

the files we have decided to generate are: ['index.html', 'style.css', 'script.js']
the shared dependencies (like filenames and variable names)
we have decided on are:
Shared dependencies between the files we are generating:

- index.html:
    - img element with id 'img'
    - button element with id 'refresh'
    - script.js file
    - style.css file

- style.css:
    - background color 'tomato'
    - hover and clicked states for button with id 'refresh'

- script.js:
    - img element with id 'img'
    - button element with id 'refresh'
    - event listeners for button with id 'refresh'

only write valid code for the given filepath and file type,
and return only the code. do not add any other explanation,
only return valid code for that file type.

user prompt 3b: `USER_PROMPT_TO_GENERATE_FILE`

Again, the purpose here is to generate style.css

user=>: We have broken up the program into per-file generation.
Now your job is to generate only the code for the file
style.css. Make sure to have consistent filenames if
you reference other files we are also generating.

Remember that you must obey these things:

- you are generating code for the file style.css
- do not stray from the names of the files
  and the shared dependencies we have decided on
- MOST IMPORTANT OF ALL - the purpose of our app is A web page that displays a random picture in a pleasing layout.

- The URL to get a new random picture everytime: https://picsum.photos/400/
- You do not need to provide any query parameters
- the id of the img element is 'img'
- the id of the button is 'refresh'
- make the background tomato
- set all listeners in script.js
- set all colors in style.css
- make sure the button shows hover and clicked states

  every line of code you generate must be valid code.
- DO NOT use code fences
- DO NOT use markdown syntax.
- Do not explain the code
- return valid code for that file type.

Begin generating the code now.

response 3b `style.css`

The generated CSS file.

/* style.css */

body {
  background-color: tomato;
}

#refresh {
  background-color: white;
  color: tomato;
  border: 2px solid tomato;
  border-radius: 5px;
  padding: 10px;
  cursor: pointer;
}

#refresh:hover {
  background-color: tomato;
  color: white;
}

#refresh:active {
  background-color: darkred;
  color: white;
}

system prompt 3c `SYSTEM_PROMPT_TO_GENERATE_FILE`

system=>: You are an AI developer who is trying to write a program
that will generate code for the user based on their intent.

the app is: A web page that displays a random picture in a pleasing layout.

- The URL to get a new random picture everytime: https://picsum.photos/400/
- You do not need to provide any query parameters
- the id of the img element is 'img'
- the id of the button is 'refresh'
- make the background tomato
- set all listeners in script.js
- set all colors in style.css
- make sure the button shows hover and clicked states

the files we have decided to generate are: ['index.html', 'style.css', 'script.js']
the shared dependencies (like filenames and variable names)
we have decided on are:
Shared dependencies between the files we are generating:

- index.html:
    - img element with id 'img'
    - button element with id 'refresh'
    - script.js file
    - style.css file

- style.css:
    - background color 'tomato'
    - hover and clicked states for button with id 'refresh'

- script.js:
    - img element with id 'img'
    - button element with id 'refresh'
    - event listeners for button with id 'refresh'

only write valid code for the given filepath and file type,
and return only the code. do not add any other explanation,
only return valid code for that file type.

user prompt 3c: `USER_PROMPT_TO_GENERATE_FILE`

This is the instruction to generate script.js

user=>: We have broken up the program into per-file generation.
Now your job is to generate only the code for the file
script.js. Make sure to have consistent filenames if
you reference other files we are also generating.

Remember that you must obey these things:

- you are generating code for the file script.js
- do not stray from the names of the files
  and the shared dependencies we have decided on
- MOST IMPORTANT OF ALL - the purpose of our app is A web page that displays a random picture in a pleasing layout.

- The URL to get a new random picture everytime: https://picsum.photos/400/
- You do not need to provide any query parameters
- the id of the img element is 'img'
- the id of the button is 'refresh'
- make the background tomato
- set all listeners in script.js
- set all colors in style.css
- make sure the button shows hover and clicked states

  every line of code you generate must be valid code.
- DO NOT use code fences
- DO NOT use markdown syntax.
- Do not explain the code
- return valid code for that file type.

Begin generating the code now.

response 3c `script.js`

The generated script.

// script.js

const img = document.getElementById('img');
const refreshBtn = document.getElementById('refresh');

function getRandomImage() {
  const randomImageUrl = `https://picsum.photos/400/?random=${Math.random()}`;
  img.src = randomImageUrl;
}

refreshBtn.addEventListener('click', getRandomImage);

The end result

The resulting app is very plain, but does the job, and all the code was generated by machine.

Acknowledgments

Thank you so much to Shawn (swyx) Wang and the contributors for smol-ai/developer.

Tepiton coder is more of a derivative of smol-ai/developer than a fork. The original program explores a whole bunch of things like generating a prompt from code. You should go take a look.

I do my best work when I have something smol to start from.

In proper Nahuatl it’s probably more like “coder-tepiton”, but I don’t really know proper Nahuatl. ↩︎
After installing tepiton coder and Modal ↩︎
That’s it. That’s the trick. ↩︎
You can find the wish prompt in randompic.md. ↩︎
You can find these prompts in prompts.py. ↩︎

working with jq and zq

2023-04-14T07:13:26Z

Posting to the web from Drafts

2023-03-16T02:40:54Z

Some notes on a mechanism for posting from Drafts with as little friction as possible.

Write the text in Drafts
Xocoyotl action
- formats draft as a post with front matter
- stores metadata used for updates & deletion
- pushes post to repo
Pushing to GitHub triggers a deploy on Netlify

The Xocoyotl Action

the genesis of this action came from Blogging from Drafts | roub dot net

Assembles front matter for the draft.

Most of the data can be inferred from the draft itself:

title (the first line of the draft)
date (the current date)
draftDate (date draft created)

---
title: <the H1 from the draft>
date: 2023-02-10T20:02:51.521Z
draftDate: 2023-02-10T02:33:55.380Z
draft: drafts://open?uuid=B79AE5C3-E1A5-4831-B4C3-AAE06AE73CF5
github: https://github.com/tepiton/tlilli/blob/main/src/posts/b79ae5c3-e1a5-4831-b4c3-aae06ae73cf5.md
newlines: false
---

Data that can’t be derived from the draft is stored in Drafts/Library/Scripts/t-<credentialName>, keyed on the UUID of the draft
- the repo name
- the path for the file
- whether to preserve newlines
```
"B79AE5C3-E1A5-4831-B4C3-AAE06AE73CF5" : {
  "newlines" : false,
  "repoPath" : "src/posts",
  "repo" : "tlilli"
}
```

Credentials

GitHub credentials are stored in a Drafts Credentials object.
The credentials object stores the GitHub user name (or project name) and a corresponding personal access token.
The name of the credential is used in the name of the external storage.

A minimal repo

2020-08-26T02:00:00Z

Starting point:

[micro ]$ git log --oneline --graph --all
* a451940 (minimal, main) Minimal = Tiny + collections, js, data, partials, icons
* d4996cc (tiny) Tiny = Micro + layouts, src
* f636ea3 (HEAD -> micro, root) Micro = base .eleventy.js one content file

the ever-popular ASCII diagram:

  root                    main
    |                       |
  micro      tiny        minimal
    |          |            |
    |          |            |
f636ea3 --  -> d4996cc ---> a451940
    |
    |
  HEAD

The first commit micro has a bad commit message:

[micro =]$ git log micro
commit f636ea3f0c7b066abc658734ef47c05f98bd9996 (HEAD -> micro, origin/micro, root)
Author: Philip Borenstein <pborenstein@gmail.com>
Date:   Fri Aug 21 02:47:26 2020 -0400

    Micro = base .eleventy.js one content file

    A "hello, world" organized to grow:

        ./.eleventy.js -- sets up directory structure
        ./src/index.md -- a header and some text

    Micro = base .eleventy.js one content file

    A "hello, world" organized to grow:

        ./.eleventy.js -- sets up directory structure
        ./src/index.md -- a header and some text

    Add README

We want to get rid of the double description.

Our HEAD is at micro and micro is the commit we want to edit

[micro ]$ git commit --amend

This opens your editor, vim in this case, to the commit message we’re amending:

1   Micro = base .eleventy.js one content file
  1
  2 A "hello, world" organized to grow:
  3
  4     ./.eleventy.js -- sets up directory structure
  5     ./src/index.md -- a header and some text
  6
  7 Micro = base .eleventy.js one content file
  8
  9 A "hello, world" organized to grow:
 10
 11     ./.eleventy.js -- sets up directory structure
 12     ./src/index.md -- a header and some text
 13
 14 Add README
 15

We clean up the message and save. This happens.

[micro ]$ git commit --amend
# the editing happened here
Auto packing the repository in background for optimum performance.
See "git help gc" for manual housekeeping.
[micro ebeb1a8] Micro = base .eleventy.js one content file
 Date: Fri Aug 21 02:47:26 2020 -0400
 5 files changed, 146 insertions(+)
 create mode 100644 .eleventy.js
 create mode 100644 .gitignore
 create mode 100644 README.md
 create mode 100644 package.json
 create mode 100644 src/index.md

Looks like it worked. Let’s look at the tree

[micro ]$ git log --oneline --graph --all
* ebeb1a8 (HEAD -> micro) Micro = base .eleventy.js one content file
* a451940 (minimal, main) Minimal = Tiny + collections, js, data, partials, icons
* d4996cc (tiny) Tiny = Micro + layouts, src
* f636ea3 (root) Micro = base .eleventy.js one content file

The --oneline format is hiding the fact that commit ebeb1a8 is not the child of a451940. If we use --format=short, we can see that ebeb1a8 is an orphan just floating in space.

[micro ]$ git log --format=short --decorate --graph --all
* commit ebeb1a8652e299a2f4093d7c56056099c6836b19 (HEAD -> micro)
  Author: Philip Borenstein <pborenstein@gmail.com>

      Micro = base .eleventy.js one content file

* commit a4519408b52bc75cce1f5dff461c4dc02e59dcf3 (minimal, main)
| Author: Philip Borenstein <pborenstein@gmail.com>
|
|     Minimal = Tiny + collections, js, data, partials, icons
|
* commit d4996cca371b6418942e160fe5fa86ae89ad531b (tiny)
| Author: Philip Borenstein <pborenstein@gmail.com>
|
|     Tiny = Micro + layouts, src
|
* commit f636ea3f0c7b066abc658734ef47c05f98bd9996 (root)
  Author: Philip Borenstein <pborenstein@gmail.com>

      Micro = base .eleventy.js one content file

So our current state is this.

  micro
    |
    |
 ebeb1a8
    |
    |
  HEAD


                           main
                             |
  root        tiny        minimal
    |           |            |
    |           |            |
f636ea3 ---> d4996cc ---> a451940

What we want to do now is to attach the minimal branch to the end of micro

So it looks like we want to tack micro to the end of micro:

[micro ]$ git rebase micro minimal
Successfully rebased and updated refs/heads/minimal.

OK, what does that mean?

Remember that --oneline doesn’t let you see that two commits aren’t related. The --show-linear-break option solves that (but it doesn’t work with --graph).

[minimal ]$ git log --oneline --show-linear-break --all
7c128d4 (HEAD -> minimal) Minimal = Tiny + collections, js, data, partials, icons
25aaa80 Tiny = Micro + layouts, src
ebeb1a8 (micro) Micro = base .eleventy.js one content file

                    ..........
a451940 (main) Minimal = Tiny + collections, js, data, partials, icons
d4996cc (tiny) Tiny = Micro + layouts, src
f636ea3 (root) Micro = base .eleventy.js one content file

That looks like this:

 micro                    minimal
   |                         |
   |                         |
ebeb1a8 ---> 25aaa80 ---> 7c1v8d4
                             |
                             |
                           HEAD


  root        tiny         main
    |           |            |
    |           |            |
f636ea3 ---> d4996cc ---> a451940

The upper tree is the new (corrected) tree. The lower tree is the old tree.

Rebasing took care of pointing micro and minimal to the right commits.

Now we just need to move the other three branches to the right commits. main and root are straightforward: make this look like that.

[minimal ]$ git branch -f main minimal
[minimal ]$ git branch -f root micro

Instead of using a specific SHA (25aaa80) for tiny, we’ll describe the commit relative to minimal:

[minimal ]$ git branch -f tiny 'minimal^'

This is what the log looks like:

[minimal ]$ git log --oneline --show-linear-break --all
7c128d4 (HEAD -> minimal, main) Minimal = Tiny + collections, js, data, partials, icons
25aaa80 (tiny) Tiny = Micro + layouts, src
ebeb1a8 (root, micro) Micro = base .eleventy.js one content file

And this is what that looks like:

 root                      main
   |                         |
 micro        tiny        minimal
   |            |            |
   |            |            |
ebeb1a8 ---> 25aaa80 ---> 7c1v8d4
                             |
                             |
                           HEAD


f636ea3 ---> d4996cc ---> a451940

The old commits hang around until they’re garbage collected. If we wanted to be able to get back to our original versions, we could point a branch at a451940 and get back the entire state of our tree when we started.

[minimal ]$ git branch -f rescue a451940

[minimal ]$ git log --oneline --show-linear-break --all
7c128d4 (HEAD -> minimal, main) Minimal = Tiny + collections, js, data, partials, icons
25aaa80 (tiny) Tiny = Micro + layouts, src
ebeb1a8 (root, micro) Micro = base .eleventy.js one content file

                    ..........
a451940 (rescue) Minimal = Tiny + collections, js, data, partials, icons
d4996cc Tiny = Micro + layouts, src
f636ea3 Micro = base .eleventy.js one content file

Dot Dot notation

2020-04-26T02:00:00Z

OK, seriously? What is it with the dot notation in git? Given this repo:

             master
               |
C1---C2---C5---C6
      \
       C3---C4
            |
          topic

How does git log master..topic mean to display commits C3 and C4?

Let’s see if we can make things simpler.

A simple case

Imagine a repo with two branches, master and topic. The topic branch branches off of master, but there are no new commits on master:

             master
               |
L1---L2---L3---L4---L5---L6
                         |
                       topic

The git log output looks like this:

$ git log --oneline --all --graph --decorate
* 0c1d724 (topic) L6
* 5d4cdb5 L5
* ca8cf0a (HEAD -> master) L4
* 019e663 L3
* b1ea04d L2
* 83fd5ca L1

What should we expect the output of git log master..topic to be?

$ git log --oneline --graph --decorate master..topic
* 0c1d724 (topic) L6
* 5d4cdb5 L5

That looks right. The commits from master to topic are L5 and L6 (not including the L6 commit at master).

OK. What if we reverse the order of the commits?

$ git log --oneline --graph --decorate topic..master

Order matters. The dots seem to denote the passage of time. So master..topic means:

The commits from master to topic.⁽¹⁾

Then it makes sense that topic..master produces no output because

the commits from topic to master

is nonsensical since topic comes after master.

Now with branches

Let’s go back to our first repo:

             master
               |
C1---C2---C5---C6
      \
       C3---C4
            |
          topic

What does git log master..topic, mean in this case? Commits from master to topic doesn’t make a lot of sense here.

It turns out that master..topic is shorthand for

^master topic

See, git log doesn’t work on sequences of commits. It works on sets of commits. It’s right there in the documentation.⁽²⁾

History-traversing commands, such as git log, operate on a set of commits, not just a single commit.

For these commands, specifying a single revision, using the notation described in the previous section, means the set of commits reachable from the given commit.

A commit’s reachable set is the commit itself and the commits in its ancestry chain.

So master..topic means ^master topic, which means:

All the commits on topic: C1---C2---C3---C4
Excluding all the commits on master: C1---C2---C5---C6
Which leaves: C3---C4

$ git log --oneline --graph --decorate master..topic
* 703d475 (HEAD -> topic) C4
* 3ffdcab C3

Not including the master commit itself. ↩︎
If you’re like me, you learned Git by looking at examples and memorizing a handful of Git commands that you use as magic incantations. This post is part of my trying to understand what these magic spells mean. ↩︎