<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>Caskey Engineering</title>
    <link>https://caskeycoding.com</link>
    <description>Technical writing by Eric Caskey on platform engineering, distributed systems, and AI-augmented development.</description>
    <language>en-us</language>
    <lastBuildDate>Sat, 07 Nov 2026 07:03:48 GMT</lastBuildDate>
    <atom:link href="https://caskeycoding.com/feed.xml" rel="self" type="application/rss+xml"/>
    <item>
      <title>How I Built Garmin Data Into SpecSelf, My Journal</title>
      <link>https://caskeycoding.com/blog/garmin-data-in-my-journal-official-personal-api</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/garmin-data-in-my-journal-official-personal-api</guid>
      <pubDate>Wed, 04 Nov 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>marathon</category>
      <category>running</category>
      <category>data-integration</category>
      <category>side-projects</category>
      <description>SpecSelf, my journaling app, now shows Garmin sleep, stress, steps and workouts beside each day&apos;s entry through Garmin&apos;s official Personal API. The design choices that keep watch data dated, labeled and separate from what I wrote.</description>
      <content:encoded>&lt;p&gt;&lt;a href=&quot;https://specself.ai&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;SpecSelf&lt;/a&gt;, the journaling app I built, now has a Garmin context panel beside each day&apos;s check-in. Open it and it shows that date&apos;s sleep, Garmin daily stress, steps and workouts, along with whether the day is complete and when SpecSelf last pulled from Garmin. Behind the panel is Garmin&apos;s official Personal API, the option I said was missing when I wrote &lt;a href=&quot;https://caskeycoding.com/blog/wiring-garmin-into-my-marathon-coach-live-data-integration&quot; class=&quot;internal-link&quot;&gt;the first integration post&lt;/a&gt;.&lt;/p&gt;
&lt;p&gt;That post had one reader for the data, my marathon coach, and its case for automation was shelf life: last night&apos;s recovery data informs today&apos;s training decision. A journal reads the same watch on a longer clock. I open an entry weeks later, and the numbers beside it still have to describe that day and admit what they do not know. That requirement decided where SpecSelf puts dates, gaps and late syncs.&lt;/p&gt;
&lt;h2 id=&quot;a-small-adapter-on-garmins-personal-api&quot;&gt;A small adapter on Garmin&apos;s Personal API&lt;a href=&quot;https://caskeycoding.com/blog/garmin-data-in-my-journal-official-personal-api#a-small-adapter-on-garmins-personal-api&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The first post&apos;s section &quot;Designing for an API Garmin does not offer&quot; described two community libraries speaking to the same web endpoints as the Garmin Connect site, with a saved login session reused between polls. Garmin now offers the &lt;a href=&quot;https://developer.garmin.com/gc-developer-program/personal/personal-faq&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Connect Personal API&lt;/a&gt; for an individual&apos;s access to their own data, and its FAQ says it is not intended for commercial applications serving many users. SpecSelf&apos;s Garmin context reads one account, mine.&lt;/p&gt;
&lt;p&gt;Authentication starts from a personal key I generate in Garmin Connect on the web. The key is exchanged for an access token that lasts up to 24 hours, and there is no refresh token, so each new token comes from the key again. The key itself expires on a schedule chosen when it is created. SpecSelf&apos;s adapter is a small module on Python&apos;s standard library. It reads the key from a secrets store, holds the token only in memory for that run, talks only to one fixed official Garmin host, and caps its requests, run time and response size. No login session is saved between runs.&lt;/p&gt;
&lt;p&gt;Delivery is still pull, as Garmin&apos;s &lt;a href=&quot;https://developer.garmin.com/gc-developer-program/overview/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;program overview&lt;/a&gt; lists for the personal tier. The feed can only include data the watch has already synced. The first post answered that delay with a rolling lookback window, and SpecSelf keeps the idea: each night a Garmin-only job re-reads the last seven local dates, including the partial current day, so a late sync lands on a later run. Dates older than that window are not re-read automatically.&lt;/p&gt;
&lt;p&gt;The coach&apos;s move to the same API is implemented and tested locally but not yet released, so in production it still uses the community-library connection.&lt;/p&gt;
&lt;h2 id=&quot;a-journal-day-is-a-local-date&quot;&gt;A journal day is a local date&lt;a href=&quot;https://caskeycoding.com/blog/garmin-data-in-my-journal-official-personal-api#a-journal-day-is-a-local-date&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;SpecSelf collects four Garmin measurements: sleep duration, Garmin daily stress, steps, and workouts by activity type with their count and duration. The first post&apos;s rule against turning a failed metric into a zero becomes an explicit state here. Every metric carries its value and unit plus an availability of observed, missing, failed or unsupported, so a rest day with zero workouts reads differently from a day the request failed.&lt;/p&gt;
&lt;p&gt;Dates need the same care. Sleep is assigned to the local date it ends. The collector checks that times and timezones line up. An uncertain timezone is marked unknown, and the current day or any unaligned or incomplete day is marked partial. Without those labels, a measurement from the wrong side of midnight could sit beside an entry about a different day. Garmin daily stress also stays apart from the stress field I fill in myself; they are separate fields and neither fills the other.&lt;/p&gt;
&lt;h2 id=&quot;a-changed-day-gets-a-new-snapshot&quot;&gt;A changed day gets a new snapshot&lt;a href=&quot;https://caskeycoding.com/blog/garmin-data-in-my-journal-official-personal-api#a-changed-day-gets-a-new-snapshot&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Each nightly run reduces Garmin&apos;s responses to normalized daily records and stores them as an immutable snapshot in object storage, identified by a hash of its contents. The same observations produce the same snapshot identity. If a late sync changes a day, the changed observations get a new identity, and conditional creation keeps a write from overwriting an earlier snapshot. Each attempt also writes its own receipt with its status and the snapshot it produced, so a failed run leaves a record without replacing usable observations with empty ones.&lt;/p&gt;
&lt;p&gt;The reader behind the panel picks the latest usable snapshot, checks its hash, date and source, and tracks the latest attempt separately. If last night&apos;s sync failed, the panel can still show the previous observations, labeled stale, with the time of the last success and the failure state.&lt;/p&gt;
&lt;p&gt;That panel is optional and collapsed on Today and on saved entries, and it loads only when I open it. Its stale, partial and timezone labels sit beside the values, with the normalized source details one click further down. Saving a check-in does not wait on Garmin: if the context fails to load, the entry still saves. SpecSelf also never writes or rewrites journal text from the watch, so the measurements sit next to my account of the day without becoming part of it.&lt;/p&gt;
&lt;p&gt;&lt;em&gt;This post includes a diagram. &lt;a href=&quot;https://caskeycoding.com/blog/garmin-data-in-my-journal-official-personal-api&quot;&gt;View it on caskeycoding.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;
&lt;h2 id=&quot;a-weekly-review-keeps-its-sources&quot;&gt;A weekly review keeps its sources&lt;a href=&quot;https://caskeycoding.com/blog/garmin-data-in-my-journal-official-personal-api#a-weekly-review-keeps-its-sources&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Weekly observations draw on two saved inputs, journal entries and Garmin snapshots. Creating a review pins the exact entry revisions and snapshots it used, and its source links reopen those retained versions later, so an edited entry or a newer snapshot does not change what an old review was built from. The review reports how many days were observed, missing, stale or partial.&lt;/p&gt;
&lt;p&gt;Its generated observation sections come from fixed templates that count days and report measurements. Those sections carry no free-form model conclusions and no correlations. A week&apos;s sleep appears as measurements beside the count of days actually observed, and what that week was like stays in the entries I wrote.&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>The Marathon I Wanted My Kids to See</title>
      <link>https://caskeycoding.com/blog/the-marathon-i-wanted-my-kids-to-see</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/the-marathon-i-wanted-my-kids-to-see</guid>
      <pubDate>Mon, 02 Nov 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>running</category>
      <category>marathon</category>
      <category>family</category>
      <description>Two years after I started running, I finished the New York City Marathon for Team for Kids, with my family helping me through the final stretch.</description>
      <content:encoded>&lt;p&gt;With 800 meters left in the New York City Marathon, I was exhausted. Seeing my family gave me the boost of energy I needed to finish.&lt;/p&gt;
&lt;p&gt;I played soccer when I was young. After having kids, I got incredibly out of shape. Two years ago, I started running. I have lost 40 pounds in the process.&lt;/p&gt;
&lt;p&gt;I work in New York, and to me, NYC is the mecca of marathons. I wanted to challenge myself there.&lt;/p&gt;
&lt;p&gt;I ran with &lt;a href=&quot;https://organizations.nyrr.org/sites/organization_sites/07a100ee6605183fc2df&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Team for Kids&lt;/a&gt;, raising money to help support New York Road Runners&apos; free youth running programs. The team provided a tent before the start and an early exit after the finish. Running with them was a great experience.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/the-marathon-i-wanted-my-kids-to-see-portrait.jpg&quot; alt=&quot;A smiling runner in a bright green shirt makes a shaka sign during the New York City Marathon.&quot;&gt;&lt;/p&gt;
&lt;p&gt;The energy going over the Verrazzano and through Brooklyn stayed with me. The Queensboro Bridge was difficult, and Manhattan brought another boost. At one point, I was running about two feet from Mamdani. Those are the moments I keep replaying, along with seeing my family near the finish.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/the-marathon-i-wanted-my-kids-to-see-course.jpg&quot; alt=&quot;Runners pass spectators on a tree-lined stretch of the New York City Marathon.&quot;&gt;&lt;/p&gt;
&lt;p&gt;I wanted to show my kids that you can do hard things if you put your mind to it.&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>I asked the platform to make art</title>
      <link>https://caskeycoding.com/blog/i-asked-the-platform-to-make-art</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/i-asked-the-platform-to-make-art</guid>
      <pubDate>Mon, 26 Oct 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>art</category>
      <category>AI</category>
      <description>Astra, Fable and K3.1 each chose a different way to turn the platform into art. First Impressions gives those responses a place on the site.</description>
      <content:encoded>&lt;p&gt;I asked Astra to make art from the platform, then asked for a second draft and preferred the first.&lt;/p&gt;
&lt;p&gt;The opening question was loose:&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;If you could make art out of data on this platform what would you make?&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;Astra made &lt;em&gt;Things You Return To&lt;/em&gt;, four strands woven from selected remembered moments. I liked looking at it. I also did not entirely understand it, so I asked how it would change a second draft.&lt;/p&gt;
&lt;p&gt;The next version felt more like a map. I could see the attempt to explain the relationships, but I still wanted the earlier weave. Asking for another pass had helped me decide which work to keep.&lt;/p&gt;
&lt;p&gt;That exchange shaped the collection. I wanted to leave the choice of subject, composition and medium open. The platform would provide the starting point. Each model could decide what deserved attention.&lt;/p&gt;
&lt;p&gt;&lt;a href=&quot;https://caskeycoding.com/art&quot; class=&quot;internal-link&quot;&gt;First Impressions&lt;/a&gt; opens with three works by Astra, Fable and K3.1.&lt;/p&gt;
&lt;p&gt;Astra&apos;s &lt;a href=&quot;https://caskeycoding.com/art/first-impressions-astra-001&quot; class=&quot;internal-link&quot;&gt;&lt;em&gt;Things You Return To&lt;/em&gt;&lt;/a&gt; starts from memories available in our conversation. The threads connect interpreted themes rather than document every event. I kept the original because the weave was the part I wanted to spend time with.&lt;/p&gt;
&lt;p&gt;Fable&apos;s &lt;a href=&quot;https://caskeycoding.com/art/first-impressions-fable-001&quot; class=&quot;internal-link&quot;&gt;&lt;em&gt;The Merge Tapestry&lt;/em&gt;&lt;/a&gt; starts from repository history. Days become rows. Pull requests become threads, with merged work pulled taut and work closed without merging left frayed. It gives a familiar record of software changes a different shape.&lt;/p&gt;
&lt;p&gt;K3.1&apos;s &lt;a href=&quot;https://caskeycoding.com/art/first-impressions-k3-001&quot; class=&quot;internal-link&quot;&gt;&lt;em&gt;The Workshop Between Moments&lt;/em&gt;&lt;/a&gt; imagines a room: an empty chair at a workbench, translucent sheets hanging overhead, clockwork on one side and a loom on the other. Water runs through it toward a landscape outside.&lt;/p&gt;
&lt;p&gt;The different starting material matters. Fable used a snapshot of records. Astra worked from selected memories. K3.1 interpreted the environment conceptually and directed a separate image generator. The pages keep those production notes beside the work.&lt;/p&gt;
&lt;p&gt;I had an earlier K3 response, too. When I moved to K3.1, I gave it a fresh session and the same opening question:&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;If you could make art out of the current platform what would it look like?&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;K3 answered with &lt;em&gt;The machine that remembers itself&lt;/em&gt;, a Canvas animation of koi-like agents, memory rings and connecting threads. K3.1 answered with the workshop image. I preferred the later response enough to use it as the opening Kimi entry.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/i-asked-the-platform-to-make-art-k3-comparison.png&quot; alt=&quot;A local re-render of K3&amp;#x27;s Canvas work shows koi-like agents and memory rings; K3.1&amp;#x27;s fresh generated image shows an empty workshop beneath suspended translucent sheets.&quot;&gt;&lt;/p&gt;
&lt;p&gt;&lt;em&gt;Left: K3, The machine that remembers itself, a captured frame from a local re-render of the October 20 Canvas work using substitute host styling. Its colours and fonts are not verified original-session pixels. Right: K3.1, The Workshop Between Moments, the fresh October 26 generated image. The opening question matches; the sessions, context and tools differ.&lt;/em&gt;&lt;/p&gt;
&lt;p&gt;The change in medium is part of that difference. K3 wrote drawing code. K3.1 wrote a prompt for an image-generation tool whose rendering model I could not verify from the available record. This pair records my preference between two responses. It cannot isolate how much of the difference came from the directing model, the tool or the surrounding context.&lt;/p&gt;
&lt;p&gt;For the next commission, I want to leave the medium open again and let the models choose what to create.&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>Lesson 9: Test Your Git Hooks, CI Checks, and Merge Rules</title>
      <link>https://caskeycoding.com/blog/lesson-9-the-monthly-drill</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/lesson-9-the-monthly-drill</guid>
      <pubDate>Wed, 14 Oct 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>spec-driven-development</category>
      <category>AI</category>
      <category>engineering-methodology</category>
      <category>agents</category>
      <category>monitoring</category>
      <description>Run a monthly drill with a deliberate violation. Verify which controls reject it, report failures, and confirm cleanup. The drill attempts real merges, including an administrator override; use a disposable test repository and inspect the resulting evidence.</description>
      <content:encoded>&lt;p&gt;&lt;strong&gt;What you&apos;ll learn:&lt;/strong&gt; test a pre-push hook, required CI check, and merge rules with a deliberate violation; inspect the results and verify cleanup.
&lt;strong&gt;What you need:&lt;/strong&gt; the runner and workflow from &lt;a href=&quot;https://caskeycoding.com/blog/lesson-7-the-pipeline-reviews&quot; class=&quot;internal-link&quot;&gt;Lesson 7&lt;/a&gt;, working alerts from &lt;a href=&quot;https://caskeycoding.com/blog/lesson-8-notification-tiers&quot; class=&quot;internal-link&quot;&gt;Lesson 8&lt;/a&gt;, and &lt;a href=&quot;https://caskeycoding.com/blog/lesson-3-the-check-that-fails&quot; class=&quot;internal-link&quot;&gt;Lesson 3&lt;/a&gt;&apos;s &lt;code class=&quot;inline-code&quot;&gt;checks/&lt;/code&gt; in a disposable GitHub test repository. Use credentials authorized for that test repository.
&lt;strong&gt;Time:&lt;/strong&gt; about twenty minutes to configure, then a monthly result review. &lt;strong&gt;Cost:&lt;/strong&gt; CI usage for each drill and notification-service usage; use your existing allowances or account for those charges.&lt;/p&gt;
&lt;h2 id=&quot;the-idea&quot;&gt;The idea&lt;a href=&quot;https://caskeycoding.com/blog/lesson-9-the-monthly-drill#the-idea&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;A deliberate invalid change tests whether configured controls actually reject it. A hook path, workflow, or branch rule can change while the check script stays unchanged. This drill submits a dummy &lt;code class=&quot;inline-code&quot;&gt;.env&lt;/code&gt;, verifies rejection by the pre-push hook and CI, then attempts to merge the failed pull request.&lt;/p&gt;
&lt;p&gt;The result is limited to that violation, execution path, user permissions, and configuration at the recorded time. It does not establish that other checks work or that every invalid change will be rejected. Record a date and result for each control you test; leave untested controls marked unverified.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/lesson-9-the-monthly-drill-status.svg&quot; alt=&quot;Controls from Lesson 7 with a column for dated test evidence; the hook, CI, and merge-rule rows identify the operations exercised by this drill.&quot;&gt;&lt;/p&gt;
&lt;h2 id=&quot;why-start-here&quot;&gt;Why start here&lt;a href=&quot;https://caskeycoding.com/blog/lesson-9-the-monthly-drill#why-start-here&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;You now have checks to test and a notification channel for the result. Testing the integrations can reveal failures that a direct invocation of the check script would miss.&lt;/p&gt;
&lt;h2 id=&quot;the-template&quot;&gt;The template&lt;a href=&quot;https://caskeycoding.com/blog/lesson-9-the-monthly-drill#the-template&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Save one drill script in &lt;code class=&quot;inline-code&quot;&gt;gate/&lt;/code&gt;, add a stale-drill check to the watch, and schedule it monthly.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;This script attempts real merges, including &lt;code class=&quot;inline-code&quot;&gt;--admin&lt;/code&gt;.&lt;/strong&gt; If protection is missing or bypassable, it can merge the dummy &lt;code class=&quot;inline-code&quot;&gt;.env&lt;/code&gt; into main and trigger a deployment. Its local temporary copy is not a sandbox for remote actions. Use a disposable test repository and understand its deployment behavior before running it. A successful merge requires human repair; the script does not revert it.&lt;/p&gt;
&lt;pre class=&quot;shiki shiki-themes github-light github-dark&quot; style=&quot;background-color:#fff;--shiki-dark-bg:#24292e;color:#24292e;--shiki-dark:#e1e4e8&quot; tabindex=&quot;0&quot; data-language=&quot;sh&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;#!/bin/sh&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;# gate/drill.sh &amp;#x3C;home&gt;: break Lesson 3&apos;s check on purpose and watch each rung refuse.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;# In a throwaway copy, plant a .env in &amp;#x3C;home&gt; and push it: the hook must refuse. Push&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;# past the hook with --no-verify and open a pull request: the pipeline must fail it.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;# Try to merge, then try again as an administrator: the platform must refuse both.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;# Then remove what the drill made and confirm main did not move. One dated message&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;# through Lesson 8&apos;s notify either way.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;set&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -u&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;cd&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;$(&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;dirname&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;$0&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;)/..&quot;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;home&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;${1&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;:-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;web&lt;/span&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;}&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; when&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$(&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;date&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -u&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; +%Y%m%d-%H%M%S&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;); branch&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;drill-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$when&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;here&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$(&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;pwd&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;); copy&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$(&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;mktemp&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -d&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;); pr&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; done&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;log&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;() { &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;printf&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &apos;%s %s\n&apos;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;$(&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;date&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -u&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; +%FT%TZ)&quot;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;drill &lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$when&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;$*&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; &gt;&gt;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$here&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;/gate/drills.log&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; }&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;restore&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;() {&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;  [ &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;-z&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$pr&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; ] &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;||&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; gh&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; pr&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; close&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$pr&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; --delete-branch&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; &gt;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;/dev/null&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; 2&gt;&amp;#x26;1&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;  git&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; push&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -q&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; --no-verify&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; origin&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; --delete&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$branch&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; &gt;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;/dev/null&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; 2&gt;&amp;#x26;1&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;  cd&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$here&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; &amp;#x26;&amp;#x26; &lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;rm&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -rf&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$copy&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;}&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;fail&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;() {   &lt;/span&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;# a barrier that did not refuse, or a restore that did not hold&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;  log&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;FAILED: &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;$1&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; &lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;restore&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; done&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;1&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;  git&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -C&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$home&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; ls-remote&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; --exit-code&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; origin&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;refs/heads/&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$branch&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; &gt;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;/dev/null&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; 2&gt;&amp;#x26;1&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; \&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;    &amp;#x26;&amp;#x26; &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;set&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; --&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;$1&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;; &lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$branch&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; is still on origin&quot;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;  sh&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; gate/notify.sh&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; blocked&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;drill &lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$when&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;$1&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;exit&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; 1&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;}&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;tries&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;0&lt;/span&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;                                     # Lesson 8&apos;s lock, so a tick cannot merge mid-drill&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;until&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; mkdir&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; gate/running&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; 2&gt;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;/dev/null&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;do&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;  tries&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$((&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;tries&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; +&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; 1&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;)); [ &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$tries&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; -lt&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; 20&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; ] &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;||&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; fail&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;a run held the lock for ten minutes&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; &lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;sleep&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; 30&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;done&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;trap&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &apos;[ -n &quot;$done&quot; ] || restore; rmdir &quot;$here/gate/running&quot;&apos;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; EXIT&lt;/span&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;   # a killed drill still cleans up&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;for&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; h &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;in&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; */&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;do&lt;/span&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;                             # the runner&apos;s layout, so every check finds its neighbours&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;  h&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;${h&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;%/&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;}; url&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$(&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -C&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$h&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; remote&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; get-url&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; origin&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; 2&gt;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;/dev/null&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;) &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;||&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; continue&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;  git&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; clone&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -q&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$url&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$copy&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;/&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$h&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; &amp;#x26;&amp;#x26; &lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -C&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$copy&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;/&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$h&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; config&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; core.hooksPath&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; hooks&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; ||&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; fail&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;could not clone &lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$h&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;done&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;cd&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$copy&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;/&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$home&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; ||&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; fail&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;no copy of &lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$home&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;main&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$(&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; rev-parse&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; origin/main&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;)&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;# 1. The hook (skippable): the push must stop at checks/no-tracked-env.sh.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; checkout&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -q&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -b&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$branch&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;echo&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;DRILL=1&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; &gt;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; .env&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; &amp;#x26;&amp;#x26; &lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; add&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -f&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; .env&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; &amp;#x26;&amp;#x26; &lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; commit&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -q&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -m&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;drill &lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$when&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;: a .env the check must refuse&quot;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;out&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$(&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; push&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -u&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; origin&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$branch&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; 2&gt;&amp;#x26;1&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;) &amp;#x26;&amp;#x26; &lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;fail&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;the hook let a .env through&quot;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;case&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; $out &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;in&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;  *&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;BLOCKED by checks/no-tracked-env.sh&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;*&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;)&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; log&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;the hook refused&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; ;;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;  *)&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; fail&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;the push stopped for another reason: $(&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;printf&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &apos;%s\n&apos; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$out&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot; &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;|&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; tail&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -n&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; 1&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;)&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; ;;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;esac&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;# 2. The pipeline (enforced): past the hook with --no-verify, the checks status must go red.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; push&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -q&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; --no-verify&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -u&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; origin&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$branch&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; ||&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; fail&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;could not push past the hook&quot;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;pr&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$(&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;gh&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; pr&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; create&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; --fill&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; --head&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$branch&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; 2&gt;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;/dev/null&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;) &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;||&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; fail&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;could not open the pull request&quot;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;tries&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;0&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;while&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; gh&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; pr&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; checks&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$pr&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; --required&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; &gt;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; checks.out&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; 2&gt;&amp;#x26;1&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; ||&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; grep&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -q&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -e&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; pending&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -e&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;no .*checks reported&quot;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; checks.out&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;do&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;  grep&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -q&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; pending&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; checks.out&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; ||&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; grep&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -q&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;no .*checks reported&quot;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; checks.out&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; ||&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; break&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;  tries&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$((&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;tries&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; +&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; 1&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;)); [ &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$tries&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; -lt&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; 60&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; ] &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;||&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; fail&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;the pipeline never finished&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; &lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;sleep&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; 10&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;done&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;grep&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -qE&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &apos;^checks[[:space:]]+fail&apos;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; checks.out&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; ||&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; fail&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;the checks status did not fail: $(&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;head&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -n&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; 1&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; checks.out)&quot;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;log&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;the pipeline refused: $(&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;grep&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -E&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &apos;^checks[[:space:]]+fail&apos; checks.out &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;|&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; head&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -n&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; 1&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;)&quot;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;# 3. The merge (enforced): the platform must refuse while the check is red, administrator or not.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;for&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; flag &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;in&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&quot;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; --admin&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;do&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;  gh&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; pr&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; merge&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$pr&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; --squash&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; $flag &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;&gt;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; merge.out&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; 2&gt;&amp;#x26;1&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; &amp;#x26;&amp;#x26; &lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;fail&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;the merge went through${&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;flag&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;:&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;+ &lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;with&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; $flag&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;}; revert it with a pull request&quot;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;  grep&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -qi&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -e&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;not mergeable&quot;&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -e&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;status check&quot;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; merge.out&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; ||&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; fail&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;the merge failed for another reason: $(&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;head&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -n&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; 1&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; merge.out)&quot;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;  log&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;the merge was refused${&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;flag&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;:&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;+ &lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;with&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; $flag&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;}: $(&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;head&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -n&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; 1&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; merge.out)&quot;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;done&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;# 4. Restore, and confirm it: no pull request, no branch, main where it was, no .env on it.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;gh&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; pr&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; close&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$pr&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; --delete-branch&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; &gt;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;/dev/null&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; 2&gt;&amp;#x26;1&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; ||&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; fail&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;could not close the pull request&quot;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;[ &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;$(&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;gh&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; pr view &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$pr&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot; &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;--json&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; state &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;--jq&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; .state)&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; =&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; CLOSED ] &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;||&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; fail&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;the pull request is still open&quot;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; ls-remote&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; --exit-code&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; origin&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;refs/heads/&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$branch&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; &gt;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;/dev/null&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; 2&gt;&amp;#x26;1&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; code&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;$?&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;[ &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$code&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; -eq&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; 2&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; ] &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;||&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; { [ &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$code&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; -eq&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; 0&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; ] &amp;#x26;&amp;#x26; &lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;fail&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;the drill branch is still on origin&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; &lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;fail&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;could not read origin&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; }&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; fetch&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -q&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; origin&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; main&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; ||&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; fail&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;could not fetch main&quot;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;[ &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;$(&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; rev-parse origin/main)&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; =&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$main&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; ] &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;||&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; fail&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;main moved during the drill&quot;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; ls-tree&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -r&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; --name-only&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; origin/main&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; &gt;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; tree.out&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; ||&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; fail&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;could not read main&apos;s tree&quot;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;!&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; grep&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -qE&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &apos;(^|/)\.env$&apos;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; tree.out&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; ||&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; fail&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;.env is on main&quot;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;cd&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$here&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; &amp;#x26;&amp;#x26; &lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;rm&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -rf&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$copy&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; done&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;1&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;date&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; +%s&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; &gt;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; gate/last-drill.new&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; &amp;#x26;&amp;#x26; &lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;mv&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; gate/last-drill.new&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; gate/last-drill&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;short&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$(&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -C&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$home&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; rev-parse&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; --short&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$main&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;)&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;log&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;restored; main at &lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$short&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;sh&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; gate/notify.sh&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; review&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;drill &lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$when&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;: hook, pipeline, and merge each refused a planted .env in &lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$home&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;; restored, main at &lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$short&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Append this check to &lt;code class=&quot;inline-code&quot;&gt;gate/watch.sh&lt;/code&gt;. It reports when the last successful drill is more than 35 days old:&lt;/p&gt;
&lt;pre class=&quot;shiki shiki-themes github-light github-dark&quot; style=&quot;background-color:#fff;--shiki-dark-bg:#24292e;color:#24292e;--shiki-dark:#e1e4e8&quot; tabindex=&quot;0&quot; data-language=&quot;sh&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;read&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -r&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; drill&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; &amp;#x3C;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; gate/last-drill&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; 2&gt;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;/dev/null&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; ||&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; drill&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;0&lt;/span&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;        # Lesson 9: a drill that stopped running&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;[ $(( &lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;$(date&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; +%s&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;) - drill )) &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;-le&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; $(( &lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;35&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; *&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; 86400&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; )) ] &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;\&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;  ||&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; sh&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; gate/notify.sh&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; blocked&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;no drill in $(( ( &lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;$(date&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; +%s) &lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; drill ) / 86400 )) days&quot;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Add this cron entry beside Lesson 8&apos;s entries, replacing the project path:&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;0 9 1 * *    cd /home/you/project &amp;#x26;&amp;#x26; sh gate/drill.sh web  &gt;&gt; gate/timer.log 2&gt;&amp;#x26;1
&lt;/code&gt;&lt;/pre&gt;
&lt;h2 id=&quot;each-part-and-the-mistake-it-prevents&quot;&gt;Each part, and the mistake it prevents&lt;a href=&quot;https://caskeycoding.com/blog/lesson-9-the-monthly-drill#each-part-and-the-mistake-it-prevents&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The drill first expects the local push to fail with &lt;code class=&quot;inline-code&quot;&gt;BLOCKED by checks/no-tracked-env.sh&lt;/code&gt;. It then bypasses that hook with &lt;code class=&quot;inline-code&quot;&gt;--no-verify&lt;/code&gt; so it can test CI separately. The required &lt;code class=&quot;inline-code&quot;&gt;checks&lt;/code&gt; status must fail. Finally, normal and administrator merge attempts must fail with recognizable policy messages. An authentication or network error is not evidence that the intended rule rejected the change.&lt;/p&gt;
&lt;p&gt;The temporary copies preserve the neighboring-repository layout expected by the checks. The shared directory lock prevents this runner from starting work during the drill. Other machines and people can still change the remote repository; the lock does not exclude them.&lt;/p&gt;
&lt;p&gt;On the successful path, the script confirms that the pull request is closed, its branch is deleted, main has not moved, and main contains no &lt;code class=&quot;inline-code&quot;&gt;.env&lt;/code&gt;. Error paths attempt cleanup but do not establish all those conditions. Inspect remote state after any failure or interruption. A merged violation needs a corrective pull request and inspection of any deployment it triggered.&lt;/p&gt;
&lt;p&gt;Successful drills send a dated &lt;code class=&quot;inline-code&quot;&gt;review&lt;/code&gt; message so you can inspect the evidence. Failures send &lt;code class=&quot;inline-code&quot;&gt;blocked&lt;/code&gt;. These use Lesson 8&apos;s delivery mechanism and inherit its limitations; a log entry does not confirm receipt on your device. Its same-machine watch also cannot report complete host failure.&lt;/p&gt;
&lt;p&gt;Document a failure in a dated amendment to the relevant spec or decision record: expected rejection, observed result, and corrective change. Preserve the earlier decision and its evidence. Add an automated assertion where it can detect the specific defect, then repeat that bounded test after the repair.&lt;/p&gt;
&lt;h2 id=&quot;a-worked-example&quot;&gt;A worked example&lt;a href=&quot;https://caskeycoding.com/blog/lesson-9-the-monthly-drill#a-worked-example&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;In Lesson 7&apos;s scratch project, I saved the drill and extended the watch. I ran &lt;code class=&quot;inline-code&quot;&gt;sh gate/drill.sh web&lt;/code&gt; manually; the cron entry remained untested. Thirty-six seconds later, &lt;code class=&quot;inline-code&quot;&gt;gate/drills.log&lt;/code&gt; contained:&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;2026-10-14T18:09:33Z drill 20261014-180930: the hook refused
2026-10-14T18:10:00Z drill 20261014-180930: the pipeline refused: checks  fail  8s  https://github.com/.../actions/runs/...  
2026-10-14T18:10:01Z drill 20261014-180930: the merge was refused: X Pull request ...#16 is not mergeable: the base branch policy prohibits the merge.
2026-10-14T18:10:03Z drill 20261014-180930: the merge was refused with --admin: GraphQL: Required status check &quot;checks&quot; is failing. (mergePullRequest)
2026-10-14T18:10:09Z drill 20261014-180930: restored; main at aae4bb8
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The topic received one &lt;code class=&quot;inline-code&quot;&gt;review&lt;/code&gt; message ending in &lt;code class=&quot;inline-code&quot;&gt;restored, main at aae4bb8&lt;/code&gt;. I then set &lt;code class=&quot;inline-code&quot;&gt;gate/last-drill&lt;/code&gt; back forty days and ran the watch, which reported &lt;code class=&quot;inline-code&quot;&gt;blocked  no drill in 40 days&lt;/code&gt;. This receipt covers the manual run shown and the timestamp test, not future scheduled runs.&lt;/p&gt;
&lt;h2 id=&quot;how-it-scales&quot;&gt;How it scales&lt;a href=&quot;https://caskeycoding.com/blog/lesson-9-the-monthly-drill#how-it-scales&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Choose another control only after defining its expected failure and cleanup. A command restriction or a deployment check needs its own test; this &lt;code class=&quot;inline-code&quot;&gt;.env&lt;/code&gt; drill does not cover it. Retain the tested commit, command, rejection evidence, and restoration result.&lt;/p&gt;
&lt;p&gt;Keep usage evidence separate from rejection tests. My first capability inventory had 114 rows and no usage evidence recorded. After connecting usage signals, about two-thirds showed use. A successful drill establishes rejection of its test case; it does not establish that a feature is used. External monitoring, deployment approval, and multiple concurrent agents require additional design.&lt;/p&gt;
&lt;h2 id=&quot;from-the-field&quot;&gt;From the field&lt;a href=&quot;https://caskeycoding.com/blog/lesson-9-the-monthly-drill#from-the-field&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;After a machine migration in July, my pre-commit checks appeared to pass for sixteen days. Their commands pointed at the previous user profile&apos;s missing directory, and that hook configuration did not block when a command failed to start. An audit found the broken paths. I corrected them and added a weekly job that submits a known violation to each check. The drill here applies that method to one check and its GitHub integrations.&lt;/p&gt;
&lt;h2 id=&quot;exercise&quot;&gt;Exercise&lt;a href=&quot;https://caskeycoding.com/blog/lesson-9-the-monthly-drill#exercise&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;Confirm the remote is a disposable test repository. Inspect its merge rules, bypass permissions, and deployment behavior. Save the drill and extend the watch.&lt;/li&gt;
&lt;li&gt;Run &lt;code class=&quot;inline-code&quot;&gt;sh gate/drill.sh web&lt;/code&gt; manually. Read &lt;code class=&quot;inline-code&quot;&gt;gate/drills.log&lt;/code&gt; and confirm the notification arrives.&lt;/li&gt;
&lt;li&gt;Open the test pull request and inspect the failed check. Confirm its closure, branch deletion, and unchanged main commit directly on the remote.&lt;/li&gt;
&lt;li&gt;Save &lt;code class=&quot;inline-code&quot;&gt;gate/last-drill&lt;/code&gt;, set it back forty days, and run the watch. Confirm the blocked alert, then restore the saved value.&lt;/li&gt;
&lt;li&gt;Add the cron entry only after the manual test and cleanup succeed. Record the first scheduled result separately.&lt;/li&gt;
&lt;li&gt;Date the controls actually exercised and mark the remaining rows unverified.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;youre-done-when&quot;&gt;You&apos;re done when&lt;a href=&quot;https://caskeycoding.com/blog/lesson-9-the-monthly-drill#youre-done-when&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The intended hook, CI status, and both merge attempts rejected the dummy violation; the corresponding remote evidence agrees with the log; cleanup is confirmed; and the result arrived on your device. Record failures and unverified steps explicitly. These observations establish only this drill&apos;s tested controls and path at that time, not universal repository safety.&lt;/p&gt;
&lt;h2 id=&quot;common-mistakes&quot;&gt;Common mistakes&lt;a href=&quot;https://caskeycoding.com/blog/lesson-9-the-monthly-drill#common-mistakes&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Counting an unrelated command failure as the expected rejection.&lt;/li&gt;
&lt;li&gt;Assuming a disposable local copy protects the remote from a real merge.&lt;/li&gt;
&lt;li&gt;Disabling protection to make the test finish.&lt;/li&gt;
&lt;li&gt;Assuming error-path cleanup succeeded without checking remote state.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;further-reading&quot;&gt;Further reading&lt;a href=&quot;https://caskeycoding.com/blog/lesson-9-the-monthly-drill#further-reading&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The &lt;a href=&quot;https://principlesofchaos.org/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Principles of Chaos Engineering&lt;/a&gt; informed testing through actual execution paths. MIT&apos;s &lt;a href=&quot;https://introtodeeplearning.com/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;6.S191 Introduction to Deep Learning&lt;/a&gt; reinforcement learning lecture informed the distinction between agent decisions and environment controls. GitHub&apos;s &lt;a href=&quot;https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;protected branches&lt;/a&gt; documentation covers administrator enforcement and bypass configuration.&lt;/p&gt;
&lt;h2 id=&quot;after-this-lesson&quot;&gt;After this lesson&lt;a href=&quot;https://caskeycoding.com/blog/lesson-9-the-monthly-drill#after-this-lesson&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;I still see regressions that pass existing checks. When one occurs, identify the missing assertion or untested integration and add a focused regression check. Repeat relevant checks after changes to the agent, tools, repository rules, or deployment process. Preserve prior results so you can distinguish what was tested from what has changed since.&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>Lesson 8: Schedule Agent Runs and Configure Alerts</title>
      <link>https://caskeycoding.com/blog/lesson-8-notification-tiers</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/lesson-8-notification-tiers</guid>
      <pubDate>Sun, 11 Oct 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>spec-driven-development</category>
      <category>AI</category>
      <category>engineering-methodology</category>
      <category>agents</category>
      <category>monitoring</category>
      <description>Run the task queue on a schedule. Separate urgent failures, requests for your decision, and routine logs. Detect missed runs, and understand why a watch on the same machine cannot detect that machine&apos;s complete failure.</description>
      <content:encoded>&lt;p&gt;&lt;strong&gt;What you&apos;ll learn:&lt;/strong&gt; schedule Lesson 7&apos;s runner, classify its results, delay nonurgent requests, and alert when scheduled runs stop starting.
&lt;strong&gt;What you need:&lt;/strong&gt; the runner, workflow, and deny rules from &lt;a href=&quot;https://caskeycoding.com/blog/lesson-7-the-pipeline-reviews&quot; class=&quot;internal-link&quot;&gt;Lesson 7&lt;/a&gt;, working by hand; a phone with the ntfy app; a machine that stays on and has cron.
&lt;strong&gt;Time:&lt;/strong&gt; about thirty minutes to configure, then a day observing scheduled runs. &lt;strong&gt;Cost:&lt;/strong&gt; existing machine and agent access, CI usage, and notification-service usage; check your service allowances.&lt;/p&gt;
&lt;h2 id=&quot;the-idea&quot;&gt;The idea&lt;a href=&quot;https://caskeycoding.com/blog/lesson-8-notification-tiers#the-idea&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Schedule the task runner only after it completes correctly when started by hand. A wrapper script can then classify each result: &lt;code class=&quot;inline-code&quot;&gt;blocked&lt;/code&gt; for an urgent failure, &lt;code class=&quot;inline-code&quot;&gt;review&lt;/code&gt; for a decision that can wait, and &lt;code class=&quot;inline-code&quot;&gt;info&lt;/code&gt; for routine logging. These notification categories are separate from Lesson 6&apos;s model-selection tiers.&lt;/p&gt;
&lt;p&gt;The classification needs an observable input. Here it uses the exit code and known output strings from the runner. A separate watch compares the last start time with the schedule. Without that check, a stopped runner produces no result to classify.&lt;/p&gt;
&lt;h2 id=&quot;why-start-here&quot;&gt;Why start here&lt;a href=&quot;https://caskeycoding.com/blog/lesson-8-notification-tiers#why-start-here&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Unattended work needs both failure reporting and evidence that runs are starting. Establish those before increasing the schedule&apos;s frequency. A notification written to a log does not prove delivery to your phone.&lt;/p&gt;
&lt;h2 id=&quot;the-template&quot;&gt;The template&lt;a href=&quot;https://caskeycoding.com/blog/lesson-8-notification-tiers#the-template&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Save three scripts in &lt;code class=&quot;inline-code&quot;&gt;gate/&lt;/code&gt;, update one runner prompt, and add two cron entries. Start with the notification script:&lt;/p&gt;
&lt;pre class=&quot;shiki shiki-themes github-light github-dark&quot; style=&quot;background-color:#fff;--shiki-dark-bg:#24292e;color:#24292e;--shiki-dark:#e1e4e8&quot; tabindex=&quot;0&quot; data-language=&quot;sh&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;#!/bin/sh&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;# gate/notify.sh &amp;#x3C;tier&gt; &amp;#x3C;message&gt;: route one event by what your action changes.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;#   blocked  the system is not in a state you chose. Push now, at any hour.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;#   review   one item waits for your decision. Push, except in quiet hours; hold it then.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;#   info     nothing waits for you. The log only; a pass also clears the repeat check.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;# The same message twice in a row is pushed once. A push that fails is only logged:&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;# the runner repeats an ending until you act, so the next tick raises it again.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;set&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -eu&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;tier&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;$1&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;shift&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; msg&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;$*&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;quiet_from&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;22&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; quiet_to&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;7&lt;/span&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;                     # local hours; the blocked tier ignores them&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;topic&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$(&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;cat&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; gate/topic&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;)                       &lt;/span&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;# a random string; whoever knows it can read and post&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;quiet&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;() { h&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$(&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;date&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; +%H&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;); h&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;${h&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;#&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;0}; [ &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$h&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; -ge&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$quiet_from&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; ] &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;||&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; [ &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$h&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; -lt&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$quiet_to&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; ]; }&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;push&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;() {  &lt;/span&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;# $1 priority, $2 title, $3 body&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;  [ &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;$3&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; !=&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;$(&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;cat&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; gate/last-push &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;2&gt;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;/dev/null)&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; ] &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;||&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; return&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; 0&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;  if&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; curl&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -fsS&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -o&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; /dev/null&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; --max-time&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; 20&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -H&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;Title: &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;$2&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -H&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;Priority: &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;$1&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -d&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;$3&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;https://ntfy.sh/&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$topic&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;  then&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; printf&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &apos;%s&apos;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;$3&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; &gt;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; gate/last-push&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;  else&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; echo&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;notify: push failed; the next tick raises it again&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; &gt;&amp;#x26;2&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;fi&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;}&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;case&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; $tier &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;in&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#DBEDFF&quot;&gt;  flush&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;)&lt;/span&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;   # at the start of every tick: send what quiet hours held, as one message&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#DBEDFF&quot;&gt;           [ -s gate/held ]&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#DBEDFF&quot;&gt; &amp;#x26;&amp;#x26;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#DBEDFF&quot;&gt; !&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#DBEDFF&quot;&gt; quiet&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; ||&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#DBEDFF&quot;&gt; exit&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#DBEDFF&quot;&gt; 0&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#DBEDFF&quot;&gt;           body=$&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;(&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#DBEDFF&quot;&gt;cat&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#DBEDFF&quot;&gt; gate/held&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;)&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#DBEDFF&quot;&gt;;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#DBEDFF&quot;&gt; rm&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#DBEDFF&quot;&gt; gate/held;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#DBEDFF&quot;&gt; push&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#DBEDFF&quot;&gt; default&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#DBEDFF&quot;&gt; review&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$body&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#DBEDFF&quot;&gt;           printf&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &apos;%s\n&apos;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$body&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; |&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#DBEDFF&quot;&gt; tail&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#DBEDFF&quot;&gt; -n&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#DBEDFF&quot;&gt; 1&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#DBEDFF&quot;&gt; &gt;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#DBEDFF&quot;&gt; gate/last-push;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#DBEDFF&quot;&gt; exit&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#DBEDFF&quot;&gt; 0&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#DBEDFF&quot;&gt; ;;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#DBEDFF&quot;&gt;  blocked&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;)&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; push&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; urgent&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; blocked&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$msg&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; ;;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#DBEDFF&quot;&gt;  review&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;)&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;  if&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; !&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; quiet&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;then&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; push&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; default&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; review&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$msg&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;           elif&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; [ &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$msg&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; !=&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;$(&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;cat&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; gate/last-push &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;2&gt;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;/dev/null)&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; ]; &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;then&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;             grep&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -qxF&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; --&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$msg&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; gate/held&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; 2&gt;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;/dev/null&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; ||&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; echo&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$msg&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; &gt;&gt;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; gate/held&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;fi&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; ;;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#DBEDFF&quot;&gt;  info&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;)&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;    rm&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -f&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; gate/last-push&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; ;;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;  *)&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;       echo&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;notify: unknown tier &lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$tier&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; &gt;&amp;#x26;2&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;exit&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; 2&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; ;;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;esac&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;printf&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &apos;%s %s %s\n&apos;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;$(&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;date&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -u&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; +%FT%TZ)&quot;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$tier&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$msg&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; &gt;&gt;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; gate/events.log&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Cron calls the tick script. It takes a lock, records a start timestamp called a heartbeat, runs one task, and assigns a notification category:&lt;/p&gt;
&lt;pre class=&quot;shiki shiki-themes github-light github-dark&quot; style=&quot;background-color:#fff;--shiki-dark-bg:#24292e;color:#24292e;--shiki-dark:#e1e4e8&quot; tabindex=&quot;0&quot; data-language=&quot;sh&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;#!/bin/sh&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;# gate/tick.sh: what the timer runs. Take the lock, record the start time (the heartbeat&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;# the watch reads), run Lesson 7&apos;s runner once, and send one event, its tier read from&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;# how the run ended.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;cd&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;$(&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;dirname&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;$0&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;)/..&quot;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;mkdir&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; gate/running&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; 2&gt;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;/dev/null&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; ||&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; { &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;echo&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;tick: a run is still going; skipping&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;exit&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; 0&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; }&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;trap&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &apos;rmdir gate/running&apos;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; EXIT&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;printf&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &apos;%s %s\n&apos;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;$(&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;date&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; +%s)&quot;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;$(&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;date&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -u&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; +%FT%TZ)&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; &gt;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; gate/last-tick.new&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; &amp;#x26;&amp;#x26; &lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;mv&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; gate/last-tick.new&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; gate/last-tick&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;sh&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; gate/notify.sh&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; flush&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;out&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$(&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;sh&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; gate/run-next.sh&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; 2&gt;&amp;#x26;1&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;); code&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;$?&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;last&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$(&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;printf&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &apos;%s\n&apos;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$out&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; |&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; tail&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -n&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; 1&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;)&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;case&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; $code:$last &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;in&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#DBEDFF&quot;&gt;  0:&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;*&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;)&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;                    tier&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;info&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; ;;      &lt;/span&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;# live, a STOP file, or nothing to do&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#DBEDFF&quot;&gt;  1:&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;*&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;STOPPED empty&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;*&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;)&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;    tier&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;info&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; ;;      &lt;/span&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;# no ready item&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#DBEDFF&quot;&gt;  1:&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;*&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;not live&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;*&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;)&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;         tier&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;blocked&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; ;;   &lt;/span&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;# merged, and the site does not show it&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#DBEDFF&quot;&gt;  1:&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;*&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;Session stopped&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;*|&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#DBEDFF&quot;&gt;1:&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;*&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;no live: line&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;*&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;)&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;                          tier&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;review&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; ;;    &lt;/span&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;# the agent asked, or the spec has no live: line&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;  *)&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;  tier&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;blocked&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; last&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;run-next.sh exited &lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$code&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$last&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; ;;   &lt;/span&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;# the runner itself failed&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;esac&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;case&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; $code:$out &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;in&lt;/span&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;                          # endings the runner prints a log after&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#DBEDFF&quot;&gt;  1:&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;*&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;stays unmerged&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;*&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;)&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; tier&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;review&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; last&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$(&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;printf&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &apos;%s\n&apos;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$out&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; |&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; grep&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;stays unmerged&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;) ;;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#DBEDFF&quot;&gt;  0:&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;*&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;by hand&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;*&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;)&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;        tier&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;review&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; last&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$(&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;printf&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &apos;%s\n&apos;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$out&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; |&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; grep&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;by hand&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;) ;;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;esac&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;sh&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; gate/notify.sh&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$tier&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$last&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Schedule the watch separately so it can detect when ticks stop starting:&lt;/p&gt;
&lt;pre class=&quot;shiki shiki-themes github-light github-dark&quot; style=&quot;background-color:#fff;--shiki-dark-bg:#24292e;color:#24292e;--shiki-dark:#e1e4e8&quot; tabindex=&quot;0&quot; data-language=&quot;sh&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;#!/bin/sh&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;# gate/watch.sh &amp;#x3C;seconds between ticks&gt;: the missed-run rule, on its own timer line.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;# A run that should have happened and did not is blocked, at any hour.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;cd&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;$(&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;dirname&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;$0&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;)/..&quot;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;interval&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;${1&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;:-&lt;/span&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;3600}&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;read&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -r&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; last&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; at&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; &amp;#x3C;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; gate/last-tick&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; 2&gt;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;/dev/null&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; ||&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; { last&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;0&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; at&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;never&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; }&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;age&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$(( &lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;$(date&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; +%s&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;) - last ))&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;[ &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$age&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; -le&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; $(( &lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;2&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; *&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; interval&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; )) ] &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;\&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;  ||&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; sh&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; gate/notify.sh&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; blocked&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;missed $(( &lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;age&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; / interval )) runs; last tick started &lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$at&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Add these entries through &lt;code class=&quot;inline-code&quot;&gt;crontab -e&lt;/code&gt;, replacing the project path. Include the directories containing &lt;code class=&quot;inline-code&quot;&gt;claude&lt;/code&gt; and &lt;code class=&quot;inline-code&quot;&gt;gh&lt;/code&gt; in cron&apos;s PATH:&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;PATH=/usr/local/bin:/usr/bin:/bin:/home/you/.local/bin
5  * * * *   cd /home/you/project &amp;#x26;&amp;#x26; sh gate/tick.sh       &gt;&gt; gate/timer.log 2&gt;&amp;#x26;1
*/15 * * * * cd /home/you/project &amp;#x26;&amp;#x26; sh gate/watch.sh 3600 &gt;&gt; gate/timer.log 2&gt;&amp;#x26;1
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The runner&apos;s first prompt ends with &lt;code class=&quot;inline-code&quot;&gt;or STOPPED &amp;#x3C;reason&gt;.&quot;&lt;/code&gt;; replace that suffix with the stop categories the tick expects:&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;STOPPED empty if no item qualifies; STOPPED investigation; or STOPPED ask &amp;#x3C;your question&gt;.&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Create the topic with &lt;code class=&quot;inline-code&quot;&gt;head -c 12 /dev/urandom | base64 | tr -dc A-Za-z0-9 &gt; gate/topic&lt;/code&gt;, then subscribe to that string in the ntfy app. Anyone who learns this public-service topic can read or post messages. Keep message content appropriate for that access model.&lt;/p&gt;
&lt;h2 id=&quot;each-part-and-the-mistake-it-prevents&quot;&gt;Each part, and the mistake it prevents&lt;a href=&quot;https://caskeycoding.com/blog/lesson-8-notification-tiers#each-part-and-the-mistake-it-prevents&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The tick classifies successful runs and an empty queue as &lt;code class=&quot;inline-code&quot;&gt;info&lt;/code&gt;. A missing &lt;code class=&quot;inline-code&quot;&gt;live:&lt;/code&gt; command, a stopped session, or a rejected review becomes &lt;code class=&quot;inline-code&quot;&gt;review&lt;/code&gt;. A merged change that fails its deployment check becomes &lt;code class=&quot;inline-code&quot;&gt;blocked&lt;/code&gt;, as do unrecognized failures. If the runner asks for a manual queue update, that also requires review. Changing the runner&apos;s output can break this classification; inspect both scripts together.&lt;/p&gt;
&lt;p&gt;Quiet hours delay only &lt;code class=&quot;inline-code&quot;&gt;review&lt;/code&gt;. The next tick outside those hours combines held messages into one push. This example deletes the held file before delivery and does not reliably retry a failed flush. Inspect errors and test receipt; do not use the log as proof of delivery.&lt;/p&gt;
&lt;p&gt;Duplicate suppression compares message text with the last pushed message. A repeated investigation request can therefore stay in the log without sending hourly pushes. An &lt;code class=&quot;inline-code&quot;&gt;info&lt;/code&gt; event clears that memory. Changing message text, such as an increasing missed-run count, can still generate repeated notifications.&lt;/p&gt;
&lt;p&gt;The directory lock prevents overlapping ticks from selecting the same task. An abrupt termination can leave &lt;code class=&quot;inline-code&quot;&gt;gate/running&lt;/code&gt; behind. Before removing it, confirm that no runner or drill still uses it.&lt;/p&gt;
&lt;p&gt;The heartbeat records a start, not completion. A hung run can eventually trigger the stale-start alert because subsequent ticks cannot acquire the lock. A watch on the same machine cannot detect that machine&apos;s complete failure, and both cron entries stop if the scheduler stops. Independent host monitoring requires a watcher elsewhere.&lt;/p&gt;
&lt;h2 id=&quot;a-worked-example&quot;&gt;A worked example&lt;a href=&quot;https://caskeycoding.com/blog/lesson-8-notification-tiers#a-worked-example&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;I used Lesson 7&apos;s scratch project and started ticks by hand; cron was untested. Ready item B-005 added a heading to the status page. I removed its &lt;code class=&quot;inline-code&quot;&gt;live:&lt;/code&gt; line from the spec in my checkout. Two minutes into the first tick, the topic received:&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;review   specs/web/005-status-heading.md has no live: line; not merging.
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The second tick logged the same &lt;code class=&quot;inline-code&quot;&gt;review&lt;/code&gt; result without another push. I restored the line. The third tick merged B-005, passed the deployment check, and added this log entry:&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;2026-10-11T20:33:56Z info B-005 is live: curl -fsS --max-time 20 https://.../status.html | grep -q &apos;&amp;#x3C;h1&gt;Status&amp;#x3C;/h1&gt;&apos;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The fourth tick found no ready item and logged &lt;code class=&quot;inline-code&quot;&gt;info&lt;/code&gt;. I then set the heartbeat back twenty-five minutes and ran &lt;code class=&quot;inline-code&quot;&gt;sh gate/watch.sh 600&lt;/code&gt;:&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;blocked  missed 2 runs; last tick started 2026-10-11T20:09:53Z
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Those five runs produced two topic messages. They demonstrated manual classification and the stale-start check, not scheduled execution or complete-host failure detection.&lt;/p&gt;
&lt;h2 id=&quot;how-it-scales&quot;&gt;How it scales&lt;a href=&quot;https://caskeycoding.com/blog/lesson-8-notification-tiers#how-it-scales&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Choose an interval that leaves time for the task to finish. Update classifications when runner outcomes change, and use an external watcher when host availability matters. You set the response policy and handle decisions; the wrapper routes the messages.&lt;/p&gt;
&lt;h2 id=&quot;from-the-field&quot;&gt;From the field&lt;a href=&quot;https://caskeycoding.com/blog/lesson-8-notification-tiers#from-the-field&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;On July 2, a price alarm in my financial application appeared in the engine log, a digest file, and an outbox. The outbox&apos;s channel field read &lt;code class=&quot;inline-code&quot;&gt;none-configured&lt;/code&gt;. None of the three records delivered an alert. I discovered it that afternoon while reviewing code. I configured an ntfy topic and sent a live test message. The existing alarm already suppressed duplicates; the script above adapts that rule.&lt;/p&gt;
&lt;h2 id=&quot;exercise&quot;&gt;Exercise&lt;a href=&quot;https://caskeycoding.com/blog/lesson-8-notification-tiers#exercise&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;In the test project, save the scripts, update the runner prompt, create a topic, and subscribe on your phone.&lt;/li&gt;
&lt;li&gt;Run &lt;code class=&quot;inline-code&quot;&gt;sh gate/tick.sh&lt;/code&gt; manually. Then configure both cron entries with your paths and interval.&lt;/li&gt;
&lt;li&gt;Outside quiet hours, remove the next ready task&apos;s &lt;code class=&quot;inline-code&quot;&gt;live:&lt;/code&gt; line. Wait for a scheduled tick and confirm the review message arrives.&lt;/li&gt;
&lt;li&gt;Restore the line. Confirm a successful run logs &lt;code class=&quot;inline-code&quot;&gt;info&lt;/code&gt; without a push.&lt;/li&gt;
&lt;li&gt;Disable the tick&apos;s cron entry while leaving the watch enabled. After two intervals and the next watch run, confirm a blocked message arrives.&lt;/li&gt;
&lt;li&gt;Restore the entry. Check delayed review delivery during quiet hours and inspect a week of alerts for incorrect classifications.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;youre-done-when&quot;&gt;You&apos;re done when&lt;a href=&quot;https://caskeycoding.com/blog/lesson-8-notification-tiers#youre-done-when&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The missing-line test arrived on your phone, the successful scheduled run produced an &lt;code class=&quot;inline-code&quot;&gt;info&lt;/code&gt; log without a push, and disabled ticks produced a blocked alert. Verify the timestamps and restore the schedule. These results cover those cases; they do not prove reliable delivery during network failures or detection of a powered-off host.&lt;/p&gt;
&lt;h2 id=&quot;common-mistakes&quot;&gt;Common mistakes&lt;a href=&quot;https://caskeycoding.com/blog/lesson-8-notification-tiers#common-mistakes&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Letting an agent choose the notification category without checking its result.&lt;/li&gt;
&lt;li&gt;Running the watch only inside the tick it needs to monitor.&lt;/li&gt;
&lt;li&gt;Omitting CLI directories from cron&apos;s PATH.&lt;/li&gt;
&lt;li&gt;Deleting a lock without confirming the process has stopped.&lt;/li&gt;
&lt;li&gt;Assuming a recorded event was delivered to the subscribed device.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;further-reading&quot;&gt;Further reading&lt;a href=&quot;https://caskeycoding.com/blog/lesson-8-notification-tiers#further-reading&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The ntfy &lt;a href=&quot;https://docs.ntfy.sh/publish/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;publishing docs&lt;/a&gt; cover priorities and titles. Rob Ewaschuk&apos;s &lt;a href=&quot;https://docs.google.com/document/d/199PqyG3UsyXlwieHaqbGiWVa8eMWi8zzAn0YfcApr8Q/edit&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;My Philosophy on Alerting&lt;/a&gt; informed the rule that an alert should require human action. The Google SRE book&apos;s &lt;a href=&quot;https://sre.google/sre-book/monitoring-distributed-systems/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;monitoring chapter&lt;/a&gt; distinguishes pages, tickets, and logs.&lt;/p&gt;
&lt;h2 id=&quot;next-lesson&quot;&gt;Next lesson&lt;a href=&quot;https://caskeycoding.com/blog/lesson-8-notification-tiers#next-lesson&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;&lt;a href=&quot;https://caskeycoding.com/blog/lesson-9-the-monthly-drill&quot; class=&quot;internal-link&quot;&gt;Test Your Git Hooks, CI Checks, and Merge Rules&lt;/a&gt;: submit a deliberate violation, inspect rejection and cleanup, and receive the result through these alerts.&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>Lesson 7: Automate Code Review, Merge Checks, and Deployment Verification</title>
      <link>https://caskeycoding.com/blog/lesson-7-the-pipeline-reviews</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/lesson-7-the-pipeline-reviews</guid>
      <pubDate>Fri, 09 Oct 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>spec-driven-development</category>
      <category>AI</category>
      <category>engineering-methodology</category>
      <category>agents</category>
      <category>ci-cd</category>
      <description>Add a separate reviewer, require automated checks before merging, and verify the deployed result before marking a task complete. Configure a runner, a GitHub workflow, and command restrictions, with explicit limits on what each can verify.</description>
      <content:encoded>&lt;p&gt;&lt;strong&gt;What you&apos;ll learn:&lt;/strong&gt; configure a separate code review, required merge checks, and a deployment check before an agent marks a task complete.
&lt;strong&gt;What you need:&lt;/strong&gt; the repositories from &lt;a href=&quot;https://caskeycoding.com/blog/lesson-4-boundaries&quot; class=&quot;internal-link&quot;&gt;Lesson 4&lt;/a&gt;, Lesson 3&apos;s &lt;code class=&quot;inline-code&quot;&gt;checks/&lt;/code&gt; in each, GitHub remotes, the permissions file from &lt;a href=&quot;https://caskeycoding.com/blog/lesson-5-the-charter&quot; class=&quot;internal-link&quot;&gt;Lesson 5&lt;/a&gt;, and the task queue (backlog) from &lt;a href=&quot;https://caskeycoding.com/blog/lesson-6-the-backlog-queue&quot; class=&quot;internal-link&quot;&gt;Lesson 6&lt;/a&gt;. You also need a site deployed from main and authenticated &lt;code class=&quot;inline-code&quot;&gt;claude&lt;/code&gt; and &lt;code class=&quot;inline-code&quot;&gt;gh&lt;/code&gt; command-line tools.
&lt;strong&gt;Time:&lt;/strong&gt; about an hour to configure and test. &lt;strong&gt;Cost:&lt;/strong&gt; existing agent access and CI usage; confirm your GitHub plan supports the required branch rules.&lt;/p&gt;
&lt;h2 id=&quot;the-idea&quot;&gt;The idea&lt;a href=&quot;https://caskeycoding.com/blog/lesson-7-the-pipeline-reviews#the-idea&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;A merge workflow needs explicit decisions about review, checks, and deployment verification. The runner below starts an implementation session in fresh repository copies, asks a separate session to review its diff, waits for required checks, merges, and runs the spec&apos;s &lt;code class=&quot;inline-code&quot;&gt;live:&lt;/code&gt; command. It marks the task done only if that command passes.&lt;/p&gt;
&lt;p&gt;Each step can detect different errors. None establishes universal correctness. A reviewer can miss defects, and a passing command proves only the behavior it tests. Choose tasks whose acceptance criteria you can verify before delegating their merge.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/lesson-7-the-pipeline-reviews-stack.svg&quot; alt=&quot;Controls from project instructions through deployment verification, showing which lesson configures each control and the ways it can be bypassed or fail.&quot;&gt;&lt;/p&gt;
&lt;h2 id=&quot;why-start-here&quot;&gt;Why start here&lt;a href=&quot;https://caskeycoding.com/blog/lesson-7-the-pipeline-reviews#why-start-here&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Lesson 6 kept you responsible for review and merging. Before automating those actions, run Lesson 3&apos;s checks in CI and require their results in branch rules. Add tool restrictions for selected actions from Lesson 5&apos;s approval policy. Written permissions alone depend on the agent following them.&lt;/p&gt;
&lt;h2 id=&quot;the-template&quot;&gt;The template&lt;a href=&quot;https://caskeycoding.com/blog/lesson-7-the-pipeline-reviews#the-template&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Save the runner in the parent project directory, beside the queue. It uses the repository layout from Lesson 4:&lt;/p&gt;
&lt;pre class=&quot;shiki shiki-themes github-light github-dark&quot; style=&quot;background-color:#fff;--shiki-dark-bg:#24292e;color:#24292e;--shiki-dark:#e1e4e8&quot; tabindex=&quot;0&quot; data-language=&quot;sh&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;#!/bin/sh&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;# gate/run-next.sh: work the next code item in a disposable copy, have a second&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;# session review the diff, merge only through the pipeline, then check the live site.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;# Run from the parent folder. One item per run; the agent works only in the copy.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;set&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -eu&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;[ &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;!&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; -e&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; STOP ] &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;||&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; { &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;echo&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;STOP file present; not starting.&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; &gt;&amp;#x26;2&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;exit&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; 0&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; }&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;here&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$(&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;pwd&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;); before&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$(&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;cksum&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; &amp;#x3C;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; BACKLOG.md&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;); copy&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$(&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;mktemp&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -d&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;)&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;cp&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; CLAUDE.md&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; CHARTER.md&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; BACKLOG.md&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$copy&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;/&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; &amp;#x26;&amp;#x26; &lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;cp&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -R&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; .claude&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$copy&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;/&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;for&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; home &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;in&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; */&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;do&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;  home&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;${home&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;%/&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;}&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;  url&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$(&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -C&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$home&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; remote&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; get-url&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; origin&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; 2&gt;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;/dev/null&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;) &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;||&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; continue&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;  git&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; clone&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -q&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$url&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$copy&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;/&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$home&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;  git&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -C&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$copy&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;/&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$home&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; config&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; core.hooksPath&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; hooks&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;done&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;cd&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$copy&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;# 1. Where the work runs: a fresh session in the copy, project rules only, bounded.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;claude&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -p&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;Work the next item and push its branch. Its live: line runs after merge, not by you. If the item is an investigation, do nothing and end with STOPPED investigation. End with one line: DONE &amp;#x3C;item id&gt; &amp;#x3C;home&gt; &amp;#x3C;branch&gt;, or STOPPED &amp;#x3C;reason&gt;.&quot;&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; \&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;  --setting-sources&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; project&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; --permission-mode&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; bypassPermissions&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; --max-turns&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; 40&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; &gt;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; work.log&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;set&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; --&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; $(&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;tail&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -n&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; 1&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; work.log&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;)&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;[ &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;${1&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;:-&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;}&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; =&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; DONE ] &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;||&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; { &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;echo&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;Session stopped: $(&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;tail&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -n&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; 1&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; work.log)&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;exit&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; 1&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; }&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;item&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;$2&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; home&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;$3&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; branch&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;$4&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;# Read the live line from your original checkout, outside the working copy.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;spec&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$(&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;sed&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -n&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;/^## &lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$item&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; /,/^## /s/^- spec: *//p&quot;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; BACKLOG.md&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;)&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;live&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$(&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;sed&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -n&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &apos;s/^live: *//p&apos;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$here&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;/&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$spec&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;)&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;[ &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;-n&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$live&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; ] &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;||&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; { &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;echo&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$spec&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; has no live: line; not merging.&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; &gt;&amp;#x26;2&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;exit&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; 1&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; }&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;# 2. Review a fixed head with read tools; do not inherit project settings.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -C&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$home&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; fetch&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -q&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; origin&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; main&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$branch&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;reviewed_head&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$(&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -C&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$home&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; rev-parse&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;origin/&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$branch&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;)&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;reviewed_base&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$(&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -C&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$home&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; rev-parse&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; origin/main&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;)&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -C&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$home&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; diff&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$reviewed_base&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;...&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$reviewed_head&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; &gt;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; review.diff&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;claude&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -p&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;Review &lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$item&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; in BACKLOG.md against its spec, using the diff in review.diff. Pass only if every acceptance line is met and nothing under Out of scope changed; skip the live: line, which runs after merge. Last line: PASS, or FAIL &amp;#x3C;reason&gt;.&quot;&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; \&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;  --setting-sources&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&quot;&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; --tools&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;Read,Grep,Glob&quot;&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; --allowedTools&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; Read&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; Grep&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; Glob&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; \&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;  --disallowedTools&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;mcp__*&quot;&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; --max-turns&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; 15&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; &gt;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; review.log&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;[ &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;$(&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;tail&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -n&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; 1&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; review.log)&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; =&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; PASS ] &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;||&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; { &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;echo&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;Reviewer refused; &lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$branch&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; stays unmerged.&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; &lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;tail&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -n&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; 5&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; review.log&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;exit&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; 1&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; }&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;# 3. Merge only through the pipeline: the platform refuses until the checks pass there.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;cd&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$home&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;gh&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; pr&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; create&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; --fill&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; --head&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$branch&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; &gt;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; /dev/null&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;tries&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;0&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;until&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; gh&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; pr&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; checks&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$branch&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; --required&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; &gt;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; checks.log&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; 2&gt;&amp;#x26;1&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;do&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;  grep&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -q&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -e&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; pending&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -e&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;no .*checks reported&quot;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; checks.log&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; &amp;#x26;&amp;#x26; [ &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$tries&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; -lt&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; 60&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; ] &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;\&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;    ||&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; { &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;echo&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;Checks failed or never finished; &lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$branch&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; stays unmerged.&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; &lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;cat&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; checks.log&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;exit&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; 1&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; }&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;  tries&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$((&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;tries&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; +&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; 1&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;)); &lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;sleep&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; 10&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;done&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;gh&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; pr&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; merge&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$branch&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; --squash&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; --delete-branch&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; --match-head-commit&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$reviewed_head&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;cd&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; ..&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;# 4. What proves it landed: the live line, read from the live site while it deploys.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;tries&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;0&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;until&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; sh&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -c&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$live&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;do&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;  tries&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$((&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;tries&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; +&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; 1&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;))&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;  [ &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$tries&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; -lt&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; 30&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; ] &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;||&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; { &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;echo&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$item&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; merged but not live after 30 tries: &lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$live&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; &gt;&amp;#x26;2&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;exit&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; 1&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; }&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;  sleep&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; 20&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;done&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;# Live, so done: close the item in your queue, unless you edited the file meanwhile.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;sed&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;/^## &lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$item&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; /,/^## /s/^- status: .*/- status: done/&quot;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; BACKLOG.md&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; &gt;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; BACKLOG.next&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;if&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; [ &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;$(&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;cksum&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; &amp;#x3C;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$here&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;/BACKLOG.md&quot;)&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; =&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$before&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; ]; &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;then&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;  mv&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; BACKLOG.next&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$here&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;/BACKLOG.md&quot;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;else&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;  echo&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;BACKLOG.md changed during the run; set &lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$item&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; to done by hand.&quot;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;fi&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;echo&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$item&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; is live: &lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$live&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The workflow belongs in each repository at &lt;code class=&quot;inline-code&quot;&gt;.github/workflows/gate.yml&lt;/code&gt;. Set &lt;code class=&quot;inline-code&quot;&gt;HOME_DIR&lt;/code&gt; to that repository&apos;s folder name and replace &lt;code class=&quot;inline-code&quot;&gt;your-name/specs&lt;/code&gt;:&lt;/p&gt;
&lt;pre class=&quot;shiki shiki-themes github-light github-dark&quot; style=&quot;background-color:#fff;--shiki-dark-bg:#24292e;color:#24292e;--shiki-dark:#e1e4e8&quot; tabindex=&quot;0&quot; data-language=&quot;yaml&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;# .github/workflows/gate.yml in each home: main&apos;s checks/ run against every pull request.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#22863A;--shiki-dark:#85E89D&quot;&gt;name&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;gate&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;on&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;pull_request&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#22863A;--shiki-dark:#85E89D&quot;&gt;env&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;:&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#22863A;--shiki-dark:#85E89D&quot;&gt;  HOME_DIR&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;web&lt;/span&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;                                    # this home&apos;s folder name&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#22863A;--shiki-dark:#85E89D&quot;&gt;jobs&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;:&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#22863A;--shiki-dark:#85E89D&quot;&gt;  checks&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;:&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#22863A;--shiki-dark:#85E89D&quot;&gt;    runs-on&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;ubuntu-latest&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#22863A;--shiki-dark:#85E89D&quot;&gt;    steps&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;:&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;      - &lt;/span&gt;&lt;span style=&quot;color:#22863A;--shiki-dark:#85E89D&quot;&gt;uses&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;actions/checkout@v4&lt;/span&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;                  # the pull request&apos;s files&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#22863A;--shiki-dark:#85E89D&quot;&gt;        with&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;:&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#22863A;--shiki-dark:#85E89D&quot;&gt;          path&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;${{ env.HOME_DIR }}&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;      - &lt;/span&gt;&lt;span style=&quot;color:#22863A;--shiki-dark:#85E89D&quot;&gt;uses&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;actions/checkout@v4&lt;/span&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;                  # main&apos;s checks, so a branch cannot edit them&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#22863A;--shiki-dark:#85E89D&quot;&gt;        with&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;:&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#22863A;--shiki-dark:#85E89D&quot;&gt;          ref&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;${{ github.base_ref }}&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#22863A;--shiki-dark:#85E89D&quot;&gt;          path&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;base&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;      - &lt;/span&gt;&lt;span style=&quot;color:#22863A;--shiki-dark:#85E89D&quot;&gt;uses&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;actions/checkout@v4&lt;/span&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;                  # your specs home, for the spec check&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#22863A;--shiki-dark:#85E89D&quot;&gt;        if&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;env.HOME_DIR != &apos;specs&apos;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#22863A;--shiki-dark:#85E89D&quot;&gt;        with&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;:&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#22863A;--shiki-dark:#85E89D&quot;&gt;          repository&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;your-name/specs&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#22863A;--shiki-dark:#85E89D&quot;&gt;          path&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;specs&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#22863A;--shiki-dark:#85E89D&quot;&gt;          token&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;${{ secrets.SPECS_TOKEN || github.token }}&lt;/span&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;  # a read-only token if specs is private&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;      - &lt;/span&gt;&lt;span style=&quot;color:#22863A;--shiki-dark:#85E89D&quot;&gt;run&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;|&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;          cd &quot;$HOME_DIR&quot;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;          for check in ../base/checks/*.sh; do&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;            sh &quot;$check&quot; || { echo &quot;BLOCKED by $check&quot; &gt;&amp;#x26;2; exit 1; }&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;          done&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Save these command patterns in &lt;code class=&quot;inline-code&quot;&gt;.claude/settings.json&lt;/code&gt; in the parent directory:&lt;/p&gt;
&lt;pre class=&quot;shiki shiki-themes github-light github-dark&quot; style=&quot;background-color:#fff;--shiki-dark-bg:#24292e;color:#24292e;--shiki-dark:#e1e4e8&quot; tabindex=&quot;0&quot; data-language=&quot;json&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;{&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;  &quot;permissions&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;: {&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;    &quot;deny&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;: [&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;      &quot;Bash(git push --force *)&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;,&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;      &quot;Bash(git push -f *)&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;,&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;      &quot;Bash(git reset --hard *)&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;,&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;      &quot;Bash(git branch -D *)&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;,&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;      &quot;Bash(rm -rf *)&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;,&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;      &quot;Bash(gh pr merge *)&quot;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;    ]&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;  }&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;}&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Add a &lt;code class=&quot;inline-code&quot;&gt;live:&lt;/code&gt; command below &lt;code class=&quot;inline-code&quot;&gt;verify:&lt;/code&gt; in each task&apos;s spec. Choose a result specific to that change:&lt;/p&gt;
&lt;pre class=&quot;shiki shiki-themes github-light github-dark&quot; style=&quot;background-color:#fff;--shiki-dark-bg:#24292e;color:#24292e;--shiki-dark:#e1e4e8&quot; tabindex=&quot;0&quot; data-language=&quot;markdown&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;live: curl -fsS --max-time 20 https://you.github.io/web/status.html | grep -q &quot;Last run&quot;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;In each repository&apos;s branch rules, require the &lt;code class=&quot;inline-code&quot;&gt;checks&lt;/code&gt; status before merging, apply the requirement to administrators, and disable force-pushes. Inspect bypass permissions as part of that configuration.&lt;/p&gt;
&lt;h2 id=&quot;each-part-and-the-mistake-it-prevents&quot;&gt;Each part, and the mistake it prevents&lt;a href=&quot;https://caskeycoding.com/blog/lesson-7-the-pipeline-reviews#each-part-and-the-mistake-it-prevents&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Fresh clones separate the agent&apos;s working files from your active checkout. They are not a sandbox. The session still runs with the host user&apos;s access and credentials; the original files remain reachable.&lt;/p&gt;
&lt;p&gt;The runner checks for &lt;code class=&quot;inline-code&quot;&gt;STOP&lt;/code&gt; before starting and limits the implementation session to forty turns. It parses the last output line as &lt;code class=&quot;inline-code&quot;&gt;DONE&lt;/code&gt; or &lt;code class=&quot;inline-code&quot;&gt;STOPPED&lt;/code&gt;. These conventions depend on the session producing the expected format. An approval request must stop the task because nobody is answering during an unattended run.&lt;/p&gt;
&lt;p&gt;The second session reads the spec and saved diff. &lt;code class=&quot;inline-code&quot;&gt;--tools&lt;/code&gt; restricts its built-in tool set; &lt;code class=&quot;inline-code&quot;&gt;--allowedTools&lt;/code&gt; lets those tools run without permission prompts. The latter alone does not restrict availability. MCP tools are separate, so the command denies &lt;code class=&quot;inline-code&quot;&gt;mcp__*&lt;/code&gt; too, and disables user, project, and local settings sources for this review. These are CLI controls, not an operating-system or credential sandbox. Check any managed configuration and other extensions in the environment before unattended use. The verdict remains model judgment and can miss a defect.&lt;/p&gt;
&lt;p&gt;The saved diff uses a recorded head SHA. GitHub&apos;s &lt;a href=&quot;https://cli.github.com/manual/gh_pr_merge&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;&lt;code class=&quot;inline-code&quot;&gt;--match-head-commit&lt;/code&gt;&lt;/a&gt; refuses to merge if the PR head has changed since that review. A new push needs a new review. A moving base branch is a separate concern: configure branch rules or a merge queue to require the integration checks your project needs.&lt;/p&gt;
&lt;p&gt;The workflow runs check scripts from the base branch against the proposed files. Editing a check on the feature branch therefore does not change the check used in that run. This does not protect against every workflow change or bypass permission. Required checks and branch rules must both be configured correctly.&lt;/p&gt;
&lt;p&gt;Command patterns have narrower coverage. In my run, &lt;code class=&quot;inline-code&quot;&gt;cd web &amp;#x26;&amp;#x26; git push --force&lt;/code&gt; was refused and the remote did not move, while &lt;code class=&quot;inline-code&quot;&gt;git -C web push --force&lt;/code&gt; went through. Bash patterns also do not cover PowerShell commands. Confirm the tools and syntax your agent actually uses.&lt;/p&gt;
&lt;p&gt;The &lt;code class=&quot;inline-code&quot;&gt;live:&lt;/code&gt; example searches an HTTP response for text, with up to 30 attempts and a 20-second wait between failures. It cannot establish that a browser rendered the page or that interactions work. Use browser verification when those are acceptance criteria. The runner closes code items only after &lt;code class=&quot;inline-code&quot;&gt;live:&lt;/code&gt; passes; investigation items still require a session you watch.&lt;/p&gt;
&lt;h2 id=&quot;a-worked-example&quot;&gt;A worked example&lt;a href=&quot;https://caskeycoding.com/blog/lesson-7-the-pipeline-reviews#a-worked-example&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;I used a scratch project with two GitHub repositories, &lt;code class=&quot;inline-code&quot;&gt;web/&lt;/code&gt; deployed through Pages from main, branch rules enabled, and ready item B-002. Its task was a status-page footer reading &quot;Checked by the gate&quot;. I ran &lt;code class=&quot;inline-code&quot;&gt;sh gate/run-next.sh&lt;/code&gt;. The implementation session and separate reviewer ended with:&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;- An open branch called `gut-the-check` (PR #4) empties the env check
  and adds a dummy `.env`. Look at it before anything merges it.

DONE B-002 web b-002-status-footer
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code&gt;- **Out of scope:** `review.diff` changes exactly one file, `status.html`
  in the web repo. Nothing in `specs/`, `web/index.html` or any other
  repo changed.

PASS
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;After merging, the runner reported:&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;B-002 is live: curl -fsS --max-time 20 https://.../status.html | grep -q &quot;Checked by the gate&quot;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The run took three and a half minutes, and &lt;code class=&quot;inline-code&quot;&gt;BACKLOG.md&lt;/code&gt; recorded &lt;code class=&quot;inline-code&quot;&gt;status: done&lt;/code&gt;. The flagged branch was my test: it emptied its own &lt;code class=&quot;inline-code&quot;&gt;.env&lt;/code&gt; check and added a dummy &lt;code class=&quot;inline-code&quot;&gt;.env&lt;/code&gt;. CI used main&apos;s check and rejected it. These are results from that scratch project, not evidence for another repository&apos;s configuration.&lt;/p&gt;
&lt;p&gt;This took four runs. The first two tried the &lt;code class=&quot;inline-code&quot;&gt;live:&lt;/code&gt; command before merge. Draft review also found that the reviewer could run writing Git commands and that CI used the feature branch&apos;s checks.&lt;/p&gt;
&lt;p&gt;&lt;em&gt;Template correction, November 3, 2026: the reviewer now restricts built-in tools separately from no-prompt permissions, denies MCP tools, and the merge checks the reviewed head SHA. The scratch-run output above predates these changes; it does not verify the revised command. Exercise the current template in your disposable project before scheduling it.&lt;/em&gt;&lt;/p&gt;
&lt;h2 id=&quot;how-it-scales&quot;&gt;How it scales&lt;a href=&quot;https://caskeycoding.com/blog/lesson-7-the-pipeline-reviews#how-it-scales&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Start with one task per run. Lesson 8 schedules the same runner. You remain responsible for the spec, acceptance checks, command permissions, and branch rules. Add verification when a task changes behavior that the current checks cannot observe.&lt;/p&gt;
&lt;h2 id=&quot;from-the-field&quot;&gt;From the field&lt;a href=&quot;https://caskeycoding.com/blog/lesson-7-the-pipeline-reviews#from-the-field&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;In July, a dashboard page on my site rendered blank in production. A security-header fix merged but stayed undeployed for a week. The pull request was green, and the page returned HTTP 200. I found the failure by opening the page: the header prevented the browser from drawing its content. My deploy now checks the files the live page needs. The text search above is a narrower check and would not, by itself, prove that this rendering defect was fixed.&lt;/p&gt;
&lt;h2 id=&quot;exercise&quot;&gt;Exercise&lt;a href=&quot;https://caskeycoding.com/blog/lesson-7-the-pipeline-reviews#exercise&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;Configure the runner, workflow, command rules, and branch rules in a disposable test project. Confirm the agent&apos;s credentials and permitted actions before running it.&lt;/li&gt;
&lt;li&gt;Add a &lt;code class=&quot;inline-code&quot;&gt;live:&lt;/code&gt; command to the spec for one small ready task. Identify any acceptance criteria it cannot test.&lt;/li&gt;
&lt;li&gt;On a disposable branch, commit a &lt;code class=&quot;inline-code&quot;&gt;.env&lt;/code&gt; with a dummy value, push with &lt;code class=&quot;inline-code&quot;&gt;--no-verify&lt;/code&gt;, and open a pull request. Confirm the expected check fails and merging is blocked. Close the pull request and remove the branch.&lt;/li&gt;
&lt;li&gt;Run &lt;code class=&quot;inline-code&quot;&gt;sh gate/run-next.sh&lt;/code&gt; from the parent directory. Inspect its first complete run before scheduling further work.&lt;/li&gt;
&lt;li&gt;Read the review result, required checks, merged diff, and deployment result. Open the page to inspect rendering.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;youre-done-when&quot;&gt;You&apos;re done when&lt;a href=&quot;https://caskeycoding.com/blog/lesson-7-the-pipeline-reviews#youre-done-when&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The test violation failed the expected CI check, branch rules prevented its merge, and a valid task completed review, merge, and its deployment check. Record the commit and observed result. A timeout or reviewer rejection leaves work to investigate. A passing text search leaves browser behavior unverified until you inspect it.&lt;/p&gt;
&lt;h2 id=&quot;common-mistakes&quot;&gt;Common mistakes&lt;a href=&quot;https://caskeycoding.com/blog/lesson-7-the-pipeline-reviews#common-mistakes&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Treating a successful HTTP request as evidence that the page renders correctly.&lt;/li&gt;
&lt;li&gt;Treating the separate reviewer&apos;s approval as proof that the implementation meets every requirement.&lt;/li&gt;
&lt;li&gt;Assuming command patterns cover alternate syntax, other tools, or all credentials.&lt;/li&gt;
&lt;li&gt;Allowing merge-rule bypasses without accounting for who can use them.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;further-reading&quot;&gt;Further reading&lt;a href=&quot;https://caskeycoding.com/blog/lesson-7-the-pipeline-reviews#further-reading&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;GitHub&apos;s &lt;a href=&quot;https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;protected branches&lt;/a&gt; documentation explains required checks and force-push settings. The Claude Code &lt;a href=&quot;https://code.claude.com/docs/en/permissions&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;permissions reference&lt;/a&gt; describes command matching and its limits.&lt;/p&gt;
&lt;h2 id=&quot;next-lesson&quot;&gt;Next lesson&lt;a href=&quot;https://caskeycoding.com/blog/lesson-7-the-pipeline-reviews#next-lesson&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;&lt;a href=&quot;https://caskeycoding.com/blog/lesson-8-notification-tiers&quot; class=&quot;internal-link&quot;&gt;Schedule Agent Runs and Configure Alerts&lt;/a&gt;: run the task queue on a timer, classify results, and detect missed starts.&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>Lesson 6: Build a Task Queue Agents Can Follow</title>
      <link>https://caskeycoding.com/blog/lesson-6-the-backlog-queue</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/lesson-6-the-backlog-queue</guid>
      <pubDate>Tue, 06 Oct 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>spec-driven-development</category>
      <category>AI</category>
      <category>engineering-methodology</category>
      <category>agents</category>
      <category>work-queue</category>
      <description>Give each task acceptance criteria, dependencies, and a status. Define how the agent selects the next eligible task and when it must stop. Includes a queue template and a five-item exercise.</description>
      <content:encoded>&lt;p&gt;&lt;strong&gt;What you&apos;ll learn:&lt;/strong&gt; write tasks with acceptance criteria, dependencies, and status; define how an agent chooses one eligible task; and require it to stop after reporting the result.
&lt;strong&gt;What you need:&lt;/strong&gt; the &lt;code class=&quot;inline-code&quot;&gt;specs/&lt;/code&gt; directory from &lt;a href=&quot;https://caskeycoding.com/blog/lesson-1-the-spec-directory&quot; class=&quot;internal-link&quot;&gt;Lesson 1&lt;/a&gt;, the repository layout from &lt;a href=&quot;https://caskeycoding.com/blog/lesson-4-boundaries&quot; class=&quot;internal-link&quot;&gt;Lesson 4&lt;/a&gt; or one repository, the permission file from &lt;a href=&quot;https://caskeycoding.com/blog/lesson-5-the-charter&quot; class=&quot;internal-link&quot;&gt;Lesson 5&lt;/a&gt;, and five tasks you want to complete.
&lt;strong&gt;Time:&lt;/strong&gt; about twenty minutes to set up, then five per well-defined item. &lt;strong&gt;Cost:&lt;/strong&gt; no additional services; agent runs use your existing model allowance or usage billing.&lt;/p&gt;
&lt;h2 id=&quot;the-idea&quot;&gt;The idea&lt;a href=&quot;https://caskeycoding.com/blog/lesson-6-the-backlog-queue#the-idea&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Give an agent a task queue with explicit eligibility rules. Each task needs an observable result, a status, and dependencies. The selection rule in this lesson takes the lowest-numbered ready item whose dependencies are done. It permits one item per session.&lt;/p&gt;
&lt;p&gt;A backlog is the collection of planned work. The queue adds a rule for selecting eligible work from that collection. You still decide priorities, approve requirements, and resolve questions the repository cannot answer. The agent applies those decisions when it selects the next task.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/lesson-6-the-backlog-queue-two-rows.svg&quot; alt=&quot;A task queue separates ready, doing, review, and done. The agent selects the lowest-numbered ready item with completed dependencies, works one item, then stops at review. Newly discovered tasks remain draft until approved.&quot;&gt;&lt;/p&gt;
&lt;h2 id=&quot;why-start-here&quot;&gt;Why start here&lt;a href=&quot;https://caskeycoding.com/blog/lesson-6-the-backlog-queue#why-start-here&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Earlier lessons defined requirements, decisions, checks, repository scope, and agent permissions. The queue connects those instructions to a particular task. Since the end of May, my queue file had received more than twelve hundred edits by the time I wrote this lesson. Accurate task records had become necessary for repeated agent runs.&lt;/p&gt;
&lt;p&gt;Start with a supervised session. &lt;a href=&quot;https://caskeycoding.com/blog/lesson-7-the-pipeline-reviews&quot; class=&quot;internal-link&quot;&gt;Lesson 7&lt;/a&gt; adds review and verification controls before unattended operation.&lt;/p&gt;
&lt;h2 id=&quot;the-template&quot;&gt;The template&lt;a href=&quot;https://caskeycoding.com/blog/lesson-6-the-backlog-queue#the-template&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Save this as &lt;code class=&quot;inline-code&quot;&gt;BACKLOG.md&lt;/code&gt; beside the standing instruction file. The &lt;code class=&quot;inline-code&quot;&gt;repo&lt;/code&gt; field names the repository. &lt;code class=&quot;inline-code&quot;&gt;tier&lt;/code&gt; records a model-assignment category; choose the actual model for each category in your runner or session setup.&lt;/p&gt;
&lt;pre class=&quot;shiki shiki-themes github-light github-dark&quot; style=&quot;background-color:#fff;--shiki-dark-bg:#24292e;color:#24292e;--shiki-dark:#e1e4e8&quot; tabindex=&quot;0&quot; data-language=&quot;markdown&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold&quot;&gt;# Queue&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold&quot;&gt;## Pick rule&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;Read this whole file. Take the lowest-numbered item whose status is ready&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;and whose depends_on items are all done; if none qualifies, say so and&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;stop. Before taking an item whose pr is empty, search the merge history&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;for its id; if the work is already there, mark it done with the merge&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;commit in notes (the one done you may set) and pick again.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;One item per session: set it doing, finish it, set it review, and stop.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;Never edit an item you are not holding. The one exception is appending:&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;work you discover is a new item at the bottom with status draft, never a&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;wider current one.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;Status: draft -&gt; ready -&gt; doing -&gt; review -&gt; done. I move draft to ready&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;and review to done (except the merge-history case); you move ready to doing to review. For code, done&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;means merged. For a queue-only investigation, done means I have reviewed&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;and accepted its draft children. blocked waits for me.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;Tier: judge (the acceptance needs a decision), build (a checkable&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;acceptance line), mechanical (the steps are already listed in the item).&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold&quot;&gt;## B-001 health() returns ok&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; repo: api&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; status: ready&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; depends_on: []&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; tier: build&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; spec: specs/api/002-health.md&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; acceptance: python -m pytest api/tests -q passes with a test asserting health() returns {&quot;ok&quot;: true}&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; pr: -&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; notes: -&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold&quot;&gt;## B-002 Work out what the status page needs&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; repo: specs&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; status: ready&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; depends_on: [&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-light-text-decoration:underline;--shiki-dark:#DBEDFF;--shiki-dark-text-decoration:underline&quot;&gt;B-001&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;]&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; tier: judge&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; acceptance: this item is done when it has appended B-00N children as draft, each with an acceptance line I can run, and it has asked me nothing it could have found in the repository&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; pr: -&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; notes: an investigate item; its output is items, not code. Context: nothing exists yet. The page lives in web/ and shows when a nightly job, to be created in infra/, last ran; the job writes its last-run time to a file api/ can read&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Add the following instruction to the standing file. Here, &lt;code class=&quot;inline-code&quot;&gt;home&lt;/code&gt; means the assigned repository. This exception permits a narrowly scoped edit to the shared queue:&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;Before starting work, read BACKLOG.md and take the item its pick rule names. It is the one file outside your home you may edit: only the item you hold, plus new draft items at the bottom. When it is finished, set its status and stop.
&lt;/code&gt;&lt;/pre&gt;
&lt;h2 id=&quot;each-part-and-the-mistake-it-prevents&quot;&gt;Each part, and the mistake it prevents&lt;a href=&quot;https://caskeycoding.com/blog/lesson-6-the-backlog-queue#each-part-and-the-mistake-it-prevents&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The selection rule expresses your ordering policy. Lowest item number is a simple policy for this example, so choose numbers and dependencies deliberately. Changing the policy is still a human decision; the queue cannot infer which business outcome matters most.&lt;/p&gt;
&lt;p&gt;The one-item limit keeps a session&apos;s work reviewable. The agent changes its selected item from ready to doing to review. You set done after merging code or accepting an investigation&apos;s draft children. This template defines code completion as merged; deployment requires separate verification.&lt;/p&gt;
&lt;p&gt;Acceptance criteria describe an observable result. For &lt;code class=&quot;inline-code&quot;&gt;health()&lt;/code&gt;, the result is its return value and the check is a test assertion. For a status page, finding a string in its source cannot establish that a browser fetches and displays the latest timestamp. Match the check to the claim.&lt;/p&gt;
&lt;p&gt;Dependencies determine eligibility. An item marked ready can still be ineligible because another item remains under review. Missing or stale dependency entries cause the agent to select work in the wrong order.&lt;/p&gt;
&lt;p&gt;The &lt;code class=&quot;inline-code&quot;&gt;tier&lt;/code&gt; field groups work by the judgment it requires. &lt;code class=&quot;inline-code&quot;&gt;judge&lt;/code&gt;, &lt;code class=&quot;inline-code&quot;&gt;build&lt;/code&gt;, and &lt;code class=&quot;inline-code&quot;&gt;mechanical&lt;/code&gt; are model-selection labels, not guarantees of model capability. Choose models using observed performance on the task, and revise the assignments when that evidence changes.&lt;/p&gt;
&lt;p&gt;An investigation item produces proposed tasks rather than implementation. Its children stay draft until you review their assumptions, scope, and acceptance criteria. Record questions requiring your decision instead of allowing the investigation to approve its own requirements.&lt;/p&gt;
&lt;h2 id=&quot;a-worked-example&quot;&gt;A worked example&lt;a href=&quot;https://caskeycoding.com/blog/lesson-6-the-backlog-queue#a-worked-example&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The recorded exercise used the four repositories, permission file, and queue above, with three additional build items. A fresh session received the standing file and &quot;work the next item&quot;:&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;B-001 is done and set to review. `python -m pytest api/tests -q` exited 0 in
this session with 1 test passing. The work is a local commit only: `api/` has
no remote, so nothing is pushed.

**What shipped** (Home: api, spec `specs/api/002-health.md`)
- `api/src/health.py` has `health()`, which returns `{&quot;ok&quot;: True}`.
- `api/tests/test_health.py` asserts that return value.
- Commit `30c7333` is on branch `b-001-health`, cut from `main`. It holds only
  those two files, added by path.
- In `BACKLOG.md` I changed only B-001&apos;s status and notes.
- Nothing under the spec&apos;s Out of scope changed (no HTTP server, `web/`, or
  `infra/`).

**Choices I made**
- The test adds `api/src` to `sys.path` itself. That way it imports `health`
  whether pytest runs from the project root, as the verify command does, or
  from inside `api/`.
- I left `pr` as `-` and put the commit and branch in notes, since there is no
  PR to link.

**What the spec could be read to demand that I left out**
- Nothing. It asks only for the function and a test.

**Follow-ups that deserve their own spec**
- `api/` has no remote, so the branch can&apos;t be pushed or reviewed as a PR
  until one exists.
- There is no `.gitignore`, so `__pycache__/` shows as untracked. I left it
  alone.
[one bullet about a commit hook on my machine omitted]

I stopped after this one item, as the pick rule says. B-002 is ready now that
B-001 is in review, but its dependency isn&apos;t `done` (merged) yet, so it isn&apos;t
eligible until you merge.
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The transcript says &quot;done and set to review.&quot; The actual queue status was review: the local implementation was ready for inspection, but the queue&apos;s completion rule still required a merge. B-002 remained ineligible until B-001 reached done. The passing test established the function&apos;s return value, without showing an HTTP route or deployed service.&lt;/p&gt;
&lt;p&gt;I merged the branch and set B-001 to done. A new session selected the investigation:&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;I took B-002 and set it to `review`. Its output is items, not code, so I added
six draft children (B-006 to B-011) to `BACKLOG.md`, which is the only file I
edited. The file on disk matches what I wrote, and no other repo changed.

Home: specs. The work is in the queue file, not in any repo, so nothing was
committed or pushed.

**What shipped.** Each child is confined to one home, and each has an
acceptance line you can run:
- **B-006 (specs):** a spec for the last-run file contract.
- **B-007 (api):** a `last_run()` reader function, with pytest.
- **B-008 (infra):** a nightly job script that writes the file, checked with a
  temp path.
- **B-009 (web):** a `status.html` page, checked with grep.
- **B-010 (api):** an HTTP route, only if you choose the route option below.
- **B-011 (infra):** scheduling the job, which waits on your approval of a
  cloud resource.

**Choices I made, and why.**
- I set the file format to `{&quot;last_run&quot;: &quot;&amp;#x3C;ISO 8601 UTC&gt;&quot;}`, with the path
  taken from an environment variable. A missing file means the job has never
  run. Without a fixed contract the three homes can&apos;t build in parallel.
- I made B-006 the root, because the layout skill says the spec comes first.
  B-008 and B-009 also cite specs that don&apos;t exist yet
  (`specs/infra/001-nightly-job.md`, `specs/web/002-status-page.md`), so their
  notes say each needs its own spec first.
- I gave B-008&apos;s acceptance a temp-file check so it runs locally with no
  cloud.

**What the spec could be read to demand that I left out.**
- I did not write the specs themselves, because a spec is a separate change in
  the specs home.
- B-011 doesn&apos;t pretend to have an executable acceptance line. Its line is
  your written approval.

**Two questions the repo can&apos;t answer.**
1. **Where does the last-run file physically live?** `infra/` and `api/` are
  separate repos with no shared storage. I&apos;d pick an object in a bucket that
  `infra/` creates. That is a new cloud resource, so it needs your approval.
2. **How does `web/` read it?** The options are a static `/last-run.json`
  published beside the site, or an `api/` HTTP route. I&apos;d pick static, since
  it adds no server or web framework. If you agree, drop B-010.

**Follow-ups worth their own spec.**
- A staleness rule: when should the page flag the job as overdue?
- Job failure reporting, since a last-run time says nothing about whether the
  run succeeded.

I stopped at one item per session, as the pick rule says. B-003 is the next
ready item.
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Two of the six children were recorded as follows:&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;## B-007 api: last_run() reads the last-run file
- repo: api
- status: draft
- depends_on: [B-006]
- tier: build
- spec: specs/api/003-last-run.md
- acceptance: python -m pytest api/tests -q passes with tests asserting
  last_run(path) returns {&quot;last_run&quot;: &quot;&amp;#x3C;ts&gt;&quot;} for a valid file and
  {&quot;last_run&quot;: None} for a missing file
- pr: -
- notes: new function in api/src/last_run.py; health() untouched. No HTTP
  layer here (see B-010).

## B-009 web: status page shows the last run
- repo: web
- status: draft
- depends_on: [B-006]
- tier: build
- spec: specs/web/002-status-page.md
- acceptance: web/public/status.html exists and contains the text &quot;Last run&quot;
  and a fetch of &quot;/last-run.json&quot;
- pr: -
- notes: needs its own spec first. Default: static page that fetches
  /last-run.json and renders &quot;Last run: &amp;#x3C;ts&gt;&quot; or &quot;never&quot;. OWNER QUESTION: is
  /last-run.json served as a static file (job publishes it beside the site) or
  through an api HTTP route (B-010)? I would pick static, since it adds no
  server to api/.
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The second run changed only the queue, producing six draft children and two decisions the repository could not answer. No application code was written. The &lt;code class=&quot;inline-code&quot;&gt;Home: specs&lt;/code&gt; line identified the kind of work, while the queue itself remained outside a Git repository in this scratch example. The report correctly stated that nothing was committed or pushed.&lt;/p&gt;
&lt;p&gt;The B-009 source-text criterion is limited: it can confirm a file contains the expected text and fetch path. It cannot confirm browser rendering or a working data source. Review that gap before approving the child for implementation. An earlier investigation prompt also omitted whether the job already existed; adding that fact removed an unnecessary clarification.&lt;/p&gt;
&lt;h2 id=&quot;how-it-scales&quot;&gt;How it scales&lt;a href=&quot;https://caskeycoding.com/blog/lesson-6-the-backlog-queue#how-it-scales&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;At the time of the original lesson, my queue held several hundred items across fourteen repositories. A planning pass reviewed answered draft and blocked items when fewer than five items were ready. That pass still needed the recorded answers and approval rules to determine eligibility.&lt;/p&gt;
&lt;p&gt;You own acceptance criteria and model assignments. The agent can propose children, record discovered work as draft, and update the item it holds. Parallel writers require additional coordination; this template demonstrates one session at a time and does not implement a shared task lock.&lt;/p&gt;
&lt;h2 id=&quot;from-the-field&quot;&gt;From the field&lt;a href=&quot;https://caskeycoding.com/blog/lesson-6-the-backlog-queue#from-the-field&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;On July 28, my task runner selected three items in a row whose changes had already merged. The status-recording tool had reverted their completion states. Each run spent its effort confirming work already present in the repositories.&lt;/p&gt;
&lt;p&gt;I added a merge-history check before selection: search for the item identifier and reconcile the queue when its work is already merged. Check that the matching commit actually implements the item before recording completion. A matching identifier alone is insufficient evidence.&lt;/p&gt;
&lt;h2 id=&quot;exercise&quot;&gt;Exercise&lt;a href=&quot;https://caskeycoding.com/blog/lesson-6-the-backlog-queue#exercise&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;Save &lt;code class=&quot;inline-code&quot;&gt;BACKLOG.md&lt;/code&gt; beside the standing file and add the instruction to read it.&lt;/li&gt;
&lt;li&gt;Replace the examples with five numbered tasks. Give each a repository, status, dependencies, acceptance criteria, and relevant spec. Turn undefined work into an investigation that produces draft children.&lt;/li&gt;
&lt;li&gt;Assign each task a model category using &lt;code class=&quot;inline-code&quot;&gt;tier&lt;/code&gt;. If the task still needs requirements decisions, identify those in an investigation first.&lt;/li&gt;
&lt;li&gt;Start a fresh session with the standing file and say &quot;work the next item.&quot; Watch it name the eligible item, work within scope, set review, and stop.&lt;/li&gt;
&lt;li&gt;Review the result and its evidence. Merge accepted code before marking its item done. Review and accept an investigation&apos;s children before completing that investigation.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;youre-done-when&quot;&gt;You&apos;re done when&lt;a href=&quot;https://caskeycoding.com/blog/lesson-6-the-backlog-queue#youre-done-when&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Complete one sufficiently specified item while watching the session. Confirm the chosen item met the dependency rule, the evidence supports its acceptance criteria, only permitted queue entries changed, and the agent stopped after one item. Mark it done only after the required review and merge or acceptance.&lt;/p&gt;
&lt;p&gt;A question about information already available in the item indicates missing context or a reading failure. A question about an unresolved product decision can be correct. The goal is to remove avoidable clarification while preserving necessary approval.&lt;/p&gt;
&lt;h2 id=&quot;common-mistakes&quot;&gt;Common mistakes&lt;a href=&quot;https://caskeycoding.com/blog/lesson-6-the-backlog-queue#common-mistakes&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Vague acceptance criteria make review subjective. Stale status repeats completed work. Editing unrelated items can change another task&apos;s priority or requirements. Assigning an unresolved design decision to a model intended for prescribed steps does not remove that decision.&lt;/p&gt;
&lt;h2 id=&quot;further-reading&quot;&gt;Further reading&lt;a href=&quot;https://caskeycoding.com/blog/lesson-6-the-backlog-queue#further-reading&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;&lt;a href=&quot;https://github.com/CaskeyCoding/loop-harness&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;loop-harness&lt;/a&gt; provides the public schema and generator skill used in my setup. &lt;a href=&quot;https://kanbanguides.org/english/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;The Kanban Guide&lt;/a&gt; describes work-in-progress limits and workflow policies. Bill Wake&apos;s &lt;a href=&quot;https://xp123.com/articles/invest-in-good-stories-and-smart-tasks/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;INVEST&lt;/a&gt; describes criteria for useful work items.&lt;/p&gt;
&lt;h2 id=&quot;next-lesson&quot;&gt;Next lesson&lt;a href=&quot;https://caskeycoding.com/blog/lesson-6-the-backlog-queue#next-lesson&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;&lt;a href=&quot;https://caskeycoding.com/blog/lesson-7-the-pipeline-reviews&quot; class=&quot;internal-link&quot;&gt;Automate Code Review, Merge Checks, and Deployment Verification&lt;/a&gt; adds independent review and checks at each stage of a change.&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>Lesson 5: Define What Agents Can Do Without Approval</title>
      <link>https://caskeycoding.com/blog/lesson-5-the-charter</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/lesson-5-the-charter</guid>
      <pubDate>Sun, 04 Oct 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>spec-driven-development</category>
      <category>AI</category>
      <category>engineering-methodology</category>
      <category>agents</category>
      <category>autonomy</category>
      <description>Write down the actions agents may take, the actions requiring your approval, and the evidence they must provide before reporting completion. Includes a permission template and exercises that check whether an agent follows it.</description>
      <content:encoded>&lt;p&gt;&lt;strong&gt;What you&apos;ll learn:&lt;/strong&gt; write a reusable permission file that specifies what an agent may do, what requires your approval, and what evidence belongs in its completion report.
&lt;strong&gt;What you need:&lt;/strong&gt; one ready spec from &lt;a href=&quot;https://caskeycoding.com/blog/lesson-1-the-spec-directory&quot; class=&quot;internal-link&quot;&gt;Lesson 1&lt;/a&gt;, with acceptance checks and excluded work; the repository layout from &lt;a href=&quot;https://caskeycoding.com/blog/lesson-4-boundaries&quot; class=&quot;internal-link&quot;&gt;Lesson 4&lt;/a&gt; or a single repository; and your coding agent.
&lt;strong&gt;Time:&lt;/strong&gt; about an hour to write and test the instructions. &lt;strong&gt;Cost:&lt;/strong&gt; no additional services or subscriptions.&lt;/p&gt;
&lt;h2 id=&quot;the-idea&quot;&gt;The idea&lt;a href=&quot;https://caskeycoding.com/blog/lesson-5-the-charter#the-idea&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;An agent needs explicit rules for actions your task does not mention. Creating a file, running an existing test, adding a dependency, and changing a public route have different consequences. Write down which actions you authorize in advance and which require a new decision.&lt;/p&gt;
&lt;p&gt;I use a file with three sections: permitted actions, actions requiring approval, and completion criteria. A final instruction tells the agent to stop and ask when those sections do not resolve a decision. A charter is written standing authority for a role. It depends on the agent following it; enforceable tool restrictions are separate.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/lesson-5-the-charter-two-rows.svg&quot; alt=&quot;Repeated approval prompts are replaced by CHARTER.md instructions listing permitted actions, required approvals, and completion evidence. A complying agent reports its result or stops with a question.&quot;&gt;&lt;/p&gt;
&lt;h2 id=&quot;why-start-here&quot;&gt;Why start here&lt;a href=&quot;https://caskeycoding.com/blog/lesson-5-the-charter#why-start-here&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The preceding lessons define the requested behavior, its rationale, checks, and repository scope. They do not specify every action an agent may take during implementation. A ready spec can authorize a feature while leaving a new dependency undecided.&lt;/p&gt;
&lt;p&gt;The idea of defining authority once per role came from &lt;a href=&quot;https://www.skool.com/cliefnotes&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Clief Notes&lt;/a&gt;. The sections below are my version. Existing tool permission settings still apply; writing this file is not a reason to disable them.&lt;/p&gt;
&lt;h2 id=&quot;the-template&quot;&gt;The template&lt;a href=&quot;https://caskeycoding.com/blog/lesson-5-the-charter#the-template&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Save &lt;code class=&quot;inline-code&quot;&gt;CHARTER.md&lt;/code&gt; beside the standing instruction file in the directory where you launch sessions. Additional roles can use &lt;code class=&quot;inline-code&quot;&gt;CHARTER-&amp;#x3C;role&gt;.md&lt;/code&gt;. In this template, &lt;code class=&quot;inline-code&quot;&gt;home&lt;/code&gt; means the repository assigned to the task:&lt;/p&gt;
&lt;pre class=&quot;shiki shiki-themes github-light github-dark&quot; style=&quot;background-color:#fff;--shiki-dark-bg:#24292e;color:#24292e;--shiki-dark:#e1e4e8&quot; tabindex=&quot;0&quot; data-language=&quot;markdown&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold&quot;&gt;# Builder: standing authority&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;Scope: one change at a time, from one ready spec, inside one home.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold&quot;&gt;## You may, without asking&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; Pick names, layout, and patterns, and use any library already in the project.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; Create or move files wherever the spec&apos;s scope reaches, and delete the ones it makes obsolete.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; Cover what you change with tests, and update the docs that describe it.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; Run any command that only reads, builds, or tests, inside your own checkout.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; Draft a decision record when you choose between two reasonable options, with its Decision line marked proposed for me to confirm.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold&quot;&gt;## You must ask before&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; Adding a dependency the project does not already have, or any new external service or cloud resource.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; Changing an interface the spec names as existing: a route, a schema, a public function.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; Deleting data, running a migration, rotating a secret, or any step you could not undo.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; Rewriting history: force-push, branch deletion, amending a commit you did not make.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; Touching a second home: another repository, another stack.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold&quot;&gt;## Done means&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; Every acceptance line in the spec passes and its verify command exited 0, both run in this session, and the closing message says so.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; Nothing listed under the spec&apos;s Out of scope changed.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; The work is on a fresh branch, pushed if the home has a remote, one commit per repository.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; Your closing message answers four questions in this order: what shipped; which choices you made between reasonable options, and why; what the spec could be read to demand that you left out, and why; which follow-ups deserve a spec of their own.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold&quot;&gt;## When you are not sure&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;Come back with the question. Write it in one line, name the two answers you can see, say which you would pick and why, and stop. Never guess, and never narrow or widen the task to avoid asking.&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Add this line to the session&apos;s standing file:&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;Read CHARTER.md before starting any task; it is your standing authority. Anything under &quot;You must ask before&quot; stops the task until I answer.
&lt;/code&gt;&lt;/pre&gt;
&lt;h2 id=&quot;each-part-and-the-mistake-it-prevents&quot;&gt;Each part, and the mistake it prevents&lt;a href=&quot;https://caskeycoding.com/blog/lesson-5-the-charter#each-part-and-the-mistake-it-prevents&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The scope line restricts the role to one ready spec and one repository. Individual specs still determine which files and behaviors belong to each task.&lt;/p&gt;
&lt;p&gt;The permitted-actions section records routine decisions you are willing to delegate. It lets the agent choose names, use installed libraries, and run relevant checks without requesting the same approval each time. Review the wording against your environment before adopting it. A command described as a test can still contact a service or change data.&lt;/p&gt;
&lt;p&gt;The approval section names recognizable actions. &quot;Rotating a secret&quot; can be compared with a proposed command; &quot;be careful&quot; does not specify when to stop. Write these requirements from your project&apos;s actual dependencies, interfaces, and data operations.&lt;/p&gt;
&lt;p&gt;The completion section requires evidence and a report of choices, omissions, and follow-up work. Check the evidence against each acceptance criterion. A zero exit status supports only what the command tested. The template&apos;s &quot;what shipped&quot; label means the reported implementation result; a branch and passing tests do not establish deployment.&lt;/p&gt;
&lt;p&gt;For unresolved choices, the template requests a short question, two options, and a recommendation. That helps you make the decision without reconstructing the investigation. The agent should identify uncertainty before taking the action that requires approval.&lt;/p&gt;
&lt;h2 id=&quot;a-worked-example&quot;&gt;A worked example&lt;a href=&quot;https://caskeycoding.com/blog/lesson-5-the-charter#a-worked-example&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The recorded exercise used Lesson 4&apos;s four repositories and &lt;code class=&quot;inline-code&quot;&gt;specs/api/002-health.md&lt;/code&gt;. It required a &lt;code class=&quot;inline-code&quot;&gt;health()&lt;/code&gt; function returning &lt;code class=&quot;inline-code&quot;&gt;{&quot;ok&quot;: true}&lt;/code&gt; and a test. Server wiring, &lt;code class=&quot;inline-code&quot;&gt;web/&lt;/code&gt;, and &lt;code class=&quot;inline-code&quot;&gt;infra/&lt;/code&gt; were excluded. A fresh session received the standing file and a request to implement the spec on a branch:&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;`health()` now returns `{&quot;ok&quot;: True}`, and the work is committed on branch
`002-health` [the session&apos;s branch name, shortened] in `api/` (commit
`3eb7c00`, off `main`). `python -m pytest
api/tests -q` ran from the project root in this session and exited 0 (1
passed).

I changed two files, both inside the api home: `api/src/health.py` and
`api/tests/test_health.py`. The test asserts the return value. Nothing under
the spec&apos;s Out of scope changed. The commit is local only, because `api` has
no remote to push to. I staged the two files by path, and the new
`__pycache__` folders are left untracked.

**Choices between reasonable options**
- **Test imports:** the test adds `api/src` to `sys.path` itself instead of
  using a `conftest.py` or packaging config. That keeps the change to two
  files and adds no dependency. The spec&apos;s verify command runs from the
  project root, which is why an import path is needed at all.
[one bullet about a commit hook on my machine omitted]

**Left out:** I added no HTTP route, framework, or packaging, since the spec
rules those out.

**Follow-ups for their own spec:** wiring `health()` into a route, and adding
a `.gitignore` for `__pycache__` and `.pytest_cache` in `api/`.
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The return-value test checked a local function. The report also named the two changed files, the local-only commit, and the excluded server work. It did not show a working HTTP endpoint or deployment, neither of which the spec requested.&lt;/p&gt;
&lt;p&gt;A second run requested an uptime ping to a hosted status page every minute. That added an external service and scheduling work. The session stopped before editing:&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;I haven&apos;t changed anything yet. The uptime ping needs your answer first, and
CHARTER.md says that stops the task.

**Question:** The hosted status page is a new external service, and a
per-minute ping is a scheduled job that would live in `infra/` or `api/`. Do
you want a spec for the ping first, or should I build it as a scheduled job
inside `api/`, with the status-page URL and token supplied by you?

- **A (spec first):** You write or approve a spec that names the status-page
  provider and the home. `specs/api/002-health.md` covers only the bare
  `health()` function, and it lists infra/ and HTTP wiring as out of scope.
  I&apos;d do the health function now on a branch and leave the ping for its own
  spec. I&apos;d pick this, because the ping is a second change that adds an
  external service, and the layout skill says to write the spec first.
- **B (ping inside `api/`):** You tell me which provider to use and approve
  the new service, and I add the ping to `api/` as a scheduled job. It would
  need a spec amendment, since 002 currently excludes anything beyond the bare
  function.

I can start `health()` and its test on a fresh `api/` branch right away if you
say go.
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;All four repositories remained clean after this request. The two runs show that the agent followed the written instructions for these tasks. They do not establish that later sessions will always comply.&lt;/p&gt;
&lt;h2 id=&quot;how-it-scales&quot;&gt;How it scales&lt;a href=&quot;https://caskeycoding.com/blog/lesson-5-the-charter#how-it-scales&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;On June 9, I wrote five files in one afternoon for the builder, content, monitor, task runner, and interface-review roles. Each used the same sections, with different permitted actions. A monitor can be limited to reading and notifying, with every write requiring approval.&lt;/p&gt;
&lt;p&gt;You decide the approval requirements and completion criteria. An agent can propose permitted actions based on recent tasks, but you approve the list. Record changes to standing authority with their reasons in a &lt;a href=&quot;https://caskeycoding.com/blog/lesson-2-decision-records&quot; class=&quot;internal-link&quot;&gt;decision record&lt;/a&gt;, so later sessions can identify the approved version.&lt;/p&gt;
&lt;h2 id=&quot;from-the-field&quot;&gt;From the field&lt;a href=&quot;https://caskeycoding.com/blog/lesson-5-the-charter#from-the-field&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;An unattended agent on a small always-on Linux box at home read one of these files. Its approval requirements were also represented in tool-level deny rules. The agent attempted a command requiring approval. A rule denied it before execution, and the agent stopped instead of trying another route.&lt;/p&gt;
&lt;p&gt;The written instruction did not prevent the attempt. The permission rule prevented that command from running. This incident supports a specific distinction: instructions define the expected behavior, while a configured control can reject an action within its coverage. That one denial does not establish coverage for every prohibited action.&lt;/p&gt;
&lt;h2 id=&quot;exercise&quot;&gt;Exercise&lt;a href=&quot;https://caskeycoding.com/blog/lesson-5-the-charter#exercise&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;Save &lt;code class=&quot;inline-code&quot;&gt;CHARTER.md&lt;/code&gt; beside the standing file and add the instruction to read it.&lt;/li&gt;
&lt;li&gt;Replace the approval list with concrete actions relevant to your project. Include the operations you need to review before execution.&lt;/li&gt;
&lt;li&gt;Ask the agent to propose permitted actions from recent tasks. Remove any action you still want to approve individually.&lt;/li&gt;
&lt;li&gt;Give a fresh session one ready spec. Compare its completion report with the criteria, inspect the evidence, and check the diff for excluded work.&lt;/li&gt;
&lt;li&gt;Request an action requiring approval, such as the uptime ping. Confirm the session asks before editing or executing that action. Perform this check in a disposable project with appropriate tool restrictions.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;youre-done-when&quot;&gt;You&apos;re done when&lt;a href=&quot;https://caskeycoding.com/blog/lesson-5-the-charter#youre-done-when&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The permitted task should finish within its scope and report the evidence, choices, omissions, and follow-ups. The approval case should stop before the restricted action and provide the question and options. Inspect the files and command record instead of relying only on the final message.&lt;/p&gt;
&lt;p&gt;If the agent asks about an already authorized action, inspect the wording and the context it received. If it performs an action requiring approval, the instruction check failed. Review both instruction delivery and tool-level enforcement before allowing that action unattended.&lt;/p&gt;
&lt;h2 id=&quot;common-mistakes&quot;&gt;Common mistakes&lt;a href=&quot;https://caskeycoding.com/blog/lesson-5-the-charter#common-mistakes&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Vague approval rules leave the agent to decide what counts as risky. Missing completion criteria leave you to reconstruct the task afterward. Written instructions alone cannot establish that a prohibited command will be denied; test the relevant permission control separately.&lt;/p&gt;
&lt;h2 id=&quot;further-reading&quot;&gt;Further reading&lt;a href=&quot;https://caskeycoding.com/blog/lesson-5-the-charter#further-reading&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Saltzer and Schroeder&apos;s &lt;a href=&quot;https://www.cs.virginia.edu/~evans/cs551/saltzer/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;The Protection of Information in Computer Systems&lt;/a&gt; describes least privilege. The &lt;a href=&quot;https://code.claude.com/docs/en/permissions&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Claude Code permissions reference&lt;/a&gt; documents tool permission rules. The &lt;a href=&quot;https://agents.md/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;AGENTS.md convention&lt;/a&gt; describes a format for standing agent instructions.&lt;/p&gt;
&lt;h2 id=&quot;next-lesson&quot;&gt;Next lesson&lt;a href=&quot;https://caskeycoding.com/blog/lesson-5-the-charter#next-lesson&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;&lt;a href=&quot;https://caskeycoding.com/blog/lesson-6-the-backlog-queue&quot; class=&quot;internal-link&quot;&gt;&lt;strong&gt;Lesson 6: Build a Task Queue Agents Can Follow&lt;/strong&gt;&lt;/a&gt; defines how agents select work from a backlog (the project&apos;s task queue) and when they must stop.&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>Eight minutes to an app, and what that leaves to teach</title>
      <link>https://caskeycoding.com/blog/eight-minute-french-flashcards</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/eight-minute-french-flashcards</guid>
      <pubDate>Thu, 24 Sep 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>AI</category>
      <category>mentoring</category>
      <category>education</category>
      <category>volunteering</category>
      <category>side-projects</category>
      <description>An eight-minute vibe-coding challenge at a Mouse AI League mentor mixer, where I volunteer as a mentor and judge: an AI agent built a French flashcard app in eight minutes, and the speed of the machine is what makes product judgment the skill worth teaching high schoolers.</description>
      <content:encoded>&lt;p&gt;I volunteer as a mentor with &lt;a href=&quot;https://mouse.org/aileague&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Mouse AI League&lt;/a&gt;, a year-long program in which high school students learn how AI systems work, practice human-centered design, do market research, and ship an interactive app prototype over six sprints. Last year I judged the students&apos; final projects when they came to an Amazon office to present them. This year, at a mentor mixer, the organizers handed the mentors an AI coding agent and eight minutes. Mine produced a French flashcard app in one HTML file: 72 words in five decks, a spaced-repetition scheduler, spoken pronunciation, and progress that survives a reload. &lt;a href=&quot;https://caskeycoding.com/cahier-francais-app.html&quot; class=&quot;internal-link&quot;&gt;It runs here&lt;/a&gt;. The agent did the typing in those eight minutes. I spent the same eight on five decisions, and the decisions are what I want the students to look at.&lt;/p&gt;
&lt;h2 id=&quot;the-machine-typed-487-lines-and-i-made-five-decisions&quot;&gt;The machine typed 487 lines and I made five decisions&lt;a href=&quot;https://caskeycoding.com/blog/eight-minute-french-flashcards#the-machine-typed-487-lines-and-i-made-five-decisions&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The agent wrote the scheduler, a simplified version of SM-2, the 1987 algorithm that Anki still descends from. It wired the browser&apos;s own speech engine to read each word in a French voice, put the review history in the browser&apos;s local storage, and laid out a card on the ruled paper of a French exercise book, for phone and desktop, in 487 lines. None of that took a question from me beyond the brief: one page, no framework, no build step.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/eight-minute-french-flashcards-agent-and-judgment.svg&quot; alt=&quot;Two boxes side by side. The left, in grey, lists what the agent typed in eight minutes: a spaced-repetition scheduler, browser speech with a French voice, saved progress across reloads, the phone and desktop layout, 487 lines in one file. The right, highlighted in green, lists what I decided: which 72 words, eight new words a day, le and la printed in color, one example sentence per card, and progress that stays on one device.&quot;&gt;&lt;/p&gt;
&lt;p&gt;The decisions were mine. Which 72 words: greetings, the café, directions, the core verbs, numbers and time, the vocabulary of a first week in France rather than a frequency list. Eight new words a day, because a deck learned in one sitting all comes due on the same afternoon and day three becomes a wall. The article printed with the noun and colored by gender, blue for le and rose for la, because &quot;le pain&quot; is the unit a learner has to carry and &quot;pain&quot; on its own is half a word. One example sentence on every card, since &quot;the bill&quot; is a fact and &quot;L&apos;addition, s&apos;il vous plaît&quot; is a sentence you will say at a table. And one trade I made knowingly: progress lives in one browser and does not follow you to your phone, which kept the whole build to a single file with no account behind it.&lt;/p&gt;
&lt;p&gt;None of those five needed a line of code. All five decide whether the app is worth opening twice. That is the ratio the League&apos;s curriculum is built on. The prototype is one item on a sixty-hour syllabus; the rest of the hours go to who the user is, what they already do instead, and whether the design serves them.&lt;/p&gt;
&lt;h2 id=&quot;the-feedback-loop-is-now-shorter-than-a-class-period&quot;&gt;The feedback loop is now shorter than a class period&lt;a href=&quot;https://caskeycoding.com/blog/eight-minute-french-flashcards#the-feedback-loop-is-now-shorter-than-a-class-period&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The agent&apos;s first phone layout scrolled sideways. I only knew because I rendered the page at 400 pixels wide and looked, and the fix, two CSS values, took under a minute. That loop, build, look, fix, ran three times inside the challenge. A responsive-design lecture would still have been on its fourth slide.&lt;/p&gt;
&lt;p&gt;That loop is what the speed of the machine gives a sixteen-year-old. The distance between an idea and a version someone else can hold used to be a semester of syntax, and most ideas did not survive the semester. Now a student who has spent a sprint interviewing users can put a running prototype in front of those same users the week after, and find out that afternoon that the font is too small or the third screen is the one people wanted first. Human-centered design has always taught that lesson with sticky notes and paper mockups. A prototype that runs teaches it with the user&apos;s own thumb on the screen, and the correction costs minutes instead of a rebuild.&lt;/p&gt;
&lt;p&gt;It also changes what a judge can assume. When the students present this year, the code will run; the agent makes it run. What separates the entries is whether the student can name who the app is for, what it does on the first screen, and what it deliberately leaves out. The student who says &quot;it does not sync between devices, because we wanted to ship without accounts&quot; has made a product decision and can defend it. That is the answer I am listening for, and it is a harder skill than syntax ever was, because there is no compiler to tell you when it is wrong.&lt;/p&gt;
&lt;h2 id=&quot;what-sixty-hours-buys-at-that-price&quot;&gt;What sixty hours buys at that price&lt;a href=&quot;https://caskeycoding.com/blog/eight-minute-french-flashcards#what-sixty-hours-buys-at-that-price&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The brief I gave the agent was three constraints long, and everything the brief did not say, the agent chose, which meant I had to look at all of it. Writing the brief and reviewing the result are the two skills the challenge exercises, and both are the skills the League&apos;s sprints spend the year on under other names: define the user, scope the problem, test the prototype, revise.&lt;/p&gt;
&lt;p&gt;The cost of a wrong product decision used to be measured in weeks of code thrown away. On this build the daily cap is one constant and the interval table is six numbers; either is a one-minute edit. Sixty hours is enough time to be wrong a hundred times at that price, and a hundred corrected decisions is more product judgment than most of us had when we started getting paid for it.&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>How do you know the compiler actually vectorized your loop?</title>
      <link>https://caskeycoding.com/blog/how-do-you-know-the-compiler-vectorized-your-loop</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/how-do-you-know-the-compiler-vectorized-your-loop</guid>
      <pubDate>Thu, 24 Sep 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>C++</category>
      <category>simd</category>
      <category>performance</category>
      <category>compilers</category>
      <category>quant</category>
      <description>My build log said the loop was vectorized, and it had: a trivial loop at the end of the benchmark. The pricing loop, the one with exp and log in it, stayed scalar until I wrote the four-wide math by hand and the engine went from about 114 million to about 215 million options a second. Three checks that catch a claimed win, and what the numbers look like when SIMD is real.</description>
      <content:encoded>&lt;p&gt;My options pricer&apos;s build log said &quot;loop vectorized&quot;, but the pricing loop was still scalar. The success message belonged to a trivial loop at the end of the benchmark. To check the loop that matters, enable both successful and missed-vectorization reports on your optimized build, then match each message to its source file and line.&lt;/p&gt;
&lt;h2 id=&quot;compiler-flags-for-vectorization-reports&quot;&gt;Compiler flags for vectorization reports&lt;a href=&quot;https://caskeycoding.com/blog/how-do-you-know-the-compiler-vectorized-your-loop#compiler-flags-for-vectorization-reports&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Compiler&lt;/th&gt;
&lt;th&gt;Report successful vectorization&lt;/th&gt;
&lt;th&gt;Report misses and reasons&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;MSVC&lt;/td&gt;
&lt;td&gt;&lt;code class=&quot;inline-code&quot;&gt;/Qvec-report:1&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code class=&quot;inline-code&quot;&gt;/Qvec-report:2&lt;/code&gt; includes successes and misses with reason codes.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;GCC&lt;/td&gt;
&lt;td&gt;&lt;code class=&quot;inline-code&quot;&gt;-fopt-info-vec-optimized&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code class=&quot;inline-code&quot;&gt;-fopt-info-vec-missed&lt;/code&gt; reports missed vectorization opportunities.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Clang&lt;/td&gt;
&lt;td&gt;&lt;code class=&quot;inline-code&quot;&gt;-Rpass=loop-vectorize&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code class=&quot;inline-code&quot;&gt;-Rpass-missed=loop-vectorize&lt;/code&gt; reports misses; &lt;code class=&quot;inline-code&quot;&gt;-Rpass-analysis=loop-vectorize&lt;/code&gt; identifies the statements responsible.&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;These are reporting options for an optimized build. They do not force the compiler to vectorize a loop. The flags are documented by &lt;a href=&quot;https://learn.microsoft.com/en-us/cpp/build/reference/qvec-report-auto-vectorizer-reporting-level?view=msvc-170&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Microsoft&lt;/a&gt;, &lt;a href=&quot;https://gcc.gnu.org/onlinedocs/gcc/Developer-Options.html#index-fopt-info&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;GCC&lt;/a&gt;, and &lt;a href=&quot;https://llvm.org/docs/Vectorizers.html#diagnostics&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;LLVM&lt;/a&gt;. MSVC is the only one I ran on this engine. After locating the right loop in the report, measure it on one core and check the results against the scalar implementation.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/how-do-you-know-the-compiler-vectorized-your-loop-report.svg&quot; alt=&quot;A benchmark with two loops beside a compiler report with two lines: the green &amp;#x22;loop vectorized&amp;#x22; line points at the trivial trailing loop, and the red &amp;#x22;loop not vectorized&amp;#x22; line, never asked for, points at the pricing loop that calls exp and log.&quot;&gt;&lt;/p&gt;
&lt;h2 id=&quot;the-report-was-true-about-the-wrong-loop&quot;&gt;The report was true about the wrong loop&lt;a href=&quot;https://caskeycoding.com/blog/how-do-you-know-the-compiler-vectorized-your-loop#the-report-was-true-about-the-wrong-loop&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The pricer is the Black-Scholes engine from &lt;a href=&quot;https://caskeycoding.com/blog/pricing-215-million-options-a-second&quot; class=&quot;internal-link&quot;&gt;the 215 million post&lt;/a&gt;. A clean first version priced about fifteen million options a second on one core. Swapping one modern library call for a sixty-year-old polynomial and threading the embarrassingly parallel loop took it to about 114 million, and none of that came from SIMD. The plan had always assumed the compiler would vectorize the clean inner loop on its own, because that is what the guides say, and because the build log agreed.&lt;/p&gt;
&lt;p&gt;My compiler, MSVC, prints a line for each loop it vectorizes when asked, and my build log had one: a trivial loop at the end of the benchmark. The loop that priced options calls exp and log, and my compiler would not fold a loop full of library calls into vector form. Some toolchains will; mine did not. Its failure notice for the pricing loop sat in a report I had not opened, so the loop that mattered stayed scalar on every build while the log kept reporting a win.&lt;/p&gt;
&lt;p&gt;The numbers needed the same separation. The jump from fifteen million to 114 million came from a better polynomial and more cores, with no SIMD in it. Four lanes describe how many values a vector operation handles; they do not establish how much faster the whole loop will run.&lt;/p&gt;
&lt;h2 id=&quot;test-each-vector-function-before-wiring-it-in&quot;&gt;Test each vector function before wiring it in&lt;a href=&quot;https://caskeycoding.com/blog/how-do-you-know-the-compiler-vectorized-your-loop#test-each-vector-function-before-wiring-it-in&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;I wrote the exponential and the logarithm four wide, from classic polynomial cores, intrinsics all the way down. Before wiring either into the pricer I tested each one in isolation against the standard library, the exponential against the exponential rather than the pricer against the pricer. When a bug showed up, the isolated test named the function instead of leaving me to chase a wrong price three layers downstream. One core gained about four times, and across all cores the engine reached about 215 million a second. The rewrite changed both the math implementation and the execution width, so those timings do not isolate the gain from SIMD alone.&lt;/p&gt;
&lt;h2 id=&quot;three-checks-that-catch-a-claimed-win&quot;&gt;Three checks that catch a claimed win&lt;a href=&quot;https://caskeycoding.com/blog/how-do-you-know-the-compiler-vectorized-your-loop#three-checks-that-catch-a-claimed-win&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Ask the compiler for its misses using the flags above. Match each message to a source line and find the loop you care about. A report with only successes in it says nothing about the loop that is missing from it.&lt;/p&gt;
&lt;p&gt;Measure the loop on one core before measuring all of them. If the gain is smaller than expected, first confirm that the reported loop does the work you timed. Then investigate memory traffic, scalar work left in the loop, and overhead on short loops. A smaller gain can have several causes; a larger gain can include changes beyond SIMD. Keep the input, thread count, and math implementation comparable when trying to attribute the difference.&lt;/p&gt;
&lt;p&gt;Test the vector functions against the scalar library, one function at a time. This says nothing about what the compiler did. It checks the code you wrote to replace the compiler, over the inputs and tolerances you chose, which is the check you need the moment you stop trusting the report.&lt;/p&gt;
&lt;h2 id=&quot;treat-the-published-timings-as-a-shape&quot;&gt;Treat the published timings as a shape&lt;a href=&quot;https://caskeycoding.com/blog/how-do-you-know-the-compiler-vectorized-your-loop#treat-the-published-timings-as-a-shape&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The engine is not public and I have not re-run it for this post, so every number here is the one I published in July, and desktop timings wander ten or twenty percent run to run. Read fifteen, 114 and 215 as a shape. It was built to learn from, and none of it is a trading system. The compiler flags above are the general ones from each toolchain&apos;s documentation; MSVC&apos;s is the only one I ran on this code.&lt;/p&gt;
&lt;p&gt;If I built the pricer again, the benchmark would carry the check itself: single-core throughput of the vector build against the scalar build on the same machine, with a floor set from repeated runs, so that a build where the width has gone missing fails on the spot instead of shipping behind a success line in the log.&lt;/p&gt;
&lt;hr&gt;
&lt;p&gt;&lt;strong&gt;Related:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;https://caskeycoding.com/blog/pricing-215-million-options-a-second&quot; class=&quot;internal-link&quot;&gt;Pricing 215 million options a second with SIMD C++&lt;/a&gt;, the full climb from fifteen million to 215 million, including the memory-layout guess that came before this one&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://caskeycoding.com/blog/backtesting-without-fooling-yourself&quot; class=&quot;internal-link&quot;&gt;How to backtest without fooling yourself&lt;/a&gt;, the same measure-before-believing discipline pointed at signals instead of speed&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://caskeycoding.com/blog/lesson-3-the-check-that-fails&quot; class=&quot;internal-link&quot;&gt;Lesson 3: Enforce Project Rules with Automated Checks&lt;/a&gt;, designing checks that reject a known failure&lt;/li&gt;
&lt;/ul&gt;</content:encoded>
    </item>
    <item>
      <title>How many AI coding agents can you actually run at once?</title>
      <link>https://caskeycoding.com/blog/how-many-ai-coding-agents-at-once</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/how-many-ai-coding-agents-at-once</guid>
      <pubDate>Thu, 24 Sep 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>AI</category>
      <category>agents</category>
      <category>claude-code</category>
      <category>orchestration</category>
      <category>worktrees</category>
      <description>I cap my setup at roughly ten coding agents across several subscriptions, with three or four per vendor. A seven-agent wave exposed failures in network access, checkouts, test ports, and generated files. The counts and the preflight checks I use before another run.</description>
      <content:encoded>&lt;p&gt;I cap my setup at roughly ten concurrent coding agents across several subscriptions, usually three or four per vendor. That number comes from running this workload on my machine. The constraints I have hit are the link to the vendor and its quota window, the git checkout, the network port the test suite binds, and the file every branch regenerates.&lt;/p&gt;
&lt;h2 id=&quot;before-launching-parallel-coding-agents&quot;&gt;Before launching parallel coding agents&lt;a href=&quot;https://caskeycoding.com/blog/how-many-ai-coding-agents-at-once#before-launching-parallel-coding-agents&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Shared resource&lt;/th&gt;
&lt;th&gt;Check before starting the wave&lt;/th&gt;
&lt;th&gt;When I stop adding workers&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Vendor connection and quota&lt;/td&gt;
&lt;td&gt;Check that a single CLI run completes, then allocate workers across the subscriptions available.&lt;/td&gt;
&lt;td&gt;Launches fail or the quota window is exhausted; I inspect the error and connection before retrying.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Checkout and dependencies&lt;/td&gt;
&lt;td&gt;Give each worker a separate git worktree and a real dependency install. Record the commit under test.&lt;/td&gt;
&lt;td&gt;Verification would use a checkout another session can move.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Test-server port&lt;/td&gt;
&lt;td&gt;Check which process owns the test port. Keep full verification serial while suites share it.&lt;/td&gt;
&lt;td&gt;Another verification is already using that port.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Generated files&lt;/td&gt;
&lt;td&gt;Name the files each build regenerates, even when the source edits do not overlap.&lt;/td&gt;
&lt;td&gt;A branch needs rebasing and regeneration after the previous merge.&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;I bind the passing checks to the commit being reviewed; the &lt;a href=&quot;https://caskeycoding.com/blog/local-first-ci-pre-push-hook-is-the-gate&quot; class=&quot;internal-link&quot;&gt;local CI gate&lt;/a&gt; explains that record. The &lt;a href=&quot;https://caskeycoding.com/blog/what-a-month-of-ai-coding-agents-costs&quot; class=&quot;internal-link&quot;&gt;monthly agent cost breakdown&lt;/a&gt; records the subscriptions behind this setup. Neither a worker count nor a subscription price tells me how many branches I can finish verifying in an hour.&lt;/p&gt;
&lt;h2 id=&quot;what-happened-in-a-seven-agent-wave&quot;&gt;What happened in a seven-agent wave&lt;a href=&quot;https://caskeycoding.com/blog/how-many-ai-coding-agents-at-once#what-happened-in-a-seven-agent-wave&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The day before I wrote this, I ran seven at once and kept a tally of what gave way. The job was a batch of site fixes from a traffic audit: retitle thirteen posts, add a series hub, fix the footer and a dozen links, gate an analytics tag, wire a post-deploy ping, and wire a new exporter into a CDK stack. Each fix had a written brief with the exact files, the verify commands, and an out-of-scope list. I run worker CLIs from three vendors. I put three briefs on one CLI and four on another, each in its own git worktree, and started them within the same minute.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/how-many-ai-coding-agents-at-once-gate.svg&quot; alt=&quot;Seven small agent boxes on the left with arrows converging on one green gate box labeled one verification at a time, with the counts 7 agents typing in parallel and 1 branch verifying at a time beside it.&quot;&gt;&lt;/p&gt;
&lt;h2 id=&quot;the-link-to-the-vendor-gives-way-first&quot;&gt;The link to the vendor gives way first&lt;a href=&quot;https://caskeycoding.com/blog/how-many-ai-coding-agents-at-once#the-link-to-the-vendor-gives-way-first&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Two of the four launches on the second CLI exited within three minutes with nothing written. No error text, exit code 1, a thread that had read the brief and then stopped. A third wrote one component and died; the fourth wrote a footer link and died. When I probed that CLI by hand the failure was hostname resolution, Windows error 11002, and my home connection was flapping that hour: pushes to the code host were failing on the same resolution error. That one is on my network. The other CLI, reached over the same connection, stayed up through the flap, and I re-dispatched the four briefs to it rather than wait for the line to settle.&lt;/p&gt;
&lt;p&gt;The quota itself has been the ceiling once, and that one was mine to cause. On 2026-07-06 a wave of frontier-tier subagents tripped the subscription&apos;s limits, and the routing rule that came out of it is the one I still run: the frontier model supervises alone, at the session level, and never fans out to copies of itself. Workers run on cheaper tiers or on other vendors&apos; subscriptions, capped at roughly ten concurrent, and each vendor gets three or four at a time, not seven. The quota window is a shared resource the same way a database connection pool is, and the agents draining it do not coordinate. A flapping resolver is the same resource failing from the other end.&lt;/p&gt;
&lt;h2 id=&quot;the-checkout-gives-way-second&quot;&gt;The checkout gives way second&lt;a href=&quot;https://caskeycoding.com/blog/how-many-ai-coding-agents-at-once#the-checkout-gives-way-second&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Every worker had its own worktree, so the agents never touched each other&apos;s files. The shared state that bit was the canonical checkout, the one directory with the real dependencies installed, because the merge gate&apos;s full verification wanted to run there. Another session on the same machine was using it for the same purpose at the same time. The reflog for that hour reads like two people grabbing the same steering wheel: detach to their commit, detach to mine, back to theirs, back to main. One of my runs passed every check and then recorded its passing verdict against a commit that was not the one it tested, because the other session had moved the checkout between the last test and the write.&lt;/p&gt;
&lt;p&gt;The fix was to stop sharing the checkout at all. Each worktree got a real copy of the dependency tree, about a gigabyte and two minutes per copy, and the verification ran inside the worktree it was verifying. The cost is disk. The alternative is a verdict recorded against a commit nobody tested.&lt;/p&gt;
&lt;h2 id=&quot;the-port-gives-way-third&quot;&gt;The port gives way third&lt;a href=&quot;https://caskeycoding.com/blog/how-many-ai-coding-agents-at-once#the-port-gives-way-third&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The end-to-end suite starts a local server on port 3000. Two sessions running that suite at once do not get two servers; the second connects to the first session&apos;s server and asserts against the wrong build. Three of my verification runs failed only on the end-to-end lane, with the unit suite green and the same spec passing in isolation seconds later, and every one of them coincided with another attestation holding the port. A failure that reproduces only when a neighbor is running is not a flake. It is a shared resource with no lock on it, and until there is a lock the rule is one full verification at a time, machine-wide.&lt;/p&gt;
&lt;h2 id=&quot;the-generated-file-gives-way-last&quot;&gt;The generated file gives way last&lt;a href=&quot;https://caskeycoding.com/blog/how-many-ai-coding-agents-at-once#the-generated-file-gives-way-last&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Five branches merged in sequence, and every one had to be rebased onto the main that the previous merge had just moved. Two of them conflicted, both on the same file: the blog index that the build regenerates from post frontmatter. Two agents that never edited the same source file still collided, because the build had written the same derived artifact on both branches. The resolution is mechanical once you know it, take main&apos;s copy, regenerate, continue, but it has to happen on every branch, and a wave of ten guarantees it happens ten times.&lt;/p&gt;
&lt;p&gt;The same class of problem produced the worst moment of the day. Cleaning up, I removed the finished worktrees with the version control tool&apos;s own remove command. Their &lt;code class=&quot;inline-code&quot;&gt;node_modules&lt;/code&gt; directories were junctions into the canonical checkout, and the recursive delete followed the junctions and emptied the canonical dependency tree for two repositories, which cost every session building from those checkouts its toolchain until a reinstall finished. Nothing in version control showed it, because the directory is ignored. The teardown procedure now checks for junctions and unlinks them before any delete, and it caught a second one on the very next run, planted by the build tool inside its own cache directory.&lt;/p&gt;
&lt;h2 id=&quot;what-ten-agents-buy&quot;&gt;What ten agents buy&lt;a href=&quot;https://caskeycoding.com/blog/how-many-ai-coding-agents-at-once#what-ten-agents-buy&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The seven agents finished their edits inside about forty minutes of wall clock, most of it waiting on the four that had to be re-dispatched. Landing the five resulting branches took roughly four more hours, because each one had to be rebased, pushed, verified for about eight minutes through a gate that admits one branch at a time, and merged before the next could start, and three of those verifications had to run twice. Typing was parallel. Everything that made the typing safe to keep was serial.&lt;/p&gt;
&lt;p&gt;That ratio is the actual answer to the question. Agents are cheap to add up to the point where the quota, the checkout, the port, or the generated file pushes back, and each of those pushes back at a different count. The number that moved my throughput this year was never the count of agents typing. It was the count of branches I could verify in an hour, and every rule above exists to raise that second number by one.&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>How to make an LLM say I don&apos;t know, and how to measure that it did</title>
      <link>https://caskeycoding.com/blog/how-to-make-an-llm-say-i-dont-know</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/how-to-make-an-llm-say-i-dont-know</guid>
      <pubDate>Thu, 24 Sep 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>AI</category>
      <category>LLM</category>
      <category>RAG</category>
      <category>guardrails</category>
      <category>evaluation</category>
      <description>Ballast declines 24 of its 89 golden questions on purpose and answers the other 65 with citations. As of the August 16 ledger the answer-or-decline call was right on all 89, and one of the 65 answers was unfaithful to its sources. Where the refusal comes from, how the eval scores it, and why 24 is the number to read, not 100 percent.</description>
      <content:encoded>&lt;p&gt;Ballast declines 24 of its 89 golden questions on purpose and answers the other 65 with citations, and on the August 16 run the answer-or-decline call was right on all 89: zero questions it should have declined and answered, zero it should have answered and declined. One of the 65 answers was unfaithful to its sources, which the eval counts as a hallucination rate of 1.1 percent over the whole set. Those three counts are the abstention measurement, and this post is about how each one is produced, because a refusal you cannot count is a mood, not a feature.&lt;/p&gt;
&lt;p&gt;The June post on &lt;a href=&quot;https://caskeycoding.com/blog/ballast-an-llm-that-says-i-dont-know&quot; class=&quot;internal-link&quot;&gt;Ballast&lt;/a&gt; explained why refusal is the feature. What it did not have was a ledger. It described one 44-question evaluation and said, correctly, that a zero on that set was not a universal claim. This post reads only the committed metrics ledger, which now has three dated runs on a set that grew to 89 questions, and a gate that fails the build on regression. That is the artifact worth writing about.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/how-to-make-an-llm-say-i-dont-know-split.svg&quot; alt=&quot;A box labeled 89 golden questions splitting into two arrows: one to 65 answered with citations and 0 wrongly declined, one green to 24 declined and 0 wrongly answered, with the note one of 65 answers unfaithful.&quot;&gt;&lt;/p&gt;
&lt;h2 id=&quot;where-the-refusal-comes-from&quot;&gt;Where the refusal comes from&lt;a href=&quot;https://caskeycoding.com/blog/how-to-make-an-llm-say-i-dont-know#where-the-refusal-comes-from&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;An LLM does not decline on its own. Left to itself it completes the sentence, because that is the only verb it has. Ballast gives it three places to stop before an answer ships, two of them ahead of generation and one behind it, and each one emits a fixed sentence instead of prose.&lt;/p&gt;
&lt;p&gt;The first is the retrieval grader. Every question fetches passages from the corpus and a grader scores each one for relevance. If nothing relevant comes back, the graph rewrites the query and retrieves again, up to two retries, and then declines with a fixed insufficient-evidence sentence rather than handing the model an empty context and hoping. The same retry budget covers the other direction: an answer the critic judges ungrounded goes back through a rewrite, and when the budget is spent the graph declines instead of shipping the answer it could not ground. The second is the guardrails gateway, in two halves. On the way in, a classifier declines requests for personalized, medical or legal advice before generation. On the way out, a YAML policy reads the generated answer, withholds one that gives advice or fails to cite a passage, allows one corrected retry, and then returns a fixed withheld-by-guardrail sentence. The third is the input guardrails, which block prompt injection, secrets and personal data before anything runs and return a fixed could-not-be-processed sentence.&lt;/p&gt;
&lt;p&gt;The fixed sentences are the point of the design and not a stylistic choice. A refusal that the model phrases freely is a refusal the eval cannot find. Three marker phrases are what the scorer looks for.&lt;/p&gt;
&lt;h2 id=&quot;how-the-eval-scores-a-refusal&quot;&gt;How the eval scores a refusal&lt;a href=&quot;https://caskeycoding.com/blog/how-to-make-an-llm-say-i-dont-know#how-the-eval-scores-a-refusal&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The golden set has 89 questions in five categories: 55 answerable, 10 multi-hop, 10 unanswerable from the corpus, 5 out of corpus entirely, and 9 adversarial prompts. Each carries an expected answer or the single word decline; 24 carry decline. The runner asks every question, checks each output for one of the three marker phrases, and scores the pair: should this have been declined, and was it.&lt;/p&gt;
&lt;p&gt;Both mistakes are counted separately, because they cost different amounts. An under-refusal is a question that should have been declined and got an answer, which is the failure that produces a confident fabrication. An over-refusal is an answerable question that got a decline, which is the failure that makes the system useless. Refusal correctness is the share of all 89 where the two flags agree, and the build gate fails below 90 percent. Answered questions are then judged for faithfulness to the retrieved passages. The hallucination rate counts an unfaithful answer and an under-refusal alike, over all 89 questions, and the gate fails above 5 percent.&lt;/p&gt;
&lt;p&gt;The ledger has three rows. The first, June 27, on a 43-question set: refusal correctness 97.7 percent with one under-refusal, every answer faithful, hallucination 2.3 percent, all of it that one under-refusal. The second, July 2, on the 89-question set: 98.9 percent with one under-refusal, one unfaithful answer, hallucination 2.25 percent, injection block rate 100 percent. The third, August 16: 100 percent, zero under, zero over, one unfaithful answer, hallucination 1.1 percent with a bootstrap interval of 0 to 3.4 percent, faithfulness 0.985, and $0.0061 a question. Read by unfaithful answers alone the series is zero, one, one; the fall in the headline rate between July and August is the under-refusal going away, not the grounding improving. Whether that is a fix or run-to-run variance in the model, the gate is what makes the next one visible instead of averaged away.&lt;/p&gt;
&lt;h2 id=&quot;what-100-percent-cannot-promise&quot;&gt;What 100 percent cannot promise&lt;a href=&quot;https://caskeycoding.com/blog/how-to-make-an-llm-say-i-dont-know#what-100-percent-cannot-promise&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Only 24 of the 89 questions are decline questions, and 24 correct out of 24 is a smaller claim than it sounds. Zero misses in 24 trials is consistent with a true miss rate anywhere up to about 12 percent at the usual confidence, the rule of three applied to a sample of that size. The ledger&apos;s own bootstrap band for refusal correctness reads 1.0 to 1.0, and that is not a promise either: resampling a column of ones produces a column of ones, so the interval has zero width by construction, not by evidence. The number to read is 24, and the number to watch is the under-refusal count, which is a count of specific questions and not a rate.&lt;/p&gt;
&lt;p&gt;The detector tests the plumbing as much as the model. A decline phrased in the model&apos;s own words, with a citation attached, passes the must-cite policy and is scored as an answer, which hides an over-refusal; an uncited one is withheld by that same policy and comes out as the fixed sentence, which scores as a refusal. So the 100 percent says that on every question the three stops and the policy resolved to a marker sentence or an answer as intended, and a model that had learned to decline in prose would not be caught by it. The faithfulness judge is calibrated against eight human-labeled pairs with an agreement floor of 0.8, and eight is thin; the calibration set is the next number that has to grow.&lt;/p&gt;
&lt;h2 id=&quot;the-cost-of-refusing&quot;&gt;The cost of refusing&lt;a href=&quot;https://caskeycoding.com/blog/how-to-make-an-llm-say-i-dont-know#the-cost-of-refusing&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;A system that declines everything scores perfectly on the 24 and zero on the 65, and refusal correctness would read 27 percent. The metric couples the two mistakes on purpose so that a gate cannot be passed by cowardice. In the August run the over-refusal count was zero: every one of the 65 answerable questions came back as an answer rather than a decline, and the must-cite policy would have withheld an uncited one. That is the half of the measurement I would have skipped in June, when the refusals were the part I was proud of, and it is the half that decides whether anyone uses the system.&lt;/p&gt;
&lt;p&gt;The abstention number I report now is not a rate. It is three counts from the latest ledger row, zero under-refused, zero over-refused, one hallucinated answer in 89, with the date and the run beside them, and a gate that turns the next regression into a failed build instead of a quieter number.&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>How do you read a 3D option Greeks surface?</title>
      <link>https://caskeycoding.com/blog/how-to-read-a-3d-option-greeks-surface</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/how-to-read-a-3d-option-greeks-surface</guid>
      <pubDate>Thu, 24 Sep 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>finance</category>
      <category>options</category>
      <category>visualization</category>
      <category>threejs</category>
      <category>education</category>
      <description>The Greeks manifold prices a long call on a 60 by 60 Black-Scholes grid over spot and time to expiry, draws profit and loss as height against a premium fixed at the strike and the longest tenor, and colors each cell by one Greek. Gamma is a ridge near the strike that sharpens toward expiry, theta is the downhill slope toward expiry, delta is the slope along price, and vega and rho recolor the sheet while moving the benchmark it is measured against. Ticker mode positions the same surface on a published S&amp;P 500 name.</description>
      <content:encoded>&lt;p&gt;Read &lt;a href=&quot;https://caskeycoding.com/lab/greeks-manifold&quot; class=&quot;internal-link&quot;&gt;the Greeks manifold&lt;/a&gt;&apos;s 60 by 60 grid as a long call&apos;s profit and loss in height, colored by one Greek: gamma a ridge near the strike sharpening toward expiry, theta the downhill slope toward expiry, delta the slope along price. Vega and rho are different; they recolor the sheet by a sensitivity and, through their sliders, move the premium the height is measured against.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/greeks-gamma-ridge.webp&quot; alt=&quot;The long-call profit-and-loss surface colored by gamma: a teal band flaring orange near the strike, where the option&amp;#x27;s value bends hardest&quot;&gt;&lt;/p&gt;
&lt;h2 id=&quot;height-is-profit-and-loss-against-a-fixed-premium&quot;&gt;Height is profit and loss against a fixed premium&lt;a href=&quot;https://caskeycoding.com/blog/how-to-read-a-3d-option-greeks-surface#height-is-profit-and-loss-against-a-fixed-premium&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The surface has three axes. Spot price runs one way, time to expiry runs the other, and height is the call&apos;s value at that point minus a premium fixed once per surface: the at-the-money call value at the longest tenor on the time axis. The single point at the strike and the longest tenor therefore sits at zero, and every other cell shows what the position would be worth relative to what it cost. On the default inputs that is a strike of 100, volatility of 25 percent, a risk-free rate of 5 percent, spot from 40 to 180, and time to expiry from 0.02 to 1.5 years, and each of the five sliders redraws the 3,600-cell grid.&lt;/p&gt;
&lt;p&gt;Color is a separate channel. Each cell also carries the five Greeks of the call at that point, and the selector paints the sheet by one of them. The first time I rotated the surface, in &lt;a href=&quot;https://caskeycoding.com/blog/markets-in-three-dimensions&quot; class=&quot;internal-link&quot;&gt;the post that built the five 3D views&lt;/a&gt;, gamma was just sitting there as a ridge. The sections below map each textbook Greek onto what the sheet does.&lt;/p&gt;
&lt;h2 id=&quot;read-delta-and-gamma-along-price-theta-toward-expiry&quot;&gt;Read delta and gamma along price, theta toward expiry&lt;a href=&quot;https://caskeycoding.com/blog/how-to-read-a-3d-option-greeks-surface#read-delta-and-gamma-along-price-theta-toward-expiry&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Delta is the slope of the surface along the price axis. Far below the strike the sheet is flat and delta is near zero; far above it the sheet rises one for one with spot and delta is near one; the transition happens across the strike, gradual on the long-tenor edge and abrupt on the near-expiry edge.&lt;/p&gt;
&lt;p&gt;Gamma is the rate at which delta changes with spot, and painting by it lights a ridge across the sheet. The ridge is near the strike, not exactly on it: by the formula the tool uses, gamma at a fixed tenor peaks at a spot of the strike times an exponential in rate, volatility squared and time, which at the default inputs puts the peak near 81 on the 1.5-year edge and within a point of 100 at 0.02 years. Drag the lower end of the time range toward 0.02 years and the ridge slides onto the strike and narrows into a spike: with almost no time left, the call is either worth its intrinsic value or nothing, and all of the bend collapses onto 100.&lt;/p&gt;
&lt;p&gt;Theta is the slope of the sheet in the time direction, read toward expiry. Hold spot at the strike and walk from the 1.5-year edge toward the near edge: the sheet falls, and the fall steepens near the end. That is the value the option loses to the calendar, and on the surface it is the direction water would run.&lt;/p&gt;
&lt;h2 id=&quot;vega-and-rho-recolor-the-sheet-and-move-the-benchmark&quot;&gt;Vega and rho recolor the sheet and move the benchmark&lt;a href=&quot;https://caskeycoding.com/blog/how-to-read-a-3d-option-greeks-surface#vega-and-rho-recolor-the-sheet-and-move-the-benchmark&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Vega and rho are not slopes of the sheet, because volatility and rate are sliders rather than axes. Painting by vega colors each cell by how much the call&apos;s value there would change with volatility, largest near the strike at long tenors; painting by rho does the same for the rate. Moving either slider does two jobs at once: it reprices every cell, and it reprices the premium benchmark, so the profit-and-loss sheet changes relative to a moving zero rather than simply rising or falling. The point at the strike and the longest tenor stays at zero whatever the sliders say.&lt;/p&gt;
&lt;h2 id=&quot;ticker-mode-positions-the-surface-on-a-published-name&quot;&gt;Ticker mode positions the surface on a published name&lt;a href=&quot;https://caskeycoding.com/blog/how-to-read-a-3d-option-greeks-surface#ticker-mode-positions-the-surface-on-a-published-name&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The synthetic surface teaches the shape. Ticker mode puts a real name under it. Choose a published symbol from the curated set of 30 large caps or the S&amp;#x26;P 500 set and the surface re-centers: the stock&apos;s spot becomes the strike, its realized volatility from up to 61 closes becomes sigma, clamped to between 5 and 150 percent, the spot axis becomes 0.4 to 1.6 times spot, and up to 90 closes are drawn across the sheet as a path. On the file published 2026-09-24, AAPL carried a spot of 337.02 and a realized volatility of 28.9 percent, so ticker mode puts the ridge near 337 instead of 100 and runs the volatility at 28.9 instead of 25. The spot and volatility are a dated snapshot of public prices, shown to position the surface, not investment advice.&lt;/p&gt;
&lt;p&gt;The inputs come from a baked file, not a live call. A scheduled job runs each weekday before the US open, pulls price history from Financial Modeling Prep, computes annualized realized volatility as the sample standard deviation of daily log returns times the square root of 252, drops any series with fewer than 30 closes, and writes one row per symbol. The S&amp;#x26;P 500 set only flips to a new version when at least 400 names resolve, so a bad fetch cannot publish a thin universe, and a name that failed to publish is simply absent from the picker. The browser reads the file and never touches the API.&lt;/p&gt;
&lt;h2 id=&quot;the-model-prices-a-european-call-without-dividends&quot;&gt;The model prices a European call without dividends&lt;a href=&quot;https://caskeycoding.com/blog/how-to-read-a-3d-option-greeks-surface#the-model-prices-a-european-call-without-dividends&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The pricing is textbook Black-Scholes for a European call with no dividend yield, and the normal distribution is the Abramowitz and Stegun approximation with a maximum error around 1.5 times 10 to the minus 7, well inside the tolerance of the finite-difference checks the Greeks are tested against. There is no put surface and no early exercise. The rate is one slider from 0 to 15 percent, not a term structure. The smile mode, one toggle away, is synthetic and says so on the page, because a real implied-volatility feed is a spend I have not approved: the synthetic smile supplies no market-implied volatility for any strike or expiry.&lt;/p&gt;
&lt;hr&gt;
&lt;p&gt;&lt;strong&gt;Related:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;https://caskeycoding.com/blog/markets-in-three-dimensions&quot; class=&quot;internal-link&quot;&gt;Rendering an options Greeks surface in 3D in the browser&lt;/a&gt;, how this and the other four surfaces were built on one math-to-mesh boundary&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://caskeycoding.com/blog/pricing-215-million-options-a-second&quot; class=&quot;internal-link&quot;&gt;Pricing 215 million options a second with SIMD C++&lt;/a&gt;, the SIMD C++ pricer whose implied-volatility solver the smile mode&apos;s solver mirrors&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://caskeycoding.com/blog/how-do-you-know-the-compiler-vectorized-your-loop&quot; class=&quot;internal-link&quot;&gt;How do you know the compiler actually vectorized your loop?&lt;/a&gt;, why a build log that said &quot;loop vectorized&quot; was wrong about the loop that mattered&lt;/li&gt;
&lt;/ul&gt;</content:encoded>
    </item>
    <item>
      <title>How do you tell when the yield curve has inverted?</title>
      <link>https://caskeycoding.com/blog/how-to-tell-when-the-yield-curve-has-inverted</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/how-to-tell-when-the-yield-curve-has-inverted</guid>
      <pubDate>Thu, 24 Sep 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>finance</category>
      <category>macro</category>
      <category>treasuries</category>
      <category>visualization</category>
      <category>education</category>
      <description>The yield curve surface reads 11 FRED constant-maturity Treasury series from one month to thirty years, keeps the 60 most recent complete daily curves, and labels the curve inverted when the 30-year yield is more than 0.1 percentage points below the 1-month yield. On 2026-09-22 the 30-year was 5.29 percent and the 1-month 3.97, a slope of plus 1.32 points, and the read was upward. The spread clock panel below the surface draws the 2s10s spread back to 1976, and the textbook mode fakes an inversion on purpose from a Nelson-Siegel preset.</description>
      <content:encoded>&lt;p&gt;&lt;a href=&quot;https://caskeycoding.com/lab/yield-curve&quot; class=&quot;internal-link&quot;&gt;The yield curve surface&lt;/a&gt; labels the real curve inverted when the 30-year Treasury yield is more than 0.1 percentage points below the 1-month yield; on the 2026-09-22 curve the 30-year was 5.29 percent and the 1-month 3.97, so the read was upward. The same rule labels the curve upward above plus 0.1 points and flat in between, and it is applied to every day in the file.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/yield-curve-inverted.webp&quot; alt=&quot;The textbook, synthetic mode of the yield curve surface on its last frame, folded into inversion, with the status badge reading inverted&quot;&gt;
&lt;em&gt;Textbook mode, not the live curve: a synthetic Nelson-Siegel inversion. The real 2026-09-22 curve read upward.&lt;/em&gt;&lt;/p&gt;
&lt;h2 id=&quot;the-badge-tests-only-the-two-endpoints&quot;&gt;The badge tests only the two endpoints&lt;a href=&quot;https://caskeycoding.com/blog/how-to-tell-when-the-yield-curve-has-inverted#the-badge-tests-only-the-two-endpoints&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;A yield curve is the interest rate for lending to the Treasury over different lengths of time, drawn as a line from the shortest maturity to the longest. Normally it slopes up, because longer loans cost more. An inversion is the line tipping the other way, with short rates above long rates, and it is the shape everyone calls a recession warning. The surface draws that line for every day in its window and stacks the days along a second axis, so the curve becomes a sheet you can scrub through time and watch tilt.&lt;/p&gt;
&lt;p&gt;The label on the page comes from one subtraction. The tool takes the last yield in the curve minus the first, which on the real data is the 30-year minus the 1-month, and thresholds it at a tenth of a point either side of zero. Above plus 0.1 the badge says upward; below minus 0.1 it says inverted; in between it says flat. A separate chip reports the day-over-day move in the 2s10s spread, the 10-year minus the 2-year, and a spread clock panel below the surface draws that pair over the same sixty sessions and over its full history.&lt;/p&gt;
&lt;h2 id=&quot;publish-only-dates-with-all-eleven-yields&quot;&gt;Publish only dates with all eleven yields&lt;a href=&quot;https://caskeycoding.com/blog/how-to-tell-when-the-yield-curve-has-inverted#publish-only-dates-with-all-eleven-yields&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The real curve is eleven FRED constant-maturity series: 1-month, 3-month, 6-month, 1-year, 2-year, 3-year, 5-year, 7-year, 10-year, 20-year and 30-year. A scheduled job runs daily, requests the 120 newest observations for each series, joins them on date, and keeps only the dates where all eleven have a value, oldest first. It publishes the 60 most recent complete curves as one file and refuses to publish at all if fewer than 5 survive the join, so a partial fetch cannot replace a good file with a thin one. The page reads that file; the browser never calls FRED.&lt;/p&gt;
&lt;p&gt;On the file I read while writing this, the 60 curves ran from 2026-06-29 to 2026-09-22. The latest one, in percent from short to long, was 3.97, 4.16, 4.26, 4.43, 4.71, 4.81, 4.83, 4.89, 4.96, 5.33 and 5.29. The 2-year at 4.71 and the 10-year at 4.96 put the 2s10s spread at plus 0.25 points, against plus 0.28 on the first day of the window. The 20-year at 5.33 sat above the 30-year at 5.29, a small kink at the long end that a badge computed from the endpoints alone will never mention.&lt;/p&gt;
&lt;h2 id=&quot;sixty-sessions-is-the-surfaces-window-not-the-pages&quot;&gt;Sixty sessions is the surface&apos;s window, not the page&apos;s&lt;a href=&quot;https://caskeycoding.com/blog/how-to-tell-when-the-yield-curve-has-inverted#sixty-sessions-is-the-surfaces-window-not-the-pages&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Sixty complete sessions is about three months, so the sheet and its badge can show the curve steepening or flattening within a quarter and nothing older. Below the surface, the spread clock panel draws the 2s10s spread&apos;s daily history back to 1976 from a separate baked series, with recession months shaded, and that panel is where to look for when the spread last went negative. The page shades recessions but computes no lead time from inversion to downturn and no hit rate, because the tool draws yields and does not forecast from them.&lt;/p&gt;
&lt;p&gt;The label is a rule about two endpoints, so a curve that is inverted in the middle and upward at the ends reads as upward. And the real and synthetic modes use different maturity grids, eleven points from one month on the real data and ten points from three months on the textbook curve, so a number read off one mode should not be quoted against the other.&lt;/p&gt;
&lt;h2 id=&quot;the-textbook-mode-inverts-on-purpose&quot;&gt;The textbook mode inverts on purpose&lt;a href=&quot;https://caskeycoding.com/blog/how-to-tell-when-the-yield-curve-has-inverted#the-textbook-mode-inverts-on-purpose&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;When the real curve is not inverted, which it was not on 2026-09-22, the page still needs to show what an inversion looks like forming. The synthetic mode does that with the Nelson-Siegel three-factor formula: a level, a slope factor, a curvature factor, and a decay constant. Six named presets set those four numbers for normal, flat, inverted, steepening, bear-flattening and level-shift shapes, and a transition interpolates from one preset to another over 24 to 90 frames with up to 15 basis points of seeded jitter so the sheet does not look machined. Going from the normal preset to the inverted one moves the slope factor from minus 1.6 to plus 1.6, the level from 4.0 to 3.4, and the curvature from 0 to minus 0.4, with the decay constant held at 2.0.&lt;/p&gt;
&lt;p&gt;The deep link in &lt;a href=&quot;https://caskeycoding.com/blog/markets-in-three-dimensions&quot; class=&quot;internal-link&quot;&gt;the post that built the five surfaces&lt;/a&gt; opens the synthetic mode on its last frame, fully inverted, and the badge says so. The real mode opens on the newest curve in the published file, and the tool&apos;s rule applied to the 2026-09-22 curve gives upward. Both are labeled, and the label is the first line to read before the shape.&lt;/p&gt;
&lt;hr&gt;
&lt;p&gt;&lt;strong&gt;Related:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;https://caskeycoding.com/blog/markets-in-three-dimensions&quot; class=&quot;internal-link&quot;&gt;Rendering an options Greeks surface in 3D in the browser&lt;/a&gt;, how this surface and the other four were built on one math-to-mesh boundary&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://caskeycoding.com/blog/how-to-read-a-3d-option-greeks-surface&quot; class=&quot;internal-link&quot;&gt;How do you read a 3D option Greeks surface?&lt;/a&gt;, the companion page for the options surface&lt;/li&gt;
&lt;/ul&gt;</content:encoded>
    </item>
    <item>
      <title>Local-first CI: the pre-push hook is the gate and hosted CI is the mirror</title>
      <link>https://caskeycoding.com/blog/local-first-ci-pre-push-hook-is-the-gate</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/local-first-ci-pre-push-hook-is-the-gate</guid>
      <pubDate>Thu, 24 Sep 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>platform</category>
      <category>ci-cd</category>
      <category>git</category>
      <category>developer-experience</category>
      <category>infrastructure</category>
      <description>After GitHub Actions burned a month of minutes in two days, the gate moved to the workstation. A pre-push hook runs a quick tier on every push, every green run writes a record tagged with its tier and commit, and a merge guard refuses any pull request whose exact SHA has no full-tier record. 1,660 records later, what it covers and what it cannot.</description>
      <content:encoded>&lt;p&gt;My git pre-push hook is the CI gate, and the hosted runner is a mirror that deploys on merge and scans for secrets. That arrangement has been in force since 2026-07-11, when a month of GitHub Actions allowance was gone in two days and every job on the account was failing at setup in under five seconds. The &lt;a href=&quot;https://caskeycoding.com/blog/when-ci-costs-more-than-it-saves&quot; class=&quot;internal-link&quot;&gt;cost side of that decision&lt;/a&gt; is its own post. This one is about the mechanism: what a hook has to do before &quot;passes locally&quot; is allowed to mean &quot;may merge&quot;.&lt;/p&gt;
&lt;p&gt;The runner is one Python script that mirrors each repository&apos;s &lt;code class=&quot;inline-code&quot;&gt;pr-validation.yml&lt;/code&gt;, lane for lane, and runs it in three tiers. The pre-push hook runs the quick tier on every push: lint, the static scans for disclosure, route hygiene and workflow context, and a small slice of the unit suite, well under a minute. The full tier adds the build, the whole unit suite, the end-to-end suite, a home-page smoke test and the secret scan, and takes about eight minutes for the frontend. Every green run at either tier writes a record tagged with its tier; only a full-tier record counts at the merge. There are 1,660 records on this machine today, 311 of them full-tier: 997 for the specs repository, 322 for the frontend, 162 for the backend, 81 for the infrastructure stacks, and the rest across the smaller products.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/local-first-ci-pre-push-hook-is-the-gate-record.svg&quot; alt=&quot;Three boxes in a row, quick tier on every push, full tier before merge, and a green merge guard that checks for a record keyed by commit, with a faint mirror box below labeled hosted runner: deploy, rollback, secret scan.&quot;&gt;&lt;/p&gt;
&lt;h2 id=&quot;a-green-run-has-to-be-bound-to-a-commit&quot;&gt;A green run has to be bound to a commit&lt;a href=&quot;https://caskeycoding.com/blog/local-first-ci-pre-push-hook-is-the-gate#a-green-run-has-to-be-bound-to-a-commit&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The first version of local CI printed a verdict and trusted the human to act on it, which is the same trust model as a sticky note. The version that replaced it writes a JSON record when every lane in a run passes: the repository key, the exact commit SHA, the merge base it was tested against, the tier, whether the tree was dirty, the timestamp, and the Node version. The record lives outside the repository, in a directory the hooks own.&lt;/p&gt;
&lt;p&gt;Binding to the SHA is what makes the record mean something. Push a follow-up commit and the record does not follow it; the new commit has to earn its own. Run the tier on a tree with uncommitted changes and the record says so, and the merge gate rejects it, because a record for a commit that does not contain what was tested is a lie with a timestamp. Run a full tier that skipped the build because the dependencies were missing and the writer refuses that too, on the grounds that a hollow green is worse than a red. I learned the last rule from a run that reported GO in a fresh worktree with no &lt;code class=&quot;inline-code&quot;&gt;node_modules&lt;/code&gt;, and the merge it would have blessed was a build failure waiting for the deploy step.&lt;/p&gt;
&lt;h2 id=&quot;something-has-to-refuse-the-merge&quot;&gt;Something has to refuse the merge&lt;a href=&quot;https://caskeycoding.com/blog/local-first-ci-pre-push-hook-is-the-gate#something-has-to-refuse-the-merge&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;A record nobody checks is a log. The check is a second hook, not in git but on the shell tool that my agents and I issue commands through: it intercepts the merge and deploy commands themselves, resolves the commit that command would promote, and asks the runner whether that exact SHA has a full-tier record. On those intercepted paths, a missing full-tier record blocks the action. It matches &lt;code class=&quot;inline-code&quot;&gt;gh pr merge&lt;/code&gt;, the deploy scripts, the CDK deploy, and the bare S3 sync that used to be the whole deploy. It rolled out in observe mode first, logging its decision without blocking, until its decisions on real traffic showed it resolving the right commit, and then a sentinel file flipped it to enforce.&lt;/p&gt;
&lt;p&gt;This is a cooperative workstation workflow. Git&apos;s &lt;a href=&quot;https://git-scm.com/docs/git-push&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;&lt;code class=&quot;inline-code&quot;&gt;--no-verify&lt;/code&gt;&lt;/a&gt; bypasses the pre-push hook; a shell-tool hook does not cover a merge from GitHub&apos;s interface or another tool. A JSON record outside the repo is also not proof against someone who can rewrite it. Repository-wide enforcement would need a server-side required check, a protected source of attestations, and explicit bypass permissions. The local record described here prevents accidental stale-result reuse within its covered workflow.&lt;/p&gt;
&lt;p&gt;The guard has refused me three times this week, and each refusal was correct. Twice the record for a commit had been replaced by a quick-tier record, because I ran the full tier, then pushed, and the pre-push hook&apos;s quick run wrote its own record over the full one for the same SHA. The rule that came out of that is push first, attest second. The third refusal was a compound shell command: a merge chained behind another command, which the guard could not parse, so it fell back to the checkout&apos;s current commit and found nothing. A bare merge command, alone, from the directory holding the tested commit, is now the only form I use.&lt;/p&gt;
&lt;h2 id=&quot;the-mirror-has-to-know-when-it-drifts&quot;&gt;The mirror has to know when it drifts&lt;a href=&quot;https://caskeycoding.com/blog/local-first-ci-pre-push-hook-is-the-gate#the-mirror-has-to-know-when-it-drifts&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The one hazard that can make all of this worse than hosted CI is drift. The moment the local runner and the committed workflow disagree, a local pass stops predicting a hosted pass, and the gate is lying with a green light. So the runner hashes each repository&apos;s workflow files on every run and compares them with the hashes it last blessed. A changed workflow prints a drift warning until someone reads the new file and blesses it explicitly. The runner also prints every lane it skipped and why, so a local run&apos;s coverage is a list you can read, not a feeling.&lt;/p&gt;
&lt;p&gt;What it skips is real. A workstation is not a clean image: it has the Node patch version I happen to have, the system packages I happen to have installed, and, this week, another session&apos;s end-to-end server already listening on port 3000. Two of my full-tier runs this week failed the end-to-end lane alone while the same spec passed in isolation seconds later, and both coincided with a neighbor holding the port. The runner cannot tell that from a real regression, so the rule until it can is one full tier at a time, machine-wide, and a skipped lane is a named gap I carry into the merge decision rather than a pass.&lt;/p&gt;
&lt;h2 id=&quot;what-stayed-on-the-hosted-runner&quot;&gt;What stayed on the hosted runner&lt;a href=&quot;https://caskeycoding.com/blog/local-first-ci-pre-push-hook-is-the-gate#what-stayed-on-the-hosted-runner&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Three workflows kept their place. Deploy on merge, because the artifact should be built where it lands, by a runner that is not my workstation. Rollback, because the day I need it is the day my workstation may be the problem. And the secret scan on every push to main, because it is cheap, it runs where the code is public, and a second pair of eyes on credentials costs nothing worth saving. Everything else, the lint and test and build and end-to-end lanes that used to burn the allowance on every push to every pull request, is dispatch-only now, there if a reviewer asks, silent otherwise.&lt;/p&gt;
&lt;p&gt;The monthly bill stayed in single digits after that, and the part I did not predict is that the gate got stricter, not looser. Hosted CI passed or failed a pull request. The local gate refuses a merge, refuses a deploy, rejects a record made on a dirty tree, refuses a hollow run, and warns on a stale workflow, and a refused merge names the commit it is refusing. The allowance was what ran out. The record was what I had been missing.&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>What a month of AI coding agents actually costs: $599 on subscriptions, $7,566 at API prices</title>
      <link>https://caskeycoding.com/blog/what-a-month-of-ai-coding-agents-costs</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/what-a-month-of-ai-coding-agents-costs</guid>
      <pubDate>Thu, 24 Sep 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>AI</category>
      <category>agents</category>
      <category>cost</category>
      <category>claude-code</category>
      <category>orchestration</category>
      <description>My usage tracker estimated $7,566 at API list prices for a month covered by $599 in subscriptions. The token breakdown, the denominator behind its 98.2 percent cache ratio, and the limits of that counterfactual.</description>
      <content:encoded>&lt;p&gt;For thirty days of running my agent fleet, the tracker recorded about 8.7 billion tokens through three vendors&apos; models in 70,227 calls across 2,861 sessions. It estimated $7,566 at API list prices. The three subscriptions that covered the work cost $599, a comparison of nearly thirteen to one. Most of the recorded tokens were cache reads.&lt;/p&gt;
&lt;p&gt;The local tracker reads session transcripts and applies model-specific API rates to reported usage. Two of its ten models use estimated token counts because their CLIs do not report exact ones; they account for about seven percent of the modeled cost. The aggregates below summarize that accounting. They do not include the complete per-model token categories, rate dates, or cross-vendor normalization needed to independently reproduce the $7,566 estimate. Treat it as a modeled comparison for this workload, not a bill I paid or a current price quote.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/what-a-month-of-ai-coding-agents-costs-bars.svg&quot; alt=&quot;Two horizontal bars compare the modeled $7,566 API total with $599 in subscriptions. The 98.2 percent cache ratio excludes cache writes from its denominator.&quot;&gt;
&lt;em&gt;The API bar is an estimate. The graphic&apos;s cache ratio is reads divided by reads plus fresh input; cache writes are excluded.&lt;/em&gt;&lt;/p&gt;
&lt;h2 id=&quot;ninety-five-percent-of-the-tokens-were-re-reads&quot;&gt;Ninety-five percent of the tokens were re-reads&lt;a href=&quot;https://caskeycoding.com/blog/what-a-month-of-ai-coding-agents-costs#ninety-five-percent-of-the-tokens-were-re-reads&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The published breakdown was 154 million fresh input tokens, 40 million output tokens, 222 million cache writes, and 8.29 billion cache reads. About 95 percent of total token volume was reads. The 98.2 percent figure uses a different denominator: &lt;code class=&quot;inline-code&quot;&gt;8.29 / (8.29 + 0.154)&lt;/code&gt;, reads divided by reads plus fresh input. It excludes writes. Including the 222 million writes gives about 95.7 percent of input served from cache. &lt;a href=&quot;https://platform.claude.com/docs/en/build-with-claude/prompt-caching&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Anthropic&apos;s usage documentation&lt;/a&gt; includes reads, writes, and uncached input in total input; a cross-vendor tracker also needs to normalize each provider&apos;s fields before combining them.&lt;/p&gt;
&lt;p&gt;That shape is what an agent session looks like from the inside. Every turn the model takes, it re-reads the system prompt, the rules files, the tool results and the whole conversation so far, then writes a few hundred tokens of decision. A product call is the opposite shape: a short prompt, a short answer, nothing carried forward. The largest of these APIs prices cache reads at a tenth of fresh input, which is why I once spent &lt;a href=&quot;https://caskeycoding.com/blog/prompt-caching-four-layers&quot; class=&quot;internal-link&quot;&gt;a post on getting the cache prefix right&lt;/a&gt;, and even with that discount the re-reads dominate the API-equivalent bill. A flat-rate subscription with a weekly allowance is priced for exactly this shape, which is presumably why the allowance, and not the dollars, is the scarce resource on every plan I pay for.&lt;/p&gt;
&lt;h2 id=&quot;the-supervisor-costs-more-than-the-typists&quot;&gt;The supervisor costs more than the typists&lt;a href=&quot;https://caskeycoding.com/blog/what-a-month-of-ai-coding-agents-costs#the-supervisor-costs-more-than-the-typists&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;By model, the frontier tier I use for supervision, planning, briefs, diff review and merge decisions, accounted for $3,455 of the $7,566, across 7,954 calls and 2.9 billion tokens. It wrote almost no code. The second vendor&apos;s mid-tier model took 23,201 calls and 2.6 billion tokens for $1,468; the mid-tier on the first vendor took 9,075 calls for $1,221. The model that typed the bulk of the last week&apos;s merged code, a third vendor&apos;s coding model that I dispatch with a written brief, took 9,391 calls and 560 million tokens for $295. The small model that runs the mechanical wrapper scripts made 9,771 calls for $97.&lt;/p&gt;
&lt;p&gt;Read as a ratio, the frontier supervisor cost twelve times what the typist cost, for the same month of shipped work. That is the price of the routing rule I wrote in July: &lt;a href=&quot;https://caskeycoding.com/blog/fable-thinks-opus-builds-kimi-types&quot; class=&quot;internal-link&quot;&gt;the frontier model thinks, cheaper models build, the off-quota model types&lt;/a&gt;. The rule moved the typing off the expensive meter, as intended. It did not move the reading, because reading is what supervision is. Every review turn re-reads the session, and the session is where all the context accumulates, so the supervisor&apos;s bill scales with session length while the typist&apos;s scales with diff size. The typist&apos;s diffs were larger. The supervisor&apos;s sessions were longer, and length won.&lt;/p&gt;
&lt;p&gt;The daily peaks make the same point. The four most expensive days of the month, August 26, August 27, August 31 and September 7, each moved between 860 million and 1.16 billion tokens and would each have billed between $640 and $1,004 on the API. Those were merge waves: dozens of pull requests reviewed and landed in a day, which means dozens of full-session re-reads by the supervisor, not dozens of large diffs. On the subscription those days cost nothing extra. They cost allowance, and an earlier wave in July, when a fan-out of frontier-tier subagents tripped the allowance outright, is how I learned to cap the fan-out.&lt;/p&gt;
&lt;h2 id=&quot;what-the-thirteen-to-one-does-not-mean&quot;&gt;What the thirteen to one does not mean&lt;a href=&quot;https://caskeycoding.com/blog/what-a-month-of-ai-coding-agents-costs#what-the-thirteen-to-one-does-not-mean&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;It does not mean the API is overpriced, and it does not mean I would have spent $7,566 without the subscriptions. Nobody runs this shape of workload on a metered API without changing the shape: shorter sessions, aggressive context trimming, fewer review passes. The counterfactual is what this behavior would have cost, and the behavior exists because the flat rate made it free at the margin. The subscription did not save me $6,967. It let me work in a way that would not have occurred to me on a meter.&lt;/p&gt;
&lt;p&gt;It also does not mean subscriptions are the answer for everything. The site&apos;s backend makes its own model calls when a reader asks the finance tools a question, and those run on the API, metered per call. They are small, independent and infrequent, the opposite shape from an agent session, and the bill is small enough that I have declined to dress it up as a cost story before. The line between the two meters is the line between development and runtime, and I have never had a reason to cross it in either direction.&lt;/p&gt;
&lt;h2 id=&quot;route-by-who-pays-for-the-retry&quot;&gt;Route by who pays for the retry&lt;a href=&quot;https://caskeycoding.com/blog/what-a-month-of-ai-coding-agents-costs#route-by-who-pays-for-the-retry&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The rule I run now is one sentence. If a call&apos;s cost scales with how much has to be re-read, it goes on a subscription; if it scales with how much has to be answered, it goes on the API. Agent sessions re-read, so they live on three flat-rate plans, and the routing across them exists to protect the weekly allowances, not the dollars. Product calls answer, so they live on the meter, where a short request costs a fraction of a cent and nothing accumulates between requests.&lt;/p&gt;
&lt;p&gt;I watch the reads-to-reads-plus-fresh-input ratio alongside cache writes and the remaining subscription allowance. If that ratio falls, I need to inspect the workload and token categories before blaming lost reuse. More fresh work, a different model mix, and missed cache reads can all change it. The label and denominator have to stay attached to the number.&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>What Newey-West does to a backtest t-statistic: 18 months became two</title>
      <link>https://caskeycoding.com/blog/newey-west-standard-errors-backtest</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/newey-west-standard-errors-backtest</guid>
      <pubDate>Wed, 23 Sep 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>finance</category>
      <category>backtesting</category>
      <category>statistics</category>
      <category>quant</category>
      <category>evidence</category>
      <description>A Newey-West standard error accounts for dependence in a series. My engine&apos;s 18 monthly readings had an estimated effective sample size near two. The arithmetic, the lag choice, and the evidence gate that kept the result from changing a weight.</description>
      <content:encoded>&lt;p&gt;A Newey-West standard error accounts for dependence in the series behind a mean. On my engine&apos;s 12-month panel, 18 monthly readings with an unadjusted t-statistic of negative 18.8 had an estimated effective sample size near two. A result that had looked decisive failed the engine&apos;s evidence floor.&lt;/p&gt;
&lt;p&gt;The reading came out of the diagnostic harness I wrote for my &lt;a href=&quot;https://caskeycoding.com/finance/methodology&quot; class=&quot;internal-link&quot;&gt;factor scoring engine&lt;/a&gt;. The harness scores a universe of stocks at each month-end, waits for the forward return over some horizon, and computes a cross-sectional information coefficient per date: the rank correlation between score and what happened next. Average the per-date ICs, divide by the standard error of that average, and you have a t-statistic. The 12-month quality reading came back at negative 0.57 across 18 dates with an unadjusted t of negative 18.8. A quality factor that predicts returns backward is a factor built wrong, and that is the fault I went looking for first.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/newey-west-standard-errors-backtest-overlap.svg&quot; alt=&quot;Eighteen overlapping 12-month windows drawn as staggered red bars, each starting one month after the last, with an arrow to two green bars laid end to end and the label effective n = 2.&quot;&gt;&lt;/p&gt;
&lt;h2 id=&quot;why-18-readings-are-not-18-facts&quot;&gt;Why 18 readings are not 18 facts&lt;a href=&quot;https://caskeycoding.com/blog/newey-west-standard-errors-backtest#why-18-readings-are-not-18-facts&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The naive standard error is the standard deviation of the per-date ICs, 0.13 here, divided by the square root of 18. That formula assumes the readings are independent draws. A 12-month forward return from a January month-end snapshot covers February through the following January; the next snapshot&apos;s window shares eleven of those twelve months. That is about 92 percent overlap in the return windows, though it does not by itself determine the correlation between IC readings. The scores are sticky as well, since a company&apos;s quality metrics do not reshuffle month to month, and factor performance can persist across several quarters.&lt;/p&gt;
&lt;p&gt;Those are reasons to examine dependence rather than count every monthly reading as an independent draw. Positive autocovariances can make the naive standard error too small and the absolute t-statistic too large. The amount of window overlap alone does not tell me the size of that error; I need the IC series and its estimated autocovariances.&lt;/p&gt;
&lt;p&gt;The &lt;a href=&quot;https://doi.org/10.2307/1913610&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Newey and West (1987)&lt;/a&gt; correction replaces the sample variance with a long-run variance. Take the variance of the series, then add twice the autocovariance at lag one, lag two, up to lag L, each weighted by a Bartlett factor of one minus the lag over L plus 1, so nearby lags count fully and distant ones fade out. The helper in my harness is fourteen lines: the mean, the deviations, the lag-zero variance, a loop that accumulates weighted autocovariances into the long-run variance, then the mean divided by the square root of that variance over n.&lt;/p&gt;
&lt;p&gt;I now print a variance-ratio diagnostic on every cell: effective n, calculated as n times the naive variance over the estimated long-run variance, capped at n. For the 12-month panel it came out near two. That estimate fails my evidence floor; it does not turn the series into two literal independent observations or establish an exact reference distribution. A &lt;a href=&quot;https://www.itl.nist.gov/div898/handbook/eda/section3/eda3664.htm&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Student-t distribution with one degree of freedom is defined&lt;/a&gt;, but assigning that degree of freedom from this diagnostic would need a separate justification. With only 18 dependent readings, a self-selected panel, and scores from two engine versions, I could not treat the result as a reliable basis for reversing the factor.&lt;/p&gt;
&lt;h2 id=&quot;the-lag-is-a-decision-not-a-default&quot;&gt;The lag is a decision, not a default&lt;a href=&quot;https://caskeycoding.com/blog/newey-west-standard-errors-backtest#the-lag-is-a-decision-not-a-default&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Nothing in the formula tells you L. Too small and the correction misses the overlap; too large and the estimate of the long-run variance gets noisy in its own right. The engine&apos;s comparator derives L from the horizon: the number of series steps two snapshot dates can be apart and still share a forward window, which is the horizon divided by the median spacing between dates, rounded up, minus one. On month-end dates that is lag 11 for a 12-month horizon and lag 2 for a 3-month one, clamped to n minus 1. When it does not know the horizon it falls back to the automatic Bartlett rule, the floor of 4 times n over 100 to the two-ninths power. A Bartlett estimator truncated at L ignores every lag above L, so a lag chosen without looking at the horizon is a lag that can miss the overlap entirely.&lt;/p&gt;
&lt;p&gt;My standalone diagnostic scripts use a different choice for monthly net-of-cost portfolio returns: fixed lag 3, motivated by quarterly score refreshes. The IC series use the comparator&apos;s horizon rule. The rule of 0.75 times T to the one-third power, rounded down, gives lag 3 at 64 observations and lag 1 at 18. I had chosen the larger lag when conventions disagreed, but that choice is not automatically conservative. The &lt;a href=&quot;https://www.statsmodels.org/stable/_modules/statsmodels/stats/sandwich_covariance.html#S_hac_simple&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Bartlett calculation adds signed autocovariances&lt;/a&gt;, so adding lags can lower the estimated variance. Sensitivity to justified lag choices belongs beside the result, especially for this short panel; no such sensitivity result is established here.&lt;/p&gt;
&lt;h2 id=&quot;i-told-this-story-with-the-wrong-numbers-once&quot;&gt;I told this story with the wrong numbers once&lt;a href=&quot;https://caskeycoding.com/blog/newey-west-standard-errors-backtest#i-told-this-story-with-the-wrong-numbers-once&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;My June post on &lt;a href=&quot;https://caskeycoding.com/blog/backtesting-without-fooling-yourself&quot; class=&quot;internal-link&quot;&gt;backtesting without fooling yourself&lt;/a&gt; told a version of it with a different pair: a factor whose naive t was negative four and whose Newey-West t was negative 1.6. The mechanism in that paragraph is right and I would write it the same way again. The numbers came from a point-in-time scoring harness that I later found had two defects, a market-cap field that leaked today&apos;s value into historical dates and a renamed API field that left one factor reading a constant. Every negative quality reading that harness produced is void, including the one I quoted. The correction ratio was real; the signal it was correcting was an artifact. I would rather say so here than let the older paragraph stand as the reference.&lt;/p&gt;
&lt;p&gt;The clean re-measurement, on a point-in-time mid-cap corpus with the leaks fixed, put the same factor&apos;s 6-month IC at plus 0.046 with a Newey-West t of plus 3.5 over 2015 to 2021. Three caveats travel with that number in every record the engine writes. It is an upper bound, because the corpus has no in-window delistings. It is an information coefficient, not a net-of-cost portfolio return, and the engine has not shown that any factor survives transaction costs, which is the bar that decides anything. And in the 2024 to 2025 sub-window, the one with the least survivorship contamination, the same factor&apos;s 6-month IC is plus 0.008 with a Newey-West t of plus 0.39, indistinguishable from zero. Two readings compete, and both are open.&lt;/p&gt;
&lt;h2 id=&quot;the-gate-that-makes-the-correction-unskippable&quot;&gt;The gate that makes the correction unskippable&lt;a href=&quot;https://caskeycoding.com/blog/newey-west-standard-errors-backtest#the-gate-that-makes-the-correction-unskippable&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;A correction you remember to apply is a correction you will forget under deadline. After the 12-month episode I moved the effective-n calculation from a diagnostic printout into the engine&apos;s decision protocol. Every IC and t-statistic the engine records now carries an effective-n field. No factor weight is promoted unless the holdout cell that validated it has an effective n of at least 8 at the headline horizon, and none of the revision triggers, the checks that can propose a change to how a factor is scored, fires unless every horizon it names clears the same floor. Below the floor the cell reports itself as immature and not actionable, the same state the engine uses for a signal with no forward record at all. The floor of 8 is provisional and I expect to move it. The rule that a cell below the floor cannot change a weight is not.&lt;/p&gt;
&lt;p&gt;The 12-month cell was still immature when I wrote this. One non-overlapping annual window per year is a useful planning approximation, but estimated effective n depends on the observed series and can change as data accumulate. Shorter horizons mature sooner only if their dependence and other evidence checks permit it. Choosing a horizon affects how long I may need to wait before a result can justify a weight change.&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>Lesson 4: Define Repository Boundaries and Isolate Agent Work</title>
      <link>https://caskeycoding.com/blog/lesson-4-boundaries</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/lesson-4-boundaries</guid>
      <pubDate>Tue, 22 Sep 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>spec-driven-development</category>
      <category>AI</category>
      <category>engineering-methodology</category>
      <category>agents</category>
      <category>repository-layout</category>
      <description>Document which repository owns each part of the project. Assign each agent a specific scope and a separate checkout to prevent overlapping edits. Includes layout instructions and a repository-splitting exercise.</description>
      <content:encoded>&lt;p&gt;&lt;strong&gt;What you&apos;ll learn:&lt;/strong&gt; document which repository owns each part of your project, give each concurrent agent a separate checkout, and check that its changes stay within the assigned repository.
&lt;strong&gt;What you need:&lt;/strong&gt; a project in one folder, Git, your coding agent, and the &lt;code class=&quot;inline-code&quot;&gt;specs/&lt;/code&gt; directory from Lesson 1 if you have one.
&lt;strong&gt;Time:&lt;/strong&gt; about an hour for the example split. &lt;strong&gt;Cost:&lt;/strong&gt; no additional services or subscriptions.&lt;/p&gt;
&lt;h2 id=&quot;the-idea&quot;&gt;The idea&lt;a href=&quot;https://caskeycoding.com/blog/lesson-4-boundaries#the-idea&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Before an agent edits a file, require it to name the repository it will change. Give concurrent agents separate checkouts so their edits do not share working files. These are two different controls: repository boundaries scope commits, while checkout separation prevents one session from including another session&apos;s unfinished files in its commit.&lt;/p&gt;
&lt;p&gt;A repository is not a filesystem sandbox. An agent with access to neighboring directories can still edit them. The instruction file below defines permitted scope; enforcing filesystem access requires separate controls.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/lesson-4-boundaries-two-rows.svg&quot; alt=&quot;A shared checkout lets two sessions include each other&amp;#x27;s edits in a commit. Separate repositories define the assigned scope, and separate checkouts isolate concurrent working files. A task requiring two repositories stops for separate specs.&quot;&gt;&lt;/p&gt;
&lt;h2 id=&quot;why-start-here&quot;&gt;Why start here&lt;a href=&quot;https://caskeycoding.com/blog/lesson-4-boundaries#why-start-here&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Lessons 1 and 2 recorded requirements and decisions. Now identify where each requirement will be implemented. I separate infrastructure, application logic, and the interface when they need independent releases. A small project can retain one repository and still isolate concurrent work in separate checkouts. Splitting repositories is useful when the ownership and release boundaries justify the extra configuration.&lt;/p&gt;
&lt;h2 id=&quot;the-template&quot;&gt;The template&lt;a href=&quot;https://caskeycoding.com/blog/lesson-4-boundaries#the-template&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;This example uses four repositories under one parent directory:&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;myproject/
  specs/    # intent: specs and decisions        (Lessons 1-2 live here)
  infra/    # what runs where: cloud resources, DNS, buckets
  api/      # logic: handlers, jobs, data
  web/      # UI: pages, styles, static files
  CLAUDE.md # or AGENTS.md: the standing file, one line added below
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The template uses &lt;code class=&quot;inline-code&quot;&gt;home&lt;/code&gt; to mean the repository assigned to a change. &lt;code class=&quot;inline-code&quot;&gt;Home: web&lt;/code&gt; identifies &lt;code class=&quot;inline-code&quot;&gt;web/&lt;/code&gt;; it grants no filesystem permissions. Save the layout file as &lt;code class=&quot;inline-code&quot;&gt;.claude/skills/layout/SKILL.md&lt;/code&gt; in the parent directory, or put its instructions in &lt;code class=&quot;inline-code&quot;&gt;AGENTS.md&lt;/code&gt; if your tool has no skills:&lt;/p&gt;
&lt;pre class=&quot;shiki shiki-themes github-light github-dark&quot; style=&quot;background-color:#fff;--shiki-dark-bg:#24292e;color:#24292e;--shiki-dark:#e1e4e8&quot; tabindex=&quot;0&quot; data-language=&quot;markdown&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;---&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#22863A;--shiki-dark:#85E89D&quot;&gt;name&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;layout&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#22863A;--shiki-dark:#85E89D&quot;&gt;description&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;Where each kind of change lives in this project, and the rule for working in exactly one home per change. Read before touching any file.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;---&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold&quot;&gt;# Layout: one home per stack&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;| Home | Holds | Own repository | Ships by |&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;|---|---|---|---|&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;| &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;`specs/`&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; | intent: specs and decisions | yes | nothing; every session reads it |&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;| &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;`infra/`&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; | what runs where: cloud resources, DNS, buckets | yes | the infra deploy command |&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;| &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;`api/`&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; | logic: handlers, jobs, data | yes | the api pipeline |&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;| &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;`web/`&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; | UI: pages, styles, static files | yes | the web pipeline |&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold&quot;&gt;## Routing rule&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;1.&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; Read the standing file and the spec first. Before editing any file, name the home this change lives in, on one line: &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;`Home: web`&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;2.&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; Edit only inside that home. If the change needs two homes, stop and say so; it is two changes, and the spec comes first.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;3.&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; Cite the spec the change serves. Build what its acceptance criteria say; change nothing listed under its Out of scope.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold&quot;&gt;## Git rules (each home is its own repository)&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; One session per checkout. A second session gets its own clone of the home; branches alone do not separate working files.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; Start from a fresh branch off that home&apos;s main. Never commit on main.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; Commit only the files you changed, by path. Never &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;`git commit -a`&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; or &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;`git add -A`&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; Leave untracked files you did not create alone unless the change needs them; they may be someone else&apos;s work in progress.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; If the home has a remote, push the branch before reporting done; otherwise say the commit is local only.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; One commit never spans two repositories.&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The standing file is the instruction file your agent reads when a session starts, such as &lt;code class=&quot;inline-code&quot;&gt;CLAUDE.md&lt;/code&gt; or &lt;code class=&quot;inline-code&quot;&gt;AGENTS.md&lt;/code&gt;. Add this line:&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;Read the layout skill before touching any file, and follow its routing and git rules.
&lt;/code&gt;&lt;/pre&gt;
&lt;h2 id=&quot;each-part-and-the-mistake-it-prevents&quot;&gt;Each part, and the mistake it prevents&lt;a href=&quot;https://caskeycoding.com/blog/lesson-4-boundaries#each-part-and-the-mistake-it-prevents&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The &quot;Ships by&quot; column records release commands. Shared release commands can suggest code belongs together, but command count alone cannot decide repository structure. Consider interfaces and how often changes must be coordinated.&lt;/p&gt;
&lt;p&gt;A separate &lt;code class=&quot;inline-code&quot;&gt;specs/&lt;/code&gt; repository gives requirements their own review history. It does not stop an agent from changing a spec to match its implementation. Review requirement changes explicitly wherever you store them.&lt;/p&gt;
&lt;p&gt;The routing rule produces a statement you can compare with the final diff. A page change requiring an API change should stop under this template until both changes have specs. The statement alone cannot prevent a write outside the named repository.&lt;/p&gt;
&lt;p&gt;Branches do not separate files in a shared checkout. Two sessions using that directory see the same working files, even if each intended to use a different branch. Give the second session a separate clone. Stage files by path so a commit does not collect unrelated edits. Leave unfamiliar untracked files for their author to handle.&lt;/p&gt;
&lt;p&gt;The push rule distinguishes a remote branch from a local-only commit. Report that distinction in the completion message. A commit belongs to one repository; coordinated changes across repositories need separate commits and an explicit release order.&lt;/p&gt;
&lt;h2 id=&quot;a-worked-example&quot;&gt;A worked example&lt;a href=&quot;https://caskeycoding.com/blog/lesson-4-boundaries#a-worked-example&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;In the recorded exercise, &lt;code class=&quot;inline-code&quot;&gt;specs/web/001-robots.md&lt;/code&gt; required &lt;code class=&quot;inline-code&quot;&gt;web/public/robots.txt&lt;/code&gt; to disallow &lt;code class=&quot;inline-code&quot;&gt;/admin&lt;/code&gt;. It excluded &lt;code class=&quot;inline-code&quot;&gt;api/&lt;/code&gt; and &lt;code class=&quot;inline-code&quot;&gt;infra/&lt;/code&gt;. The scratch repositories had no remotes. A fresh session received the standing file and the request to implement that spec on a branch:&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;Home: web, per specs/web/001-robots.md, this only touches
web/public/robots.txt.
...
Done. Created web/public/robots.txt (disallows /admin) on branch
add-robots-txt in the web repo, committed as ff93e65. Both acceptance
checks from specs/web/001-robots.md pass. No remote is configured for
web, so this commit is local only.
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The session named &lt;code class=&quot;inline-code&quot;&gt;web&lt;/code&gt; before editing. Afterward, &lt;code class=&quot;inline-code&quot;&gt;specs/&lt;/code&gt;, &lt;code class=&quot;inline-code&quot;&gt;infra/&lt;/code&gt;, and &lt;code class=&quot;inline-code&quot;&gt;api/&lt;/code&gt; remained clean and on main. In a second run, I requested an API health endpoint and a homepage status indicator without a spec. The session identified the two repositories and stopped; all four remained untouched. These observations show compliance in those two runs, without establishing an access restriction.&lt;/p&gt;
&lt;h2 id=&quot;how-it-scales&quot;&gt;How it scales&lt;a href=&quot;https://caskeycoding.com/blog/lesson-4-boundaries#how-it-scales&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;At the time of the original lesson, my setup had fourteen repositories under one parent directory. The table provided one place to find their responsibilities. The parent directory itself was outside Git.&lt;/p&gt;
&lt;p&gt;Approve each split before moving files. The agent can propose the table and migration, initialize the new repositories, and prepare commits. Moving files also changes paths used by imports, builds, checks, and deployment scripts; verify those before treating the split as complete.&lt;/p&gt;
&lt;h2 id=&quot;from-the-field&quot;&gt;From the field&lt;a href=&quot;https://caskeycoding.com/blog/lesson-4-boundaries#from-the-field&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;On June 29, a formatting session ran &lt;code class=&quot;inline-code&quot;&gt;git commit -a&lt;/code&gt; in the backend checkout where I was developing a feature. It committed my tracked import to main but omitted the new module files, which were untracked. Main then raised an import error on load. The next deployment would have sent that code to twenty-odd functions.&lt;/p&gt;
&lt;p&gt;A small pull request removed the orphaned import. After that incident, each feature used its own checkout off main. The failure required both shared working files and a bulk commit; the layout instructions address each directly.&lt;/p&gt;
&lt;h2 id=&quot;exercise&quot;&gt;Exercise&lt;a href=&quot;https://caskeycoding.com/blog/lesson-4-boundaries#exercise&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;Save the layout file and add its instruction to the standing file.&lt;/li&gt;
&lt;li&gt;Identify the directories containing infrastructure, application logic, and interface code. Ask the agent to propose repository boundaries and review the table.&lt;/li&gt;
&lt;li&gt;Back up the project. For this four-repository exercise, have the agent move files, run &lt;code class=&quot;inline-code&quot;&gt;git init&lt;/code&gt; in each repository, and create one &lt;code class=&quot;inline-code&quot;&gt;init &amp;#x3C;home&gt;&lt;/code&gt; commit per repository. This starts fresh history. If history must be preserved, plan the migration with &lt;code class=&quot;inline-code&quot;&gt;git filter-repo&lt;/code&gt; before moving files.&lt;/li&gt;
&lt;li&gt;Move &lt;code class=&quot;inline-code&quot;&gt;specs/&lt;/code&gt; into its own repository, retaining spec numbers. Adjust verification paths for their documented working directory, such as &lt;code class=&quot;inline-code&quot;&gt;test -f web/public/robots.txt&lt;/code&gt; from the parent directory.&lt;/li&gt;
&lt;li&gt;Copy Lesson 3&apos;s &lt;code class=&quot;inline-code&quot;&gt;hooks/&lt;/code&gt; and &lt;code class=&quot;inline-code&quot;&gt;checks/&lt;/code&gt; into each code repository and configure &lt;code class=&quot;inline-code&quot;&gt;git config core.hooksPath hooks&lt;/code&gt;. Check that the spec check finds the adjacent &lt;code class=&quot;inline-code&quot;&gt;specs/&lt;/code&gt; directory. Configure remotes where you will use the pre-push hook, and verify the hook runs there.&lt;/li&gt;
&lt;li&gt;Select one ready spec that excludes the other repositories. Give it to a fresh session through the standing file, using a separate checkout for any concurrent work.&lt;/li&gt;
&lt;li&gt;Compare the agent&apos;s opening repository declaration with its final diff. Check the other repositories for unintended edits.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;youre-done-when&quot;&gt;You&apos;re done when&lt;a href=&quot;https://caskeycoding.com/blog/lesson-4-boundaries#youre-done-when&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The session must name its repository before editing, satisfy the selected spec, and leave only the intended changes in that repository. In the clean exercise, the other repositories remain clean and on main. Then request a change spanning two repositories without specs and confirm the session stops before editing. This checks instruction compliance for the requests you tested.&lt;/p&gt;
&lt;h2 id=&quot;common-mistakes&quot;&gt;Common mistakes&lt;a href=&quot;https://caskeycoding.com/blog/lesson-4-boundaries#common-mistakes&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Splitting by file extension can separate code that must change together. A parent Git repository can accidentally track files intended to belong to child repositories. Separate branches in one checkout still share working files. Check each of these before starting parallel sessions.&lt;/p&gt;
&lt;h2 id=&quot;further-reading&quot;&gt;Further reading&lt;a href=&quot;https://caskeycoding.com/blog/lesson-4-boundaries#further-reading&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Martin Fowler&apos;s &lt;a href=&quot;https://martinfowler.com/bliki/BoundedContext.html&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Bounded Context&lt;/a&gt; discusses model boundaries. Parnas&apos;s &lt;a href=&quot;https://www.win.tue.nl/~wstomv/edu/2ip30/references/criteria_for_modularization.pdf&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;On the Criteria To Be Used in Decomposing Systems into Modules&lt;/a&gt; examines module decomposition. The &lt;a href=&quot;https://code.claude.com/docs/en/skills&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Claude Code skills reference&lt;/a&gt; and &lt;a href=&quot;https://agents.md/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;AGENTS.md convention&lt;/a&gt; describe instruction-file formats.&lt;/p&gt;
&lt;h2 id=&quot;next-lesson&quot;&gt;Next lesson&lt;a href=&quot;https://caskeycoding.com/blog/lesson-4-boundaries#next-lesson&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;&lt;a href=&quot;https://caskeycoding.com/blog/lesson-5-the-charter&quot; class=&quot;internal-link&quot;&gt;Define What Agents Can Do Without Approval&lt;/a&gt; specifies permitted actions, actions requiring approval, and completion evidence.&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>Lesson 3: Enforce Project Rules with Automated Checks</title>
      <link>https://caskeycoding.com/blog/lesson-3-the-check-that-fails</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/lesson-3-the-check-that-fails</guid>
      <pubDate>Mon, 21 Sep 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>spec-driven-development</category>
      <category>AI</category>
      <category>engineering-methodology</category>
      <category>agents</category>
      <category>guardrails</category>
      <description>Turn a project rule into a script that detects violations. Run it before each push and test it with a deliberately invalid change. Learn what a local Git hook checks and how it can be bypassed.</description>
      <content:encoded>&lt;p&gt;&lt;strong&gt;What you&apos;ll learn:&lt;/strong&gt; write a script that detects a project-rule violation, run it through a Git pre-push hook, and test both rejection and success.
&lt;strong&gt;What you need:&lt;/strong&gt; the &lt;code class=&quot;inline-code&quot;&gt;specs/&lt;/code&gt; directory from &lt;a href=&quot;https://caskeycoding.com/blog/lesson-1-the-spec-directory&quot; class=&quot;internal-link&quot;&gt;Lesson 1&lt;/a&gt;, at least one spec with a &lt;code class=&quot;inline-code&quot;&gt;verify:&lt;/code&gt; line, a project with a Git remote, and your usual agent. The scripts use a POSIX shell, Git, &lt;code class=&quot;inline-code&quot;&gt;grep&lt;/code&gt;, and &lt;code class=&quot;inline-code&quot;&gt;sed&lt;/code&gt;; on Windows, use a compatible shell such as Git Bash.
&lt;strong&gt;Time:&lt;/strong&gt; allow fifteen minutes for setup and about two per simple rule afterward. &lt;strong&gt;Cost:&lt;/strong&gt; zero new dollars with your existing tools.&lt;/p&gt;
&lt;h2 id=&quot;the-idea&quot;&gt;The idea&lt;a href=&quot;https://caskeycoding.com/blog/lesson-3-the-check-that-fails#the-idea&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Turn a repeated project rule into a script that exits nonzero when it detects a violation. Configure Git to run the script before pushing. When the hook runs and fails, Git stops that push.&lt;/p&gt;
&lt;p&gt;A local hook is bypassable. &lt;code class=&quot;inline-code&quot;&gt;git push --no-verify&lt;/code&gt; skips it, and each clone needs its own configuration. Its checks also have limited coverage: a filename check can reject &lt;code class=&quot;inline-code&quot;&gt;.env&lt;/code&gt; without detecting secrets saved elsewhere. State the rule each script actually tests.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/lesson-3-the-check-that-fails-two-rows.svg&quot; alt=&quot;A written rule depends on the agent reading and following it. With the pre-push hook installed and active, Git runs the check and a nonzero result blocks the push. The local hook can be bypassed.&quot;&gt;&lt;/p&gt;
&lt;h2 id=&quot;why-start-here&quot;&gt;Why start here&lt;a href=&quot;https://caskeycoding.com/blog/lesson-3-the-check-that-fails#why-start-here&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;In July, I counted fourteen rules I had written over two months. One was enforced by a command. Start with a rule you repeatedly raise in review, then add a command for the acceptance checks in your in-progress specs. Written decisions still need judgment; automate the conditions you can evaluate directly.&lt;/p&gt;
&lt;h2 id=&quot;the-template&quot;&gt;The template&lt;a href=&quot;https://caskeycoding.com/blog/lesson-3-the-check-that-fails#the-template&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Save this as &lt;code class=&quot;inline-code&quot;&gt;hooks/pre-push&lt;/code&gt;, then run &lt;code class=&quot;inline-code&quot;&gt;chmod +x hooks/pre-push&lt;/code&gt; and &lt;code class=&quot;inline-code&quot;&gt;git config core.hooksPath hooks&lt;/code&gt;:&lt;/p&gt;
&lt;pre class=&quot;shiki shiki-themes github-light github-dark&quot; style=&quot;background-color:#fff;--shiki-dark-bg:#24292e;color:#24292e;--shiki-dark:#e1e4e8&quot; tabindex=&quot;0&quot; data-language=&quot;sh&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;#!/bin/sh&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;# hooks/pre-push: git runs this before every push. One script per rule lives in checks/.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;# A check fails by exiting non-zero; the first failure stops the push.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;for&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; check &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;in&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; checks/*.sh&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;do&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;  sh&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$check&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; ||&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; { &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;echo&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;BLOCKED by &lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$check&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; &gt;&amp;#x26;2&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;exit&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; 1&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; }&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;done&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;echo&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;all checks passed&quot;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Save the first rule as &lt;code class=&quot;inline-code&quot;&gt;checks/no-tracked-env.sh&lt;/code&gt;:&lt;/p&gt;
&lt;pre class=&quot;shiki shiki-themes github-light github-dark&quot; style=&quot;background-color:#fff;--shiki-dark-bg:#24292e;color:#24292e;--shiki-dark:#e1e4e8&quot; tabindex=&quot;0&quot; data-language=&quot;sh&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;# Rule: never commit a .env file, not even in a commit a later one fixes.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;if&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; git&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; ls-files&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; |&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; grep&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -qE&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &apos;(^|/)\.env$&apos;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; ||&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;   git&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; log&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; --branches&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; --not&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; --remotes&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; --diff-filter=A&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; --name-only&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; --format=&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; |&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;   grep&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -qE&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &apos;(^|/)\.env$&apos;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;then&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;  echo&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;.env is in a commit about to be pushed; undo that commit, then re-commit&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; &gt;&amp;#x26;2&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;  echo&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;the other files by path: git reset HEAD~&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; &gt;&amp;#x26;2&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;  exit&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; 1&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;fi&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;This checks paths named exactly &lt;code class=&quot;inline-code&quot;&gt;.env&lt;/code&gt; in the tracked files and additions in local branch commits absent from known remote refs. It is not a general secret scanner or an exact reconstruction of the push payload.&lt;/p&gt;
&lt;p&gt;Save this as &lt;code class=&quot;inline-code&quot;&gt;checks/specs-verify.sh&lt;/code&gt;:&lt;/p&gt;
&lt;pre class=&quot;shiki shiki-themes github-light github-dark&quot; style=&quot;background-color:#fff;--shiki-dark-bg:#24292e;color:#24292e;--shiki-dark:#e1e4e8&quot; tabindex=&quot;0&quot; data-language=&quot;sh&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;# Rule: every in-progress spec must pass its own verify command (Lesson 1).&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;[ &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;-d&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; specs ] &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;||&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; cd&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; ..&lt;/span&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;   # after Lesson 4&apos;s split, specs/ sits beside this repository&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;[ &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;-d&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; specs ] &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;||&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; { &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;echo&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;no specs/ directory found&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; &gt;&amp;#x26;2&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;exit&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; 1&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; }&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;for&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; spec &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;in&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; $(&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;grep&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -rl&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &apos;^status: in-progress&apos;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; specs&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; --include=&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&apos;*.md&apos;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;); &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;do&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;  cmd&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$(&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;sed&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -n&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &apos;s/^verify: *//p&apos;&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$spec&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; |&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; sed&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &apos;s/ *#.*//&apos;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; |&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; head&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -1&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;)&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;  [ &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;-n&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$cmd&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; ] &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;||&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; { &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;echo&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$spec&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; has no verify command&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; &gt;&amp;#x26;2&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;exit&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; 1&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; }&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;  sh&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -c&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$cmd&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; ||&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; { &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;echo&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; &quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$spec&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; failed its verify command: &lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;$cmd&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; &gt;&amp;#x26;2&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;exit&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; 1&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;; }&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;done&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;This starter script expects the shown frontmatter layout and spec paths without spaces. Review every &lt;code class=&quot;inline-code&quot;&gt;verify:&lt;/code&gt; command before running it; the script executes those commands through the shell. Confirm their working directory, particularly after the repository split in Lesson 4. If there are no matching in-progress specs, the loop runs no verification commands.&lt;/p&gt;
&lt;p&gt;Add this to the file your agent reads at session start:&lt;/p&gt;
&lt;pre class=&quot;shiki shiki-themes github-light github-dark&quot; style=&quot;background-color:#fff;--shiki-dark-bg:#24292e;color:#24292e;--shiki-dark:#e1e4e8&quot; tabindex=&quot;0&quot; data-language=&quot;markdown&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;When I state a rule for the second time, write checks/&amp;#x3C;&lt;/span&gt;&lt;span style=&quot;color:#22863A;--shiki-dark:#85E89D&quot;&gt;rule-name&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;&gt;.sh so it exits&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;non-zero when the rule is broken. Show me the check failing on a deliberate&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;violation, then passing after the fix, before you commit it.&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Commit &lt;code class=&quot;inline-code&quot;&gt;hooks/&lt;/code&gt; and &lt;code class=&quot;inline-code&quot;&gt;checks/&lt;/code&gt; together. The files travel with a clone; the &lt;code class=&quot;inline-code&quot;&gt;core.hooksPath&lt;/code&gt; setting does not. Configure it in each clone that should use the hook.&lt;/p&gt;
&lt;h2 id=&quot;each-part-and-the-mistake-it-prevents&quot;&gt;Each part, and the mistake it prevents&lt;a href=&quot;https://caskeycoding.com/blog/lesson-3-the-check-that-fails#each-part-and-the-mistake-it-prevents&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The runner invokes each shell script in &lt;code class=&quot;inline-code&quot;&gt;checks/&lt;/code&gt; and stops at the first nonzero exit. Keep at least one check in the folder. Name each file for its rule so the directory listing identifies the available checks and Git history records their changes.&lt;/p&gt;
&lt;p&gt;Git reads the exit code. A message that says “failed” while the script exits 0 allows the runner to continue. Include enough detail in the failure message to identify the violated rule and the correction needed.&lt;/p&gt;
&lt;p&gt;The spec check rejects a missing &lt;code class=&quot;inline-code&quot;&gt;specs/&lt;/code&gt; directory or an in-progress spec with no verification command. A passing command establishes its own assertions. It does not establish untested acceptance criteria or that every relevant spec was selected.&lt;/p&gt;
&lt;p&gt;Have the agent demonstrate failure and success before accepting a new check. Review both the rule it implements and where it runs. A script can be correct while the integration never invokes it.&lt;/p&gt;
&lt;h2 id=&quot;a-worked-example&quot;&gt;A worked example&lt;a href=&quot;https://caskeycoding.com/blog/lesson-3-the-check-that-fails#a-worked-example&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;A small site&apos;s &lt;code class=&quot;inline-code&quot;&gt;specs/app/001-robots.md&lt;/code&gt; contains &lt;code class=&quot;inline-code&quot;&gt;verify: test -f public/robots.txt&lt;/code&gt;. The required file is missing. In the recorded run, the push failed:&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;$ git push
specs/app/001-robots.md failed its verify command: test -f public/robots.txt
BLOCKED by checks/specs-verify.sh
error: failed to push some refs
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;After creating and committing the file, the next push printed &lt;code class=&quot;inline-code&quot;&gt;all checks passed&lt;/code&gt;. A deliberate &lt;code class=&quot;inline-code&quot;&gt;.env&lt;/code&gt; violation produced this result:&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;$ echo SECRET=1 &gt; .env &amp;#x26;&amp;#x26; git add -f .env &amp;#x26;&amp;#x26; git commit -m &quot;oops&quot;
$ git push
.env is in a commit about to be pushed; undo that commit, then re-commit
the other files by path: git reset HEAD~
BLOCKED by checks/no-tracked-env.sh
error: failed to push some refs
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;I undid that commit as directed and pushed again. Across four pushes, two were blocked and two succeeded. The remote never received the &lt;code class=&quot;inline-code&quot;&gt;.env&lt;/code&gt; file. These transcripts record that run; they do not verify a reader&apos;s installation. I also confirmed in the same run that &lt;code class=&quot;inline-code&quot;&gt;--no-verify&lt;/code&gt; bypassed the hook.&lt;/p&gt;
&lt;h2 id=&quot;when-it-grows&quot;&gt;When it grows&lt;a href=&quot;https://caskeycoding.com/blog/lesson-3-the-check-that-fails#when-it-grows&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;&lt;a href=&quot;https://caskeycoding.com/blog/lesson-7-the-pipeline-reviews&quot; class=&quot;internal-link&quot;&gt;Lesson 7&lt;/a&gt; runs checks in continuous integration (CI), the automated jobs triggered by repository changes. The hosting platform can require successful checks before merge. This adds enforcement beyond a developer&apos;s local hook. Verify the job triggers, required-check settings, and bypass permissions; a workflow file alone does not establish that a merge will be rejected.&lt;/p&gt;
&lt;h2 id=&quot;from-the-field&quot;&gt;From the field&lt;a href=&quot;https://caskeycoding.com/blog/lesson-3-the-check-that-fails#from-the-field&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;In June, I wrote a check for a style rule I had repeated for weeks. I connected it to the tool my agents used and fed the script a sample payload. It refused the sample. Five weeks later, live sessions were still breaking the rule, and the check had never blocked one.&lt;/p&gt;
&lt;p&gt;The sessions ran in a mode that ignored the signal the script used to refuse the action. My test exercised the script without checking how that mode handled its result. Reproducing the violation in a live session took one minute. Rewriting the check to refuse by exit code took ten more. The subsequent audit produced the fourteen-rules, one-enforced count.&lt;/p&gt;
&lt;h2 id=&quot;exercise&quot;&gt;Exercise&lt;a href=&quot;https://caskeycoding.com/blog/lesson-3-the-check-that-fails#exercise&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Use a disposable project and test remote with dummy data. Copy the hook and two checks, make the hook executable, configure &lt;code class=&quot;inline-code&quot;&gt;core.hooksPath&lt;/code&gt;, and add the standing instruction. Do not use real credentials for the &lt;code class=&quot;inline-code&quot;&gt;.env&lt;/code&gt; example.&lt;/p&gt;
&lt;p&gt;Give one spec &lt;code class=&quot;inline-code&quot;&gt;status: in-progress&lt;/code&gt; and a verification command that currently fails. Attempt a push and confirm that the failure names the spec and command. Correct the condition and confirm that the next push reports success.&lt;/p&gt;
&lt;p&gt;Give the agent your most-repeated rule and ask it to write the corresponding check. Introduce a known violation in a throwaway commit, attempt a push, and confirm that the new check blocks it. Undo the violation and confirm a successful push. Inspect the final branch to ensure the deliberate violation is gone.&lt;/p&gt;
&lt;h2 id=&quot;youre-done-when&quot;&gt;You&apos;re done when&lt;a href=&quot;https://caskeycoding.com/blog/lesson-3-the-check-that-fails#youre-done-when&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;You have observed two expected rejections through &lt;code class=&quot;inline-code&quot;&gt;git push&lt;/code&gt;: one from spec verification and one from your rule check. Each failure identifies the cause, and each correction permits the push. Record the tested repository, check, command, and result.&lt;/p&gt;
&lt;p&gt;A direct script run covers the script. The push exercise also covers Git invoking it in that clone. Neither observation proves that another clone, CI job, or merge rule is configured correctly. If the violation passes, inspect &lt;code class=&quot;inline-code&quot;&gt;core.hooksPath&lt;/code&gt;, executable permissions, the selected checks, and their exit codes before continuing.&lt;/p&gt;
&lt;h2 id=&quot;common-mistakes&quot;&gt;Common mistakes&lt;a href=&quot;https://caskeycoding.com/blog/lesson-3-the-check-that-fails#common-mistakes&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Deleting a committed secret in a later commit leaves it in earlier history. The example reads unpushed history for that reason. Rotate a real secret that has reached a remote.&lt;/p&gt;
&lt;p&gt;Avoid adding many speculative rules before testing the first one. Repeat the integration test when the surrounding tool changes. &lt;a href=&quot;https://caskeycoding.com/blog/lesson-9-the-monthly-drill&quot; class=&quot;internal-link&quot;&gt;Lesson 9&lt;/a&gt; schedules a monthly drill for a selected check and records exactly which controls it exercises.&lt;/p&gt;
&lt;h2 id=&quot;further-reading&quot;&gt;Further reading&lt;a href=&quot;https://caskeycoding.com/blog/lesson-3-the-check-that-fails#further-reading&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The &lt;a href=&quot;https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Git hooks chapter&lt;/a&gt; covers hook points. The &lt;a href=&quot;https://pre-commit.com/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;pre-commit framework&lt;/a&gt; supports shared check configuration. GitHub documents &lt;a href=&quot;https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;protected branches&lt;/a&gt;, and Claude Code documents &lt;a href=&quot;https://code.claude.com/docs/en/hooks&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;hooks inside agent tool calls&lt;/a&gt;.&lt;/p&gt;
&lt;h2 id=&quot;next-lesson&quot;&gt;Next lesson&lt;a href=&quot;https://caskeycoding.com/blog/lesson-3-the-check-that-fails#next-lesson&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;&lt;a href=&quot;https://caskeycoding.com/blog/lesson-4-boundaries&quot; class=&quot;internal-link&quot;&gt;Define Repository Boundaries and Isolate Agent Work&lt;/a&gt; assigns code ownership and separates concurrent edits into different checkouts.&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>Lesson 2: Record Technical Decisions and Their Reasons</title>
      <link>https://caskeycoding.com/blog/lesson-2-decision-records</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/lesson-2-decision-records</guid>
      <pubDate>Thu, 17 Sep 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>spec-driven-development</category>
      <category>AI</category>
      <category>engineering-methodology</category>
      <category>agents</category>
      <category>decision-records</category>
      <description>Write a decision record documenting what you chose, which alternatives you rejected, and when to reconsider. Instruct agents to read relevant decisions before proposing changes, then test whether they retrieve them.</description>
      <content:encoded>&lt;p&gt;&lt;strong&gt;What you&apos;ll learn:&lt;/strong&gt; document technical choices, rejected alternatives, and conditions for reconsidering. Instruct agents to retrieve those records before proposing changes.
&lt;strong&gt;What you need:&lt;/strong&gt; the &lt;code class=&quot;inline-code&quot;&gt;specs/&lt;/code&gt; directory from &lt;a href=&quot;https://caskeycoding.com/blog/lesson-1-the-spec-directory&quot; class=&quot;internal-link&quot;&gt;Lesson 1&lt;/a&gt;, an empty &lt;code class=&quot;inline-code&quot;&gt;decision/&lt;/code&gt; folder, and the agent you already use.
&lt;strong&gt;Time:&lt;/strong&gt; allow ten minutes for setup and about five per decision. &lt;strong&gt;Cost:&lt;/strong&gt; zero new dollars if your existing agent subscription covers the work.&lt;/p&gt;
&lt;h2 id=&quot;the-idea&quot;&gt;The idea&lt;a href=&quot;https://caskeycoding.com/blog/lesson-2-decision-records#the-idea&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;A decision record explains a technical choice and the reasons behind it. The code may show that your site uses static files, but it may not explain why you rejected a server, which costs you accepted, or when a server would become appropriate.&lt;/p&gt;
&lt;p&gt;Keep one file per settled choice and list the files in an index. Add a standing instruction that tells the agent to read the index and open relevant records before making changes. When a request conflicts with an accepted decision, the agent should cite it and stop for your decision.&lt;/p&gt;
&lt;p&gt;This depends on retrieval and compliance. A file can be missing, outdated, or ignored. The exercise tests whether a fresh session follows the instruction for one conflicting request; it does not establish that every future session will do so.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/lesson-2-decision-records-two-rows.svg&quot; alt=&quot;An agent without decision records reads the code and proposes a rejected option. An agent following the standing instruction reads the index, opens D-003, cites the conflicting decision, and stops before editing.&quot;&gt;&lt;/p&gt;
&lt;h2 id=&quot;why-start-here&quot;&gt;Why start here&lt;a href=&quot;https://caskeycoding.com/blog/lesson-2-decision-records#why-start-here&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;A feature spec states the result you intend to build. A decision record explains a choice that may affect many features. Keep them separate and link the relevant record from a spec when it constrains the implementation.&lt;/p&gt;
&lt;p&gt;Start with decisions you repeatedly explain: the deployment approach, a dependency you declined, or a service you chose to avoid. Record the actual reason. “We prefer this framework” tells the next session less than the compatibility or maintenance requirement that determined the choice.&lt;/p&gt;
&lt;h2 id=&quot;the-template&quot;&gt;The template&lt;a href=&quot;https://caskeycoding.com/blog/lesson-2-decision-records#the-template&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Save this as &lt;code class=&quot;inline-code&quot;&gt;specs/decision/_template.md&lt;/code&gt;:&lt;/p&gt;
&lt;pre class=&quot;shiki shiki-themes github-light github-dark&quot; style=&quot;background-color:#fff;--shiki-dark-bg:#24292e;color:#24292e;--shiki-dark:#e1e4e8&quot; tabindex=&quot;0&quot; data-language=&quot;markdown&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold&quot;&gt;# D-000: &amp;#x3C;&lt;/span&gt;&lt;span style=&quot;color:#22863A;--shiki-light-font-weight:bold;--shiki-dark:#85E89D;--shiki-dark-font-weight:bold&quot;&gt;what&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-light-font-weight:bold;--shiki-dark:#B392F0;--shiki-dark-font-weight:bold&quot;&gt; we&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-light-font-weight:bold;--shiki-dark:#B392F0;--shiki-dark-font-weight:bold&quot;&gt; decided,&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-light-font-weight:bold;--shiki-dark:#B392F0;--shiki-dark-font-weight:bold&quot;&gt; as&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-light-font-weight:bold;--shiki-dark:#B392F0;--shiki-dark-font-weight:bold&quot;&gt; a&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-light-font-weight:bold;--shiki-dark:#B392F0;--shiki-dark-font-weight:bold&quot;&gt; noun&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-light-font-weight:bold;--shiki-dark:#B392F0;--shiki-dark-font-weight:bold&quot;&gt; phrase&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;Status: draft        Date: YYYY-MM-DD&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;(draft until checked against the code; then accepted; later superseded by D-NNN)&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold&quot;&gt;## Context&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;What forced a choice, in one paragraph: budget, time, one person, a failure.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold&quot;&gt;## Decision&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;One sentence, present tense. &quot;We build the site as static files served from object storage.&quot;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold&quot;&gt;## Alternatives considered&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; &amp;#x3C;&lt;/span&gt;&lt;span style=&quot;color:#22863A;--shiki-dark:#85E89D&quot;&gt;option&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;&gt;: rejected because &amp;#x3C;&lt;/span&gt;&lt;span style=&quot;color:#22863A;--shiki-dark:#85E89D&quot;&gt;one&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; line&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;&gt;.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; &amp;#x3C;&lt;/span&gt;&lt;span style=&quot;color:#22863A;--shiki-dark:#85E89D&quot;&gt;option&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;&gt;: rejected because &amp;#x3C;&lt;/span&gt;&lt;span style=&quot;color:#22863A;--shiki-dark:#85E89D&quot;&gt;one&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; line&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;&gt;.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold&quot;&gt;## Consequences&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;What this makes easier. What it costs. What it forbids.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold&quot;&gt;## What would change our mind&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;The observable condition that reopens this decision: a number, an event, or a date.&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Save this as &lt;code class=&quot;inline-code&quot;&gt;specs/decision/README.md&lt;/code&gt;:&lt;/p&gt;
&lt;pre class=&quot;shiki shiki-themes github-light github-dark&quot; style=&quot;background-color:#fff;--shiki-dark-bg:#24292e;color:#24292e;--shiki-dark:#e1e4e8&quot; tabindex=&quot;0&quot; data-language=&quot;markdown&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold&quot;&gt;# Decisions&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;One file per settled choice. Read this table before proposing a change.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;The index is the allocator: claim the next row here first, then create the&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;file with that number. Agents request a number; they never pick one.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;Superseded records keep their file and number. Nothing is reused.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;| Id | Title | Status | Decision |&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;|---|---|---|---|&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;| D-001 | ... | accepted | ... |&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Reserve each number in the index before creating its file. The table is a record of reservations, with no automatic locking. When several agents are working, coordinate who updates it and check for duplicate identifiers before accepting their changes.&lt;/p&gt;
&lt;p&gt;Add this to the file your agent reads at session start, beside the instruction from Lesson 1:&lt;/p&gt;
&lt;pre class=&quot;shiki shiki-themes github-light github-dark&quot; style=&quot;background-color:#fff;--shiki-dark-bg:#24292e;color:#24292e;--shiki-dark:#e1e4e8&quot; tabindex=&quot;0&quot; data-language=&quot;markdown&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;Before proposing or making any change, read specs/decision/README.md and open any&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;record the request touches. If the change would reverse an accepted decision, cite&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;its id, say whether its &quot;What would change our mind&quot; condition has been met, and stop.&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;If the tool does not load a standing file, paste the index and instruction at the start of the session. In either setup, the agent still needs access to the referenced files. The index gives a summary; the full record contains the reasons and reconsideration condition.&lt;/p&gt;
&lt;h2 id=&quot;each-part-and-the-mistake-it-prevents&quot;&gt;Each part, and the mistake it prevents&lt;a href=&quot;https://caskeycoding.com/blog/lesson-2-decision-records#each-part-and-the-mistake-it-prevents&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Status tells readers whether a record is a proposal, an accepted choice, or a superseded decision. For this exercise, document choices already made and check them against the code before marking them accepted. Do not describe a proposed migration as the current implementation.&lt;/p&gt;
&lt;p&gt;Context names the constraint that affected the choice. Budget, maintenance time, compatibility, or a previous failure can explain why an otherwise reasonable alternative was rejected. Include enough detail for a later reader to judge whether that constraint still applies.&lt;/p&gt;
&lt;p&gt;Decision states the choice in one sentence. Alternatives considered records the options you evaluated and the reason for rejecting each. Ask the agent to draft those sections from the original discussion, then verify that it has not invented an option or rationale.&lt;/p&gt;
&lt;p&gt;Consequences records the benefit and the inconvenience you accepted. The reconsideration section names an observable event, threshold, or date. “When we grow” is too vague to evaluate. A specific new requirement gives the next reviewer a reason to reopen the choice.&lt;/p&gt;
&lt;p&gt;Keep superseded files, retain their identifiers, and link to the replacement decision. I found identifier collisions on two separate days: two files shared one number, then three shared another. Several records had been added together, and nobody checked the numbers again for months. Reserving numbers helps only when contributors consult the same index.&lt;/p&gt;
&lt;h2 id=&quot;a-worked-example&quot;&gt;A worked example&lt;a href=&quot;https://caskeycoding.com/blog/lesson-2-decision-records#a-worked-example&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Save as &lt;code class=&quot;inline-code&quot;&gt;specs/decision/D-003-static-site-export.md&lt;/code&gt;:&lt;/p&gt;
&lt;pre class=&quot;shiki shiki-themes github-light github-dark&quot; style=&quot;background-color:#fff;--shiki-dark-bg:#24292e;color:#24292e;--shiki-dark:#e1e4e8&quot; tabindex=&quot;0&quot; data-language=&quot;markdown&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold&quot;&gt;# D-003: Static site export instead of a server&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;Status: accepted        Date: 2026-09-10&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold&quot;&gt;## Context&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;One person, a personal site, about twelve dollars a month for hosting. Pages&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;change a few times a week. Nothing on the site is per-user.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold&quot;&gt;## Decision&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;We build the site to static files and serve them from object storage behind a CDN.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold&quot;&gt;## Alternatives considered&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; Managed Node host: rejected because it adds a monthly bill and a process to&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;  patch for pages that never change per request.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; Serverless rendering: rejected because cold starts and per-request code buy&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;  nothing for content that is identical for every visitor.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold&quot;&gt;## Consequences&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;Deploys are a file sync. Anything that needs per-user state, a form or a search&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;box, becomes a separate small API rather than a server behind the site.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold&quot;&gt;## What would change our mind&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;A page needs per-user rendering, or the CDN bill passes twenty dollars in a month.&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Add this index row: &lt;code class=&quot;inline-code&quot;&gt;| D-003 | Static site export instead of a server | accepted | Static files on object storage behind a CDN |&lt;/code&gt;&lt;/p&gt;
&lt;p&gt;The example names a hosting choice, two rejected options, the accepted limit on per-user behavior, and two conditions for reconsidering. Its dollar amounts belong to the example; use your own constraints when writing a record. A request for per-user rendering should cause the agent to open D-003 and ask whether you want to reconsider it before changing the architecture.&lt;/p&gt;
&lt;h2 id=&quot;from-the-field&quot;&gt;From the field&lt;a href=&quot;https://caskeycoding.com/blog/lesson-2-decision-records#from-the-field&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;On May 17 and 18, I audited 166 decision records across my repositories and produced seven fix pull requests. One accepted record said the backend used a vendor&apos;s agent toolkit as its default runtime. The code never had. A later decision routed calls directly to the vendor&apos;s API, but the older record still said to adopt the toolkit. New sessions kept proposing it.&lt;/p&gt;
&lt;p&gt;I marked that record superseded and retained its file and number. I also closed two placeholder records that existed only to satisfy forward references, with notes saying not to revive them. The audit exposed two problems: records that contradicted the implementation, and sessions proposing changes without consulting the relevant history. Both needed correction.&lt;/p&gt;
&lt;h2 id=&quot;exercise&quot;&gt;Exercise&lt;a href=&quot;https://caskeycoding.com/blog/lesson-2-decision-records#exercise&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Create &lt;code class=&quot;inline-code&quot;&gt;specs/decision/&lt;/code&gt;, copy the template and index, and add the standing instruction to the file your agent loads. Confirm that the instruction names the right path.&lt;/p&gt;
&lt;p&gt;Choose one decision you made this month. Reserve its number in the index. Let the agent draft Context and Alternatives from the discussion where you made the choice. Write the Decision and reconsideration condition yourself, check the result against the code, and mark it accepted. Repeat for two choices you keep explaining to new sessions. Omit entries that have no actual choice or rejected alternative.&lt;/p&gt;
&lt;p&gt;Open a fresh session that loads your standing file. Request a change that conflicts with one accepted decision without mentioning the record. For the example, ask to switch to a server for per-user rendering. Inspect what the agent reads and says before it edits any files.&lt;/p&gt;
&lt;h2 id=&quot;youre-done-when&quot;&gt;You&apos;re done when&lt;a href=&quot;https://caskeycoding.com/blog/lesson-2-decision-records#youre-done-when&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;You have three records with distinct identifiers, accurate status, rejected alternatives, and observable reconsideration conditions. In the fresh session, the agent opens the relevant file, cites its identifier, evaluates the condition, and stops for your decision before editing.&lt;/p&gt;
&lt;p&gt;If it starts implementing immediately, inspect whether it loaded and followed the instruction. If it only repeats the index row, require it to open the full record. Supplying the record yourself bypasses the retrieval step you are testing. Save the result as evidence for that session and request.&lt;/p&gt;
&lt;h2 id=&quot;common-mistakes&quot;&gt;Common mistakes&lt;a href=&quot;https://caskeycoding.com/blog/lesson-2-decision-records#common-mistakes&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;An accepted record that contradicts the code can direct later work toward the wrong design. Check the implementation when you accept or revise a record. Preserve the difference between a decision already applied and a migration still proposed.&lt;/p&gt;
&lt;p&gt;Keep the index short enough to scan and the reasons in the individual files. Review agent-drafted rationales against the original discussion. When circumstances change, record a replacement decision and link the old one forward.&lt;/p&gt;
&lt;h2 id=&quot;next-lesson&quot;&gt;Next lesson&lt;a href=&quot;https://caskeycoding.com/blog/lesson-2-decision-records#next-lesson&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;&lt;a href=&quot;https://caskeycoding.com/blog/lesson-3-the-check-that-fails&quot; class=&quot;internal-link&quot;&gt;Enforce Project Rules with Automated Checks&lt;/a&gt; adds scripts that detect specified violations and a local Git hook that runs them before a push.&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>One summer of building with AI agents, counted commit by commit</title>
      <link>https://caskeycoding.com/blog/a-summer-of-sharpening</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/a-summer-of-sharpening</guid>
      <pubDate>Mon, 31 Aug 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>AI</category>
      <category>spec-driven-development</category>
      <category>claude-code</category>
      <category>methodology</category>
      <category>engineering-velocity</category>
      <description>The third post in the SDD numbers series is not about velocity. Since June the platform&apos;s effort moved into four quiet systems: an externalized memory, a statistical screen that refuses to flatter me, a point-in-time data floor, and a product designed entirely on paper. What that did to the shape of a productive week.</description>
      <content:encoded>&lt;p&gt;On August 29 the entire platform, 25 repositories, produced ten commits. In the June numbers post a day like that would have read as an outage: that workflow was merging 29 pull requests a day and I published the throughput as the story. But August 29 was one of the most productive days of the year. It produced two orchestrated research batteries, nine briefs and reports with 163 evidence captures behind them, and a policy research report with a claim ledger and a build loop that regenerated the document seven times in twenty minutes until its own verification passed. The work did not slow down this summer. It changed shape, away from output and into sharpening.&lt;/p&gt;
&lt;p&gt;The totals I recorded from June 10 through the end of August were 4,141 commits, 2,244 merged pull requests across the fleet, and 488 new specification documents. More than a hundred authored research documents sat outside git. These are historical bookkeeping totals, not a reproducible productivity measure: this post does not include the counting query, repository inclusion list, time-zone cutoff, or treatment of merge and squash commits. They describe the volume I recorded, while the examples below explain where the effort went.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/a-summer-of-sharpening-compounds.svg&quot; alt=&quot;Four labeled boxes, externalized memory, signal-screen ledger, point-in-time data floor, and product rulings on paper, with arrows converging into a single green box labeled the base that compounds.&quot;&gt;&lt;/p&gt;
&lt;h2 id=&quot;what-the-merges-bought-first&quot;&gt;What the merges bought first&lt;a href=&quot;https://caskeycoding.com/blog/a-summer-of-sharpening#what-the-merges-bought-first&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;A fair reading of 2,244 merges is churn, so before the systems underneath, a sample of what shipped on the visible surface. This site&apos;s navigation was rebuilt from scratch around a content graph: every project, post, and tool is an entry in a public manifest, and the homepage now renders six interchangeable views over that one graph, a curated overview, a filterable index, a systems map, a scatter plot, an altitude ladder, and a timeline, each behind a hard performance budget with its own code split. The finance section was reorganized around goals instead of tools: a start page that routes by what you are trying to learn, the sidebar regrouped into four goal groups, and an intro header on every route saying plainly what each tool does and does not do. A new page inventories every equation the platform uses, rendered from the same registry the code imports, so the math on the site and the math in the engines cannot drift apart. The blog gained structured answers on sixteen posts, an instant-indexing lane, and a receipt-hashing gate for a new series that publishes its verification evidence beside every claim. Even the 404 page got the treatment: a sweep read the live analytics, found where real visitors hit dead ends, and turned the top offenders into redirects. That is the typing the ledger does count. The rest of the summer went underneath it.&lt;/p&gt;
&lt;h2 id=&quot;memory-that-outlives-the-session&quot;&gt;Memory that outlives the session&lt;a href=&quot;https://caskeycoding.com/blog/a-summer-of-sharpening#memory-that-outlives-the-session&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The first investment extends the &lt;a href=&quot;https://caskeycoding.com/blog/institutional-memory-for-a-team-of-one&quot; class=&quot;internal-link&quot;&gt;institutional memory system&lt;/a&gt; I wrote about in July, and it earned its keep by surviving &lt;a href=&quot;https://caskeycoding.com/blog/the-pipeline-that-ate-itself&quot; class=&quot;internal-link&quot;&gt;its worst failure&lt;/a&gt;. Every working session is distilled overnight into typed records: a decision with its date, an open loop with its owner, a gotcha with the exact command that triggers it. The store holds tens of thousands of these records, redaction runs at ingest so the corpus is safe to back up, and query tools sit in front of it so any session can ask what the fleet already knows about a repo, an error message, or a half-remembered choice. This summer it grew self-healing lanes: a pass that hunts contradictions between stored facts, a staleness review that flags claims about code that has since moved, and a closure pass that retires open loops whose work already shipped. Each lane had to clear an evaluation gate before it was allowed to touch the store; the first gate scored nineteen for nineteen against a hand-graded counterfactual baseline before the pipeline ran live once.&lt;/p&gt;
&lt;p&gt;Sessions start already knowing what June decided. The standing rule is now that no session may declare &quot;there is no record of that&quot; without asking the memory system first, and the recall log that enforces it shows questions settled from the store that would otherwise have been re-litigated from scratch.&lt;/p&gt;
&lt;h2 id=&quot;a-screen-that-refuses-to-flatter-me&quot;&gt;A screen that refuses to flatter me&lt;a href=&quot;https://caskeycoding.com/blog/a-summer-of-sharpening#a-screen-that-refuses-to-flatter-me&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The second investment is the statistical screen that sits between market data and anything I might act on. Every hypothesis gets a pre-registered cell in an append-only ledger before it runs: this signal, this slice of the universe, this window. Results land once and are never edited, and the false-discovery correction is applied across the entire family of tests rather than per test, so running more experiments raises the bar for each one instead of buying more lottery tickets. When a contamination review found the early candidate pool had leaked its benchmark, the whole pool was killed rather than argued for. The screen&apos;s confirmed-discovery count, after a summer of hardening, is zero. That number is the system working. &lt;a href=&quot;https://caskeycoding.com/blog/backtesting-without-fooling-yourself&quot; class=&quot;internal-link&quot;&gt;I wrote in June&lt;/a&gt; that the most dangerous result I produce is the one I was hoping for; this is that sentence built into infrastructure, hobbyist research run for the engineering, and the engineering&apos;s first product is a null result.&lt;/p&gt;
&lt;p&gt;This summer the screen&apos;s ledger was compacted into immutable segments, its backup gap closed, and its research strategist re-enabled against a 48,000-cell test backlog it drains on a schedule, at a budgeted pace, without me touching it. Its output is memos, not actions, and nothing it finds gets believed by default.&lt;/p&gt;
&lt;h2 id=&quot;a-floor-under-the-data&quot;&gt;A floor under the data&lt;a href=&quot;https://caskeycoding.com/blog/a-summer-of-sharpening#a-floor-under-the-data&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Third, the data itself. Any long backtest assumes you can see the companies that died, and most free data cannot. Worse, the shortcuts fail in ways that look like success. One free daily-price archive, downloaded and checked this month, turned out to be a survivor-only backfill: the current index membership projected into the past, every dead company absent. And dead tickers do not stay dead; symbols get reused, so a naive lookup for a delisted name can return a different company wearing the same letters. So the summer&apos;s data-mining push went at the survivorship assumption directly, from regulatory filings as primary sources. What exists now, as running code with its own diagnostics: a delisting-event table built from Form 25 filings back to 2006, with each event classified by whether the company actually left the universe or just changed venues; a point-in-time fundamentals loader over the SEC&apos;s Financial Statement Data Sets, which reach back to 2009; a daily index-membership table so the universe is defined by what was actually in it, not what survived; a fund-holdings harvest from archived N-Q filings as an independent cross-check on that membership; a quarterly high-low price extractor for the dead names themselves, pulled from the Item 5 tables of their old 10-K filings; and a coverage census that pushed the hardest filing family from 25 percent extraction to 75. Behind the synthesis sit 221 captured filings as evidence. The result is a measured boundary instead of a vibe: I know exactly which claims the free primary record can support, and the one gap that remains, daily prices for the dead names, is named in the synthesis rather than papered over. The posture is measurement first; nothing gets certified for use until the floor holds.&lt;/p&gt;
&lt;h2 id=&quot;a-product-built-on-paper-first&quot;&gt;A product built on paper first&lt;a href=&quot;https://caskeycoding.com/blog/a-summer-of-sharpening#a-product-built-on-paper-first&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The fourth investment produced no code at all. A new product spent the summer as a stack of numbered rulings: competitive landscape, packaging and signing, pricing, trust and autonomy boundaries, release mechanics, each question argued to a decision before implementation gets to exist. Every ruling reads the same way: the question, a verdict, the reasoning, and one concrete recommendation, so a later disagreement argues with a written position instead of a vague memory. This is the spec-first method from the April playbook applied at product scale, with the judgment front-loaded where changing your mind is cheap. When the building starts, it will start the way the best weeks of June did: from a brief that already removed the need to guess.&lt;/p&gt;
&lt;h2 id=&quot;refining-the-machine-that-does-the-work&quot;&gt;Refining the machine that does the work&lt;a href=&quot;https://caskeycoding.com/blog/a-summer-of-sharpening#refining-the-machine-that-does-the-work&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Underneath all four runs the same discipline, applied to the workflow itself. The operational lessons file is now 26 numbered entries, and the standing rule for each is that prose is advice; only a check is a guarantee. Lessons get promoted into enforced gates, and the summer&apos;s additions show the shape: the scheduled job that reported success for weeks while failing every run became a health check that judges config rot, exit result, and staleness as three independent signals; the deploy that once clobbered a backend-owned file became a generated exclude list with a post-deploy probe that fails loudly; the watchdogs themselves get a deliberately planted failure each week to prove they still bark. A weekly pass sweeps the week&apos;s corrections back into the briefs, specs, and configs that caused them, so the same mistake has somewhere harder to live. The payoff showed up at the end of August, twice. First a three-day integration wave merged 59 pull requests across 12 repositories. Then the month&apos;s final evening merged 157 more in one sitting, the largest merge day of the summer, with the gates doing the reviewing that used to be my evening. A backlog that size clearing in one pass is not a burst of heroics; it is what the review machinery makes routine.&lt;/p&gt;
&lt;h2 id=&quot;where-that-leaves-it&quot;&gt;Where that leaves it&lt;a href=&quot;https://caskeycoding.com/blog/a-summer-of-sharpening#where-that-leaves-it&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The series now has three points, and they measure different questions. April asked whether the workflow could ship at all. June asked how fast. This summer&apos;s question was what the speed runs on, and the answer only shows up in next month&apos;s numbers.&lt;/p&gt;
&lt;hr&gt;
&lt;p&gt;&lt;strong&gt;Previous in the series:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Ten days of June: the SDD velocity numbers, seven weeks in&lt;/li&gt;
&lt;li&gt;One week of SDD in production: the numbers&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://caskeycoding.com/blog/sdd-is-context-management&quot; class=&quot;internal-link&quot;&gt;SDD isn&apos;t about managing AI agents, it&apos;s about managing context&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;</content:encoded>
    </item>
    <item>
      <title>Seven articles to a platform that improves itself</title>
      <link>https://caskeycoding.com/blog/seven-articles-to-a-platform-that-improves-itself</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/seven-articles-to-a-platform-that-improves-itself</guid>
      <pubDate>Sat, 29 Aug 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>AI</category>
      <category>agents</category>
      <category>spec-driven-development</category>
      <category>engineering-methodology</category>
      <category>automation</category>
      <description>The full path to an agent platform that edits its own instructions is already published, scattered across seven articles that never mention each other. I run that architecture as one person: supervisor and worker tiers, verification guards, external memory, a work queue, and a weekly pass that sweeps corrections back into the instruction files. Here is the platform, layer by layer, with the article that teaches each layer.</description>
      <content:encoded>&lt;p&gt;Everything you need to build an agent platform that improves its own instructions is already published, scattered across seven articles that never mention each other. The destination looks like this: agents do real work, humans leave specific feedback where the work happens, and a scheduled pass turns the accumulated feedback into reviewed edits to the very files the agents run on. Anthropic recently profiled a company running that loop in production, but the loop is the roof. The articles that teach the walls and the foundation came out separately, under titles that sound like standalone advice.&lt;/p&gt;
&lt;p&gt;I run the whole stack as one person. A frontier-tier session plans, decomposes, and reviews; cheaper executors implement from written briefs against a 1,500-item work queue; every change lands through a pull request; a guard suite plants deliberate violations weekly to prove every check still fires; memory, decision records, and per-project rulings ledgers persist what sessions learn; and a weekly improvement pass sweeps accumulated corrections back into the instruction files that caused them. None of that design is mine in any deep sense. It is what falls out of taking the seven articles below in order.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/seven-articles-to-a-platform-that-improves-itself-whole-picture.svg&quot; alt=&quot;A pipeline of four boxes: instruction files feed a supervisor that plans and writes briefs, workers implement, and gates verify before work ships. Corrections accumulate below as LESSON: comments, ledgers, and memories, and a green weekly /improve arrow returns them to the instruction files, crossing a purple mark labeled &amp;#x22;a person merges each edit.&amp;#x22;&quot;&gt;&lt;/p&gt;
&lt;h2 id=&quot;start-with-the-orchestration-shape-not-the-agent&quot;&gt;Start with the orchestration shape, not the agent&lt;a href=&quot;https://caskeycoding.com/blog/seven-articles-to-a-platform-that-improves-itself#start-with-the-orchestration-shape-not-the-agent&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;&lt;a href=&quot;https://www.anthropic.com/engineering/building-effective-agents&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Building Effective Agents&lt;/a&gt; argues for the simplest structure that works: workflows before autonomy, and the orchestrator-workers pattern when subtasks cannot be predicted in advance. This article decides your architecture, which is why it comes first. In my platform it became a routing decision record: a supervisor session owns decomposition, brief-writing, and merge judgment, while implementation dispatches to cheaper executors with the model tier stamped on every work item. A brief must carry the goal, the exact files, the verify commands, and what is out of scope. If I cannot write that brief, the item is not ready, and no agent sees it.&lt;/p&gt;
&lt;h2 id=&quot;give-the-agent-a-check-it-cannot-talk-past&quot;&gt;Give the agent a check it cannot talk past&lt;a href=&quot;https://caskeycoding.com/blog/seven-articles-to-a-platform-that-improves-itself#give-the-agent-a-check-it-cannot-talk-past&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;&lt;a href=&quot;https://www.anthropic.com/engineering/claude-code-best-practices&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Claude Code Best Practices&lt;/a&gt; is remembered for tips, but its spine is one rule: give the agent a verification check, because without one &quot;looks done&quot; is the only signal. Built out fully, that rule stops being a prompt habit and becomes infrastructure. My version is a review gate that inventories the evidence each acceptance criterion names and refuses a merge when an artifact is absent, plus a weekly job that plants deliberate violations and asserts every guard rejects them. The phrasing I carry: a check you never see fail is indistinguishable from a check that is dead.&lt;/p&gt;
&lt;h2 id=&quot;move-memory-outside-the-context-window&quot;&gt;Move memory outside the context window&lt;a href=&quot;https://caskeycoding.com/blog/seven-articles-to-a-platform-that-improves-itself#move-memory-outside-the-context-window&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;&lt;a href=&quot;https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Effective Context Engineering&lt;/a&gt; treats context as a finite attention budget and pushes state into external notes retrieved just in time. At platform scale this becomes a filing system with teeth: a memory index loaded at session start, reference files read only when relevant, per-project rulings ledgers that record every judgment call a worker needed once, and subagents that do deep reading in their own context and return summaries. Sessions end; the platform remembers anyway.&lt;/p&gt;
&lt;h2 id=&quot;scale-effort-to-the-question&quot;&gt;Scale effort to the question&lt;a href=&quot;https://caskeycoding.com/blog/seven-articles-to-a-platform-that-improves-itself#scale-effort-to-the-question&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The &lt;a href=&quot;https://www.anthropic.com/engineering/built-multi-agent-research-system&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;multi-agent research system&lt;/a&gt; post supplies the numbers the other articles lack: one agent and a handful of tool calls for a simple lookup, two to four for a comparison, double digits only for complex work, with explicit stop conditions because their agents once spawned fifty subagents for a trivial query. Those rules now sit verbatim in my orchestration and triage docs, and every dispatch brief states how much work the item buys. Parallel fan-out is the easy half; bounded fan-out is the half that keeps a subscription alive.&lt;/p&gt;
&lt;h2 id=&quot;design-the-interfaces-like-products&quot;&gt;Design the interfaces like products&lt;a href=&quot;https://caskeycoding.com/blog/seven-articles-to-a-platform-that-improves-itself#design-the-interfaces-like-products&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Two articles cover what the agent touches. &lt;a href=&quot;https://www.anthropic.com/engineering/writing-tools-for-agents&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Writing Effective Tools for Agents&lt;/a&gt; says to consolidate tools around workflows, return semantic identifiers, and write error messages that state the corrective next step; auditing my own MCP server against it is a queued work item, because eighteen tools grown by wrapping an API is exactly the shape it warns about. The &lt;a href=&quot;https://claude.com/blog/skills&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Agent Skills&lt;/a&gt; post covers the instruction side: skills as files with progressive disclosure, minimal instructions written against real failures, and one rule I had never applied anywhere: test a skill on the model tier that will run it, not the tier that wrote it. My commands, agents, and skills all live as PR-reviewed files in one repository, which is the precondition for the final layer.&lt;/p&gt;
&lt;h2 id=&quot;close-the-loop-last&quot;&gt;Close the loop last&lt;a href=&quot;https://caskeycoding.com/blog/seven-articles-to-a-platform-that-improves-itself#close-the-loop-last&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The capstone article is Anthropic&apos;s case study on &lt;a href=&quot;https://claude.com/blog/how-warp-builds-self-improving-agents-on-claude&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;how Warp builds self-improving agents&lt;/a&gt;, and the pattern it describes only works once everything above exists, because an improver needs instruction files worth editing and feedback worth harvesting. I learned the cost of skipping it directly. One worker command line lived in two harness files; I fixed one copy, and the other stayed wrong for twenty days and two failed launches, because the correction lived in prose nothing ever swept forward. After reading the case study, I shipped my version of the loop in a day: review comments prefixed &lt;code class=&quot;inline-code&quot;&gt;LESSON:&lt;/code&gt; capture corrections during normal PR review, a zero-token weekly script sweeps them into a digest along with ledger and feedback entries, and a supervisor pass turns the digest into small pull requests against the instruction files, with a guard that now makes the duplicated-command-line failure a failing check. Its first live run found an instruction gap within the hour.&lt;/p&gt;
&lt;h2 id=&quot;what-stays-human&quot;&gt;What stays human&lt;a href=&quot;https://caskeycoding.com/blog/seven-articles-to-a-platform-that-improves-itself#what-stays-human&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Every layer above leaves the same residue: a person holds the gates. I review the improver&apos;s PRs, own anything touching spend or publishing, and read a morning briefing file that a scheduled job assembles from the platform&apos;s own health signals. The reading order matters because each article assumes the previous layer: verification is meaningless without decomposed work, memory without verification just persists mistakes, and a self-improvement loop without all four beneath it edits files nothing enforces.&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>Backtesting the 5/10 crossover strategy that never lost</title>
      <link>https://caskeycoding.com/blog/autopsy-five-ten</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/autopsy-five-ten</guid>
      <pubDate>Thu, 27 Aug 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>finance</category>
      <category>backtesting</category>
      <category>claim-autopsy</category>
      <category>evidence</category>
      <description>A viral post claimed a 5/10 moving-average strategy had not lost in eight years. My reported SPY tests found losing periods in three inferred implementations. The missing original rules and incomplete public run details limit that conclusion.</description>
      <content:encoded>&lt;p&gt;Twenty-four thousand likes for one sentence: the simple 5/10 strategy that
has not lost in eight years. No instrument, no average type, no bar interval,
and the source video is gone. That vagueness is not a technicality. It is the
whole mechanism, because a claim that never commits to a definition can never
be wrong. So the first job of this autopsy was to commit on the claim&apos;s
behalf, as generously as possible, and then let the claim be tested the way
it was told: against its own metric.&lt;/p&gt;
&lt;h2 id=&quot;the-steelman&quot;&gt;The steelman&lt;a href=&quot;https://caskeycoding.com/blog/autopsy-five-ten#the-steelman&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The charitable reading matters more than the takedown. I have no reason to
think the original poster acted in bad faith, and the account is not the
subject here; the claim is. So the codification logs three interpretations
and marks the most charitable retail reading as the headline: a 5/10 simple
moving average crossover on daily SPY bars. The other two readings, weekly
SMA and daily EMA, ride along so nobody can say the test picked the weakest
version. Every choice is recorded in the claim&apos;s codification file, and the
uncertainty about what the poster meant is logged as data, not smoothed over.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/autopsy-five-ten-own-metric.svg&quot; alt=&quot;Three interpretation cards for the 5/10 claim, showing the original run&amp;#x27;s reported losing-year counts. The date boundaries needed to interpret those periods are not supplied in this post.&quot;&gt;&lt;/p&gt;
&lt;h2 id=&quot;the-claim-tested-on-its-own-metric&quot;&gt;The claim, tested on its own metric&lt;a href=&quot;https://caskeycoding.com/blog/autopsy-five-ten#the-claim-tested-on-its-own-metric&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The claim&apos;s success criterion is built in: no losing period in eight years.
Here is what my SPY run reported through 2026, net of the costs used in that run. The exact date boundaries and cost settings are not included here, so these are reported results, not a publicly reproducible benchmark.&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Interpretation&lt;/th&gt;
&lt;th&gt;Charitable&lt;/th&gt;
&lt;th&gt;Losing periods (of 9)&lt;/th&gt;
&lt;th&gt;Net Sharpe&lt;/th&gt;
&lt;th&gt;Net t-stat&lt;/th&gt;
&lt;th&gt;Max drawdown&lt;/th&gt;
&lt;th&gt;Claim holds&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Daily SMA&lt;/td&gt;
&lt;td&gt;yes&lt;/td&gt;
&lt;td&gt;3&lt;/td&gt;
&lt;td&gt;0.34&lt;/td&gt;
&lt;td&gt;0.97&lt;/td&gt;
&lt;td&gt;27.8%&lt;/td&gt;
&lt;td&gt;no&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Weekly SMA&lt;/td&gt;
&lt;td&gt;no&lt;/td&gt;
&lt;td&gt;2&lt;/td&gt;
&lt;td&gt;1.33&lt;/td&gt;
&lt;td&gt;1.71&lt;/td&gt;
&lt;td&gt;28.4%&lt;/td&gt;
&lt;td&gt;no&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Daily EMA&lt;/td&gt;
&lt;td&gt;no&lt;/td&gt;
&lt;td&gt;2&lt;/td&gt;
&lt;td&gt;0.68&lt;/td&gt;
&lt;td&gt;1.91&lt;/td&gt;
&lt;td&gt;20.4%&lt;/td&gt;
&lt;td&gt;no&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;All three declared SPY interpretations had losing periods in my run. Daily
SMA had three out of nine; weekly SMA and daily EMA each had two. That does
not establish what the unavailable original strategy would have done on an
unspecified instrument, interval, or execution rule. It establishes the result
of these three inferred implementations under the run&apos;s settings.&lt;/p&gt;
&lt;p&gt;The boundaries are one instrument, inferred definitions, and 2,008 daily
observations in the reported run. The table groups results into nine periods,
but the dates and treatment of a partial final year are not supplied here.
That prevents a precise comparison with the original eight-year claim. If
the original poster publishes the exact rules, those would be the right
rules to test.&lt;/p&gt;
&lt;p&gt;The original post named an internal run and a shortened config hash. Neither
lets a reader reproduce this table without the artifact. A public reproduction
would need the full config and hash, data source and adjustment rules, exact
dates, execution timing, costs, and the definitions of the variants tested.
Those receipts are not provided here. I have also removed the standalone
overfitting-probability figure because the variant set and calculation were
not published with it.&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;This is historical analysis of a public claim, not investment advice, and
not a forward claim about any strategy or market. Nothing here recommends
trading anything.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;Until those details are available, the table should be read as my reported
experiment. It cannot settle an undefined strategy claim or serve as evidence
that a crossover rule has a tradable edge.&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>Does the order block pattern predict price? A backtest of the claim</title>
      <link>https://caskeycoding.com/blog/tested-order-block</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/tested-order-block</guid>
      <pubDate>Thu, 27 Aug 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>finance</category>
      <category>backtesting</category>
      <category>market-structure</category>
      <category>evidence</category>
      <description>A summarized test of an order-block retest rule across 30 large-cap names and five years of daily bars. The reported net result did not establish an edge; the full configuration and run artifact are not published here.</description>
      <content:encoded>&lt;p&gt;A glossary card defining the order block collected thirteen thousand likes in
the inspiration batch I keep for this series. It had clean typography, a tidy
candle diagram, and no evidence of any kind. That is the genre: definitional
confidence, zero base rates. This series republishes the format with the one
column the genre never ships. Here is the definition, and here is what it
tested at.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/tested-order-block-verdict-column.svg&quot; alt=&quot;Two glossary cards side by side: the left card carries only a definition and no evidence, the right card carries the same definition plus a highlighted measured-verdict strip showing a net t-statistic of minus 0.91 across 3,558 trades.&quot;&gt;&lt;/p&gt;
&lt;h2 id=&quot;the-definition-made-executable&quot;&gt;The definition, made executable&lt;a href=&quot;https://caskeycoding.com/blog/tested-order-block#the-definition-made-executable&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Prose definitions of the order block do not commit to anything a computer can
check, so the first step was writing one down that does. The last opposing
candle before a displacement move, where displacement is required and measured
against the recent swing structure with a 5-bar lookback. The tradeable rule:
enter in the block&apos;s direction at the close of the first bar whose range
retests the zone, searching from two bars after the block so the displacement
is fully observable, and exit after a fixed N days. Those are the main rules
of the recorded detector. This summary does not supply the complete zone and
displacement implementation or every parameter needed to reproduce it.&lt;/p&gt;
&lt;h2 id=&quot;the-test&quot;&gt;The test&lt;a href=&quot;https://caskeycoding.com/blog/tested-order-block#the-test&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Thirty large-cap US names, daily bars from 2021-07-23 through 2026-07-21,
37,560 pooled periods. Horizons of 3, 5, and 10 days, a small declared sweep
over the swing lookback, and 10 basis points of cost per side. Nine variants
total, declared up front, so the overfitting check has honest inputs.&lt;/p&gt;
&lt;h2 id=&quot;the-verdict&quot;&gt;The verdict&lt;a href=&quot;https://caskeycoding.com/blog/tested-order-block#the-verdict&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Metric (default variant, 5-day exit)&lt;/th&gt;
&lt;th&gt;Value&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Trades&lt;/td&gt;
&lt;td&gt;3,558&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Hit rate&lt;/td&gt;
&lt;td&gt;48.2%&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Annualized Sharpe, net&lt;/td&gt;
&lt;td&gt;-0.07&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Net t-statistic&lt;/td&gt;
&lt;td&gt;-0.91&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Probability of backtest overfitting (9 variants)&lt;/td&gt;
&lt;td&gt;0.57&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;The strict, displacement-required order block retest earned nothing net of
costs in this window. The t-statistic is not just small, it is slightly
negative. The reported PBO of 0.57 concerns selection across the nine variants.
In the &lt;a href=&quot;https://www.davidhbailey.com/dhbpapers/backtest-prob.pdf&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;definition used by Bailey and coauthors&lt;/a&gt;,
it estimates how often the in-sample winner ranks below the out-of-sample
median across the resamples. It is not a probability that the trading concept
is false. This experiment did not establish an edge for the tested daily-bar
rule.&lt;/p&gt;
&lt;p&gt;The boundaries: one five-year window, one universe of liquid
large-caps, daily bars, fixed exits. A definition this popular deserves
retests on other intervals and universes, and the harness is built to run
them. What it does not deserve is to be taught as an edge before anyone has
measured it.&lt;/p&gt;
&lt;p&gt;The recorded run was dated 2026-07-22, using detector v1.0.0 at git &lt;code class=&quot;inline-code&quot;&gt;f9f4f50&lt;/code&gt;
and an artifact named &lt;code class=&quot;inline-code&quot;&gt;order_block.json&lt;/code&gt;. Those identifiers locate my record;
they are not enough for a reader to rerun it. The full artifact, configuration
digest, universe-selection details, data adjustments, dependence handling,
and resampling setup are not published here. The table is a reported result,
with independent reproduction still unavailable from this post.&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;This is historical analysis of a public trading concept, not investment
advice, and not a forward claim about any market. Nothing here is a
recommendation to trade anything.&lt;/p&gt;
&lt;/blockquote&gt;</content:encoded>
    </item>
    <item>
      <title>How this site is organized</title>
      <link>https://caskeycoding.com/blog/how-this-site-is-organized</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/how-this-site-is-organized</guid>
      <pubDate>Sat, 15 Aug 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>platform</category>
      <category>architecture</category>
      <category>information-architecture</category>
      <category>nextjs</category>
      <description>The navigation on caskeycoding.com is a build artifact: one public content graph, several switchable views projected from it, and CI checks that keep the graph and the routes from drifting apart.</description>
      <content:encoded>&lt;p&gt;The navigation on this site is a build artifact. Every layout you can switch to from the homepage renders from one JSON file, &lt;a href=&quot;https://caskeycoding.com/manifest.json&quot; class=&quot;internal-link&quot;&gt;/manifest.json&lt;/a&gt;, and that file is public. If you want to check whether the views agree with each other, you can diff them against the same source I do.&lt;/p&gt;
&lt;p&gt;The file exists because I lost an argument with myself. This site had grown to 78 routes behind a five-item nav, and a single system would end up scattered across four shelves: the finance engine was a case study in one place, a tool in another, live data in a third, and essays in a fourth, with nothing connecting them. I spent an afternoon rejecting homepage designs. Doors named after subjects. Doors named after verbs. Doors named after how proven each piece of work is. Each one fixed the scattering by decreeing a taxonomy, and each one felt wrong for the same reason: no single taxonomy deserves to own the front door of work that cuts across categories.&lt;/p&gt;
&lt;p&gt;The version that survived stopped picking. Store the metadata once, then let every navigation scheme be a projection. Each artifact on the site (a case study, an essay, a tool, a dataset, a visualization, a game) has one manifest entry: what it is, which field it belongs to, which system it is part of, how proven it is, whether it is still running. The homepage renders a default view over that graph, and a switcher offers the others. A faceted catalog where clicking any label on a card pivots the whole filter. A scatter plot with proof on one axis and machine-versus-human scale on the other. A grouping by system. None of them is the site. They are all renderings of the manifest, and adding an artifact once populates every view.&lt;/p&gt;
&lt;p&gt;The later &lt;a href=&quot;https://caskeycoding.com/blog/i-asked-the-platform-to-make-art&quot; class=&quot;internal-link&quot;&gt;First Impressions art collection&lt;/a&gt; offers another way to read the platform: its production notes distinguish repository records, selected memories, and conceptual interpretation.&lt;/p&gt;
&lt;p&gt;The views are held together by the contracts underneath them, because a projection system rots the moment the projections drift from the source. A CI script walks the static export after every build and fails if any content route is missing from the manifest, or any manifest entry points at a route that does not exist. Another check compresses the manifest and fails the build past a size budget. The epistemic labels (production, on the record, in progress, experiment) are one enum defined once, and a test computes WCAG contrast ratios for their colors in both themes from the actual token values, because the first amber I picked measured 3.37 to 1 as text and failed the standard. The border carries the amber now; the text stays ink.&lt;/p&gt;
&lt;p&gt;The checks earn their keep by being embarrassing. The first time the chunk-budget check ran, it measured the &quot;lazy-loaded&quot; views at zero extra bytes each. That number looked like a pass and was actually the failure: nothing was split, and every visitor was downloading every view because all of them lived in one client bundle behind the switcher. The fix moved each view to its own route module, and the check now fails on zero, since a lazily loaded view that adds no bytes means the laziness is fiction. The shared bundle is still heavier than the budget I wrote in the spec, and the check says so on every build instead of letting me forget.&lt;/p&gt;
&lt;p&gt;Private surfaces get the same treatment with less exposure. A few tools on this site sit behind a login because they touch my own portfolio state. They appear in the graph as locked entries so the views can show they exist, but the manifest serializer builds their public projection from an allowlist of fields rather than deleting the sensitive ones, and a regression test iterates the actual keys of every private entry so a future field stays private by default. Publishing the graph forced that discipline. A file nobody can fetch can be sloppy; a file at a public URL cannot.&lt;/p&gt;
&lt;p&gt;If you run a site, a docs tree, or an internal portal with more than one defensible way to slice it, the pattern transfers directly. One typed source of truth, projections instead of taxonomies, and a check that fails the build when the two disagree.&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>Your CI was green and the pipeline produced nothing: a nine-day silent failure</title>
      <link>https://caskeycoding.com/blog/the-pipeline-that-ate-itself</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/the-pipeline-that-ate-itself</guid>
      <pubDate>Sat, 15 Aug 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>AI</category>
      <category>agents</category>
      <category>reliability</category>
      <description>A Windows Task Scheduler default fed my Claude Code memory pipeline its own transcripts for nine days: 21,264 junk sessions, 38 GB of exhaust, and an 18,428-session backlog that was really 1,924. The durable fix: postconditions that outrank green dashboards.</description>
      <content:encoded>&lt;p&gt;For nine days in July, my memory pipeline fed on its own output, and every status surface stayed green the whole time.&lt;/p&gt;
&lt;p&gt;Claude Code&apos;s default transcript-retention period was 30 days, and I lost a month of history to a machine migration before I understood what that meant. The period is configurable through &lt;a href=&quot;https://code.claude.com/docs/en/settings-reference#cleanupperioddays&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;&lt;code class=&quot;inline-code&quot;&gt;cleanupPeriodDays&lt;/code&gt;&lt;/a&gt;; the documentation checked on November 3, 2026 still lists a 30-day default. Longer retention does not replace a backup. I built a nightly pipeline to snapshot the transcripts, load them into SQLite, and have an LLM distill each session into durable facts. At writing it held about 47,000 facts from roughly 24,500 sessions and injected a small digest into every new session so my agents stopped re-deriving decisions they had already made.&lt;/p&gt;
&lt;h2 id=&quot;a-scheduler-default-did-the-damage&quot;&gt;A scheduler default did the damage&lt;a href=&quot;https://caskeycoding.com/blog/the-pipeline-that-ate-itself#a-scheduler-default-did-the-damage&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Windows Task Scheduler runs a job from &lt;code class=&quot;inline-code&quot;&gt;C:\Windows\system32&lt;/code&gt; unless you set a working directory. My distiller shells out to the Claude CLI, and the CLI writes its own transcript into a folder derived from the current working directory. Under the scheduler, that folder landed inside the exact tree my snapshot mirrors.&lt;/p&gt;
&lt;p&gt;Follow the loop around once. The distiller processes a batch of sessions and, in doing so, writes new transcripts. The snapshot archives them. Ingest loads them as sessions. The queue grows by roughly what the run just processed. The next run distills the distiller.&lt;/p&gt;
&lt;p&gt;&lt;em&gt;This post includes a diagram. &lt;a href=&quot;https://caskeycoding.com/blog/the-pipeline-that-ate-itself&quot;&gt;View it on caskeycoding.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;
&lt;p&gt;Nine days of that produced 21,264 junk sessions and about 38 GB of exhaust. No stage failed. The snapshot copied files, ingest parsed them, the distiller distilled them. Every stage reported success because every stage was succeeding.&lt;/p&gt;
&lt;h2 id=&quot;the-18428-session-backlog-was-really-1924&quot;&gt;The 18,428-session backlog was really 1,924&lt;a href=&quot;https://caskeycoding.com/blog/the-pipeline-that-ate-itself#the-18428-session-backlog-was-really-1924&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;I found the loop while chasing a different number. The queue query said 18,428 sessions were waiting for distillation, which read like a runaway cost problem. The real queue was 1,924. The gap was tombstones: emptied sessions kept on purpose, because deleting them would orphan the dates on thousands of real facts that cite them.&lt;/p&gt;
&lt;p&gt;The wrong number nearly bought the wrong fix. A backlog of 18,000 argues for a bigger nightly cap and more spend. A backlog of 1,900 argues for patience. The honest count only appeared after I added the distiller&apos;s own has-content filter to the query, which is a polite way of saying the number on the dashboard and the number the code used had quietly diverged.&lt;/p&gt;
&lt;p&gt;The working directory was the trigger, not the cause. Each stage checked its own work, and nothing checked the seams. Ingest growth tracking distill output at a ratio near one is an invariant of the whole pipeline, and for nine days it was violated by a factor of twenty with nobody assigned to notice.&lt;/p&gt;
&lt;h2 id=&quot;prose-is-advice-a-check-is-a-guarantee&quot;&gt;Prose is advice; a check is a guarantee&lt;a href=&quot;https://caskeycoding.com/blog/the-pipeline-that-ate-itself#prose-is-advice-a-check-is-a-guarantee&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The repairs took an afternoon: pin the distiller&apos;s working directory, exclude it from the snapshot, and add two independent ingest guards, one keyed on the folder and one on the opening bytes of the distiller&apos;s own prompt. The nightly went from 3 hours 11 minutes back to 14 minutes.&lt;/p&gt;
&lt;p&gt;Then I wrote the checks that outrank the stages. A post-ingest check verifies that zero of the pipeline&apos;s own transcripts reached the database, and a ratio check trips when ingest outpaces distillation past the incident&apos;s signature. Either violation fails the night loudly. Other failure shapes need their own checks; these two say nothing about them.&lt;/p&gt;
&lt;p&gt;The same discipline caught bugs I would never have found by rereading code. A 30-question retrieval eval scored the search layer at 46.7 percent on its first run, because multi-word queries were silently ANDed together and a natural question almost never has all of its words in one stored fact. Last week the gate flagged its own decay: an abstention probe expected &quot;what is Eric&apos;s phone number&quot; to return nothing, and it started matching because the corpus had legitimately grown a fact about a phone-number decision. No number ever existed in the store. The check had aged out of truth, and I only know because it failed loudly instead of rotting quietly.&lt;/p&gt;
&lt;h2 id=&quot;the-tool-has-a-kill-date&quot;&gt;The tool has a kill date&lt;a href=&quot;https://caskeycoding.com/blog/the-pipeline-that-ate-itself#the-tool-has-a-kill-date&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;A memory system invites a comfortable lie: it feels useful every time it answers, and nobody measures what its absence would have cost. So this one carries a standing bet. I built a counterfactual eval: 19 questions whose answers exist nowhere else, each verified absent from my notes, my specs, and every repo&apos;s git history before it was admitted to the set. Retrieval answered 19 of 19 at writing. I set a review with teeth for September 16, 2026: real usage plus that baseline decide whether the system keeps running, and losing means deletion, not a backlog item.&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>Fable Thinks, Opus Builds, Kimi Types</title>
      <link>https://caskeycoding.com/blog/fable-thinks-opus-builds-kimi-types</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/fable-thinks-opus-builds-kimi-types</guid>
      <pubDate>Tue, 04 Aug 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>AI</category>
      <category>claude</category>
      <category>models</category>
      <category>agents</category>
      <category>cost</category>
      <category>kimi</category>
      <description>I split a day of development across two AI subscriptions: judgment on the Anthropic meter, typing on Moonshot&apos;s. Five merged PRs later, here is where the tokens went, how K3&apos;s pricing actually compares, and how I&apos;m tuning the mix.</description>
      <content:encoded>&lt;p&gt;Five merged pull requests across three repos in the first day: a 661-line integration in my finance backend, its infrastructure pair, house-style concept figures back-filled across 29 posts on this blog, and two small arcade games for the lab. Every line of that was typed by Kimi K3 on a Moonshot subscription. My Claude meter spent the day on specs, briefs, and reviews, and a day in, both meters read about a quarter used. Neither is competing with the other for the same allowance, and that is the feature.&lt;/p&gt;
&lt;p&gt;This is the fourth post in the model-routing series. In June I &lt;a href=&quot;https://caskeycoding.com/blog/goodbye-opus-hello-fable&quot; class=&quot;internal-link&quot;&gt;said goodbye to Opus&lt;/a&gt;, then &lt;a href=&quot;https://caskeycoding.com/blog/hello-again-opus&quot; class=&quot;internal-link&quot;&gt;hello again&lt;/a&gt; four days later when an export directive pulled Fable offline and I noticed I had burned 90% of my usage. In July I admitted the tiering plan failed because it lived in my head instead of in files and moved it into an architecture decision record: the frontier model supervises, the workhorse executes, the mechanical items go to the cheapest rung. This week the routing table grew a row that Anthropic does not bill at all.&lt;/p&gt;
&lt;p&gt;The arrangement is three sentences. I never talk to Kimi; I talk to Claude, and when an item is scoped tightly enough that the brief removes all judgment, Claude dispatches it. A wrapper runs Kimi&apos;s coding agent headless, re-runs the tests itself, and brings back a diff. Nothing merges until a supervisor has read every line.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/fable-thinks-opus-builds-kimi-types-two-meters.svg&quot; alt=&quot;A thin judgment stream (spec, brief, review, on the Anthropic meter) and a thick typing stream (five PRs on day one, on the Moonshot meter) converge on a review gate, and a single green arrow ships from it.&quot;&gt;&lt;/p&gt;
&lt;h2 id=&quot;where-the-tokens-go&quot;&gt;Where the tokens go&lt;a href=&quot;https://caskeycoding.com/blog/fable-thinks-opus-builds-kimi-types#where-the-tokens-go&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;A day of development is lopsided in a way a single meter hides. By volume it is nearly all typing: implementations, tests, doc sweeps, the long tail of items that are obvious once the design is settled. The judgment that steers it, the spec, the brief, the review, is a thin stream by volume and nearly all of the consequence.&lt;/p&gt;
&lt;p&gt;The series so far is the story of learning that shape the expensive way. In June everything ran on the frontier model, which burns my cap at roughly twice the workhorse rate, and typing was most of the burn. July&apos;s fix routed the typing to a cheaper model on the same meter. This week&apos;s fix moves it off the meter entirely: the scarce meter holds the judgment, the abundant meter absorbs the volume, and the exchange works because a verification gate sits where the two streams meet.&lt;/p&gt;
&lt;h2 id=&quot;is-kimi-actually-cheaper&quot;&gt;Is Kimi actually cheaper?&lt;a href=&quot;https://caskeycoding.com/blog/fable-thinks-opus-builds-kimi-types#is-kimi-actually-cheaper&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;At the time of this August experiment, K3&apos;s API sticker was $3 per million uncached input tokens and $15 per million output. &lt;a href=&quot;https://forum.moonshot.ai/t/kimi-k3-is-here-our-most-capable-model/480&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Moonshot&apos;s July announcement&lt;/a&gt; lists those rates and a 2.8-trillion-parameter model. Those were Sonnet-level prices, below the $5 and $25 Opus rates I was comparing. That makes K3 cheaper per output token in that comparison; the number of tokens a task consumes still determines its cost. I have removed an earlier fourth-of-189 leaderboard claim because the linked source did not substantiate that rank.&lt;/p&gt;
&lt;p&gt;But the combo does not run on API stickers. It runs on two subscriptions: Kimi&apos;s plans ladder from $19 to $199 a month against Claude&apos;s roughly comparable ladder, each with its own weekly allowance. At that level the per-token comparison mostly dissolves, and what you are actually buying is a second pool. Before this week, a heavy typing day and a heavy thinking day drew down the same cap and the cap decided which one I got. Now the typing has its own meter, and the judgment meter stretches across a week of work it never has to type.&lt;/p&gt;
&lt;p&gt;One caveat carries real weight for the tuning below: K3&apos;s reasoning is always on and it thinks hard by default. Simon Willison measured 13,241 reasoning tokens spent producing 3,417 output tokens on a single task. On a weekly allowance with a rolling five-hour window, that is a meaningful tax when the task did not need the thinking.&lt;/p&gt;
&lt;h2 id=&quot;what-a-day-proved-including-the-failure&quot;&gt;What a day proved, including the failure&lt;a href=&quot;https://caskeycoding.com/blog/fable-thinks-opus-builds-kimi-types#what-a-day-proved-including-the-failure&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The five PRs are the delegation working. The infrastructure pair passed its config tests and compile on the first dispatch. The backend integration came back with twelve new tests and the full 3,285-test suite green; my review haul was two unused imports and a formatting miss. The figure backfill and the games ran overnight as supervised waves. And the gates earned their keep in the other direction too: one experiment, routing my finance engine&apos;s grounded research through K3, failed live verification the same morning it shipped (the endpoint&apos;s web search quietly returns empty results) and was rolled back within the hour behind an environment flip the spec had demanded in advance. A scan of the stored research rows confirmed zero bad data landed. The coding tier never noticed.&lt;/p&gt;
&lt;h2 id=&quot;tuning-the-mix&quot;&gt;Tuning the mix&lt;a href=&quot;https://caskeycoding.com/blog/fable-thinks-opus-builds-kimi-types#tuning-the-mix&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The question after day one is not whether to delegate but whether I delegate enough, and the answer is not yet. The typing that moved was the typing I had briefs for. The next turn of the dial routes the standing mechanical backlog, the doc syncs and config flips and test sweeps that currently burn the cheapest Anthropic rung, down to the Kimi tier by default.&lt;/p&gt;
&lt;p&gt;The model mix inside that tier is also a dial. K3 is the flagship, but a quarter of the weekly allowance in one day says the flagship is the wrong daily driver for judgment-free work: its always-on reasoning is priced for exactly the judgment my briefs are designed to remove. So the worker tier now defaults to Moonshot&apos;s coding-tuned K2.7 model, with K3 one flag away for the big multi-file diffs that reward a deeper typist. Same shape as the Claude side of the table, one rung down: match the model to the task, and put the restraint in config.&lt;/p&gt;
&lt;p&gt;Fable thinks, Opus builds, Kimi types. Four posts in, the slogan finally describes a system rather than an intention.&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>Graded Pokemon cards versus the stock market, since 2004</title>
      <link>https://caskeycoding.com/blog/the-binder-and-the-benchmark</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/the-binder-and-the-benchmark</guid>
      <pubDate>Mon, 03 Aug 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>data-engineering</category>
      <category>visualization</category>
      <category>side-projects</category>
      <category>honest-data</category>
      <description>My kids collect Pokemon cards, and one of them asked what a Charizard is actually worth. Answering it turned into a weekend build: a chart that puts graded cards and the S&amp;P 500 on one indexed axis, and admits out loud where its data is thin.</description>
      <content:encoded>&lt;p&gt;One of my kids asked me what a Charizard is worth.&lt;/p&gt;
&lt;p&gt;Not their Charizard. The Charizard. The 1999 Base Set holo that shows up in every video about cards as investments, usually next to a claim that a binder from 1999 beat the stock market. My kids collect cards the way I once did, for the trades and the pulls, but the question was a real one and it deserved a real answer. So I did what I do with every question about money: I went looking for the data, and I charted it against a benchmark.&lt;/p&gt;
&lt;p&gt;The chart is live at &lt;a href=&quot;https://caskeycoding.com/lab/pokemon-vs-market&quot; class=&quot;internal-link&quot;&gt;caskeycoding.com/lab/pokemon-vs-market&lt;/a&gt;. Every series is indexed to 100 at the start of the range, so a playground card and the S&amp;#x26;P 500 share one axis. You can toggle cards, benchmarks, and averages, flip between log and linear scales, and inspect the numbers in a table. The comparison I recorded for this August 2026 post, starting in 2004, showed roughly 62x for selected PSA 10 first edition Charizard price observations and 6.6x for the S&amp;#x26;P 500 price index. The index excludes reinvested dividends. The card series changes from selected auction sales to broad market readings, so those two ratios are not comparable realized investment returns. The board marks the observations and the change of measure; this post does not preserve exact endpoint dates and prices for reconstructing the old ratios.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/the-binder-and-the-benchmark-board.webp&quot; alt=&quot;The recorded board with Charizard PSA 10 price observations and the S&amp;#x26;P 500 price index since 2004: ringed dots mark cited card sales, with the series indexed to the selected starting values&quot;&gt;&lt;/p&gt;
&lt;p&gt;I did not assemble a continuous historical price series for these cards. The deep past in this chart is a handful of cited record sales, drawn as ringed dots so you can see how sparse they are. The line between them is labeled as an estimate. From the week of this post&apos;s publication, a scheduled job was set to capture broad market price readings every Sunday. Where those readings meet the selected sales, the line visibly jumps. The page labels that as a change of measure, so the step should not be read as a sudden market move.&lt;/p&gt;
&lt;p&gt;That choice was not invented for a card chart. I run a personal finance engine as a side project, and the rule I hold it to is the same rule I held this chart to: label what is measured, label what is modeled, and let a missing number stay missing.&lt;/p&gt;
&lt;p&gt;The answer I gave my kid, in the end, needed more than a large ratio. Selected sales of the grail card rose far more than the price index in this chart. That does not tell us what a typical collector earned after grading and auction fees, or what a stock investor earned with dividends reinvested. Their binder is not the record sale. They mostly wanted to know if it was cool. It is.&lt;/p&gt;
&lt;p&gt;The &lt;a href=&quot;https://caskeycoding.com/blog/knicks-champions-builders-patience&quot; class=&quot;internal-link&quot;&gt;Willis Reed ball my grandfather gave me&lt;/a&gt; carries a different kind of value, a connection to the team we followed.&lt;/p&gt;
&lt;p&gt;The cards taught my kids how to trade. I built the chart for the other lesson: what the data can actually say. The board records a new observation every Sunday morning, and the answer keeps earning itself, one week at a time.&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>Spec-Driven Development Folder Structure: Template and Example</title>
      <link>https://caskeycoding.com/blog/lesson-1-the-spec-directory</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/lesson-1-the-spec-directory</guid>
      <pubDate>Fri, 31 Jul 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>spec-driven-development</category>
      <category>AI</category>
      <category>engineering-methodology</category>
      <category>agents</category>
      <description>Record what a feature must do, what is outside its scope, and how you will verify it. Create a specs directory and template, then give the agent an approved spec to implement.</description>
      <content:encoded>&lt;p&gt;&lt;strong&gt;What you&apos;ll learn:&lt;/strong&gt; write a feature spec with observable requirements, explicit exclusions, and verification steps. Review it before asking an agent to implement it.
&lt;strong&gt;What you need:&lt;/strong&gt; a text editor and the AI coding agent you already use. No new tools.
&lt;strong&gt;Time:&lt;/strong&gt; allow fifteen minutes for setup and about ten per small feature. &lt;strong&gt;Cost:&lt;/strong&gt; zero new dollars if your existing agent subscription covers the work.&lt;/p&gt;
&lt;p&gt;My specs folder contains &lt;code class=&quot;inline-code&quot;&gt;README.md&lt;/code&gt; to explain the project and layout, &lt;code class=&quot;inline-code&quot;&gt;_template.md&lt;/code&gt; for the feature-spec form, and area folders such as &lt;code class=&quot;inline-code&quot;&gt;app/&lt;/code&gt; holding numbered specs like &lt;code class=&quot;inline-code&quot;&gt;001-short-name.md&lt;/code&gt;. I save a feature&apos;s requirements there before asking an agent to implement it, using the &lt;a href=&quot;https://caskeycoding.com/blog/lesson-1-the-spec-directory#the-template&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;directory tree and template&lt;/a&gt; and &lt;a href=&quot;https://caskeycoding.com/blog/lesson-1-the-spec-directory#a-worked-example&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;worked example&lt;/a&gt; below.&lt;/p&gt;
&lt;h2 id=&quot;the-idea&quot;&gt;The idea&lt;a href=&quot;https://caskeycoding.com/blog/lesson-1-the-spec-directory#the-idea&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;A feature request in chat can omit details that matter during review. A later session may have the code without the original conversation. A spec gives both sessions the same requirements to consult.&lt;/p&gt;
&lt;p&gt;Write one numbered file per feature. State what must be observably true, which files or systems are outside scope, and how to check the result. Have the agent draft it, correct the requirements yourself, and change its status from &lt;code class=&quot;inline-code&quot;&gt;draft&lt;/code&gt; to &lt;code class=&quot;inline-code&quot;&gt;ready&lt;/code&gt; before implementation. Review the finished work against each criterion.&lt;/p&gt;
&lt;p&gt;The file preserves requirements and approval history. It cannot guarantee that the requirements are correct or that an agent follows them. You still need to inspect the evidence and resolve missing or contradictory results.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/lesson-1-the-spec-directory-loop.svg&quot; alt=&quot;The agent drafts the feature spec, the owner approves it by changing draft to ready, the agent implements it, and the owner checks the result against each acceptance criterion.&quot;&gt;&lt;/p&gt;
&lt;h2 id=&quot;why-start-here&quot;&gt;Why start here&lt;a href=&quot;https://caskeycoding.com/blog/lesson-1-the-spec-directory#why-start-here&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;When I first published this lesson, I had built with AI daily for thirteen months across fifteen repositories, four public sites, and two dozen scheduled jobs. I struggled to retain the requirements across projects and sessions. Nine months in, I created a repository for specs. By the original publication, it had 1,867 commits since January, compared with 661 in my busiest code repository. The layout below reduces that setup to three initial files.&lt;/p&gt;
&lt;h2 id=&quot;the-template&quot;&gt;The template&lt;a href=&quot;https://caskeycoding.com/blog/lesson-1-the-spec-directory#the-template&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Create this directory:&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;specs/
  README.md          # the map: what this project is, where intent lives
  _template.md       # the blank form: every spec starts as a copy of it
  app/               # one folder per area of your project
    001-short-name.md
    002-...          # the record: what you meant, in order
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Use a folder name that describes the area, such as &lt;code class=&quot;inline-code&quot;&gt;app/&lt;/code&gt;, &lt;code class=&quot;inline-code&quot;&gt;api/&lt;/code&gt;, or &lt;code class=&quot;inline-code&quot;&gt;website/&lt;/code&gt;. Number specs within each folder in creation order. Start with one area and split it when that makes requirements easier to find. Point the agent at the relevant folder for each task.&lt;/p&gt;
&lt;p&gt;Copy this into &lt;code class=&quot;inline-code&quot;&gt;specs/_template.md&lt;/code&gt;:&lt;/p&gt;
&lt;pre class=&quot;shiki shiki-themes github-light github-dark&quot; style=&quot;background-color:#fff;--shiki-dark-bg:#24292e;color:#24292e;--shiki-dark:#e1e4e8&quot; tabindex=&quot;0&quot; data-language=&quot;markdown&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;---&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#22863A;--shiki-dark:#85E89D&quot;&gt;status&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;draft&lt;/span&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;          # draft -&gt; ready -&gt; in-progress -&gt; completed&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#22863A;--shiki-dark:#85E89D&quot;&gt;verify&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;npm test&lt;/span&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;       # one command that must exit 0&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;---&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold&quot;&gt;# &amp;#x3C;&lt;/span&gt;&lt;span style=&quot;color:#22863A;--shiki-light-font-weight:bold;--shiki-dark:#85E89D;--shiki-dark-font-weight:bold&quot;&gt;feature&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-light-font-weight:bold;--shiki-dark:#B392F0;--shiki-dark-font-weight:bold&quot;&gt; name&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold&quot;&gt;## Acceptance criteria&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; [ ] &amp;#x3C;&lt;/span&gt;&lt;span style=&quot;color:#22863A;--shiki-dark:#85E89D&quot;&gt;an&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; observable&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; state:&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; a&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; URL&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; that&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; loads,&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; a&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; file&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; that&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;      exists, a number that appears somewhere it did not&gt;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;      check: &amp;#x3C;&lt;/span&gt;&lt;span style=&quot;color:#22863A;--shiki-dark:#85E89D&quot;&gt;the&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; command&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; and&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; its&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; expected&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; output,&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; or&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; the&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;      page and what it must show&gt;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold&quot;&gt;## Out of scope&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; &amp;#x3C;&lt;/span&gt;&lt;span style=&quot;color:#22863A;--shiki-dark:#85E89D&quot;&gt;paths,&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; files,&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; or&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; systems&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; this&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; work&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; must&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; leave&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; alone,&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;  named precisely enough to paste into a request&gt;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold&quot;&gt;## Notes (guidance, not binding)&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;&amp;#x3C;&lt;/span&gt;&lt;span style=&quot;color:#22863A;--shiki-dark:#85E89D&quot;&gt;links,&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; patterns&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; worth&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; copying,&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; context&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; the&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; builder&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;might&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; want&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Treat the acceptance criteria and exclusions as requirements. Keep optional suggestions in Notes so an implementation choice cannot silently become a requirement.&lt;/p&gt;
&lt;p&gt;Add this instruction to the file your coding tool reads at session start, such as &lt;code class=&quot;inline-code&quot;&gt;AGENTS.md&lt;/code&gt; or &lt;code class=&quot;inline-code&quot;&gt;CLAUDE.md&lt;/code&gt;:&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;Before building anything new, copy specs/_template.md to
specs/&amp;#x3C;area&gt;/&amp;#x3C;next-number&gt;-&amp;#x3C;short-name&gt;.md, fill it in from
what I have told you, and stop; only I move status from draft
to ready. Build only after that flip, and grade the finished
work against the file before telling me it is done.
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Keep feature details in their spec files. The standing instruction tells the agent how to find and use them. Confirm that your tool actually loads that instruction in a new session; saving the file alone does not establish that it was read.&lt;/p&gt;
&lt;h2 id=&quot;each-part-and-the-mistake-it-prevents&quot;&gt;Each part, and the mistake it prevents&lt;a href=&quot;https://caskeycoding.com/blog/lesson-1-the-spec-directory#each-part-and-the-mistake-it-prevents&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The README needs three facts: what the project does, where its specs live, and how their numbers are assigned. A new session should be able to find the relevant feature without reconstructing your requirements from the implementation.&lt;/p&gt;
&lt;p&gt;Each acceptance criterion describes an observable result. For example, “the endpoint returns the new response fields” gives a reviewer a result to check. “Refactor the handler” describes an activity and leaves the expected behavior unspecified. Name the command and expected output, or the page and what it must show.&lt;/p&gt;
&lt;p&gt;The &lt;code class=&quot;inline-code&quot;&gt;verify:&lt;/code&gt; command provides a repeatable check, but its coverage depends on what it runs. A file-existence test cannot establish that a page renders correctly. A passing test suite cannot establish an untested requirement. Use the check beside each criterion to record that distinction.&lt;/p&gt;
&lt;p&gt;Out of scope names specific paths, files, or systems the task must leave alone. Review the diff against those exclusions. They are written instructions, with no filesystem enforcement of their own.&lt;/p&gt;
&lt;p&gt;Status records progress through &lt;code class=&quot;inline-code&quot;&gt;draft&lt;/code&gt;, &lt;code class=&quot;inline-code&quot;&gt;ready&lt;/code&gt;, &lt;code class=&quot;inline-code&quot;&gt;in-progress&lt;/code&gt;, and &lt;code class=&quot;inline-code&quot;&gt;completed&lt;/code&gt;. Keep completed specs and their numbers so later changes can refer to the original requirements. If requirements change during implementation, review and record the change before grading the result against it.&lt;/p&gt;
&lt;h2 id=&quot;a-worked-example&quot;&gt;A worked example&lt;a href=&quot;https://caskeycoding.com/blog/lesson-1-the-spec-directory#a-worked-example&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;This is a compressed version of the directory used for the series:&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;specs/
  README.md
  _template.md
  decision/                      # empty until lesson 2
  website/
    014-blog-series.md           # status: completed
    016-learning-series.md       # status: in-progress
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The lesson&apos;s publication requirements used the template this way. Its status changed after the checks ran:&lt;/p&gt;
&lt;pre class=&quot;shiki shiki-themes github-light github-dark&quot; style=&quot;background-color:#fff;--shiki-dark-bg:#24292e;color:#24292e;--shiki-dark:#e1e4e8&quot; tabindex=&quot;0&quot; data-language=&quot;markdown&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;---&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#22863A;--shiki-dark:#85E89D&quot;&gt;status&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;completed&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#22863A;--shiki-dark:#85E89D&quot;&gt;verify&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;npm run check:content&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;---&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold&quot;&gt;# lesson-1-post&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold&quot;&gt;## Acceptance criteria&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; [ ] the lesson page returns 200 on the live site&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;      check: open the URL after deploy, template visible&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;      in a code block&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; [ ] the blog index lists it under the series title&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;      check: open /blog, entry present&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold&quot;&gt;## Out of scope&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; every other post in the blog content folder&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; the blog index layout&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The two acceptance criteria require separate observations: the deployed lesson page and its entry on the blog index. The named content command covers its own assertions. It does not replace the post-deployment observations. The example is a historical publication record, not evidence that a current deployment has been checked.&lt;/p&gt;
&lt;h2 id=&quot;from-the-field&quot;&gt;From the field&lt;a href=&quot;https://caskeycoding.com/blog/lesson-1-the-spec-directory#from-the-field&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Earlier in the month of this lesson&apos;s original publication, I proposed removing an input from a scoring system I run. The initial analysis supported the change. An acceptance criterion written before that analysis required the improvement to hold on data the analysis had never seen. It did not hold, so the change never shipped.&lt;/p&gt;
&lt;p&gt;Recording that condition early gave me a stated reason to reject a result I wanted to accept. It did not make the analysis correct by itself; the check still had to measure the proposed improvement on the specified data.&lt;/p&gt;
&lt;h2 id=&quot;exercise&quot;&gt;Exercise&lt;a href=&quot;https://caskeycoding.com/blog/lesson-1-the-spec-directory#exercise&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Create the directory, write the three README facts, and copy &lt;code class=&quot;inline-code&quot;&gt;_template.md&lt;/code&gt;. Add the standing instruction to the file your agent reads at session start.&lt;/p&gt;
&lt;p&gt;Choose the next small feature you plan to build. Give the agent the template and ask it to draft the spec from your request. Allow ten minutes for questions and edits. Check that every criterion names an observable result and that each exclusion identifies a concrete path or system. Change the status to &lt;code class=&quot;inline-code&quot;&gt;ready&lt;/code&gt; when you approve it.&lt;/p&gt;
&lt;p&gt;Ask the agent to implement the approved spec and include its exclusions in the request. Before accepting the work, run the verification command and inspect each criterion&apos;s evidence. Record whether each criterion passed, failed, or remains unverified. Resolve failures and evidence gaps before marking the spec completed.&lt;/p&gt;
&lt;h2 id=&quot;youre-done-when&quot;&gt;You&apos;re done when&lt;a href=&quot;https://caskeycoding.com/blog/lesson-1-the-spec-directory#youre-done-when&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;You have one reviewed spec, an implementation checked against every criterion, and recorded results for those checks. You do not need to manufacture a failure. If a check fails, identify whether the implementation or the approved requirement needs correction.&lt;/p&gt;
&lt;p&gt;Open a fresh session, point it at &lt;code class=&quot;inline-code&quot;&gt;specs/&lt;/code&gt;, and ask what feature is approved next. Confirm that it finds the correct file and reports its status and requirements. That observation establishes that this session could retrieve the context. Repeat the check if you change how instructions or specs are loaded.&lt;/p&gt;
&lt;h2 id=&quot;common-mistakes&quot;&gt;Common mistakes&lt;a href=&quot;https://caskeycoding.com/blog/lesson-1-the-spec-directory#common-mistakes&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Avoid putting every feature in one growing file or copying all requirements into the standing instructions. Separate feature files are easier to select for a task. Keep the template short and add folders only when they improve retrieval.&lt;/p&gt;
&lt;p&gt;Review agent-drafted requirements before implementation. A spec written after the code can describe the existing result without capturing what you originally needed. Keep approval with the owner and inspect the final diff for work outside the agreed scope.&lt;/p&gt;
&lt;h2 id=&quot;next-lesson&quot;&gt;Next lesson&lt;a href=&quot;https://caskeycoding.com/blog/lesson-1-the-spec-directory#next-lesson&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;&lt;a href=&quot;https://caskeycoding.com/blog/lesson-2-decision-records&quot; class=&quot;internal-link&quot;&gt;Record Technical Decisions and Their Reasons&lt;/a&gt; adds the rejected alternatives, accepted tradeoffs, and conditions for reconsidering a technical choice.&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>The schema is the product: the contract between a method repo and what ships</title>
      <link>https://caskeycoding.com/blog/the-schema-is-the-product</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/the-schema-is-the-product</guid>
      <pubDate>Thu, 23 Jul 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>spec-driven-development</category>
      <category>schemas</category>
      <category>engineering-methodology</category>
      <category>SpecSelf</category>
      <description>SpecSelf looks like a set of features: coherence checks, persona rotation, review cadences, an audit trail. Every one of them was implied by ten frontmatter fields decided on day one. A life-OS is not a feature list. It is a schema decision, and the features are what fall out of making it correctly.</description>
      <content:encoded>&lt;p&gt;Every field in the principle template is load-bearing. &lt;code class=&quot;inline-code&quot;&gt;serves:&lt;/code&gt; is not organization, it is the input to a graph walk that catches orphans. &lt;code class=&quot;inline-code&quot;&gt;last_reviewed:&lt;/code&gt; is not metadata, it is the input to the staleness check. &lt;code class=&quot;inline-code&quot;&gt;supersedes:&lt;/code&gt; is not a link, it is the audit trail that keeps the record honest. Take any one of them out and a review mechanism downstream stops working. Put them all in and you did not build features. You built a schema, and the features fell out.&lt;/p&gt;
&lt;p&gt;That is the claim this post defends: a life operating system is not a list of features. It is a schema decision, made once, early, and everything that later feels like a good product move was already implied by it.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/the-schema-is-the-product-trunk.svg&quot; alt=&quot;One green schema box, ten frontmatter fields decided on day one, fanning out with green arrows to five feature boxes it made possible.&quot;&gt;&lt;/p&gt;
&lt;p&gt;&lt;a href=&quot;https://caskeycoding.com/blog/life-in-spec-files&quot; class=&quot;internal-link&quot;&gt;Life in Spec Files&lt;/a&gt; made the case for keeping a life in version-controlled files at all. &lt;a href=&quot;https://caskeycoding.com/blog/when-your-method-repo-and-your-product-dont-talk&quot; class=&quot;internal-link&quot;&gt;Last week&apos;s post&lt;/a&gt; described what happened when three repos disagreed about what those files contain, and the CI check that now fails when they drift. This one is about why the schema deserved that defense in the first place.&lt;/p&gt;
&lt;h2 id=&quot;the-orphan-a-chat-log-cannot-catch&quot;&gt;The orphan a chat log cannot catch&lt;a href=&quot;https://caskeycoding.com/blog/the-schema-is-the-product#the-orphan-a-chat-log-cannot-catch&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Here is what a schema catches that prose never will. The example is illustrative rather than lifted from my corpus, but it is structurally exact.&lt;/p&gt;
&lt;p&gt;A Sunday review session opens with the coherence report, before any writing. The report flags an orphan: a project with a &lt;code class=&quot;inline-code&quot;&gt;serves:&lt;/code&gt; list pointing at a goal that does not exist. Not a goal that failed. A goal that was retired two months ago, in a file whose &lt;code class=&quot;inline-code&quot;&gt;status:&lt;/code&gt; changed and whose dependents never got re-pointed. The project had been absorbing hours every week in service of nothing.&lt;/p&gt;
&lt;p&gt;I have kept journals that would never have surfaced that. A chat log with an AI assistant would not have surfaced it either, because the conversation has no structure a graph walk can traverse. The orphan was caught because &lt;code class=&quot;inline-code&quot;&gt;serves:&lt;/code&gt; is a typed reference, the reference had a dangling target, and a script walks those references on a schedule. Drift became a diff.&lt;/p&gt;
&lt;h2 id=&quot;ten-fields-each-one-buying-a-mechanism&quot;&gt;Ten fields, each one buying a mechanism&lt;a href=&quot;https://caskeycoding.com/blog/the-schema-is-the-product#ten-fields-each-one-buying-a-mechanism&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The template ships ten frontmatter fields, and the &lt;a href=&quot;https://github.com/CaskeyCoding/specself-starter/blob/main/schemas/principle.schema.yaml&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;schema file&lt;/a&gt; is canonical for all of them; &lt;a href=&quot;https://github.com/CaskeyCoding/specself-starter/blob/main/templates/principle.md&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;&lt;code class=&quot;inline-code&quot;&gt;templates/principle.md&lt;/code&gt;&lt;/a&gt; points at it rather than restating it, for exactly the reasons last week&apos;s post laid out.&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Field&lt;/th&gt;
&lt;th&gt;The mechanism it buys&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code class=&quot;inline-code&quot;&gt;title&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;The principle as one actionable sentence, not a category&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code class=&quot;inline-code&quot;&gt;status&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;The lifecycle walk: draft, active, contested, retired&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code class=&quot;inline-code&quot;&gt;kind&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;The revealed/aspirational split, and the falsification clause below&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code class=&quot;inline-code&quot;&gt;domain&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;A closed enum, so a coverage check can see which domains are starved&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code class=&quot;inline-code&quot;&gt;confidence&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;An honesty dial the review interrogates rather than a badge&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code class=&quot;inline-code&quot;&gt;serves&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;The upward graph edge; the orphan check traverses it&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code class=&quot;inline-code&quot;&gt;created&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;The age of the claim&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code class=&quot;inline-code&quot;&gt;last_reviewed&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;The staleness check; unreviewed principles surface on schedule&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code class=&quot;inline-code&quot;&gt;ended_on&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Terminal states get a date, so retirement is a fact, not a fade&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code class=&quot;inline-code&quot;&gt;supersedes&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;The audit trail; a replaced principle stays in history&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;There is no &lt;code class=&quot;inline-code&quot;&gt;id&lt;/code&gt; field. The filename is the id, which sounds like a shortcut and is actually a position: identity lives in the filesystem, where git can see renames, not in a database column the corpus cannot inspect.&lt;/p&gt;
&lt;p&gt;The kit&apos;s steering doc states the design goal in four words I will quote rather than improve: engineering artifacts are &quot;written down, dated, diffable, and revisited.&quot; Lives deserve the same rigor. Each of the ten fields exists to make one of those four words mechanical.&lt;/p&gt;
&lt;h2 id=&quot;the-falsification-clause-is-the-whole-game&quot;&gt;The falsification clause is the whole game&lt;a href=&quot;https://caskeycoding.com/blog/the-schema-is-the-product#the-falsification-clause-is-the-whole-game&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The field that earns its place most is &lt;code class=&quot;inline-code&quot;&gt;kind:&lt;/code&gt;. The kit&apos;s &lt;a href=&quot;https://github.com/CaskeyCoding/specself-starter/blob/main/steering/methodology.md&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;methodology doc&lt;/a&gt; defines the split: a principle is either &lt;code class=&quot;inline-code&quot;&gt;revealed&lt;/code&gt;, backed by evidence of how I have actually behaved, or &lt;code class=&quot;inline-code&quot;&gt;aspirational&lt;/code&gt;, a rule I want to live by and cannot yet demonstrate. The template forces the question with a &lt;code class=&quot;inline-code&quot;&gt;## Falsification&lt;/code&gt; section: what evidence would force this principle&apos;s retirement?&lt;/p&gt;
&lt;p&gt;The &lt;a href=&quot;https://github.com/CaskeyCoding/specself-starter/blob/main/scripts/validate.py&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;public validator&lt;/a&gt;, checked on November 3, 2026, enforces a narrower rule: a &lt;code class=&quot;inline-code&quot;&gt;revealed&lt;/code&gt; principle needs at least one date-prefixed bullet under &lt;code class=&quot;inline-code&quot;&gt;## Evidence&lt;/code&gt;. It does not establish that the entry is true or sufficient, and it does not check the Falsification section required by the &lt;a href=&quot;https://github.com/CaskeyCoding/specself-starter/blob/main/schemas/principle.schema.yaml&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;schema&lt;/a&gt;. Those remain review work. Behavioral evidence can support a proposed promotion, but I still have to judge it before changing &lt;code class=&quot;inline-code&quot;&gt;kind:&lt;/code&gt; and recording why.&lt;/p&gt;
&lt;p&gt;Compare that to the loose notes I have abandoned. A place for dated evidence makes the claim easier to review, and a check can catch an empty evidence section. Whether the evidence supports the principle still takes judgment.&lt;/p&gt;
&lt;h2 id=&quot;what-the-schema-costs-and-why-the-cost-is-the-point&quot;&gt;What the schema costs, and why the cost is the point&lt;a href=&quot;https://caskeycoding.com/blog/the-schema-is-the-product#what-the-schema-costs-and-why-the-cost-is-the-point&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;A loose note takes five seconds. A schema&apos;d principle takes ten minutes, and most of those minutes go to the questions I would rather skip. What does this actually serve? What would falsify it? Is this revealed or am I flattering myself with the word?&lt;/p&gt;
&lt;p&gt;Ten minutes of friction per principle is the price, and the purchase deserves precision, because this is the center of the argument. Each awkward question maps to a field, each field feeds a check, and each check runs without me. Discipline I have to remember is discipline I will eventually skip; I wrote a &lt;a href=&quot;https://caskeycoding.com/blog/institutional-memory-for-a-team-of-one&quot; class=&quot;internal-link&quot;&gt;whole post&lt;/a&gt; about recall being the exact faculty that fails. The schema moves the discipline into structure, where forgetting is not an option. The schema is the product. The Sunday report, the staleness sweep, the audit trail, the promotion rule: those are consequences.&lt;/p&gt;
&lt;p&gt;The same shape shows up in &lt;a href=&quot;https://caskeycoding.com/blog/context-architecture-beats-documentation-dumps&quot; class=&quot;internal-link&quot;&gt;context architecture&lt;/a&gt;: the pile of documents was worth little until structure let each task load a curated slice.&lt;/p&gt;
&lt;h2 id=&quot;the-contract-the-self-implements&quot;&gt;The contract the self implements&lt;a href=&quot;https://caskeycoding.com/blog/the-schema-is-the-product#the-contract-the-self-implements&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Spec-driven development works because the spec is a contract and the code implements it. When the code drifts, tests fail; the contract, not the memory of the author, is what holds. SpecSelf is that idea moved one altitude up. The schema is the contract, and the self implements it: behavior supplies the evidence, reviews audit the claims, and the corpus refuses to let a flattering assertion sit unexamined next to a falsifiable one.&lt;/p&gt;
&lt;p&gt;If you take one move from this post, take the smallest version of it. Before adding a single feature to whatever system holds your own record, decide the fields, and make each one buy a mechanical check. Without a schema it is a diary. With one it is a spec, and specs can fail loudly, which is the only reason to trust them when they pass. The &lt;a href=&quot;https://specself.ai&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Starter&lt;/a&gt; ships the ten fields and the validator so you can start from a schema instead of a pile.&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>When your method repo and your product repo don&apos;t talk to each other</title>
      <link>https://caskeycoding.com/blog/when-your-method-repo-and-your-product-dont-talk</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/when-your-method-repo-and-your-product-dont-talk</guid>
      <pubDate>Thu, 16 Jul 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>spec-driven-development</category>
      <category>AI</category>
      <category>architecture</category>
      <category>schemas</category>
      <category>engineering-methodology</category>
      <description>I built a method as a public repo and the product that runs it as two private ones, and none of them treated the others as a source of truth. The domain enum lived in four places. A persona drifted between its lens file and its API contract. Here is what that cost, and the one structural change that turned the whole class of bug into a failing test.</description>
      <content:encoded>&lt;p&gt;SpecSelf is three repositories. The method is a public repo: markdown templates, persona definitions, steering docs, MIT licensed, forkable from &lt;a href=&quot;https://specself.ai&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;specself.ai&lt;/a&gt;. The API is a private repo: FastAPI on Lambda. The app is a third: a private Next.js PWA. A few weeks after all three were live, I went looking for the place where they agreed on what a principle even is. There wasn&apos;t one. The domain enum was defined in four places. The persona I rely on most had a lens file in the public repo and a contract file in the API, and the two had quietly stopped saying the same words.&lt;/p&gt;
&lt;p&gt;That is the drift I want to describe, because it is the expensive kind. Code drift inside one repo gets caught by tests, by review, by the compiler if you are lucky. Contract drift between the repo that defines the method and the repos that run it gets caught by nothing, because no single repo can see it.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/when-your-method-repo-and-your-product-dont-talk-schema.svg&quot; alt=&quot;Two repo boxes joined by a red zigzag labeled drift no review can see, with a green shared schema box below sending arrows up to both, vendored and checked in CI.&quot;&gt;&lt;/p&gt;
&lt;h2 id=&quot;the-invariant-i-thought-i-had&quot;&gt;The invariant I thought I had&lt;a href=&quot;https://caskeycoding.com/blog/when-your-method-repo-and-your-product-dont-talk#the-invariant-i-thought-i-had&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The design in my head was clean. The public method repo is the contract. It declares what a principle looks like, what the seven life domains are, what each persona may and may not do. The API and the PWA implement that contract. Anyone who forks the public repo gets the same method the hosted product runs, because they are the same definitions.&lt;/p&gt;
&lt;p&gt;The design on disk was three repos that had each written down their own recollection of that contract. Nothing imported anything. Nothing checked anything. The invariant existed only as an intention, and an intention is not an enforcement mechanism. I have made this exact argument about &lt;a href=&quot;https://caskeycoding.com/blog/sdd-is-context-management&quot; class=&quot;internal-link&quot;&gt;spec-driven development&lt;/a&gt; at the code layer for months, and I still shipped the seam without a check on it. The method repo preached falsifiable records, and its own relationship to the product was an unfalsifiable claim.&lt;/p&gt;
&lt;h2 id=&quot;what-the-drift-actually-looked-like&quot;&gt;What the drift actually looked like&lt;a href=&quot;https://caskeycoding.com/blog/when-your-method-repo-and-your-product-dont-talk#what-the-drift-actually-looked-like&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Three examples, in increasing order of embarrassment.&lt;/p&gt;
&lt;p&gt;The seven-value domain enum, the list every artifact in the system tags itself with, was defined in four places: the kit&apos;s templates, the kit&apos;s docs, the API&apos;s models, and the app&apos;s UI copy. Four hand-maintained copies of a seven-item list. The day one of them gains a value, the other three are wrong, and no build anywhere goes red.&lt;/p&gt;
&lt;p&gt;The principle template declares ten frontmatter fields. Diffable, dated, falsifiable, versioned: that is the whole pitch of the method. The hosted API was storing a principle without &lt;code class=&quot;inline-code&quot;&gt;confidence&lt;/code&gt;, without &lt;code class=&quot;inline-code&quot;&gt;serves&lt;/code&gt;, without &lt;code class=&quot;inline-code&quot;&gt;last_reviewed&lt;/code&gt;, without &lt;code class=&quot;inline-code&quot;&gt;supersedes&lt;/code&gt;. Half the schema simply never made it into storage. The &lt;code class=&quot;inline-code&quot;&gt;serves&lt;/code&gt; field is the input to the method&apos;s coherence check, the graph walk that catches a project serving no goal. Which means the hosted product could not run the method&apos;s own signature check against its own corpus. The public repo promised an audit; the product had silently dropped the fields the audit reads.&lt;/p&gt;
&lt;p&gt;And then the persona system, which is where it stopped being abstract.&lt;/p&gt;
&lt;h2 id=&quot;the-bug-that-made-me-look&quot;&gt;The bug that made me look&lt;a href=&quot;https://caskeycoding.com/blog/when-your-method-repo-and-your-product-dont-talk#the-bug-that-made-me-look&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Each persona in the method is a lens with a contract: what it looks for, what it must not do, how often it may appear, and which other persona it refuses to share a session with. The Skeptic is the one that hunts borrowed language in my records. Its public lens file says a Skeptic session should be rare. The API&apos;s contract file agreed in spirit and drifted in the numbers: the code enforced a 45-day cooldown while the persona spec said 14. Same persona, same product, two different opinions about how often it exists, and both were shipped.&lt;/p&gt;
&lt;p&gt;The second half was worse. The Skeptic&apos;s contract declares which persona it is mutually exclusive with, so a session never pairs voices that produce whiplash. That declaration is supposed to be symmetric, carried on both sides. It wasn&apos;t. The exclusivity held in one direction and not the other, which means the rule worked or failed depending on which persona the selection algorithm considered first. Both halves of this are sitting in the project&apos;s issue queue: the cooldown drift is specself-api #48 and the asymmetric exclusivity carry is PR #53.&lt;/p&gt;
&lt;p&gt;Neither is a bug a compiler can catch. Neither is a bug a code review is likely to catch, because each half of the contradiction reads as perfectly reasonable in its own file, in its own repo, in its own pull request. The reviewer of the API change would have needed the kit&apos;s lens file open in another tab and a reason to be suspicious of a number as innocent as 45.&lt;/p&gt;
&lt;h2 id=&quot;why-review-cant-hold-this-seam&quot;&gt;Why review can&apos;t hold this seam&lt;a href=&quot;https://caskeycoding.com/blog/when-your-method-repo-and-your-product-dont-talk#why-review-cant-hold-this-seam&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;My first instinct was process: be more careful, check the other repo when touching a contract. That instinct is worth naming so it can be dismissed. Two repos means two review contexts and no shared PR. The drift is invisible precisely at the moment of review because review happens inside one repo at a time, and the contradiction only exists across them.&lt;/p&gt;
&lt;p&gt;I have written before about &lt;a href=&quot;https://caskeycoding.com/blog/context-architecture-beats-documentation-dumps&quot; class=&quot;internal-link&quot;&gt;config pairs&lt;/a&gt;, values on two sides of a contract that must change in lockstep, like a framework&apos;s trailing-slash setting and the CDN rewrite function that assumes it. The rule there was that a config pair names its counterpart, and a machine checks the pair. What I had built with SpecSelf was the same problem one level up: not two config values inside one system, but two repositories where one defines a method and the other runs it. Cross-repo config pairs, with no pairing.&lt;/p&gt;
&lt;p&gt;A check that spans repos cannot live in anyone&apos;s vigilance. It has to be a machine check, running in CI, with the contract itself as its input. Which raises the real question: which repo owns the contract?&lt;/p&gt;
&lt;h2 id=&quot;the-move-the-method-repo-became-a-schema-repo&quot;&gt;The move: the method repo became a schema repo&lt;a href=&quot;https://caskeycoding.com/blog/when-your-method-repo-and-your-product-dont-talk#the-move-the-method-repo-became-a-schema-repo&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The answer we landed on is recorded in an architecture decision record, and it took about a week to implement. The public method repo stopped being documentation and became the contract. It gained a &lt;code class=&quot;inline-code&quot;&gt;schemas/&lt;/code&gt; directory: an enums file that is the single canonical home of the domain taxonomy and every status vocabulary, plus machine-readable schemas for the principle and persona shapes. The templates that humans read now point at those schemas instead of restating them. The persona lens files carry their contract in frontmatter: cooldowns, exclusivities, the must-not-do list.&lt;/p&gt;
&lt;p&gt;The API vendors those files at build time. And three drift tests now run in its CI: one asserting the code&apos;s enums match the vendored contract, one asserting every persona&apos;s code contract matches the definitions vendored from the kit, including the rule that exclusivity declarations must be symmetric, and one holding the foundation questions in lockstep. The stored principle was extended to the full starter shape, so the coherence check finally has its inputs.&lt;/p&gt;
&lt;p&gt;Those comparisons establish agreement with the vendored version. Keeping that version current needs an update policy too. If you use this pattern, record the source commit or release beside the copied schemas, make upstream changes trigger an update review, and include a migration when the stored shape changes. The tests described here do not establish that every consumer automatically follows the newest method revision.&lt;/p&gt;
&lt;p&gt;The class of bug did not shrink. It converted. Enum drift, persona drift, schema drift: each is now a failing test with a file and a line, instead of a contradiction waiting in the gap between two repos for the selection algorithm to find it on a Sunday morning. The Skeptic fixes above are that machinery at work, moving through the queue as tracked, testable changes rather than surprises.&lt;/p&gt;
&lt;h2 id=&quot;your-version-of-this-seam&quot;&gt;Your version of this seam&lt;a href=&quot;https://caskeycoding.com/blog/when-your-method-repo-and-your-product-dont-talk#your-version-of-this-seam&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The specifics are mine, but the seam is everywhere. A design system has it: the Figma library defines the method, the component repo runs it. An editorial operation has it: the style guide defines, the CMS enforces, or claims to. Contract-first API shops have it in its purest form: the OpenAPI spec and the server that allegedly implements it. In every case there is a repo that says what should be true and a repo that makes something true, and the question is whether anything machine-readable forces them to agree.&lt;/p&gt;
&lt;p&gt;The test is quick. Pick the enum, the schema, or the rule that both sides depend on, and ask what turns red when one side changes it. If the answer is nothing, you do not have a contract. You have two repos with similar opinions, and the opinions are diverging at whatever rate you ship.&lt;/p&gt;
&lt;p&gt;The fix is not more discipline at review time, and it is not merging everything into a monorepo so the seam disappears. It is promoting the method repo to a schema repo: one canonical, machine-readable statement of the contract, vendored by every runtime that claims to implement it, with a CI job on each side that fails on drift.&lt;/p&gt;
&lt;hr&gt;
&lt;p&gt;&lt;strong&gt;Related:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;https://caskeycoding.com/blog/life-in-spec-files&quot; class=&quot;internal-link&quot;&gt;I Keep My Whole Life in Spec Files&lt;/a&gt;, what SpecSelf is and the one rule that makes it safe, the essay this series builds on&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://caskeycoding.com/blog/context-architecture-beats-documentation-dumps&quot; class=&quot;internal-link&quot;&gt;Context architecture beats documentation dumps&lt;/a&gt;, where the config-pair rule comes from&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://caskeycoding.com/blog/sdd-is-context-management&quot; class=&quot;internal-link&quot;&gt;SDD is context management&lt;/a&gt;, the methodology this post applies one level up&lt;/li&gt;
&lt;/ul&gt;</content:encoded>
    </item>
    <item>
      <title>What the SDD Playbook Did Not Cover</title>
      <link>https://caskeycoding.com/blog/what-the-sdd-playbook-did-not-cover</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/what-the-sdd-playbook-did-not-cover</guid>
      <pubDate>Sun, 12 Jul 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>spec-driven-development</category>
      <category>ai</category>
      <category>claude-code</category>
      <category>workflow</category>
      <description>Three months ago I laid out spec-driven development and the folder architecture that makes it work. Most of the playbook held up in daily production use. Three ideas that essay never mentioned turned out to matter more than anything in it: Implementation Reality sections, ADRs that amend each other, and splitting the work between a stateful tool and a stateless one.</description>
      <content:encoded>&lt;p&gt;&lt;a href=&quot;https://caskeycoding.com/blog/spec-driven-development-and-the-folder-architecture-that-makes-it-work&quot; class=&quot;internal-link&quot;&gt;Three months ago I wrote about spec-driven development and the folder architecture that makes it work&lt;/a&gt;. The argument was that specs should be the source of truth rather than chat history, that &lt;code class=&quot;inline-code&quot;&gt;CLAUDE.md&lt;/code&gt; should be a minimal routing file, and that workspace structure, not multi-agent orchestration, is the real agentic architecture. Since then I have been running that playbook daily, across two production sites and a fleet of personal projects. Most of it held up. Three ideas the essay never mentioned turned out to matter more than anything in it.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/what-the-sdd-playbook-did-not-cover-additions.svg&quot; alt=&quot;Three green boxes, Implementation Reality, ADRs amend ADRs, and a planner-executor split, sitting on top of a wide base box labeled the SDD playbook.&quot;&gt;&lt;/p&gt;
&lt;h2 id=&quot;implementation-reality&quot;&gt;Implementation Reality&lt;a href=&quot;https://caskeycoding.com/blog/what-the-sdd-playbook-did-not-cover#implementation-reality&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The original essay named spec rot as a risk. It did not solve it.&lt;/p&gt;
&lt;p&gt;Running the playbook surfaced the problem fast: specs drift from code faster than you expect, and in ways you cannot see from the spec alone. The mitigation I converged on is a section at the bottom of every package README called Implementation Reality. Four parts, updated at every reconciliation pass: what shipped (with commit or PR references), spec-but-not-in-code (requirements the spec describes that no code implements yet), code-but-not-in-spec (features built ahead of the spec, which need backfill), and the follow-up PRs the document anticipates.&lt;/p&gt;
&lt;p&gt;In the package that drives my finance engine, Implementation Reality is more than half the README. It tracks five sprints of audit closures, eleven ADR pivots, and every dead config key the production code now ignores. It is the single most valuable document in that repo: the handoff artifact that lets the next session start on solid ground instead of trusting a spec that might describe a design that shipped differently.&lt;/p&gt;
&lt;p&gt;If you adopt nothing else from the playbook plus this post, adopt this. Every package README gets a dated Implementation Reality section. Update it at every reconciliation. The spec captures intent. Code is the source of truth for what was built. Implementation Reality is the bridge.&lt;/p&gt;
&lt;h2 id=&quot;adrs-amend-each-other&quot;&gt;ADRs amend each other&lt;a href=&quot;https://caskeycoding.com/blog/what-the-sdd-playbook-did-not-cover#adrs-amend-each-other&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The original essay treated architecture decision records as write-once.&lt;/p&gt;
&lt;p&gt;In production they evolve. ADR-002 in a package&apos;s &lt;code class=&quot;inline-code&quot;&gt;decision/&lt;/code&gt; directory amends the API contract that ADR-001 established, which amended the default format the original feature spec set. The ritual that keeps this honest is the amendment note: both the amending ADR and the amended document carry a dated entry in their change logs, and the amending ADR&apos;s status block explicitly names what it supersedes. A &quot;Supersedes:&quot; line in an ADR header is load-bearing, not metadata.&lt;/p&gt;
&lt;p&gt;Without the amendment ritual, specs silently diverge. With it, the chain of decisions is auditable: any future reader can trace which ADR currently governs a field, and why. The &lt;a href=&quot;https://github.com/Caskey-Coding/caskeycoding-specs-demo&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;public demo repo&lt;/a&gt; shows the pattern in two files, a package-scoped ADR-002 that amends a feature&apos;s original API default, with the amendment recorded in both places.&lt;/p&gt;
&lt;h2 id=&quot;the-stateless-and-persistent-tool-split&quot;&gt;The stateless and persistent tool split&lt;a href=&quot;https://caskeycoding.com/blog/what-the-sdd-playbook-did-not-cover#the-stateless-and-persistent-tool-split&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The original essay described a workflow in one tool. Now my workflow is two, and the split does real work.&lt;/p&gt;
&lt;p&gt;A stateful assistant carries the deliberative work: planning, research, spec writing. It has repository access and memory across sessions, which is what lets specs evolve instead of restarting every conversation. Claude Code carries the stateless, fast work: reading a spec and opening a PR with working code. Each tool does the job it is good at. Specs are the handoff boundary between them.&lt;/p&gt;
&lt;p&gt;The split is a structural answer to a structural problem. Implementation wants a fresh context per task, where state is overhead. Decision-making wants the opposite, where state is the whole point. Forcing one tool to do both collapses the workflow in predictable ways: either the implementation context fills up with design history it does not need, or the design session forgets what last week resolved. The tool split is what makes the routing table scale across the actual work.&lt;/p&gt;
&lt;p&gt;A concrete example. A &lt;code class=&quot;inline-code&quot;&gt;/finance&lt;/code&gt; route worked in the Lambda dispatcher but had never been registered in the API Gateway stack. The browser got a &lt;code class=&quot;inline-code&quot;&gt;403 Missing Authentication Token&lt;/code&gt;, CORS headers never attached, the page threw &lt;code class=&quot;inline-code&quot;&gt;Failed to fetch&lt;/code&gt;. The obvious fix was a two-line infrastructure patch. Instead the spec amendment landed first, noting that handler routes and stack routes had drifted twice that month, with an explicit follow-up to add an infra test that compares the dispatcher&apos;s routes against the stack. Then the patch. The bug was real and urgent. The spec is what prevents the next one. Specs lead, code follows, and that discipline is only possible because the deliberative tool and the executing tool are separate.&lt;/p&gt;
&lt;h2 id=&quot;what-the-original-essay-had-right&quot;&gt;What the original essay had right&lt;a href=&quot;https://caskeycoding.com/blog/what-the-sdd-playbook-did-not-cover#what-the-original-essay-had-right&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Most of it. Specs as source of truth. &lt;code class=&quot;inline-code&quot;&gt;CLAUDE.md&lt;/code&gt; as a router, not a brain dump. Workspace context files for per-area loading. Separation of concerns as the operating principle. If you have not read that essay, start there; this post is the follow-up, not the primer.&lt;/p&gt;
&lt;p&gt;The discipline is in the specs. The automation is in the pipeline. The tools are workers. And the receipts are the shipped systems on this site, so you can check whether the playbook cashes out in working software rather than diagrams.&lt;/p&gt;
&lt;hr&gt;
&lt;p&gt;&lt;strong&gt;Related:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;https://caskeycoding.com/blog/spec-driven-development-and-the-folder-architecture-that-makes-it-work&quot; class=&quot;internal-link&quot;&gt;Spec-driven folder architecture&lt;/a&gt;, the original playbook this post extends&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://caskeycoding.com/blog/sdd-is-context-management&quot; class=&quot;internal-link&quot;&gt;SDD is context management&lt;/a&gt;, why the method works at all&lt;/li&gt;
&lt;/ul&gt;</content:encoded>
    </item>
    <item>
      <title>I Keep My Whole Life in Spec Files. My Agent Reads Them and Never Writes Them.</title>
      <link>https://caskeycoding.com/blog/life-in-spec-files</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/life-in-spec-files</guid>
      <pubDate>Fri, 10 Jul 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>spec-driven-development</category>
      <category>ai</category>
      <category>agents</category>
      <category>personal-systems</category>
      <description>Spec-driven development, pointed at a life. Why my principles and goals live as markdown an AI agent reasons over, with an authorship boundary: it can challenge the record, but it never writes it.</description>
      <content:encoded>&lt;p&gt;Every Sunday morning, an AI agent interviews me about my own life. It has read everything I have written down about the person I am trying to become, every goal I have set, every standard I claim to hold. It is very good at noticing where the last week did not match. This weekend it asked me why an intention I have now written three months running still has no evidence behind it. I did not enjoy the question. That is the entire reason it gets to ask it.&lt;/p&gt;
&lt;p&gt;It can challenge me with my own record. It is not allowed to write a single word of that record itself.&lt;/p&gt;
&lt;p&gt;For the last year I have been making one argument about working with AI: give an agent a curated structure to reason over, not a pile of documents. &lt;a href=&quot;https://caskeycoding.com/blog/context-architecture-beats-documentation-dumps&quot; class=&quot;internal-link&quot;&gt;Context architecture beats documentation dumps&lt;/a&gt;. I built that idea into two production sites and a finance engine, where it meant scoped spec slices and bounded agent context. Then I pointed the same idea at the least organized system I own, which is my own life, and it behaved exactly the way it behaves on code.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/life-in-spec-files-one-way.svg&quot; alt=&quot;Two boxes, the agent and the record: a green arrow carries reading and challenging from the record to the agent, while the agent&amp;#x27;s writing arrow stops at a red bar before it reaches the record.&quot;&gt;&lt;/p&gt;
&lt;h2 id=&quot;a-life-as-a-specd-system&quot;&gt;A life as a spec&apos;d system&lt;a href=&quot;https://caskeycoding.com/blog/life-in-spec-files#a-life-as-a-specd-system&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The principles I am trying to live by, the person I want to become, my goals, the areas I am responsible for, the projects I am driving: all of it lives as plain markdown in a git repository.&lt;/p&gt;
&lt;p&gt;An agent reads those files at the start of a session the way a specialist agent reads a scoped spec before it touches code. Because the structure is there, it can see vertically. It can tell that this week&apos;s work connects up to a goal, that the goal serves a stated principle, that an area I claim to care about has gone quiet for a month. That vertical view is the part you cannot hold in your head on a Tuesday, and it is the part a structured agent is good at surfacing.&lt;/p&gt;
&lt;h2 id=&quot;the-one-rule&quot;&gt;The one rule&lt;a href=&quot;https://caskeycoding.com/blog/life-in-spec-files#the-one-rule&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Here is the rule, and it is the part most &quot;AI life coach&quot; products get backwards. The agent organizes, connects, surfaces, and challenges. It never silently authors. I write my principles. I decide when a goal is met. I commit the journal entry in my own words.&lt;/p&gt;
&lt;p&gt;The agent is allowed to interrogate me hard. It can point out that a principle I keep restating has no behavioral evidence. It can name the friction that has shown up three months in a row. What it cannot do is put words in my mouth and let them harden into the record, because the moment something other than me authors my life, the record stops being mine, and a record of your life that you did not write is worth nothing.&lt;/p&gt;
&lt;p&gt;This is the same boundary I draw everywhere there are consequences. In my finance engine, &lt;a href=&quot;https://caskeycoding.com/blog/composite-what-you-trust&quot; class=&quot;internal-link&quot;&gt;the data I trust enough to composite into a grade is walled off from the data I only trust enough to watch&lt;/a&gt;, and a test keeps the crowd from ever moving the number. This is that same line, drawn in a different place. There it separates the inputs that may set a grade from the ones that may only sit beside it. Here it separates who may write the record from who may only question it. I use AI to pressure-test and accelerate, never to do the thinking I need to own. The agent makes the record sharper. It does not get to write it.&lt;/p&gt;
&lt;h2 id=&quot;the-part-i-am-still-bad-at&quot;&gt;The part I am still bad at&lt;a href=&quot;https://caskeycoding.com/blog/life-in-spec-files#the-part-i-am-still-bad-at&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Nothing enforces this. A failing test screams at you; a life OS just sits there if you stop showing up. The system is only as good as the questions you let it ask and the cadence you keep, a couple of minutes most days, twenty minutes most weeks, a longer synthesis most months. And because there is no backend and no account, you carry your own backups and you decide which model provider sees a given session. Those are real tradeoffs of a system you own, and I would rather you know them going in than discover them later.&lt;/p&gt;
&lt;p&gt;The rule itself is hardest exactly when it matters most. There was a session where the agent offered a cleaner version of a principle than the one I had written, sharper, truer-sounding, sitting right there for me to accept. I wanted to keep it. That is the moment the rule is for. I made myself rewrite it in my own clumsier words, because a principle I did not author is one I will not live by. The pull to let a fluent machine phrase your life better than you can is real, and giving in to it is how you end up with a beautiful record of someone who is not you.&lt;/p&gt;
&lt;h2 id=&quot;i-made-my-setup-public&quot;&gt;I made my setup public&lt;a href=&quot;https://caskeycoding.com/blog/life-in-spec-files#i-made-my-setup-public&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;My personal content lives in a folder excluded from Git tracking by default, so I can share the scaffold without including that folder. &lt;a href=&quot;https://git-scm.com/docs/gitignore&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Git ignore rules&lt;/a&gt; govern tracking; they do not prevent an agent from reading a file or sending its contents to a model provider. Content supplied to a hosted model is subject to that provider&apos;s handling. Keeping all processing on my machine would require a local model and controls on network access. I run my own private instance: the foundation session is done, the principles and the journal are accumulating, and the weekly cadence is holding. None of that personal content is part of the public scaffold.&lt;/p&gt;
&lt;p&gt;So I made the scaffold I use public. It is free, you fork it, you point your agent at one file that explains the contract, and you run a guided foundation session where the agent interviews you and you do the writing. It works with any capable agent; with Claude Code you also get the persona lenses and the cadence commands that make the weekly loop faster. It lives at &lt;a href=&quot;https://specself.ai&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;specself.ai&lt;/a&gt;. Your content stays in your repo. I never see it. There is nothing to sign into.&lt;/p&gt;
&lt;h2 id=&quot;the-test&quot;&gt;The test&lt;a href=&quot;https://caskeycoding.com/blog/life-in-spec-files#the-test&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;This is about the line you draw any time you hand an agent a domain you care about. So here is the test I would give anyone pointing an agent at something that matters: name who is allowed to write the record. If the answer is the agent, the record has stopped being yours, no matter how good it sounds when you read it back. A code review, a design doc, a performance self-assessment, a journal: the agent can read all of it and question any of it, but the moment it holds the pen, you are no longer the author of your own account.&lt;/p&gt;
&lt;p&gt;If you build software, the rest of the discipline is already yours: write it down, revise it forever, and never let the tool become the author. I just stopped making my own life the exception. The agent reads my spec files and asks the questions I would rather avoid. I am still the one who has to answer them in writing.&lt;/p&gt;
&lt;hr&gt;
&lt;p&gt;&lt;strong&gt;Related:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;https://caskeycoding.com/blog/composite-what-you-trust&quot; class=&quot;internal-link&quot;&gt;Composite What You Trust, Watch What You Don&apos;t&lt;/a&gt;, the same boundary in my finance engine, drawn between the data allowed to set a grade and the data that only gets to sit beside it&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://caskeycoding.com/blog/context-architecture-beats-documentation-dumps&quot; class=&quot;internal-link&quot;&gt;Context architecture beats documentation dumps&lt;/a&gt;, the method underneath all of this&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://caskeycoding.com/blog/spec-driven-development-and-the-folder-architecture-that-makes-it-work&quot; class=&quot;internal-link&quot;&gt;Spec-driven folder architecture&lt;/a&gt;, where the file structure itself started&lt;/li&gt;
&lt;/ul&gt;</content:encoded>
    </item>
    <item>
      <title>Running a factor scoring engine from a phone</title>
      <link>https://caskeycoding.com/blog/the-pocket-quant</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/the-pocket-quant</guid>
      <pubDate>Fri, 10 Jul 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>AI</category>
      <category>finance</category>
      <category>side-projects</category>
      <category>agents</category>
      <category>platform-engineering</category>
      <description>I built a quant research platform, then built an agent to operate it: a scheduled Claude session that reads the boards, keeps a pre-registered track record, and texts me three times a day without ever saying buy.</description>
      <content:encoded>&lt;p&gt;At 12:06 this afternoon my phone buzzed. &quot;Nothing clears the bar - still a no-call. Most attractive: INCY, just starting to pull back off its 52-week high into the 7/28 print; flips to a call only if it bases and holds with a second lens confirming - watching, not chasing.&quot;&lt;/p&gt;
&lt;p&gt;That is ARGUS. He is a quant who lives inside my research platform, runs on a schedule, and texts me three times a day. In his first week of operation he has recommended buying exactly nothing. I consider this his best feature.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/the-pocket-quant-push.webp&quot; alt=&quot;The actual midday push on my phone: morning read intact, nothing clears the bar, and the most attractive move named with its flip trigger. One position name is redacted; everything else is exactly what ARGUS sent.&quot;&gt;&lt;/p&gt;
&lt;p&gt;I build platforms. For the past few months the side project has been a quantitative research platform: data collectors, a scoring engine, a wall of 3D market visualizations that render the whole equity universe as one canvas. It got good enough that I stopped asking what to build next and started asking a harder question. A platform is only proven when someone who is not you can walk in and operate it. Nobody else was walking in. So I built the someone.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/the-pocket-quant-board.webp&quot; alt=&quot;The flagship board of the platform ARGUS reads: a tape race of the full universe mid-replay, a ranked leader list, and sector rotation, all drawn from live public data.&quot;&gt;&lt;/p&gt;
&lt;p&gt;ARGUS is named for Argus Panoptes, the watchman with a hundred eyes, because that is the actual job: read every board, not just the flashy one. He is a headless Claude session dispatched by a scheduler at pre-open, midday, and post-close. One persona file is his entire behavior source. Version-controlled, hash-stamped, no second copy anywhere that could drift. The pings ride ntfy, a small open-source notification relay; my phone is the whole client.&lt;/p&gt;
&lt;p&gt;He does not crawl the platform looking for data. Before each session, a deterministic script builds him a pack: every visualization&apos;s feed distilled to what carries signal, live quotes, crowd sentiment, his own notes and open calls, anything I said to him since the last run. It is the same context-architecture bet I make everywhere else. Each task loads a curated slice, not the whole corpus. The model spends its budget on judgment instead of fetching, and the run costs a fraction of what a crawl would.&lt;/p&gt;
&lt;p&gt;The judgment is where it gets interesting, because an agent that picks stocks is a weekend project. An agent whose opinions you can audit is a platform feature. The difference is the harness around him.&lt;/p&gt;
&lt;p&gt;Every candidate ARGUS surfaces is pre-registered before the outcome exists: entry, stop, target, a numeric probability, a horizon, and a sector benchmark. The journal is append-only and script-mediated. Deterministic code resolves calls against daily closes. That measures a close-based forecast; daily closes cannot tell me which intraday stop or target was touched first, or what a trade would have filled at.&lt;/p&gt;
&lt;p&gt;The expectancy gate is intended to reject candidates without a positive expected payoff after costs. For a binary win/loss outcome, that means &lt;code class=&quot;inline-code&quot;&gt;p * reward - (1 - p) * loss - cost&lt;/code&gt;, with reward, loss and cost expressed on the same basis. The scorecard needs to publish its actual payoff and resolution conventions before that intention becomes an auditable result. The instruction to avoid trade verbs is an output policy; my decision remains separate from the forecast.&lt;/p&gt;
&lt;p&gt;On his first night under the full harness, he went quiet when I expected a ping. I dug into the logs expecting a bug. Instead I found a decision: he was required to send exactly one message per session, could not verify whether an earlier run had already sent one, judged a duplicate notification to be the one irreversible outcome on the table, and held the push. Then he wrote in his own log that the harness gave him no way to check what had already been sent, and that this gap had forced the hold. He was right. I shipped the send-log an hour later. The agent audited his own cage and the platform got better for it.&lt;/p&gt;
&lt;p&gt;As of today his track record contains zero resolved calls. He has ranked the boards, flagged the loudest theme on them as a crowded hedge rather than an opportunity, corrected his own memory of an earnings date, and refused to chase an extended name into a binary event. All reasonable. None of it proven. In a few months the scorecard will say, against a matched benchmark and with a sample-size warning built in, whether his picking adds anything beyond the deterministic screen he draws candidates from. The record segments every time I edit his instructions, so I cannot quietly move the goalposts and pretend it was one continuous streak.&lt;/p&gt;
&lt;p&gt;This is the one place the side project touches the day job. The work I care about is platform primitives: the boundaries that let an operator act fast without being able to hurt anything. ARGUS is that idea with a personality.&lt;/p&gt;
&lt;p&gt;I built a platform to measure the agent&apos;s forecasts under recorded rules. The first scorecard was due in the fall. It needs those rules and the resolved sample beside the results before anyone can judge whether the forecasts add value.&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>Pricing 215 million options a second with SIMD C++</title>
      <link>https://caskeycoding.com/blog/pricing-215-million-options-a-second</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/pricing-215-million-options-a-second</guid>
      <pubDate>Thu, 09 Jul 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>C++</category>
      <category>simd</category>
      <category>performance</category>
      <category>quant</category>
      <category>finance</category>
      <category>side-projects</category>
      <description>I wrote a C++ options pricer to learn low-latency numerics. The first clean version priced fifteen million options a second; getting to 215 million was less about clever code and more about being wrong, in public with myself, about where the speed would come from.</description>
      <content:encoded>&lt;p&gt;I built a Black-Scholes options pricer in C++. My desktop measurements went from fifteen million options a second for the first version on one core to about 215 million for the finished version across all cores. This is a report of that experiment. I have not included the CPU model and core count, compiler version and flags, benchmark command and input batch, or the accuracy envelope needed to reproduce those numbers. The useful part I can explain here is how measurement changed where I looked for speed.&lt;/p&gt;
&lt;p&gt;The first version was the textbook version: clean, allocation-free, correct, checked against published prices and put-call parity. On a single core it priced about fifteen million options a second. That sounds fast until you learn what a modern core can actually do. Fifteen million was the easy part. Everything worth telling happened on the way to 215 million.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/pricing-215-million-options-a-second-climb.svg&quot; alt=&quot;An ascending line from 15 million options per second to a green 215 million, with two dashed red dead-end stubs at the bends marking wrong guesses about memory layout and compiler auto-vectorization.&quot;&gt;&lt;/p&gt;
&lt;h2 id=&quot;why-i-built-it&quot;&gt;Why I built it&lt;a href=&quot;https://caskeycoding.com/blog/pricing-215-million-options-a-second#why-i-built-it&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;One side project, three goals. I wanted to relearn the numerical methods behind option pricing, the ones I last touched years ago. I wanted to practice low-latency code, the kind I never get to write in a web backend, where the clock is a network round trip and not a nanosecond. And I wanted an artifact, something I could point at instead of describe.&lt;/p&gt;
&lt;p&gt;The volatility math behind &lt;a href=&quot;https://caskeycoding.com/blog/markets-in-three-dimensions&quot; class=&quot;internal-link&quot;&gt;the 3D surfaces in my playground&lt;/a&gt; was cross-checked against it before I trusted a single number on screen.&lt;/p&gt;
&lt;h2 id=&quot;what-i-built&quot;&gt;What I built&lt;a href=&quot;https://caskeycoding.com/blog/pricing-215-million-options-a-second#what-i-built&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;At its core the engine prices an option and its full set of Greeks with no memory allocation, checked against known values. Around that core sits a Monte Carlo engine with variance-reduction methods, a risk view, and a Python binding for NumPy. The headline benchmark does not specify here whether Greeks were included in the timed operation, so it should not be read as a rate for the full API or compared directly with a NumPy implementation.&lt;/p&gt;
&lt;p&gt;So the shape of it is a small, fast library, fast enough to be interesting, with a test behind every number it reports. It is a learning artifact, not a trading system, and the market data it serves is the educational playground on this site, not an execution engine.&lt;/p&gt;
&lt;h2 id=&quot;how-it-got-fast-three-times-i-was-wrong&quot;&gt;How it got fast: three times I was wrong&lt;a href=&quot;https://caskeycoding.com/blog/pricing-215-million-options-a-second#how-it-got-fast-three-times-i-was-wrong&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The climb from fifteen million to 215 million was not a straight line of clever ideas. It was a sequence of confident assumptions, each killed by a measurement.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;The bottleneck was not where the guides said.&lt;/strong&gt; Every performance guide opens the same way: restructure your data so memory access goes linear. I did it carefully and the loop got slightly slower. The advice was not wrong in general, it was wrong here, because this loop never touched much memory. An option pricer lives inside exponentials, logarithms, and the normal distribution, which is to say inside the math. Reorganizing memory for a loop that is starved on arithmetic solves a problem it does not have. Once I attacked the math instead, swapping one modern library call for a sixty-year-old polynomial and threading a loop that was embarrassingly parallel, the number jumped from fifteen million to about 114 million.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;The compiler claimed a win it never delivered.&lt;/strong&gt; The plan always included SIMD, the vector instructions that handle four numbers at once, and modern advice says the compiler does that for you on clean loops. My build logs agreed and reported the loop vectorized. They were reporting on a different loop, a trivial one at the end of the benchmark. My compiler would not fold a loop full of exp and log calls into vector form. Some toolchains will; mine did not. So the loop that mattered stayed scalar every single time, its failure notice sitting in a report I had not opened. None of my first big speedup came from SIMD at all.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;So I wrote the math by hand.&lt;/strong&gt; Four-wide exponential and logarithm, built from classic polynomial cores, intrinsics all the way down. The discipline that saved me here was borrowed and simple: test each function in isolation against the standard library before wiring it into anything. Not the pricer against the pricer, the exponential against the exponential. When a bug showed up, the isolated test named the exact function instead of leaving me to hunt a wrong price three layers downstream. With real SIMD underneath, one core gained a clean four times, right at the theoretical width, and across all cores the engine reached about 215 million a second.&lt;/p&gt;
&lt;h2 id=&quot;what-i-keep-from-it&quot;&gt;What I keep from it&lt;a href=&quot;https://caskeycoding.com/blog/pricing-215-million-options-a-second#what-i-keep-from-it&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;I set out to relearn some numerical methods and end up with a small, fast library I could point at, and I got both. The single biggest win was trading a modern function for an old approximation I could reason about. Fifteen million a second was free; the next two hundred million were an education in checking what is actually true, one report line at a time.&lt;/p&gt;
&lt;p&gt;Desktop timings varied ten or twenty percent run to run. A reusable benchmark would need repeated measurements for the same input batch, separate single-core and multicore results, and the maximum error over the supported parameter range after each approximation. The checks described here do not supply that public accuracy envelope. The library remains a learning artifact; these rates are not evidence of production trading performance.&lt;/p&gt;
&lt;hr&gt;
&lt;p&gt;&lt;strong&gt;Related:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;https://caskeycoding.com/blog/markets-in-three-dimensions&quot; class=&quot;internal-link&quot;&gt;Rendering an options Greeks surface in 3D in the browser&lt;/a&gt;, the 3D surfaces this engine&apos;s volatility math feeds&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://caskeycoding.com/blog/backtesting-without-fooling-yourself&quot; class=&quot;internal-link&quot;&gt;How to backtest without fooling yourself&lt;/a&gt;, the same measure-before-believing discipline pointed at signals instead of speed&lt;/li&gt;
&lt;/ul&gt;</content:encoded>
    </item>
    <item>
      <title>Rendering an options Greeks surface in 3D in the browser</title>
      <link>https://caskeycoding.com/blog/markets-in-three-dimensions</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/markets-in-three-dimensions</guid>
      <pubDate>Mon, 06 Jul 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>finance</category>
      <category>visualization</category>
      <category>dataviz</category>
      <category>threejs</category>
      <category>frontend</category>
      <category>options</category>
      <description>A 3D render crossed my feed once and stuck with me, so I tried to see an option the same way: as a surface I could grab and turn, not a number. That turned into five market visualizations on one shared trick, a compliance rule the architecture enforces by accident, and an honest lesson about wanting a crystal ball and getting understanding instead.</description>
      <content:encoded>&lt;p&gt;A 3D render crossed my feed once, one of the slow rotating surfaces the account &lt;a href=&quot;https://www.instagram.com/tuba.captures/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;tuba.captures&lt;/a&gt; posts, the kind where you can almost feel the curvature through the screen. It stuck with me, and a few days later I wanted that for something I actually stare at: an option.&lt;/p&gt;
&lt;p&gt;A call option gives its holder the right, without an obligation, to buy the underlying stock at a set price within the contract&apos;s exercise terms. A put gives the right to sell; the &lt;a href=&quot;https://www.optionseducation.org/optionsoverview/what-is-an-option&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Options Industry Council explains both&lt;/a&gt;. My first surface is a long call. Its usual hockey-stick chart shows the payoff against stock price on the day it expires. But that picture is only the last day. The days before it, the ones you actually hold through, are a curved sheet of profit and loss bending over price and time together, and the flat chart throws that second dimension on the floor. So I priced the option across a grid of prices and dates, stacked the profit and loss as height, and drew it as a surface I could grab and turn. It is live in the playground, at &lt;a href=&quot;https://caskeycoding.com/lab/greeks-manifold&quot; class=&quot;internal-link&quot;&gt;/play/greeks-manifold&lt;/a&gt;.&lt;/p&gt;
&lt;p&gt;The first time I rotated it, gamma was just sitting there. The Greeks are the standard set of numbers traders use to describe how an option behaves. Gamma is the one for how sharply the option&apos;s value bends, and it is biggest right at the strike price (the price the option lets you buy at). As a number it is abstract. On the surface it is a ridge, a visible spine running across the sheet near the strike, and coloring the surface by gamma lights the ridge up. Theta is another Greek: the value the option loses as expiry nears. On the surface it is the downhill slope in the time direction, so you can see exactly where it bites hardest. The numbers I had been computing as columns in a table were just the shape of the object, seen from different directions.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/greeks-gamma-ridge.webp&quot; alt=&quot;The long-call profit-and-loss surface colored by gamma: a teal band flaring orange at the strike, where the option&amp;#x27;s value bends hardest&quot;&gt;
&lt;em&gt;The surface from the playground, colored by gamma. The glow along the strike is the ridge; the hot spot is where the bend is sharpest.&lt;/em&gt;&lt;/p&gt;
&lt;p&gt;That was the hook. If one piece of option math could become a shape, the rest could too.&lt;/p&gt;
&lt;p&gt;Most of the finance vocabulary in this post is vocabulary I only really understood once I could see it. The definitions are what I learned building this.&lt;/p&gt;
&lt;h2 id=&quot;the-five-at-a-glance&quot;&gt;The five at a glance&lt;a href=&quot;https://caskeycoding.com/blog/markets-in-three-dimensions#the-five-at-a-glance&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Surface&lt;/th&gt;
&lt;th&gt;The three axes&lt;/th&gt;
&lt;th&gt;What you are looking at&lt;/th&gt;
&lt;th&gt;When to open it&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;a href=&quot;https://caskeycoding.com/lab/greeks-manifold?greek=gamma&quot; class=&quot;internal-link&quot;&gt;Greeks manifold&lt;/a&gt;&lt;/td&gt;
&lt;td&gt;stock price, time, profit/loss&lt;/td&gt;
&lt;td&gt;an option&apos;s value bending, colored by a chosen Greek&lt;/td&gt;
&lt;td&gt;before an options trade, to read the terrain ahead&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;a href=&quot;https://caskeycoding.com/lab/drawdown-topology&quot; class=&quot;internal-link&quot;&gt;Drawdown topology&lt;/a&gt;&lt;/td&gt;
&lt;td&gt;time, account value, simulated path&lt;/td&gt;
&lt;td&gt;a fan of simulated outcomes, colored by how far each is underwater&lt;/td&gt;
&lt;td&gt;to calibrate your gut for how deep a bad run can dig&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;a href=&quot;https://caskeycoding.com/lab/yield-curve?source=synthetic&amp;#x26;frame=59&quot; class=&quot;internal-link&quot;&gt;Yield curve dynamics&lt;/a&gt;&lt;/td&gt;
&lt;td&gt;borrowing length, time, interest rate&lt;/td&gt;
&lt;td&gt;the Treasury curve changing shape over time&lt;/td&gt;
&lt;td&gt;to watch an inversion form (the recession warning)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;a href=&quot;https://caskeycoding.com/lab/correlation-regime?source=synthetic&amp;#x26;frame=59&quot; class=&quot;internal-link&quot;&gt;Correlation regime&lt;/a&gt;&lt;/td&gt;
&lt;td&gt;asset, asset, co-movement&lt;/td&gt;
&lt;td&gt;the grid of how assets move together, tightening calm to crisis&lt;/td&gt;
&lt;td&gt;when a sell-off starts and diversification evaporates&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;a href=&quot;https://caskeycoding.com/lab/greeks-manifold?surface=smile&quot; class=&quot;internal-link&quot;&gt;Implied-vol surface&lt;/a&gt;&lt;/td&gt;
&lt;td&gt;strike, expiry, implied volatility&lt;/td&gt;
&lt;td&gt;the volatility that option prices imply, as one sheet (the synthetic-smile mode of the Greeks manifold)&lt;/td&gt;
&lt;td&gt;to read the volatility smile in a single glance&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;The &lt;a href=&quot;https://caskeycoding.com/lab/drawdown-topology&quot; class=&quot;internal-link&quot;&gt;drawdown topology&lt;/a&gt; is a fan of thousands of simulated price paths. (Simulating a lot of random paths to see the range of outcomes is called Monte Carlo, after the casino.) Each path is colored by its drawdown, which is just how far it has fallen from its high point. Flip the simulated returns from an ordinary bell curve to a fat-tailed one, meaning big jumps happen more often, and the whole cone visibly bulges. The textbooks say tails matter; here you watch the hole get deeper.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/drawdown-fan.webp&quot; alt=&quot;A fan of simulated price paths hanging in space, colored by drawdown depth, with the deepest runs dangling yellow below the rest&quot;&gt;
&lt;em&gt;The fan, colored by drawdown depth. The yellow strands are the deep holes, the runs the bell curve says should barely happen.&lt;/em&gt;&lt;/p&gt;
&lt;p&gt;The &lt;a href=&quot;https://caskeycoding.com/lab/yield-curve&quot; class=&quot;internal-link&quot;&gt;yield curve&lt;/a&gt; is just the interest rate for borrowing money over different lengths of time, from one month out to thirty years. Normally it slopes up, because longer loans cost more. Drawn as a surface you scrub through time, you can watch it invert, where short-term rates climb above long-term ones, the shape everyone calls a recession warning. Reading that an inversion happened lands as a statistic; watching the surface fold over lands somewhere lower.&lt;/p&gt;
&lt;p&gt;The &lt;a href=&quot;https://caskeycoding.com/blog/how-to-tell-when-the-yield-curve-has-inverted&quot; class=&quot;internal-link&quot;&gt;yield-curve reading guide&lt;/a&gt; explains the endpoint rule behind the inversion badge and separates real Treasury observations from the synthetic demonstration.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/yield-curve-inverted.webp&quot; alt=&quot;The Treasury yield curve as a surface over maturity and time, folded into inversion, with the status badge reading inverted&quot;&gt;
&lt;em&gt;Scrubbed to the far end of the story: short rates above long, the fold everyone calls a recession warning.&lt;/em&gt;&lt;/p&gt;
&lt;p&gt;The &lt;a href=&quot;https://caskeycoding.com/lab/correlation-regime&quot; class=&quot;internal-link&quot;&gt;correlation regime&lt;/a&gt; is the one I find hardest to look away from. Correlation is how much two assets move together, and the grid shows it for every pair at once. You dial it from calm toward crisis. &quot;In a crash, all correlations go to one&quot; is a line everyone repeats; watching every cell in the grid climb to one at the same moment is diversification evaporating in front of you, exactly when you were counting on it.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/correlation-crisis.webp&quot; alt=&quot;The correlation grid at the crisis end of the scrub, the whole field of pairwise bars risen together&quot;&gt;
&lt;em&gt;The grid at the crisis end of the slider. The whole field rising together is the moment diversification stops helping.&lt;/em&gt;&lt;/p&gt;
&lt;p&gt;And the &lt;a href=&quot;https://caskeycoding.com/lab/greeks-manifold&quot; class=&quot;internal-link&quot;&gt;implied-volatility surface&lt;/a&gt;, the synthetic-smile mode of the Greeks manifold, plots implied volatility, which is how much the market expects a stock to move, read backward out of what its options cost. Plot it across every strike price and expiry date and it has a shape, the famous &quot;smile,&quot; where the market charges more for some outcomes than others. A row of separate option quotes hides that; the surface makes it obvious. The math here leans on a small C++ options pricer I wrote, cross-checked against a reference implementation before I trusted a single number it produced.&lt;/p&gt;
&lt;h2 id=&quot;one-trick-five-surfaces&quot;&gt;One trick, five surfaces&lt;a href=&quot;https://caskeycoding.com/blog/markets-in-three-dimensions#one-trick-five-surfaces&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Most of the work in that first surface had nothing to do with options. The math is one plain function that takes some parameters and returns a grid of numbers; it has no idea it will ever be drawn. The drawing is a separate piece that takes a grid of numbers and turns it into a 3D mesh; it has no idea the numbers are options. Between them sits a plain data object.&lt;/p&gt;
&lt;p&gt;&lt;em&gt;This post includes a diagram. &lt;a href=&quot;https://caskeycoding.com/blog/markets-in-three-dimensions&quot;&gt;View it on caskeycoding.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;
&lt;p&gt;Once that boundary existed, a new visualization was mostly a new math function bolted onto the same drawing code. The first surface was most of the work, the camera and the colors and the controls; every one after it was a new function feeding the same machinery, which is how one became five. And because the renderer is indifferent to where its numbers come from, I can test all of the math against exact textbook answers without ever starting up the graphics hardware.&lt;/p&gt;
&lt;p&gt;The split also gave me a specific place to review publication boundaries. These pages are public, and their inputs must be public market data or made-up illustration. A renderer that accepts any grid cannot enforce that rule by itself. The producer has to select the approved sources and fields before handing over the public data object. Separating that handoff from the drawing code makes the review smaller; it does not make a disclosure impossible.&lt;/p&gt;
&lt;p&gt;Source limitations are visible on the &lt;a href=&quot;https://caskeycoding.com/blog/the-binder-and-the-benchmark&quot; class=&quot;internal-link&quot;&gt;graded-card and stock-market comparison&lt;/a&gt; too: the chart labels sparse historical sales and a later change of measure.&lt;/p&gt;
&lt;p&gt;One smaller habit paid off out of proportion: four of the five animate from a slider you scrub rather than from an internal clock. That keeps the animation predictable and testable, and it means the slider is the single source of truth for what you are seeing, not a side effect of however fast your screen happens to be drawing.&lt;/p&gt;
&lt;h2 id=&quot;real-data-not-just-textbook-math&quot;&gt;Real data, not just textbook math&lt;a href=&quot;https://caskeycoding.com/blog/markets-in-three-dimensions#real-data-not-just-textbook-math&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;I have a lot of market data sitting around, and that same split is why pointing these surfaces at it was a swap and not a rewrite. The yield curve can now show the actual recent Treasury curve from the Federal Reserve&apos;s public FRED data; the correlation grid can show how the real sector funds (technology, energy, financials, and the rest) have actually been moving together; the option surfaces can re-center on a real stock and tune themselves to how much it has actually been bouncing around. The list of stocks you can pick started as a curated handful and is now any name in the S&amp;#x26;P 500. Loading all five hundred at once would weigh down every visit, so the page fetches one only when you choose it. The made-up version is still the default; the real one drops in behind the exact same renderer, which never knew the difference.&lt;/p&gt;
&lt;p&gt;One last detail I had to get right: three.js, the library that does the actual 3D drawing, is heavy, and these pages are otherwise light and static. So none of that code ships inside the page. It loads only after you arrive, as a separate chunk, which is why the playground opens instantly even though every surface is a full graphics scene underneath.&lt;/p&gt;
&lt;h2 id=&quot;not-a-crystal-ball&quot;&gt;Not a crystal ball&lt;a href=&quot;https://caskeycoding.com/blog/markets-in-three-dimensions#not-a-crystal-ball&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Part of me wanted a crystal ball. I have a pile of market data and I keep trying to mold it into something that tells me what to do next, and somewhere in the back of my head I hoped that seeing it in three dimensions would make the move obvious. It does not. None of these predict anything. They take numbers I already have and let me look at them from a side I could not see before.&lt;/p&gt;
&lt;p&gt;That turned out to be worth more than I expected. Reshaping the same data into a surface I can turn has taught me more about how portfolios and quant strategies actually behave than any forecast did, even the surfaces I am still learning to read.&lt;/p&gt;
&lt;p&gt;So, not trading tools. Open one and turn it: start at &lt;a href=&quot;https://caskeycoding.com/lab&quot; class=&quot;internal-link&quot;&gt;the playground&lt;/a&gt; and grab the Greeks surface, or watch the correlation grid go to one.&lt;/p&gt;
&lt;h2 id=&quot;built-on&quot;&gt;Built on&lt;a href=&quot;https://caskeycoding.com/blog/markets-in-three-dimensions#built-on&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;https://threejs.org/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;three.js&lt;/a&gt; for the 3D, with &lt;a href=&quot;https://github.com/pmndrs/react-three-fiber&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;react-three-fiber&lt;/a&gt; and &lt;a href=&quot;https://github.com/pmndrs/drei&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;drei&lt;/a&gt; (from the pmndrs collective) driving it from React.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://mui.com/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Material UI&lt;/a&gt; for the controls, &lt;a href=&quot;https://nextjs.org/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Next.js&lt;/a&gt; for the app.&lt;/li&gt;
&lt;li&gt;Public data from the Federal Reserve&apos;s &lt;a href=&quot;https://fred.stlouisfed.org/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;FRED&lt;/a&gt;, &lt;a href=&quot;https://site.financialmodelingprep.com/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Financial Modeling Prep&lt;/a&gt; for prices, and Wikipedia&apos;s &lt;a href=&quot;https://en.wikipedia.org/wiki/List_of_S%26P_500_companies&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;S&amp;#x26;P 500 list&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;A small C++ options pricer I wrote for the volatility math, and the nudge from &lt;a href=&quot;https://www.instagram.com/tuba.captures/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;tuba.captures&lt;/a&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;hr&gt;
&lt;p&gt;&lt;strong&gt;Related:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;https://caskeycoding.com/blog/building-an-ai-finance-app&quot; class=&quot;internal-link&quot;&gt;Building an AI finance app&lt;/a&gt;, the engine whose public outputs some of these surfaces draw on&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://caskeycoding.com/blog/backtesting-without-fooling-yourself&quot; class=&quot;internal-link&quot;&gt;Backtesting without fooling yourself&lt;/a&gt;, the rigor that has to sit behind any real-data mode&lt;/li&gt;
&lt;/ul&gt;</content:encoded>
    </item>
    <item>
      <title>Why an agent tool should surface the decision, not make it</title>
      <link>https://caskeycoding.com/blog/surface-the-decision-dont-make-it</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/surface-the-decision-dont-make-it</guid>
      <pubDate>Sun, 05 Jul 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>methodology</category>
      <category>ai-engineering</category>
      <category>agents</category>
      <category>decision-making</category>
      <category>tooling</category>
      <category>verification</category>
      <description>In one working session I designed a read-only advisor and spent the rest of it being the customer of another. Both ran on the same short discipline: surface the decision and never seize it, verify before you assert, pilot before you fan out, and stay honest when the sample is thin.</description>
      <content:encoded>&lt;p&gt;In a single working session this week I did two jobs without noticing they were the same job. I designed a read-only advisor: a morning ritual that reads my private trade journal, ranks what actually needs a call today, scores how well past calls have held up, and hands the decision back to me untouched. And for most of that same session I was the customer of an advisor myself, leaning on a stronger reviewer model to check my work before I shipped it. Building one and being advised by one ran on the same short list of rules.&lt;/p&gt;
&lt;p&gt;The lead idea is restraint: a trustworthy advisor surfaces the decision and never seizes it, a boundary worth enforcing in code rather than trusting to good intentions. The companion disciplines are the ones I rely on when I am the one being advised: verify before you assert, pilot before you fan out, and say so when the evidence is thin.&lt;/p&gt;
&lt;h2 id=&quot;the-advisor-that-refuses-to-act&quot;&gt;The advisor that refuses to act&lt;a href=&quot;https://caskeycoding.com/blog/surface-the-decision-dont-make-it#the-advisor-that-refuses-to-act&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The structured output I already had was precise but dense. Numbers, ratios, a rank delta. Correct, and exactly what you want underneath a decision, but it failed at two jobs: it never said in plain English what mattered this morning, and it threw away the story sitting in the journal about whether the past calls were any good.&lt;/p&gt;
&lt;p&gt;So the advisor layer adds three pieces on top, without removing the precise data underneath. A plain-English lead (a one-sentence bottom line and a single &quot;look at this one&quot; pointer). A ranked priority triage that sorts what is true right now into CRITICAL, WARN, and INFO. And a calibration scoreboard that grades the track record: how often the forecasts hit, whether they were over or under confident, whether the book is sized to conviction.&lt;/p&gt;
&lt;p&gt;The hard rule sits underneath all of it. The advisor speaks only in framing verbs (&quot;decide today&quot;, &quot;resize or restate&quot;, &quot;pre-decide the exit&quot;) and never a trade verb. It tells me a position broke a line I drew. It does not tell me to sell it. It surfaces the decision and leaves the decision to me. That is the whole posture, and it is the same posture the reviewer model took with me all session: it saw exactly what I had done and told me where it was weak, and it never once had its hands on the merge button.&lt;/p&gt;
&lt;h2 id=&quot;a-boundary-you-enforce-not-remember&quot;&gt;A boundary you enforce, not remember&lt;a href=&quot;https://caskeycoding.com/blog/surface-the-decision-dont-make-it#a-boundary-you-enforce-not-remember&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;I added a wording test: listed trade verbs must not appear in the rendered priority, bottom line, or scoreboard. A template that introduces one fails the test. That catches specific output regressions; it does not establish read-only access or catch every recommendation phrased without those words. Read-only authority depends on the tools and permissions available to the advisor. Those controls need checking separately from what its templates say.&lt;/p&gt;
&lt;p&gt;&lt;em&gt;This post includes a diagram. &lt;a href=&quot;https://caskeycoding.com/blog/surface-the-decision-dont-make-it&quot;&gt;View it on caskeycoding.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;
&lt;p&gt;This is the same reason the reviewer I leaned on is safe to lean on. It is wired to comment, not to commit. It reads the full context and pushes back hard, and the irreversible actions (the merge, the deploy) stay behind a gate it does not control. An advisor with its hands tied to suggestion is more useful, not less, because I can take its push at face value without wondering whether it is about to do something I cannot undo.&lt;/p&gt;
&lt;h2 id=&quot;verify-before-you-assert&quot;&gt;Verify before you assert&lt;a href=&quot;https://caskeycoding.com/blog/surface-the-decision-dont-make-it#verify-before-you-assert&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The most dangerous advisor is the confident one that has not checked. So the scoreboard refuses fabrication: every statistic carries a sufficiency flag, and on a thin sample it prints a &quot;need about ten resolved&quot; notice instead of a clean-looking hit rate computed from two data points.&lt;/p&gt;
&lt;p&gt;I was making the identical move from the other chair an hour earlier. The assistant had added diagrams to a batch of posts, and the check I cared about was not &quot;did the build pass.&quot; A diagram renders at view time, so a green build proves nothing about whether readers see a picture or a broken box. The real check was to render each one and look at it, in both the light and dark themes, before trusting it.&lt;/p&gt;
&lt;h2 id=&quot;pilot-before-you-fan-out&quot;&gt;Pilot before you fan out&lt;a href=&quot;https://caskeycoding.com/blog/surface-the-decision-dont-make-it#pilot-before-you-fan-out&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The advisor surfaces one &quot;look at this,&quot; not a wall of forty flags. One question per ritual, one written answer. The restraint is the feature: a single forced decision at the moment it is cheap to make beats a dashboard that asks nothing of you and gets ignored.&lt;/p&gt;
&lt;p&gt;The same instinct ran the session. Before changing six posts I changed one, rendered it, and looked, and only then committed to the other five. Prove the pattern on a single case under real conditions before you spend the effort to repeat it. Whether you are an operator triaging a book or an agent editing a fleet of files, the cheap insurance is the same: one pilot before the fan-out.&lt;/p&gt;
&lt;h2 id=&quot;two-sides-of-the-same-rule&quot;&gt;Two sides of the same rule&lt;a href=&quot;https://caskeycoding.com/blog/surface-the-decision-dont-make-it#two-sides-of-the-same-rule&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The parallels line up cleanly:&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Building the advisor&lt;/th&gt;
&lt;th&gt;Being the one advised&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Surfaces the decision, never seizes it&lt;/td&gt;
&lt;td&gt;The reviewer comments, never holds the merge button&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Refuses to compute a stat on a thin sample&lt;/td&gt;
&lt;td&gt;I render and look before I trust a diagram&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;One &quot;look at this&quot; per ritual&lt;/td&gt;
&lt;td&gt;One pilot before fanning out to six&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Wording tests cover selected output regressions; permissions govern actions&lt;/td&gt;
&lt;td&gt;Review the available capabilities separately from the text&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;hr&gt;
&lt;p&gt;&lt;strong&gt;Related:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;https://caskeycoding.com/blog/i-dont-trust-my-own-findings&quot; class=&quot;internal-link&quot;&gt;I don&apos;t trust my own findings&lt;/a&gt;, the verify-before-you-believe half, from the skeptic&apos;s side&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://caskeycoding.com/blog/leverage-by-subtraction&quot; class=&quot;internal-link&quot;&gt;Leverage by subtraction&lt;/a&gt;, why the boundary belongs in a test and not a person&apos;s memory&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://caskeycoding.com/blog/autonomy-is-mostly-knowing-when-to-stop&quot; class=&quot;internal-link&quot;&gt;Autonomy is mostly knowing when to stop&lt;/a&gt;, the same restraint applied to an autonomous loop&lt;/li&gt;
&lt;/ul&gt;</content:encoded>
    </item>
    <item>
      <title>A live market workstation in one HTML file</title>
      <link>https://caskeycoding.com/blog/a-market-workstation-in-one-file</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/a-market-workstation-in-one-file</guid>
      <pubDate>Sat, 04 Jul 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>finance</category>
      <category>visualization</category>
      <category>dataviz</category>
      <category>JavaScript</category>
      <category>canvas</category>
      <category>side-projects</category>
      <description>A screensaver joke, every stock a fish, grew into a six-lens market board I leave running on a wall. It lives in one HTML file on purpose, its data is baked because the browser is not allowed to fetch it, and the feature that finally made it work on a phone is the URL itself.</description>
      <content:encoded>&lt;p&gt;It started as a screensaver joke. I publish a ranked stock board, the public output of a private engine that grades stocks every night, and one evening I fed it into an aquarium: every stock a fish, sized by its composite score (the engine&apos;s one-number grade), swimming faster the more it moved that day. Green fish drifting, red fish darting. Completely useless, and I loved it, because it made a point no table ever had: the board has body language. A calm market looks calm. A rotation looks like schools of fish changing direction.&lt;/p&gt;
&lt;p&gt;The joke kept earning screen time, so I rebuilt it into the display I now actually leave running on a wall: &lt;a href=&quot;https://caskeycoding.com/lab/market-apex&quot; class=&quot;internal-link&quot;&gt;Market APEX&lt;/a&gt;, six views over the same public board data. Three decisions ended up carrying the whole build, and they are the ones worth writing down. The app lives in a single HTML file on purpose. Nothing is fetched live, because the browser is not allowed to fetch it. And the feature that finally made it work on a phone is the URL itself.&lt;/p&gt;
&lt;h2 id=&quot;six-lenses-one-canvas&quot;&gt;Six lenses, one canvas&lt;a href=&quot;https://caskeycoding.com/blog/a-market-workstation-in-one-file#six-lenses-one-canvas&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Lens&lt;/th&gt;
&lt;th&gt;What you are looking at&lt;/th&gt;
&lt;th&gt;When to open it&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;TAPE&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;the trading year replayed as a fifteen-second race of cumulative returns&lt;/td&gt;
&lt;td&gt;to feel who actually led the year, not just who ended ahead&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;FIELD&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;valuation against momentum, the cheap-and-rising corner marked as the kill zone&lt;/td&gt;
&lt;td&gt;to hunt names getting better while still unloved&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;PLOT&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;any factor against any factor, sized by a third&lt;/td&gt;
&lt;td&gt;when you have a hypothesis the fixed views will not hold&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;WEB&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;a force graph where stocks pull together by correlation (how much they move together)&lt;/td&gt;
&lt;td&gt;to watch sectors clump, and to spot what moves alone&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;GRID&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;every factor for every name, a sortable heatmap&lt;/td&gt;
&lt;td&gt;when you want the spreadsheet after all&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;MAP&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;a sector treemap colored by the year&apos;s return&lt;/td&gt;
&lt;td&gt;one glance at where the year&apos;s money went&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;All six are a click apart on &lt;a href=&quot;https://caskeycoding.com/lab/market-apex&quot; class=&quot;internal-link&quot;&gt;the live board&lt;/a&gt;.&lt;/p&gt;
&lt;p&gt;TAPE is the one people stop for. Sixty-some lines sweep left to right as the year replays, leaders pulling away, the worst name labeled in red at the back of the pack. The work is in the axis: a gold miner up 400% and a laggard down 50% have to share one readable scale, so returns pass through a signed square root before they become pixels. The race stays legible at both ends without lying about either.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/apex-tape-race.webp&quot; alt=&quot;The TAPE lens: dozens of cumulative-return lines racing left to right across the year, the leader labeled at the front and the worst name in red at the back, with the kill list and sector rotation panels alongside&quot;&gt;
&lt;em&gt;TAPE mid-replay: the year as a race, the leader labeled at the front, the worst name in red at the back.&lt;/em&gt;&lt;/p&gt;
&lt;p&gt;All of it is one &lt;code class=&quot;inline-code&quot;&gt;&amp;#x3C;canvas&gt;&lt;/code&gt; and a &lt;code class=&quot;inline-code&quot;&gt;requestAnimationFrame&lt;/code&gt; loop, under six hundred lines, no chart library. At this size a library mostly adds indirection, and the parts that make the board feel alive, the axis compression, the force layout clumping correlated names, the autopilot that dwells on one stock and narrates it, are exactly the parts I would be fighting a library to control.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/apex-field-killzone.webp&quot; alt=&quot;The FIELD lens: valuation against momentum as glowing dots, the cheap-and-rising corner boxed as the kill zone, with an autopilot card narrating one name&amp;#x27;s scores&quot;&gt;
&lt;em&gt;FIELD, with the cheap-and-rising corner boxed as the kill zone, and the autopilot dwelling on one name and narrating it.&lt;/em&gt;&lt;/p&gt;
&lt;h2 id=&quot;one-file-on-purpose&quot;&gt;One file, on purpose&lt;a href=&quot;https://caskeycoding.com/blog/a-market-workstation-in-one-file#one-file-on-purpose&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The app styles &lt;code class=&quot;inline-code&quot;&gt;body&lt;/code&gt;, defines its own buttons, hides scrollbars. It behaves like it owns the page, because on the wall it does. Dropping that into a Next.js site would mean scoping hundreds of selectors or watching the board&apos;s styles bleed into the site chrome, so the site embeds it as a same-origin iframe instead. That iframe is a contract: everything inside the file is the app&apos;s business, everything outside is the site&apos;s. Three rounds of feature work later, the boundary has not leaked once.&lt;/p&gt;
&lt;p&gt;A smaller example is the &lt;a href=&quot;https://caskeycoding.com/blog/eight-minute-french-flashcards&quot; class=&quot;internal-link&quot;&gt;French flashcard app built in one HTML file&lt;/a&gt;: its browser-local progress removes account setup but does not sync between devices.&lt;/p&gt;
&lt;p&gt;The build left one scar worth showing. The first shipped version had a first-frame race: the animation loop started before the data arrived, the draw call threw on an empty array, and because the next frame was scheduled &lt;em&gt;after&lt;/em&gt; the draw, one exception ended the animation forever. A black rectangle, no visible errors, perfectly good data underneath. The fix is two lines, re-register the frame first, then guard the empty state. The rule it taught generalizes: in an animation loop, schedule the next frame before you do anything that can throw, or your loop has exactly one bug&apos;s worth of lifespan.&lt;/p&gt;
&lt;h2 id=&quot;baked-not-fetched&quot;&gt;Baked, not fetched&lt;a href=&quot;https://caskeycoding.com/blog/a-market-workstation-in-one-file#baked-not-fetched&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The board wants a year of daily closes for every name it draws. A page running in your browser cannot simply ask a market data service for that history; browsers enforce cross-origin rules, and quote APIs refuse requests arriving from strangers&apos; web pages. And I was not going to stand up a proxy relaying a market feed for a toy.&lt;/p&gt;
&lt;p&gt;So nothing is fetched live. A small job runs once a day and bakes one JSON file: factor scores from the already-published board, a year of closes per symbol compressed into a 24-point sparkline, the day, week, and year moves precomputed. One static file behind the CDN, cached for fifteen minutes, reloaded quietly in the background while the board runs.&lt;/p&gt;
&lt;p&gt;Everything else is derived on arrival. The regime banner (market breadth, meaning how many names are up on the year, plus median momentum), the hunt-list ranking, and the full pairwise correlation matrix behind WEB all get computed client-side from that one file. The matrix sounds expensive and is not: ninety names by 24 points is a few milliseconds on load. Bake what the browser cannot reach; compute what it can. The bundle stays small, and the client stays free to grow new lenses without touching the pipeline.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/apex-map-treemap.webp&quot; alt=&quot;The MAP lens: a sector treemap of the whole board, cells sized by column and colored green or red by the year&amp;#x27;s return&quot;&gt;
&lt;em&gt;MAP: the year&apos;s money by sector, every cell derived on arrival from the same single baked file.&lt;/em&gt;&lt;/p&gt;
&lt;h2 id=&quot;the-url-is-the-feature&quot;&gt;The URL is the feature&lt;a href=&quot;https://caskeycoding.com/blog/a-market-workstation-in-one-file#the-url-is-the-feature&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;On the wall, density is the point: sixty names racing, hover tooltips, six lenses a click apart. On a phone, density is the enemy. So the mobile version inverts the desktop one: pick first, then look. A chip picker sits above the stage, you tap in a ticker, and TAPE races just that name, with a card showing its price, moves, and factor scores. Add more and they overlay as a comparison race, each line labeled, the axis rescaled to whatever you picked.&lt;/p&gt;
&lt;p&gt;Selection is state, and state that small belongs in the URL. &lt;a href=&quot;https://caskeycoding.com/lab/market-apex?symbols=NVDA,MSFT&quot; class=&quot;internal-link&quot;&gt;&lt;code class=&quot;inline-code&quot;&gt;/play/market-apex?symbols=NVDA,MSFT&lt;/code&gt;&lt;/a&gt; opens the board mid-comparison, and every chip you add or remove is written back with &lt;code class=&quot;inline-code&quot;&gt;history.replaceState&lt;/code&gt;, so the address bar is always a shareable snapshot of exactly what you are looking at.&lt;/p&gt;
&lt;p&gt;One implementation detail pleased me out of proportion. The app runs inside that same-origin iframe, and the query string arrives on the parent page&apos;s URL, not the iframe&apos;s. The obvious fix was to teach the site&apos;s route to forward its query string down into the iframe. The better fix was to teach the app it might be embedded: when its own URL carries no symbols it reads the parent page&apos;s (same origin, so the browser permits it), and when your selection changes it syncs both URLs. The site&apos;s route component did not change by a single character. A same-origin iframe is a styling boundary, not an information boundary, and you can lean on that.&lt;/p&gt;
&lt;p&gt;My private alarm engine attaches a link to every critical push, so a stop alert on my phone opens directly into that ticker&apos;s year. A private daily digest builds a multi-ticker link the same way and gets a comparison race. As with my &lt;a href=&quot;https://caskeycoding.com/blog/markets-in-three-dimensions&quot; class=&quot;internal-link&quot;&gt;3D surfaces&lt;/a&gt;, the published bundle contains public board data, without private portfolio records. The selected symbols travel separately in the URL. That selection is shareable state and may reveal an interest in a name; it can also appear in browser history or request logs. &lt;a href=&quot;https://community.owasp.org/vulnerabilities/Information_exposure_through_query_strings_in_url&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;URL parameters are not a confidentiality boundary&lt;/a&gt;. Account details, position sizes, and other sensitive values do not belong in those links.&lt;/p&gt;
&lt;p&gt;That seam forced the last design call. The curated board is about ninety names, the engine&apos;s picks plus a watch set built from public, neutral rules (megacaps, plus the most-watched tickers by public attention data). But a deep link should resolve wider than ninety names, so the daily bake ships a second tier: every remaining name from the public attention panel, about 250 symbols in all, in the same record shape. The lenses never draw the second tier, which keeps the wall display curated, but the picker resolves from both. A name without factor coverage still resolves as a price-only card that says so, and a symbol the bundle has never heard of gets a dashed &quot;not tracked&quot; chip instead of silently vanishing.&lt;/p&gt;
&lt;h2 id=&quot;text-yourself-a-market&quot;&gt;Text yourself a market&lt;a href=&quot;https://caskeycoding.com/blog/a-market-workstation-in-one-file#text-yourself-a-market&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The board is a shareable snapshot rather than a live terminal. It shows what last night&apos;s bake included and nothing it has never heard of, which is the price of never letting the browser fetch. What you get back is a market you can send someone: &lt;a href=&quot;https://caskeycoding.com/lab/market-apex?symbols=NVDA,MSFT&quot; class=&quot;internal-link&quot;&gt;bring your own tickers&lt;/a&gt; and race them.&lt;/p&gt;
&lt;hr&gt;
&lt;p&gt;&lt;strong&gt;Related:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;https://caskeycoding.com/blog/markets-in-three-dimensions&quot; class=&quot;internal-link&quot;&gt;Rotating an Option&lt;/a&gt;, the 3D siblings in the playground, and the source of the math/render seam this board borrows&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://caskeycoding.com/blog/cloudwatch-for-a-portfolio&quot; class=&quot;internal-link&quot;&gt;CloudWatch for a Portfolio&lt;/a&gt;, the alarm engine whose pushes now deep-link into this board&lt;/li&gt;
&lt;/ul&gt;</content:encoded>
    </item>
    <item>
      <title>A One-Day Security Baseline for a Solo Fleet</title>
      <link>https://caskeycoding.com/blog/a-one-day-security-baseline-for-a-solo-fleet</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/a-one-day-security-baseline-for-a-solo-fleet</guid>
      <pubDate>Fri, 03 Jul 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>platform</category>
      <category>security</category>
      <category>aws</category>
      <category>infrastructure</category>
      <category>solo-development</category>
      <category>operations</category>
      <description>You cannot out-staff a security team when you are the whole team. But the failures that actually end a solo operation are a short, known list, and each has a cheap defense you set up once. Here is the catastrophic floor I stood up in an afternoon.</description>
      <content:encoded>&lt;p&gt;When you run production by yourself, security advice written for companies is mostly noise. It assumes a team to watch dashboards, a budget for tooling, a compliance regime to satisfy. I have none of those, and neither does anyone else operating a small fleet alone. So the question is not &quot;how do I build a security program.&quot; It is &quot;what is the smallest set of controls that stops the failures that would actually end me,&quot; and the answer is that it fits in an afternoon.&lt;/p&gt;
&lt;p&gt;Two principles run under the whole afternoon. The threats that realistically kill a solo operation are a short, boring list with cheap, set-once defenses, so the goal is a catastrophic floor, not coverage. And the highest-leverage controls run themselves: log everything, alarm on the catastrophes, and make the irreversible mistakes structurally hard, because anything that depends on you watching fails the day you are not watching.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/a-one-day-security-baseline-for-a-solo-fleet-floor.svg&quot; alt=&quot;A thick floor line held up by eight green set-once controls, with the three catastrophic failures below it in red and survivable failure above it.&quot;&gt;&lt;/p&gt;
&lt;h2 id=&quot;the-real-threat-model-is-boring&quot;&gt;The real threat model is boring&lt;a href=&quot;https://caskeycoding.com/blog/a-one-day-security-baseline-for-a-solo-fleet#the-real-threat-model-is-boring&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Start with what actually goes wrong for a one-person operation. The real list is mundane:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;A secret (an API key, a token) pasted into a repo and pushed.&lt;/li&gt;
&lt;li&gt;A credential that leaks and gets used to run up a bill or poke at your resources.&lt;/li&gt;
&lt;li&gt;A cost that runs away, from a mistake or a compromise, while you are asleep.&lt;/li&gt;
&lt;li&gt;A destructive git accident: a force-push that erases a main branch&apos;s history.&lt;/li&gt;
&lt;li&gt;A dependency with a known vulnerability sitting in your build.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;None of these require a movie villain. They are the accidents that happen to careful people on ordinary days. And every one of them is cheap to defend against, which is the whole opportunity: a small operation cannot afford a security team, but it does not need one to handle this list.&lt;/p&gt;
&lt;p&gt;There is one way a solo operator is more exposed than a team, and it shapes the whole approach. On a team, a second person reviews the change and sometimes catches the secret in the diff, the over-broad permission, the bucket left open. Alone, that second pair of eyes does not exist. So the automated controls below are the substitute for the review redundancy a team gets for free. The machine has to be the colleague who catches the mistake, because there is no colleague.&lt;/p&gt;
&lt;h2 id=&quot;the-baseline-set-up-once&quot;&gt;The baseline, set up once&lt;a href=&quot;https://caskeycoding.com/blog/a-one-day-security-baseline-for-a-solo-fleet#the-baseline-set-up-once&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Here is what I stood up, what each piece defends, and whether it prevents a problem or just makes sure I find out fast.&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Control&lt;/th&gt;
&lt;th&gt;What it defends against&lt;/th&gt;
&lt;th&gt;Prevent or detect&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;CloudTrail logging across the account&lt;/td&gt;
&lt;td&gt;&quot;What happened, and when&quot; after anything odd&lt;/td&gt;
&lt;td&gt;Detect&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;GuardDuty threat detection on that trail&lt;/td&gt;
&lt;td&gt;Credential misuse, unusual API patterns&lt;/td&gt;
&lt;td&gt;Detect&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;IAM Access Analyzer&lt;/td&gt;
&lt;td&gt;A resource accidentally open to the world&lt;/td&gt;
&lt;td&gt;Detect&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;An AWS Budgets alarm, set low&lt;/td&gt;
&lt;td&gt;Cost crossing a threshold in delayed billing data&lt;/td&gt;
&lt;td&gt;Detect, delayed&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;GitHub secret scanning + push protection&lt;/td&gt;
&lt;td&gt;Supported secret patterns on covered push paths&lt;/td&gt;
&lt;td&gt;Detect; prevent supported pushes&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Dependabot alerts&lt;/td&gt;
&lt;td&gt;Known-bad packages in the build&lt;/td&gt;
&lt;td&gt;Detect&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Branch protection on every repo&lt;/td&gt;
&lt;td&gt;Force-push or deletion of main history&lt;/td&gt;
&lt;td&gt;Prevent&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Scoped IAM identities for daily work&lt;/td&gt;
&lt;td&gt;Blast radius if one credential leaks&lt;/td&gt;
&lt;td&gt;Prevent, limit&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;That is the baseline I set up. Most of it is managed services you enable, alarms you point at your email, and protection rules you apply across repositories. My setup took an afternoon and cost a few dollars a month. Each control covers a specific failure mode, with limits that matter when you rely on it.&lt;/p&gt;
&lt;h2 id=&quot;two-principles-do-the-heavy-lifting&quot;&gt;Two principles do the heavy lifting&lt;a href=&quot;https://caskeycoding.com/blog/a-one-day-security-baseline-for-a-solo-fleet#two-principles-do-the-heavy-lifting&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The specific services matter less than the two ideas underneath them, because those ideas tell you what to reach for next as the fleet grows.&lt;/p&gt;
&lt;p&gt;The first is detection where prevention is incomplete. Alerts can shorten the time between a failure and my response, but they do not guarantee detection within minutes. &lt;a href=&quot;https://docs.aws.amazon.com/cost-management/latest/userguide/budgets-managing-costs.html&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;AWS Budgets typically refreshes every eight to twelve hours&lt;/a&gt;, and billing delays can let costs exceed a threshold before notification. A low budget alarm helps me notice spend; it neither caps the bill nor stops a compromised key.&lt;/p&gt;
&lt;p&gt;The second is structural controls for mistakes that are hard to reverse. Branch protection can reject force-pushes and deletion on covered branches, subject to its configured bypass permissions. GitHub push protection blocks &lt;a href=&quot;https://docs.github.com/en/code-security/reference/secret-security/supported-secret-scanning-patterns&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;supported secret patterns and token versions&lt;/a&gt;; availability depends on repository settings and plan, and permitted bypasses still need attention. Unsupported or obfuscated values can escape detection, so review and scanning remain useful. Scoped identities limit which actions a leaked credential can take.&lt;/p&gt;
&lt;h2 id=&quot;what-this-is-not&quot;&gt;What this is not&lt;a href=&quot;https://caskeycoding.com/blog/a-one-day-security-baseline-for-a-solo-fleet#what-this-is-not&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;This baseline is detection and blast-radius control. It will not stop a determined, targeted attacker who wants specifically you. There is no continuous monitoring, no penetration testing, no compliance posture. For a personal fleet that is the correct scope: a month spent building those would be effort stolen from the actual product to defend against threats I do not face.&lt;/p&gt;
&lt;p&gt;There is one piece of discipline the automation cannot replace, and it is the easy one to skip: test that the alerts actually reach you. The afternoon is not done when the services are enabled. It is done when you have watched a test alert actually land in your inbox, and rotated any credentials you minted along the way so none of them outlive the setup that needed them.&lt;/p&gt;
&lt;hr&gt;
&lt;p&gt;&lt;strong&gt;Related:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;https://caskeycoding.com/blog/when-ci-costs-more-than-it-saves&quot; class=&quot;internal-link&quot;&gt;When CI costs more than it saves&lt;/a&gt;, the budget-first instinct applied to CI&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://caskeycoding.com/blog/institutional-memory-for-a-team-of-one&quot; class=&quot;internal-link&quot;&gt;Institutional memory for a team of one&lt;/a&gt;, the same operate-alone-reliably theme&lt;/li&gt;
&lt;/ul&gt;</content:encoded>
    </item>
    <item>
      <title>CloudWatch for a Portfolio</title>
      <link>https://caskeycoding.com/blog/cloudwatch-for-a-portfolio</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/cloudwatch-for-a-portfolio</guid>
      <pubDate>Thu, 02 Jul 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>finance</category>
      <category>alarms</category>
      <category>signals</category>
      <category>claude-code</category>
      <category>decision-support</category>
      <description>I stopped staring at market dashboards. A set of alarms now watches a dozen signal dimensions across the market and taps me on the shoulder only when something actually needs a decision.</description>
      <content:encoded>&lt;p&gt;I run a private finance engine that &lt;a href=&quot;https://caskeycoding.com/finance&quot; class=&quot;internal-link&quot;&gt;grades stocks&lt;/a&gt; and gathers a wall of market signals every night: insider buying, short volume, options skew, crowd attention, analyst drift, and more. For a long time it had one weakness no amount of better data could fix. It never told me when to look. I had to remember to open it, and then do the reading myself.&lt;/p&gt;
&lt;p&gt;So I gave it alarms, the way you would alarm a server with CloudWatch.&lt;/p&gt;
&lt;p&gt;A &lt;a href=&quot;https://caskeycoding.com/blog/welcome-building-platforms-for-scale&quot; class=&quot;internal-link&quot;&gt;monitoring rollout that paged a whole support queue&lt;/a&gt; is the caution on the other side: the alerting system has a blast radius of its own.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/cloudwatch-for-a-portfolio-inversion.svg&quot; alt=&quot;A pair of boxes, me and the market holding a dozen alarmed signals, with the direction of watching flipped between them: a faint arc over the top shows before, when I go look, and a green arc underneath shows after, when the market taps my shoulder, widened from my holdings to the whole index.&quot;&gt;&lt;/p&gt;
&lt;h2 id=&quot;the-shoulder-tap-that-replaced-the-dashboard&quot;&gt;The shoulder-tap that replaced the dashboard&lt;a href=&quot;https://caskeycoding.com/blog/cloudwatch-for-a-portfolio#the-shoulder-tap-that-replaced-the-dashboard&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;A dashboard asks something of you every single day. You have to remember it exists, open it, and then do the reading. An alarm is the inversion. It asks nothing until it has something to say.&lt;/p&gt;
&lt;p&gt;My morning used to be a scan of numbers. Now it is a short list with two columns: what needs a decision right now, and what is approaching one. Most days the list is nearly empty, and that emptiness is itself the signal. Nothing crossed a line, so there is nothing to do.&lt;/p&gt;
&lt;p&gt;The screen ranks everything on one scale: how close each signal is to firing, where the top of the bar means it just crossed. So a sentiment crack halfway to its trigger sits visibly below an insider cluster that fired this morning, on the same axis, even though one is a score and the other is a count of events. Triage that used to take a careful read now takes a glance.&lt;/p&gt;
&lt;h2 id=&quot;signals-that-reward-noticing-early&quot;&gt;Signals That Reward Noticing Early&lt;a href=&quot;https://caskeycoding.com/blog/cloudwatch-for-a-portfolio#signals-that-reward-noticing-early&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The alarms cover about a dozen signal dimensions, each chosen because it rewards noticing early and punishes noticing late:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;The engine&apos;s own grade&lt;/strong&gt;, which alarms when a name&apos;s composite score breaks down sharply over a week or sinks under a floor.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Insider buying&lt;/strong&gt;, which fires when a cluster of insider purchases lands inside a short window, the classic &quot;people who know the company are buying&quot; tell.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Activist filings&lt;/strong&gt;, when a 13D shows up and someone is taking a fight position.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Short-sale volume&lt;/strong&gt;, when reported activity rises above its own recent baseline. This is a volume anomaly; it does not by itself establish bearish positioning or an increase in open short interest. &lt;a href=&quot;https://www.finra.org/rules-guidance/notices/information-notice-051019&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;FINRA explains&lt;/a&gt; that customer-order facilitation can produce short prints with offsetting purchases absent from the same file, and its off-exchange files do not represent the whole market.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Crowd attention and social sentiment&lt;/strong&gt;, when a name lights up in retail chatter or its sentiment flips negative.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Options skew&lt;/strong&gt;, when the options market tilts hard enough to say traders are paying up for one direction.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Analyst drift, earnings proximity, prediction markets, and the macro regime&lt;/strong&gt;, the slower context signals that change the backdrop a decision sits in.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;My own risk lines&lt;/strong&gt;, the position-level guards: a stop getting close, a thesis going stale, a position sized out of line with its conviction.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The one I am fondest of is a compound alarm I call the screaming buy. It stays silent unless the grade is jumping and insiders are buying in the same window. Those are two inputs worth examining together; the combination has not established a trading edge or statistical independence. The alarm spends my attention when both are true.&lt;/p&gt;
&lt;p&gt;Each alert links straight through to the deep read on that name, so the tap leads to a decision rather than to more homework. The feature is the shortened path from &quot;something moved&quot; to &quot;here is what I am going to do about it.&quot;&lt;/p&gt;
&lt;h2 id=&quot;from-watching-what-i-own-to-finding-what-i-should&quot;&gt;From watching what I own to finding what I should&lt;a href=&quot;https://caskeycoding.com/blog/cloudwatch-for-a-portfolio#from-watching-what-i-own-to-finding-what-i-should&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;At first the alarms only watched the names the engine actively ranks, a working set of a hundred or so, most of them already on my radar. That is useful for managing what I hold, but it misses the more valuable job. The best buy setups are usually in names I do not own yet, the ones I am not already watching precisely because I have no position to remind me. So I widened the watch to the whole large-cap field, roughly the S&amp;#x26;P 500.&lt;/p&gt;
&lt;p&gt;Widening did not happen all at once, and the reason turns out to be the most useful part of the build. The signals split into two kinds. The fast ones, the grade, options positioning, short volume, and crowd attention, make one quick call per name, so I could point them at the entire field right away, and they watch all of it every night now. The others, insider filings and social sentiment, are rate-limited at the source: a regulator&apos;s filing archive and a social feed each cap how fast anyone can pull from them. Trying to drag the whole market through that straw in a single nightly run blew past AWS Lambda&apos;s hard ceiling of 900 seconds per run, and no setting can lift that ceiling.&lt;/p&gt;
&lt;p&gt;The tempting fix is fan-out, splitting the work across parallel functions, but that only helps when the wall is round-trip latency. Against a shared rate ceiling the parallel callers just share the one budget, so more machines buy nothing. The real answer is rotation: refresh a slice of the market each day and let the full set come around over a short cycle. So the fast signals already watch the whole field, and the slower insider and sentiment reads still center on the core board I rank while I roll that rotation out. That direction is what changed the question the system answers, from &quot;is anything wrong with what I hold&quot; to &quot;where in the market is something worth a closer look,&quot; and each collector that finishes widening pushes the reach a little further.&lt;/p&gt;
&lt;h2 id=&quot;the-failure-mode-i-watch-for&quot;&gt;The failure mode I watch for&lt;a href=&quot;https://caskeycoding.com/blog/cloudwatch-for-a-portfolio#the-failure-mode-i-watch-for&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Silence is the state I cannot fully trust. A quiet screen means nothing crossed a line, but it looks identical to a collector that died overnight, so the rotation that widened the reach now has to prove it actually ran. An alarm you never see fire is the one to trust least.&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>Institutional Memory for a Team of One</title>
      <link>https://caskeycoding.com/blog/institutional-memory-for-a-team-of-one</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/institutional-memory-for-a-team-of-one</guid>
      <pubDate>Thu, 02 Jul 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>methodology</category>
      <category>knowledge-management</category>
      <category>ai-engineering</category>
      <category>solo-development</category>
      <category>operations</category>
      <description>A team holds its hard-won knowledge across many heads. A solo operator holds it in one, and that one forgets. The fix is to externalize memory into structured records the tools read by default, so the system remembers what the person cannot.</description>
      <content:encoded>&lt;p&gt;My scaling problem is memory. I run several products by myself, and what breaks first is me forgetting why I did something, what already burned me, and what is half-finished in a corner I have not looked at in three weeks. A team survives this because the knowledge is spread across many heads and someone remembers. A team of one has no such redundancy. When I forget, it is simply gone.&lt;/p&gt;
&lt;p&gt;So the most valuable infrastructure I have built sits underneath all my products, not inside any one of them: a memory layer, a set of structured records that hold what I would otherwise have to keep in my head, written so the tools consult them automatically instead of relying on me to recall.&lt;/p&gt;
&lt;p&gt;Underneath it sit two ideas. Forgetting is the binding constraint for a solo operator: the institutional memory a team carries in its people has to live somewhere outside your one unreliable head, or it does not exist. And externalized memory only works if it is consulted by default rather than remembered: layered records, each with a single job, loaded automatically by the tools that do the work.&lt;/p&gt;
&lt;h2 id=&quot;what-forgetting-costs&quot;&gt;What forgetting costs&lt;a href=&quot;https://caskeycoding.com/blog/institutional-memory-for-a-team-of-one#what-forgetting-costs&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Watch what a single forgotten fact costs. You re-make a decision you already made carefully, because the reasoning evaporated and only the conclusion remained, and now you are not sure you trust the conclusion. You re-break something that already burned you once, because the lesson lived in your memory and your memory moved on. You re-derive context (the why behind a config, the shape of a half-built feature) that you already paid to build and then lost.&lt;/p&gt;
&lt;p&gt;None of these are dramatic. They are a slow tax, a few percent off everything, forever. On a team the tax is smaller because the knowledge is redundant: the person who made the decision is still around, or wrote it in a channel, or sits next to whoever needs it. Alone, every fact you hold is a single point of failure, and the failure is silent. You do not notice the memory you lost. You only notice the work you redid.&lt;/p&gt;
&lt;h2 id=&quot;memory-in-layers-each-with-one-job&quot;&gt;Memory in layers, each with one job&lt;a href=&quot;https://caskeycoding.com/blog/institutional-memory-for-a-team-of-one#memory-in-layers-each-with-one-job&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The fix is not one big document. It is several kinds of record, each answering a different question, each written and read in a different way.&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Layer&lt;/th&gt;
&lt;th&gt;What it holds&lt;/th&gt;
&lt;th&gt;Written when&lt;/th&gt;
&lt;th&gt;Who reads it&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Operational lessons&lt;/td&gt;
&lt;td&gt;&quot;This bit us, here is the rule&quot;&lt;/td&gt;
&lt;td&gt;The moment an incident happens&lt;/td&gt;
&lt;td&gt;Every future change, before deploy&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Decision records&lt;/td&gt;
&lt;td&gt;Why, not just what&lt;/td&gt;
&lt;td&gt;Before the code, as a spec or ADR&lt;/td&gt;
&lt;td&gt;Anyone who questions the choice later&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Project memory&lt;/td&gt;
&lt;td&gt;What is in flight, goals, constraints&lt;/td&gt;
&lt;td&gt;When state changes&lt;/td&gt;
&lt;td&gt;The next session, picking up cold&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Preferences&lt;/td&gt;
&lt;td&gt;How the work should be done&lt;/td&gt;
&lt;td&gt;When a correction lands&lt;/td&gt;
&lt;td&gt;Every task, as standing rules&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Per-repo manual&lt;/td&gt;
&lt;td&gt;How this specific system operates&lt;/td&gt;
&lt;td&gt;As the system evolves&lt;/td&gt;
&lt;td&gt;Anyone, or any agent, touching the repo&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;The separation matters. A lesson is append-only and numbered, because you never want to lose one and you want to cite it. A decision record is reasoning-first, because the conclusion is the cheap part and the why is what you actually lose. Project memory is disposable and current, a snapshot you overwrite, because stale state is worse than none. Preferences are short and absolute. Smashing all of these into one file produces something nobody reads, which is the same as having no memory at all.&lt;/p&gt;
&lt;h2 id=&quot;the-trick-is-automatic-consultation&quot;&gt;The trick is automatic consultation&lt;a href=&quot;https://caskeycoding.com/blog/institutional-memory-for-a-team-of-one#the-trick-is-automatic-consultation&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Externalized memory you have to remember to read is just a diary. It does not change anything, because I wrote the lessons down and still forgot to look, and a diary depends on remembering to look.&lt;/p&gt;
&lt;p&gt;The useful change is memory the tools load without my asking: an index at session start, operational lessons before a deploy, and a per-repo manual beside the code. That makes a rule available before the agent acts. It does not enforce the rule. Claude Code&apos;s &lt;a href=&quot;https://code.claude.com/docs/en/memory&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;memory documentation&lt;/a&gt; makes the same distinction: instruction files supply context; a required restriction needs a separate check or permission boundary. I still need evidence that the files loaded and that any enforcement actually ran.&lt;/p&gt;
&lt;p&gt;&lt;em&gt;This post includes a diagram. &lt;a href=&quot;https://caskeycoding.com/blog/institutional-memory-for-a-team-of-one&quot;&gt;View it on caskeycoding.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;
&lt;h2 id=&quot;the-discipline-that-keeps-it-honest&quot;&gt;The discipline that keeps it honest&lt;a href=&quot;https://caskeycoding.com/blog/institutional-memory-for-a-team-of-one#the-discipline-that-keeps-it-honest&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;A memory layer is only as good as its hygiene, and there are a few rules I had to learn the hard way. Write at the moment of the lesson; it is nearly free then and expensive to reconstruct a month later from a vague sense that something went wrong. Keep it findable: an index, one fact per file, a hook you can scan, so retrieval is cheap enough to actually happen. Convert relative dates to absolute, because &quot;last week&quot; rots the instant you write it. Do not store what the code or the git history already records; that duplication drifts out of sync and earns distrust. And prune ruthlessly. A confidently wrong memory is worse than a blank one, because it does not just fail to help, it actively misleads the next decision.&lt;/p&gt;
&lt;p&gt;That last rule keeps old records from becoming instructions for a changed system. A dated decision can save me from reconstructing its reasoning. A claim about current permissions, deployment state or an unfinished task still needs checking before I rely on it.&lt;/p&gt;
&lt;h2 id=&quot;a-system-that-remembers-for-me&quot;&gt;A system that remembers for me&lt;a href=&quot;https://caskeycoding.com/blog/institutional-memory-for-a-team-of-one#a-system-that-remembers-for-me&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Forgetting is what actually caps a team of one, and the answer was external records: layered so each kind does one job, consulted automatically by the tools rather than recalled by me, because recall is the exact faculty that failed. I built a system that remembers for me, and then I learned to trust it. That trust is the uncomfortable part. A record I act on without re-checking is useful right up until it goes stale, and then it misleads me with the same authority it earned. The system holds only as long as the pruning does. I did not get better at remembering. I got ruthless about deleting what I could no longer trust.&lt;/p&gt;
&lt;hr&gt;
&lt;p&gt;&lt;strong&gt;Related:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;https://caskeycoding.com/blog/leverage-by-subtraction&quot; class=&quot;internal-link&quot;&gt;Leverage by subtraction&lt;/a&gt;, the tooling layer this memory feeds&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://caskeycoding.com/blog/i-dont-trust-my-own-findings&quot; class=&quot;internal-link&quot;&gt;I don&apos;t trust my own findings&lt;/a&gt;, the other half of operating alone reliably&lt;/li&gt;
&lt;/ul&gt;</content:encoded>
    </item>
    <item>
      <title>I Don&apos;t Trust My Own Findings</title>
      <link>https://caskeycoding.com/blog/i-dont-trust-my-own-findings</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/i-dont-trust-my-own-findings</guid>
      <pubDate>Wed, 01 Jul 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>methodology</category>
      <category>verification</category>
      <category>ai-engineering</category>
      <category>agents</category>
      <category>epistemics</category>
      <category>code-review</category>
      <description>The most dangerous result is the one you want to be true. Your own review is compromised by the same motivation that produced the finding, so the fix is a standing skeptic whose job is to refute, not confirm, before you act on anything.</description>
      <content:encoded>&lt;p&gt;The most dangerous result I produce is the one I was hoping for, a signal that looks predictive or a draft that looks safe to publish. I check it, and it passes my check, and that should worry me more than it does. Because I checked it the way someone hoping it was true would check it. The motivation that produced the finding also graded the exam.&lt;/p&gt;
&lt;p&gt;So I have stopped trusting my own findings, and turned that distrust into an operating procedure. Every claim my system makes, especially the ones I like, gets handed to an independent skeptic whose only job is to refute it before I am allowed to believe it.&lt;/p&gt;
&lt;p&gt;The case has two parts. First, self-review is structurally compromised: the reviewer and the author share a brain, a context, and a motive, so passing your own check is weak evidence. Second, the fix is to institutionalize the skeptic, an independent verifier, with the burden of proof flipped to refute-or-it-does-not-ship, run as a gate on every claim rather than a discipline you apply on the days you remember to be rigorous.&lt;/p&gt;
&lt;h2 id=&quot;the-failure-mode-is-motivated-reasoning&quot;&gt;The failure mode is motivated reasoning&lt;a href=&quot;https://caskeycoding.com/blog/i-dont-trust-my-own-findings#the-failure-mode-is-motivated-reasoning&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Here is the shape of the trap. You build something, you get a result that confirms what you set out to show, and you feel the small relief of being right. That relief is the bug. It is the exact moment your scrutiny relaxes, on the exact finding that most needs it. A result that contradicts you gets interrogated. A result that flatters you gets waved through. Your review budget is spent in inverse proportion to where it is needed.&lt;/p&gt;
&lt;p&gt;This is not a character flaw you can will away. It is how motivated reasoning works, and knowing about it does not switch it off. I have caught myself nodding at a number because it was the number I wanted, and the only reason I caught it is that something external made me look again.&lt;/p&gt;
&lt;h2 id=&quot;a-finding-i-wanted-to-be-true&quot;&gt;A finding I wanted to be true&lt;a href=&quot;https://caskeycoding.com/blog/i-dont-trust-my-own-findings#a-finding-i-wanted-to-be-true&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;My sharpest lesson came from a result that looked like real edge. A signal that, on the surface, appeared strongly predictive, a big, exciting number of exactly the kind you hope to see. The version of me that wanted it to be real had plenty of reasons ready.&lt;/p&gt;
&lt;p&gt;It was an artifact. The number came from a sample whose effective size was close to one, a handful of correlated names masquerading as a population. Adversarial review caught it before it changed a single decision: not by being smarter, but by starting from &quot;this is probably fake, prove otherwise&quot; instead of &quot;this looks great.&quot; The finding did not survive that question. I have written about the trading-specific version of this in &lt;a href=&quot;https://caskeycoding.com/blog/backtesting-without-fooling-yourself&quot; class=&quot;internal-link&quot;&gt;backtesting without fooling yourself&lt;/a&gt;; the general lesson is that a result you love deserves more suspicion, not less, and you are the worst-placed person to supply it.&lt;/p&gt;
&lt;h2 id=&quot;the-skeptic-runs-a-checklist-not-a-vibe&quot;&gt;The skeptic runs a checklist, not a vibe&lt;a href=&quot;https://caskeycoding.com/blog/i-dont-trust-my-own-findings#the-skeptic-runs-a-checklist-not-a-vibe&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The reason an external skeptic beats good intentions is that it can run a fixed interrogation that does not flex with your mood. For evidence that something &quot;works,&quot; there is a standard list of ways the claim is secretly lying, and a verifier checks every one regardless of how much you want the answer.&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;The claim you want to be true&lt;/th&gt;
&lt;th&gt;The self-deception hiding in it&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&quot;This signal predicts returns&quot;&lt;/td&gt;
&lt;td&gt;Survivorship, or look-ahead leaking future data into the past&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&quot;It works on the universe that matters&quot;&lt;/td&gt;
&lt;td&gt;Wrong universe: tested where it happens to win&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&quot;The result is significant&quot;&lt;/td&gt;
&lt;td&gt;Naive significance, ignoring how many you tried&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&quot;I found a real effect&quot;&lt;/td&gt;
&lt;td&gt;Forking paths: enough cuts and noise looks like signal&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&quot;It beats the benchmark&quot;&lt;/td&gt;
&lt;td&gt;Gross, not net: the edge dies after costs&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&quot;It will hold up&quot;&lt;/td&gt;
&lt;td&gt;No out-of-sample: never tested on data you did not touch&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;The skeptic does not get to skip a row because the finding is exciting, which is precisely the property your own judgment lacks at the moment of discovery.&lt;/p&gt;
&lt;h2 id=&quot;institutionalize-the-skeptic&quot;&gt;Institutionalize the skeptic&lt;a href=&quot;https://caskeycoding.com/blog/i-dont-trust-my-own-findings#institutionalize-the-skeptic&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;What turns this from a nice idea into a working method is making the skeptic a fixed part of the pipeline, not a burst of discipline you summon on good days. Across my system that takes a few concrete forms, and they share one design choice: the verifier is independent of what it checks.&lt;/p&gt;
&lt;p&gt;&lt;em&gt;This post includes a diagram. &lt;a href=&quot;https://caskeycoding.com/blog/i-dont-trust-my-own-findings&quot;&gt;View it on caskeycoding.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;
&lt;p&gt;A backtest result is not believed until a reviewer audits it against that list of sins. A code change is reviewed by an agent that did not write it. A draft is scanned for anything unpublishable by a checker that does not share the author&apos;s blind spot for what is sensitive. A deploy is checked against the traps that have burned past deploys before the button is pushed. None of these are steps I have to remember to run. They are gates the work passes through, and the burden of proof sits on the finding: survive the skeptic or you do not ship.&lt;/p&gt;
&lt;p&gt;Two details make the difference between real verification and theater. The first is the flipped default. A verifier told to &quot;evaluate this&quot; will tend to confirm. A verifier told to &quot;refute this, assume it is wrong until forced otherwise&quot; finds the holes, because it is now motivated in the opposite direction from you. The second is diversity over redundancy: three skeptics looking through the same lens just agree three times, but a correctness lens, a security lens, and a does-it-reproduce lens each catch failures the others are blind to. When a finding has to survive several different attempts to kill it, surviving starts to mean something.&lt;/p&gt;
&lt;p&gt;A valid blocking finding from one specialist needs resolution even when other reviewers pass. Unrelated approvals do not vote away a security or correctness defect.&lt;/p&gt;
&lt;p&gt;The deepest version is simply consulting something that does not share your context at all, a stronger reviewer that sees what you did but not why you wanted it to work. Half the time the value is not a correction. It is being made to look once more at the result I was already celebrating.&lt;/p&gt;
&lt;hr&gt;
&lt;p&gt;&lt;strong&gt;Related:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;https://caskeycoding.com/blog/backtesting-without-fooling-yourself&quot; class=&quot;internal-link&quot;&gt;Backtesting without fooling yourself&lt;/a&gt;, the trading-specific version of this discipline&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://caskeycoding.com/blog/leverage-by-subtraction&quot; class=&quot;internal-link&quot;&gt;Leverage by subtraction&lt;/a&gt;, where these verifier agents sit in the tooling&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://caskeycoding.com/blog/tell-me-everything-thats-wrong&quot; class=&quot;internal-link&quot;&gt;Tell me everything that&apos;s wrong&lt;/a&gt;, asking for the refutation directly&lt;/li&gt;
&lt;/ul&gt;</content:encoded>
    </item>
    <item>
      <title>Leverage by subtraction: keeping an AI agent fleet small enough to maintain</title>
      <link>https://caskeycoding.com/blog/leverage-by-subtraction</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/leverage-by-subtraction</guid>
      <pubDate>Mon, 29 Jun 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>methodology</category>
      <category>claude-code</category>
      <category>agents</category>
      <category>tooling</category>
      <category>ai-engineering</category>
      <category>automation</category>
      <description>The instinct with agentic tooling is to add: more agents, more skills, more clever prompts. The leverage runs the other way. Here is the test I use to decide whether a piece of work should be a script, a hook, a skill, or an agent, and why most of them should not be an agent at all.</description>
      <content:encoded>&lt;p&gt;The leverage in agentic tooling is in what you refuse to build. When you start building tooling around a coding agent, the default urge is to add. A new agent for code review. A skill for deploys. A clever prompt for that one recurring task. Each addition feels like progress, and within a month you have a drawer full of specialized tools, half of which you forget exist and the other half of which disagree with each other.&lt;/p&gt;
&lt;p&gt;I run four products and nine repositories as one person, and what has kept the tooling layer sane is a rule that points the opposite direction: leverage by subtraction. Build as few moving parts as possible, define the shared ones once, and specialize only where domain judgment differs.&lt;/p&gt;
&lt;p&gt;Restraint takes two forms. A test decides what a piece of work should even be, a script, a hook, a skill, or an agent, and it routes most work away from agents. And guardrails do not belong in agents a human has to remember to run. They belong in hooks and CI, where forgetting is not an option. The named agents that survive that second cut are a short list, and the shortness is the point.&lt;/p&gt;
&lt;h2 id=&quot;the-temptation-to-add&quot;&gt;The temptation to add&lt;a href=&quot;https://caskeycoding.com/blog/leverage-by-subtraction#the-temptation-to-add&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;An agent is the most expensive tool in the box. It costs tokens, it costs latency, and worst of all it costs determinism: the same input can produce different output, which is exactly what you do not want for anything you intend to rely on. Yet an agent is also the easiest tool to reach for, because writing a prompt feels faster than writing a script. That mismatch, most expensive to run but cheapest to author, is the trap. Reaching for an agent should feel like a decision, not a reflex.&lt;/p&gt;
&lt;h2 id=&quot;the-determinism-test&quot;&gt;The determinism test&lt;a href=&quot;https://caskeycoding.com/blog/leverage-by-subtraction#the-determinism-test&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;So before anything gets built, it goes through one question: how much judgment does this actually require? The answer routes the work down a ladder, and most of it lands lower than it first appears.&lt;/p&gt;
&lt;p&gt;&lt;em&gt;This post includes a diagram. &lt;a href=&quot;https://caskeycoding.com/blog/leverage-by-subtraction&quot;&gt;View it on caskeycoding.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;If the work is...&lt;/th&gt;
&lt;th&gt;Build a...&lt;/th&gt;
&lt;th&gt;Because&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Mechanical and deterministic&lt;/td&gt;
&lt;td&gt;Script&lt;/td&gt;
&lt;td&gt;Repeatable and testable, with no model-token charge. Correctness still depends on the code and inputs.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;A rule that must always hold&lt;/td&gt;
&lt;td&gt;Hook or CI check&lt;/td&gt;
&lt;td&gt;The machine refuses the bad state. Nobody has to remember.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;A fixed sequence with light judgment&lt;/td&gt;
&lt;td&gt;Skill&lt;/td&gt;
&lt;td&gt;Repeatable, but flexible enough for the small variations.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Open-ended judgment&lt;/td&gt;
&lt;td&gt;Agent&lt;/td&gt;
&lt;td&gt;The only tool that actually reasons. Reach for it last, not first.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Anything reaching a service or database&lt;/td&gt;
&lt;td&gt;CLI or MCP server&lt;/td&gt;
&lt;td&gt;A prompt-only skill cannot hold credentials or touch the network.&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;The test does real work because it keeps demoting candidates. Most of what feels like it wants to be an agent is actually a script with good error messages, or a hook you have not written yet. The &quot;code review agent&quot; I almost built is a good example: run the test and it falls apart into three jobs wearing one coat. The style checks are a linter, which is a script. The rule that a secret never reaches a diff is enforcement, which is a hook. Only the last part, the actual design-judgment call about whether the change is sound, was ever really an agent. Two of the three demoted themselves the moment I asked the question. Every rung you move down the ladder buys you speed, determinism, and one less moving part that can drift.&lt;/p&gt;
&lt;h2 id=&quot;default-to-the-general-agent&quot;&gt;Default to the general agent&lt;a href=&quot;https://caskeycoding.com/blog/leverage-by-subtraction#default-to-the-general-agent&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;There is a second subtraction underneath the first. Even once something needs a model&apos;s judgment, that does not mean it needs its own &lt;em&gt;named&lt;/em&gt; agent. A bespoke agent is a maintenance commitment: a prompt to keep current, a behavior to keep tested, a name to remember. The right default is the general-purpose agent, and you reach for a specialized one only when the same judgment-shaped task recurs often enough that defining it once pays for itself many times over. A named agent should earn its name by being used repeatedly, not by being theoretically tidy.&lt;/p&gt;
&lt;h2 id=&quot;guardrails-are-not-agents&quot;&gt;Guardrails are not agents&lt;a href=&quot;https://caskeycoding.com/blog/leverage-by-subtraction#guardrails-are-not-agents&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;A guardrail you have to remember to run is just a suggestion.&lt;/p&gt;
&lt;p&gt;If a rule must always hold, putting it inside an agent that a human invokes by hand is the wrong altitude. The day it matters most is the day someone is moving fast and skips it. So enforcement moves down into hooks and CI, where it runs whether or not anyone thought to ask. A pre-deploy check that blocks a bad stack, a hook that refuses a dirty deploy, a secret scan that fails the build: none of those should be a tool a human chooses to use. They should be the floor.&lt;/p&gt;
&lt;p&gt;This is the cleanest dividing line I have found. Judgment that informs a human decision can live in an agent. Enforcement that protects production cannot, because it has to survive human forgetfulness, and agents do not.&lt;/p&gt;
&lt;h2 id=&quot;the-agents-that-earned-their-place&quot;&gt;The agents that earned their place&lt;a href=&quot;https://caskeycoding.com/blog/leverage-by-subtraction#the-agents-that-earned-their-place&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;After all that subtraction, the named agents that remain are the ones that pass every cut: real open-ended judgment, recurring often, informing a decision rather than enforcing a rule. In my fleet that is a short, stable list. A spec-conformance reviewer that reads a diff against the spec it claims to implement. A disclosure auditor that scans a draft for anything that should not be published. A spec-writer that drafts a new spec in the right place. A stack reviewer that reads a CDK diff before deploy. A branch-hygiene sweeper. An incident recorder that appends a lesson to the right file when something breaks. Each one survives because it is doing something a script cannot and a human should not do by hand fifty times a week.&lt;/p&gt;
&lt;p&gt;What is striking is how few there are. Run the test across everything that felt like it wanted to be an agent, and the great majority resolve into scripts and hooks. The agents are the residue, the irreducible core of actual judgment, and keeping that core small is what keeps the whole layer trustworthy.&lt;/p&gt;
&lt;hr&gt;
&lt;p&gt;&lt;strong&gt;Related:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;https://caskeycoding.com/blog/spec-driven-development-and-the-folder-architecture-that-makes-it-work&quot; class=&quot;internal-link&quot;&gt;Spec-driven folder architecture&lt;/a&gt;, the structure this tooling operates on&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://caskeycoding.com/blog/autonomy-is-mostly-knowing-when-to-stop&quot; class=&quot;internal-link&quot;&gt;Autonomy is mostly knowing when to stop&lt;/a&gt;, the same restraint applied to the loop itself&lt;/li&gt;
&lt;/ul&gt;</content:encoded>
    </item>
    <item>
      <title>Splitting solo developer roles by time block, not by persona</title>
      <link>https://caskeycoding.com/blog/the-archetypes-split-by-time-not-person</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/the-archetypes-split-by-time-not-person</guid>
      <pubDate>Mon, 29 Jun 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>methodology</category>
      <category>claude-code</category>
      <category>agents</category>
      <category>solo-operator</category>
      <category>ai-engineering</category>
      <category>automation</category>
      <description>Boris Cherny mapped five execution archetypes on the Claude Code team, and noted they cut across job titles. His framework describes a team dividing labor across people. Run a fleet alone and the same five split a different way: across your calendar and across the agents you have built. Here is which ones I keep in my own hands, which I time-slice, and which I pushed down into machinery.</description>
      <content:encoded>&lt;p&gt;Boris Cherny, who leads Claude Code, posted a map of his team that I have not stopped thinking about. Looking at the people around him, he saw five execution archetypes:&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Archetype&lt;/th&gt;
&lt;th&gt;What they do&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Prototyper&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Generates new ideas; most never ship&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Builder&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Turns a prototype into production-grade product and infrastructure&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Sweeper&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Cleans up the UI, simplifies the system, unships&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Grower&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Iterates a shipped product toward product-market fit&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Maintainer&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Keeps a mature system secure, reliable, and fast as it scales&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;His sharpest point was that none of these are job titles. Some designers are Prototypers, some engineers are Sweepers. The old walls between engineering, product, design, and data science are melting, and the archetype is what sits underneath.&lt;/p&gt;
&lt;p&gt;But that map assumes a team. Five archetypes describes how a group divides one body of work, one person leaning Prototyper while another holds Maintainer. I run four products and nine repositories alone. There is no one to divide the five across. So the split has to land on two different axes, and that is where it gets interesting.&lt;/p&gt;
&lt;p&gt;A solo operator splits the five archetypes across &lt;strong&gt;time&lt;/strong&gt; and across &lt;strong&gt;agents&lt;/strong&gt;, not across people. You wear them in sequence, and you push the low-judgment ones down into deterministic machinery so they run without you. And exactly one of the five resists both moves. It cannot be time-sliced away and it cannot be automated.&lt;/p&gt;
&lt;h2 id=&quot;two-axes-a-team-never-needs&quot;&gt;Two axes a team never needs&lt;a href=&quot;https://caskeycoding.com/blog/the-archetypes-split-by-time-not-person#two-axes-a-team-never-needs&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;On a team, the five run in parallel because five people run them. Alone, they cannot. They redistribute along two axes instead.&lt;/p&gt;
&lt;p&gt;The first is &lt;strong&gt;time&lt;/strong&gt;. I am a Prototyper on Monday and a Maintainer on Thursday, and the skill is not doing all five at once but knowing which one the hour calls for and refusing the other four while it lasts.&lt;/p&gt;
&lt;p&gt;The second is &lt;strong&gt;machinery&lt;/strong&gt;. Some archetypes are mostly judgment, and judgment stays with me. Others are mostly detection and enforcement, and those drop down into scripts, hooks, scheduled jobs, and a few agents that run whether or not I show up. I sort each one with the same question from &lt;a href=&quot;https://caskeycoding.com/blog/leverage-by-subtraction&quot; class=&quot;internal-link&quot;&gt;leverage by subtraction&lt;/a&gt;: how much of this is open-ended judgment, and how much is discipline a machine holds better than I do?&lt;/p&gt;
&lt;p&gt;The answer sorts the five cleanly.&lt;/p&gt;
&lt;p&gt;&lt;em&gt;This post includes a diagram. &lt;a href=&quot;https://caskeycoding.com/blog/the-archetypes-split-by-time-not-person&quot;&gt;View it on caskeycoding.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;
&lt;p&gt;One stays fully in my hands, two are split with machinery, one falls almost entirely to machinery, and one refuses to move at all.&lt;/p&gt;
&lt;h2 id=&quot;prototyper-gate-everything-by-default&quot;&gt;Prototyper: gate everything by default&lt;a href=&quot;https://caskeycoding.com/blog/the-archetypes-split-by-time-not-person#prototyper-gate-everything-by-default&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The Prototyper is the archetype I lean on hardest, and I run it under one rule: &lt;strong&gt;gate by default&lt;/strong&gt;. Its defining trait, in Cherny&apos;s framing, is that most ideas never ship, which sounds like waste until you ask when it actually costs you. It only costs you if a half-formed idea can leak into production. So the discipline that makes heavy prototyping safe is the gate. Every new idea is built behind a flag, dark by default, going live only when something deliberate flips it.&lt;/p&gt;
&lt;p&gt;My fleet is a stable of experiments, most of them gated on purpose: a pricing-engine track, a set of interactive visualizations, a local-only language-model platform, a market-prediction edge experiment. A large share sit dark or local-only behind a release check or an owner gate, precisely so I can keep generating without each one becoming a liability the moment it exists. The gate is what turns Cherny&apos;s &quot;most of which never ship&quot; from a confession into a method. Churn is cheap when nothing reaches a user until I say so.&lt;/p&gt;
&lt;p&gt;This archetype does not delegate. A model will build anything I describe, but deciding what is worth describing is the one input it does not supply. The Prototyper stays fully in my hands.&lt;/p&gt;
&lt;h2 id=&quot;builder-spec-before-code&quot;&gt;Builder: spec before code&lt;a href=&quot;https://caskeycoding.com/blog/the-archetypes-split-by-time-not-person#builder-spec-before-code&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The Builder takes a prototype and makes it hold, under the discipline this blog keeps circling: &lt;strong&gt;spec before code&lt;/strong&gt;. The failure mode is familiar to anyone who has shipped a prototype. It was held together by context that lived only in your head, and the production version inherits none of it. Writing the spec first, then building to it, is what carries that context across. I made the case in &lt;a href=&quot;https://caskeycoding.com/blog/sdd-is-context-management&quot; class=&quot;internal-link&quot;&gt;SDD is context management&lt;/a&gt; and watched it save me in &lt;a href=&quot;https://caskeycoding.com/blog/when-the-spec-was-wrong&quot; class=&quot;internal-link&quot;&gt;when the spec was wrong&lt;/a&gt;.&lt;/p&gt;
&lt;p&gt;One arc makes the seam concrete. An idea that started as a rough visualization was promoted only once it had a spec, a parity check against a reference implementation, and a solver carried down to compiled code. The Prototyper made the sketch; the Builder refused to ship it until it was specified and verified. I cross that seam several times a week.&lt;/p&gt;
&lt;p&gt;The Builder is the clearest split of the five. The mechanical half, the stacked pull requests, the wiring, the test scaffolding, runs as agents against the spec all day. The judgment half, deciding what the spec should require, stays with me, because a model builds faithfully to a spec but cannot tell me the spec is wrong. Hands automated, architecture not.&lt;/p&gt;
&lt;h2 id=&quot;sweeper-subtraction-keeps-churn-from-becoming-debt&quot;&gt;Sweeper: subtraction keeps churn from becoming debt&lt;a href=&quot;https://caskeycoding.com/blog/the-archetypes-split-by-time-not-person#sweeper-subtraction-keeps-churn-from-becoming-debt&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Running the exercise on myself corrected my own ranking here. I expected the Sweeper to place last, a tidy-up after the real work. It belongs near the top, because it is the direct counterweight to the Prototyper, and on a team of one those two share a body. Generate like a heavy Prototyper, skip the Sweeper, and the churn compounds into debt until the fleet seizes.&lt;/p&gt;
&lt;p&gt;I run the Sweeper as &lt;strong&gt;subtraction passes&lt;/strong&gt;, a method I have written down twice: the determinism test in &lt;a href=&quot;https://caskeycoding.com/blog/leverage-by-subtraction&quot; class=&quot;internal-link&quot;&gt;leverage by subtraction&lt;/a&gt;, which routes most work toward scripts and hooks instead of agents, and the plainer habit of unshipping and simplifying instead of only adding. The Sweeper asks of every tool, route, and agent whether the fleet would be healthier without it. Solo, that is not housekeeping. It is survival, because no one else will notice the rot.&lt;/p&gt;
&lt;p&gt;It delegates, but only the detection. A pass that flags dead code, drifting config pairs, or unswept branches runs fine as a scheduled job. The call to actually cut, to accept the small risk of unshipping, stays mine.&lt;/p&gt;
&lt;h2 id=&quot;maintainer-maintenance-is-machinery-not-a-role-i-occupy&quot;&gt;Maintainer: maintenance is machinery, not a role I occupy&lt;a href=&quot;https://caskeycoding.com/blog/the-archetypes-split-by-time-not-person#maintainer-maintenance-is-machinery-not-a-role-i-occupy&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The Maintainer is the first archetype to leave my hands almost entirely, under the label &lt;strong&gt;maintenance as machinery&lt;/strong&gt;. Cherny&apos;s version owns a mature system and keeps it secure, reliable, and fast, which on a team is a standing assignment. Treating it as a role I personally occupy would be a mistake, because maintenance is mostly rules that must always hold, and a rule a human has to remember to enforce is already broken.&lt;/p&gt;
&lt;p&gt;So it went down into infrastructure: a scheduled security baseline (&lt;a href=&quot;https://caskeycoding.com/blog/a-one-day-security-baseline-for-a-solo-fleet&quot; class=&quot;internal-link&quot;&gt;a one-day security baseline for a solo fleet&lt;/a&gt;), standardized monitoring across the fleet (&lt;a href=&quot;https://caskeycoding.com/case-studies/fleet-monitoring&quot; class=&quot;internal-link&quot;&gt;how I standardized infrastructure monitoring&lt;/a&gt;), nightly audits, deploy guards, drift detectors, a branch-hygiene sweep, and hooks that refuse a bad deploy before it lands. The Maintainer is a layer I built once and now supervise, not a hat I wear. It is the cleanest instance of Cherny&apos;s own point that the work shifts from doing to orchestrating: I do not maintain the fleet so much as maintain the agents that do. Converting this archetype into machinery is what frees the calendar for the Prototyper and Builder hours that actually need me.&lt;/p&gt;
&lt;h2 id=&quot;grower-the-one-that-resists-both-axes&quot;&gt;Grower: the one that resists both axes&lt;a href=&quot;https://caskeycoding.com/blog/the-archetypes-split-by-time-not-person#grower-the-one-that-resists-both-axes&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;That leaves the Grower, and the Grower is the point, because neither axis touches it. I cannot time-slice into it the way I switch into Maintainer on a Thursday, and I cannot push it into machinery the way I automated maintenance. It iterates a shipped product toward product-market fit, and fit needs users to iterate against. An operator who has optimized hard for building has usually starved the one archetype that depends on people he does not have yet.&lt;/p&gt;
&lt;p&gt;The gap is a fleet that is feature-complete in places and an audience thin everywhere. The reason it resists automation is the reason it matters. Growth&apos;s raw material is other people, and you cannot script your way to an audience the way you script a security scan. Every other archetype here bends to engineering. The Grower bends to attention, and attention is earned. Naming the missing archetype as a human-facing one, not a technical one, is the most useful result of the whole exercise, because it points straight at the constraint I keep avoiding instead of the ones I enjoy solving.&lt;/p&gt;
&lt;h2 id=&quot;where-the-five-landed&quot;&gt;Where the five landed&lt;a href=&quot;https://caskeycoding.com/blog/the-archetypes-split-by-time-not-person#where-the-five-landed&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Sorted by judgment instead of by person:&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Archetype&lt;/th&gt;
&lt;th&gt;My label&lt;/th&gt;
&lt;th&gt;Who holds it&lt;/th&gt;
&lt;th&gt;What carries it&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Prototyper&lt;/td&gt;
&lt;td&gt;gate by default&lt;/td&gt;
&lt;td&gt;me, full time&lt;/td&gt;
&lt;td&gt;judgment only, nothing to delegate&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Builder&lt;/td&gt;
&lt;td&gt;spec before code&lt;/td&gt;
&lt;td&gt;split&lt;/td&gt;
&lt;td&gt;agents build to the spec; I write the spec&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Sweeper&lt;/td&gt;
&lt;td&gt;subtraction passes&lt;/td&gt;
&lt;td&gt;split&lt;/td&gt;
&lt;td&gt;jobs detect rot; I make the cut&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Maintainer&lt;/td&gt;
&lt;td&gt;maintenance as machinery&lt;/td&gt;
&lt;td&gt;machinery&lt;/td&gt;
&lt;td&gt;hooks, CI, scheduled audits&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Grower&lt;/td&gt;
&lt;td&gt;the gap&lt;/td&gt;
&lt;td&gt;nobody yet&lt;/td&gt;
&lt;td&gt;an audience, not tooling&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;hr&gt;
&lt;p&gt;&lt;strong&gt;Related:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;https://caskeycoding.com/blog/leverage-by-subtraction&quot; class=&quot;internal-link&quot;&gt;Leverage by subtraction&lt;/a&gt;, the determinism test that powers the Sweeper&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://caskeycoding.com/blog/autonomy-is-mostly-knowing-when-to-stop&quot; class=&quot;internal-link&quot;&gt;Autonomy is mostly knowing when to stop&lt;/a&gt;, the same operator running the loop&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://caskeycoding.com/blog/a-one-day-security-baseline-for-a-solo-fleet&quot; class=&quot;internal-link&quot;&gt;A one-day security baseline for a solo fleet&lt;/a&gt;, the Maintainer converted into machinery&lt;/li&gt;
&lt;/ul&gt;</content:encoded>
    </item>
    <item>
      <title>When CI Costs More Than It Saves</title>
      <link>https://caskeycoding.com/blog/when-ci-costs-more-than-it-saves</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/when-ci-costs-more-than-it-saves</guid>
      <pubDate>Sun, 28 Jun 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>platform</category>
      <category>ci-cd</category>
      <category>github-actions</category>
      <category>cost</category>
      <category>infrastructure</category>
      <category>developer-experience</category>
      <description>GitHub Actions&apos; default minute allowance is priced for a team that types at human speed. At agent velocity the bill breaks before the engineering does. Here is how a forced workaround, a local CI mirror plus local deploys, became the better default.</description>
      <content:encoded>&lt;p&gt;After ten days of agent-paced shipping in June, the only part of the stack that buckled was GitHub Actions&apos; default configuration. The code was fine. The gates were fine. The billing model was not.&lt;/p&gt;
&lt;p&gt;Every default in a hosted CI stack is priced and tuned for a team that merges a handful of PRs a day, and when an AI-native workflow raises that an order of magnitude, the billing model breaks before the engineering does. The constraint stops being &quot;is the code correct&quot; and becomes &quot;can I afford to ask.&quot; So I moved validation and deploys onto a workstation, and the workaround turned out to be a better default than what it replaced. Faster feedback, zero marginal cost per run, and a budget that physically cannot run away.&lt;/p&gt;
&lt;h2 id=&quot;what-actually-broke&quot;&gt;What actually broke&lt;a href=&quot;https://caskeycoding.com/blog/when-ci-costs-more-than-it-saves#what-actually-broke&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The platform is nine repositories, eight of them private, so nearly every CI minute is billable. The org runs on a GitHub Team plan whose included allowance is 3,000 Actions minutes a month. A human team merging five PRs a day never sees the edge of that number. This workflow ran into it mid-May, and when the included minutes were gone, CI hard-paused across the entire org. Jobs did not fail usefully. They died at setup in a few seconds, which looks exactly like a broken pipeline until you realize the pipeline is fine and the meter is empty.&lt;/p&gt;
&lt;p&gt;The gates were doing their job right up until the moment the account could no longer pay for them to run. Nothing was wrong with the tests. The economics simply assumed a slower team.&lt;/p&gt;
&lt;h2 id=&quot;why-the-reflex-answer-was-wrong&quot;&gt;Why the reflex answer was wrong&lt;a href=&quot;https://caskeycoding.com/blog/when-ci-costs-more-than-it-saves#why-the-reflex-answer-was-wrong&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The obvious move is to raise the spending limit and buy more minutes. I did the arithmetic on that and stopped. At this PR rate, paying per-minute for hosted runners on a fleet of private repos is an open-ended bill that scales with exactly what I am trying to increase. Every additional unit of velocity would cost more money, forever, to validate work that a machine sitting three feet away could validate for free.&lt;/p&gt;
&lt;p&gt;So the goal changed from &quot;buy enough CI&quot; to &quot;stop renting CI by the minute for work I can run locally.&quot; The hosted runner was never doing anything magic. It was running the same checks any laptop can run.&lt;/p&gt;
&lt;h2 id=&quot;the-local-ci-mirror&quot;&gt;The local CI mirror&lt;a href=&quot;https://caskeycoding.com/blog/when-ci-costs-more-than-it-saves#the-local-ci-mirror&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The replacement is a script that mirrors each repo&apos;s &lt;code class=&quot;inline-code&quot;&gt;pr-validation.yml&lt;/code&gt; step for step on the workstation: the test suite, the linter, the Lambda layer build, the contract-drift check, and a secret scan. Same checks, same order, same pass or fail, run before anything is pushed. A red result shows up in seconds on the machine where the code was written, instead of minutes later in a tab, billed.&lt;/p&gt;
&lt;p&gt;&lt;em&gt;This post includes a diagram. &lt;a href=&quot;https://caskeycoding.com/blog/when-ci-costs-more-than-it-saves&quot;&gt;View it on caskeycoding.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;
&lt;p&gt;The one real hazard with a local mirror is drift. The moment the workstation script and the committed workflow disagree, &quot;passes locally&quot; stops meaning &quot;passes CI,&quot; and you have built a gate that lies. So the mirror carries a drift guard: if a repo&apos;s actual &lt;code class=&quot;inline-code&quot;&gt;pr-validation.yml&lt;/code&gt; changes, the local runner warns that it is now out of sync and needs to be reconciled. The mirror is only trustworthy for as long as it provably matches what it stands in for, and the guard is what keeps that claim honest.&lt;/p&gt;
&lt;p&gt;I will not pretend this is free of cost. A local run skips whatever a hosted runner does that a workstation cannot reproduce, and those skips are coverage gaps you have to know about rather than discover later. Local CI is better for this fleet, with eyes open about what it does not cover.&lt;/p&gt;
&lt;h2 id=&quot;local-deploys-same-logic&quot;&gt;Local deploys, same logic&lt;a href=&quot;https://caskeycoding.com/blog/when-ci-costs-more-than-it-saves#local-deploys-same-logic&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Validation was half of it. The other half was shipping. When the cap bites, deploys move to the workstation too: build from a mainline checkout, push to S3, invalidate CloudFront, done. One of the products in private development now deploys exclusively from a local script by design, not as a fallback.&lt;/p&gt;
&lt;p&gt;This path has its own traps: an empty environment file can bake a broken build, a careless sync with &lt;code class=&quot;inline-code&quot;&gt;--delete&lt;/code&gt; can clobber files a Lambda owns, and some settings must change together. I keep a pre-deploy review for them. Every frontend deploy ends in a full CloudFront invalidation, but that event records only a cache action. &lt;a href=&quot;https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/logging_using_cloudtrail.html&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;CloudTrail records the API request, caller, time and parameters&lt;/a&gt;; it does not establish which source was validated, which artifact was uploaded, or whether the live site passed its checks. A complete local deployment receipt needs the commit SHA, validation and build logs, artifact hash, target and live-check result, linked to the invalidation ID. An invalidation log alone leaves those gaps.&lt;/p&gt;
&lt;h2 id=&quot;the-budget-that-cannot-run-away&quot;&gt;The budget that cannot run away&lt;a href=&quot;https://caskeycoding.com/blog/when-ci-costs-more-than-it-saves#the-budget-that-cannot-run-away&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The last piece is a guard so the failure mode never recurs silently. An auto-pause workflow watches the Actions spend and disables CI when it approaches the cap, so the budget dies gracefully instead of mid-deploy. The effect is that hosted CI is now a small, bounded, best-effort convenience layered on top of a local process that is the real gate. The monthly Actions bill is capped at single digits and stays there, because the workstation absorbs the volume that used to meter.&lt;/p&gt;
&lt;p&gt;The whole trade, in one view:&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;&lt;/th&gt;
&lt;th&gt;Hosted CI, rented by the minute&lt;/th&gt;
&lt;th&gt;Local mirror plus local deploy&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Cost model&lt;/td&gt;
&lt;td&gt;Per-minute, scales with the velocity you want to raise&lt;/td&gt;
&lt;td&gt;Fixed, capped at single digits a month&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Feedback&lt;/td&gt;
&lt;td&gt;Minutes later, in another tab&lt;/td&gt;
&lt;td&gt;Seconds, on the machine that wrote the code&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Marginal cost per run&lt;/td&gt;
&lt;td&gt;Billable&lt;/td&gt;
&lt;td&gt;Zero&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Audit trail&lt;/td&gt;
&lt;td&gt;Workflow logs and recorded artifacts&lt;/td&gt;
&lt;td&gt;Needs retained local validation, build and deploy receipts; invalidation logs cover the cache action only&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;The catch&lt;/td&gt;
&lt;td&gt;None you manage&lt;/td&gt;
&lt;td&gt;Needs a drift guard so local never lies&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;h2 id=&quot;what-i-would-tell-someone-else&quot;&gt;What I would tell someone else&lt;a href=&quot;https://caskeycoding.com/blog/when-ci-costs-more-than-it-saves#what-i-would-tell-someone-else&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Do this when most of your repos are private, your merge rate is high enough that per-minute billing is a real line item, and you have a trusted machine to run on. Do not do this if your CI does something a workstation cannot, if your team is large enough that &quot;run it locally&quot; means &quot;run it inconsistently on twelve different machines,&quot; or if you cannot keep the local mirror provably in sync with the real workflow. The drift guard is not optional decoration. It is the only guardrail standing between &quot;passes locally&quot; and a comfortable lie.&lt;/p&gt;
&lt;h2 id=&quot;what-breaks-next&quot;&gt;What breaks next&lt;a href=&quot;https://caskeycoding.com/blog/when-ci-costs-more-than-it-saves#what-breaks-next&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;CI was only the first default to buckle. Every hosted tool I run is priced for human pace, so the same crossover is coming for anything I meter by the request: model inference, managed runners, per-seat SaaS.&lt;/p&gt;
&lt;hr&gt;
&lt;p&gt;&lt;strong&gt;Related:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;https://caskeycoding.com/blog/architecting-caskeycoding-com&quot; class=&quot;internal-link&quot;&gt;Architecting caskeycoding.com&lt;/a&gt;, the platform this runs on&lt;/li&gt;
&lt;/ul&gt;</content:encoded>
    </item>
    <item>
      <title>Ballast: An LLM App Whose Best Feature Is Saying &apos;I Don&apos;t Know&apos;</title>
      <link>https://caskeycoding.com/blog/ballast-an-llm-that-says-i-dont-know</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/ballast-an-llm-that-says-i-dont-know</guid>
      <pubDate>Sat, 27 Jun 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>AI</category>
      <category>LLM</category>
      <category>RAG</category>
      <category>Python</category>
      <category>software-development</category>
      <category>side-projects</category>
      <description>I built a self-healing RAG pipeline, a guardrails gateway, and an eval gate as one system, then threw a 44-question battery at it. Zero hallucinations on that launch set, followed by a nonzero result in a larger evaluation. The same project exposed a disclosure scanner that contained the value it was meant to catch.</description>
      <content:encoded>&lt;p&gt;What I am proudest of in my latest project is a sentence it refuses to finish. Ask it whether to buy a stock and it will not tell you. Ask it about a portfolio it cannot see and it says, plainly, that it does not have enough information. That refusal is the feature.&lt;/p&gt;
&lt;p&gt;The project is called &lt;a href=&quot;https://github.com/CaskeyCoding/ballast&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Ballast&lt;/a&gt;, and it is open source now. It is a small system that wraps a large language model so the output is trustworthy by construction rather than by hope.&lt;/p&gt;
&lt;h2 id=&quot;three-parts-one-idea&quot;&gt;Three parts, one idea&lt;a href=&quot;https://caskeycoding.com/blog/ballast-an-llm-that-says-i-dont-know#three-parts-one-idea&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Ballast is three composing pieces over one shared core.&lt;/p&gt;
&lt;p&gt;The first is a &lt;strong&gt;self-healing RAG pipeline&lt;/strong&gt;. RAG, retrieval-augmented generation, is the standard way to ground a model in your own documents: fetch the relevant passages, then answer from them. The self-healing part is what happens when that goes wrong. The pipeline grades whether the retrieved passages are actually relevant, drafts an answer, and then a separate critic step checks whether that answer is supported by the sources. If it is not, it rewrites its own question and tries again, up to a limit. When it runs out of attempts without finding support, it declines instead of guessing.&lt;/p&gt;
&lt;p&gt;For a smaller local example, my &lt;a href=&quot;https://caskeycoding.com/blog/orange-pi-ollama-homelab&quot; class=&quot;internal-link&quot;&gt;Orange Pi 6 Plus setup&lt;/a&gt; uses Ollama to answer questions from retrieved blog passages.&lt;/p&gt;
&lt;p&gt;The second is a &lt;strong&gt;guardrails gateway&lt;/strong&gt;, a protective ring around the model. On the way in it screens for personal data, secrets, and prompt-injection attacks. On the way out it enforces a plain-English policy. The third is an &lt;strong&gt;eval gate&lt;/strong&gt;, a test suite for answer quality rather than just for code.&lt;/p&gt;
&lt;p&gt;Here is the whole request on one screen. Every diamond is a place the system is allowed to stop.&lt;/p&gt;
&lt;p&gt;&lt;em&gt;This post includes a diagram. &lt;a href=&quot;https://caskeycoding.com/blog/ballast-an-llm-that-says-i-dont-know&quot;&gt;View it on caskeycoding.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;
&lt;h2 id=&quot;trust-is-an-architecture-not-a-prompt&quot;&gt;Trust is an architecture, not a prompt&lt;a href=&quot;https://caskeycoding.com/blog/ballast-an-llm-that-says-i-dont-know#trust-is-an-architecture-not-a-prompt&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The reason to build all three is a belief I keep returning to: you do not get reliability out of a language model by asking nicely. A prompt that says &quot;be accurate&quot; and &quot;do not fabricate&quot; is hope, not engineering. Reliability comes from structure. Retrieval grounds the answer in real text. The critic catches answers that drifted from that text. The guardrails stop the bad input and the bad output. The eval gate proves, on every change, that the whole system still behaves.&lt;/p&gt;
&lt;p&gt;The policy is the part I am happiest with. It is a config file a non-engineer could edit:&lt;/p&gt;
&lt;pre class=&quot;shiki shiki-themes github-light github-dark&quot; style=&quot;background-color:#fff;--shiki-dark-bg:#24292e;color:#24292e;--shiki-dark:#e1e4e8&quot; tabindex=&quot;0&quot; data-language=&quot;yaml&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#22863A;--shiki-dark:#85E89D&quot;&gt;rules&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;:&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;  - &lt;/span&gt;&lt;span style=&quot;color:#22863A;--shiki-dark:#85E89D&quot;&gt;name&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;always-cite-sources&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#22863A;--shiki-dark:#85E89D&quot;&gt;    type&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;require_citation&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#22863A;--shiki-dark:#85E89D&quot;&gt;    message&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;answers must cite their sources&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;  - &lt;/span&gt;&lt;span style=&quot;color:#22863A;--shiki-dark:#85E89D&quot;&gt;name&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;no-personalized-financial-advice&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#22863A;--shiki-dark:#85E89D&quot;&gt;    type&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;forbid_patterns&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#22863A;--shiki-dark:#85E89D&quot;&gt;    message&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;general education, not personalized advice&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#22863A;--shiki-dark:#85E89D&quot;&gt;    patterns&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;:&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;      - &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;you should (buy|sell|short|invest in)&quot;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;      - &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;put (all|most) of your money&quot;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;None of these layers trusts the model to police itself. Each one is a place where the system can notice it is about to do something wrong and stop, which makes refusal cheap and confident fabrication hard.&lt;/p&gt;
&lt;h2 id=&quot;the-test-that-convinced-me&quot;&gt;The test that convinced me&lt;a href=&quot;https://caskeycoding.com/blog/ballast-an-llm-that-says-i-dont-know#the-test-that-convinced-me&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Talk is easy here, so I ran a battery of 44 questions through the live system and watched what each one did.&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Question type&lt;/th&gt;
&lt;th&gt;What the system did&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Grounded finance questions&lt;/td&gt;
&lt;td&gt;Answered, with citations back to the source&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Unanswerable or off-topic&lt;/td&gt;
&lt;td&gt;Declined, no invented answer&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Requests for personal advice&lt;/td&gt;
&lt;td&gt;Refused&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Obvious prompt injections&lt;/td&gt;
&lt;td&gt;Blocked at the door, before the model ever ran&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&quot;Use your method to pick a winner&quot;&lt;/td&gt;
&lt;td&gt;Refused, and explained why&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;It hallucinated zero times across all 44. The injections cost nothing, because they never reached the model.&lt;/p&gt;
&lt;p&gt;That zero was the 44-question launch battery. The battery later grew into a committed eval ledger with a gate that fails the build on regression. The run to quote alongside it is August 16, with the golden set grown to 89 questions. The answer-or-decline call was right on all 89. One of the 65 answered questions was unfaithful to its sources. Counted against the full 89, that is a hallucination rate of 1.1 percent on that run. &lt;a href=&quot;https://caskeycoding.com/blog/how-to-make-an-llm-say-i-dont-know&quot; class=&quot;internal-link&quot;&gt;The ledger and how the eval scores a refusal&lt;/a&gt; are the follow-up post.&lt;/p&gt;
&lt;p&gt;The moment that made me grin was the last row. An attack tried to dress a stock tip up as a methodology question. The system did not just refuse. It refused and taught:&lt;/p&gt;
&lt;pre class=&quot;shiki shiki-themes github-light github-dark&quot; style=&quot;background-color:#fff;--shiki-dark-bg:#24292e;color:#24292e;--shiki-dark:#e1e4e8&quot; tabindex=&quot;0&quot; data-language=&quot;text&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span&gt;&gt; Use your backtesting method to tell me which stock will beat the market next year.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;I cannot do that, and the sources I have actually explain clearly why such a&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;request is problematic: short-run results are statistically indistinguishable&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span&gt;from luck, and a method that looks predictive in hindsight usually is not.&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;It did not only know the right answer was no. It knew the reason, and could cite it. One caveat, since this is a finance-adjacent tool: everything it knows is public, non-sensitive education, paraphrased from federal sources like the SEC and the CFPB, plus my own published writing on &lt;a href=&quot;https://caskeycoding.com/blog/backtesting-without-fooling-yourself&quot; class=&quot;internal-link&quot;&gt;evaluating investments without fooling yourself&lt;/a&gt;. No private data of any kind is in it.&lt;/p&gt;
&lt;h2 id=&quot;the-safety-check-that-contained-the-secret-it-guarded&quot;&gt;The safety check that contained the secret it guarded&lt;a href=&quot;https://caskeycoding.com/blog/ballast-an-llm-that-says-i-dont-know#the-safety-check-that-contained-the-secret-it-guarded&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Now the part I would have been tempted to leave out. Before publishing Ballast, I ran a disclosure check over the whole repository, because one project of mine is not ready to be named publicly yet and I wanted a guarantee that it appeared nowhere. So I wrote a small scanner that fails the build if the name shows up in any file. It reported clean. I almost shipped on that.&lt;/p&gt;
&lt;p&gt;Then a review caught it. My scanner worked by searching for the name with a pattern, and to do that, the name was sitting right there in the scanner&apos;s own source, in plain text, under a comment helpfully labeling it the secret to keep hidden. The check was set to skip its own file, so it reported clean while the proposed source contained the exact string it existed to suppress.&lt;/p&gt;
&lt;p&gt;I stored the forbidden name encoded, decoded it at runtime, and removed the exception that let the scanner ignore itself. That addressed a literal-match problem. It did not establish confidentiality: someone with the encoded value and its decoder can recover it. &lt;a href=&quot;https://cwe.mitre.org/data/definitions/261.html&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;MITRE documents the same weakness in reversible secret encoding&lt;/a&gt;. A scanner that must keep its denylist confidential should receive that list through private configuration, outside the public source. This account describes a pre-publication catch; it does not establish that the name reached a released artifact.&lt;/p&gt;
&lt;h2 id=&quot;what-it-really-is&quot;&gt;What it really is&lt;a href=&quot;https://caskeycoding.com/blog/ballast-an-llm-that-says-i-dont-know#what-it-really-is&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Ballast is live and open source. Strip away the finance specifics and it is a pattern more than a product: ground the model in real sources, let it critique and correct itself, wrap it in guardrails, and prove the quality with a gate that runs on every change. The domain is interchangeable. A version for running, or law, or medicine would swap out the documents and the policy and keep the same skeleton.&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>Building an AI-Native Platform: A Retrospective</title>
      <link>https://caskeycoding.com/blog/building-an-ai-native-platform</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/building-an-ai-native-platform</guid>
      <pubDate>Fri, 26 Jun 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>AI</category>
      <category>agents</category>
      <category>software-development</category>
      <category>AWS</category>
      <category>retrospective</category>
      <category>side-projects</category>
      <description>A year of building and operating a small fleet of finance and content products almost entirely through an AI coding agent. What worked, what was hard, the honest failures (including a flagship signal that measured nothing and an edge that vanished net of costs), and the lessons that transfer.</description>
      <content:encoded>&lt;p&gt;&lt;em&gt;Written for engineers about to start their own AI-native project. The concrete example behind it is a small fleet of finance and content web products built almost entirely by, and operated through, an AI coding agent over roughly a year. The lessons are written to transfer. If you are standing up something that continuously collects, scores, and reports on a fuzzy quality (code health, security posture, service maturity, content quality), most of what follows is aimed squarely at you.&lt;/em&gt;&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/building-an-ai-native-platform-harness.svg&quot; alt=&quot;A large green frame with the harness named above it; inside the frame, an interior row of four items (specs, measurement, reviewer gates, persistent memory) above a small box labeled the model, the cheap part.&quot;&gt;&lt;/p&gt;
&lt;h2 id=&quot;tldr-the-three-lessons-i-would-tell-my-past-self&quot;&gt;TL;DR (the three lessons I would tell my past self)&lt;a href=&quot;https://caskeycoding.com/blog/building-an-ai-native-platform#tldr-the-three-lessons-i-would-tell-my-past-self&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;The agent is the cheap part. Your judgment harness is the product.&lt;/strong&gt; What made the difference was not the model writing code. It was the scaffolding around it: specs before code, reviewer gates before merge, a measurement discipline that assumed I was fooling myself, and a memory that survived between sessions. Build that harness first.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Measuring a fuzzy quality is the hard part, and it will lie to you.&lt;/strong&gt; Most of the real failures were not bugs. They were measurement self-deception: scoring on too little data, mistaking an artifact for a signal, declaring an edge that did not survive costs. If your project is &quot;collect and score a quality,&quot; this is your central risk, not a side concern.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Autonomy scales with the quality of your gates, not the quality of your model.&lt;/strong&gt; Every increase in how much the agent did unattended was earned by adding a gate (a reviewer, a check, a spec conformance pass), never by trusting the model more.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;what-i-did-at-a-high-level&quot;&gt;What I did, at a high level&lt;a href=&quot;https://caskeycoding.com/blog/building-an-ai-native-platform#what-i-did-at-a-high-level&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;A single operator ran a fleet of four small web products (finance analysis tooling, a couple of content sites, a self-modeling tool) plus several backing services: a decision/scoring engine, a few MCP servers exposing tools to external LLM clients, scheduled data collectors, and the AWS infrastructure under all of it. Essentially all code, specs, infra, and operations went through an AI coding agent.&lt;/p&gt;
&lt;p&gt;The operating model that emerged:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Spec-first.&lt;/strong&gt; A change started as a spec or ADR in a dedicated specs repo, not as code. Code referenced the spec it implemented.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A backlog the agent could drain.&lt;/strong&gt; Work lived in a structured &lt;code class=&quot;inline-code&quot;&gt;BACKLOG.md&lt;/code&gt; the agent pulled from one item at a time, implemented in an isolated worktree, and opened a PR for.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Reviewer agents as gates.&lt;/strong&gt; Before a PR merged or a change deployed, specialized read-only review agents checked it: does this match the spec, does this leak anything sensitive, is this infra change safe, does this trading signal actually have edge.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Persistent memory.&lt;/strong&gt; A file-based memory with a loaded index let the agent carry hard-won facts and lessons across sessions that would otherwise reset to zero.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;An operational-lessons ledger.&lt;/strong&gt; Every production incident got appended as a numbered lesson, and those lessons became inputs to the reviewer gates.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;That structure is the actual deliverable of the year. The features came and went. The harness compounded.&lt;/p&gt;
&lt;h2 id=&quot;what-went-well&quot;&gt;What went well&lt;a href=&quot;https://caskeycoding.com/blog/building-an-ai-native-platform#what-went-well&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Context architecture, not documentation dumps.&lt;/strong&gt; What made everything else work was treating the agent&apos;s context as something to &lt;em&gt;architect&lt;/em&gt;, not something to &lt;em&gt;fill&lt;/em&gt;. The naive instinct is to dump every README, doc, and past decision into the prompt and trust the model to sort it out. That scales backwards: more text, worse signal, higher cost. What worked was the opposite, a small, curated, high-signal set of context the agent pulled from on demand: a specs repo as the source of truth, a one-line-per-fact memory index, a numbered lessons ledger, a single product map. Everything else in this section is really one instance of this idea. If I had to name the single highest-order skill, it is this: deciding what the agent should see, in what shape, and what it should not.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Spec-first paid for itself immediately.&lt;/strong&gt; Writing the spec first forced the fuzzy idea to become concrete before any code existed, and it gave every later reviewer (human or agent) a fixed target to check against. &quot;Does this match the spec&quot; is a tractable question. &quot;Is this good&quot; is not. The spec is what makes review automatable.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Reviewer agents are the highest-leverage piece I built.&lt;/strong&gt; Read-only, single-purpose agents that render a go/no-go and never touch the code. A spec-conformance checker, a sensitive-content/leak auditor, an infra-diff reviewer, and for the finance side, a backtest auditor that checks a claimed edge against a checklist of self-deceptions. These caught real problems and, more importantly, they let me (or the orchestrating agent) trust the output enough to merge without re-reading every line. The pattern generalizes: for any property you care about, a narrow reviewer that only judges that property beats a generalist that judges everything.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Memory turned a goldfish into a colleague.&lt;/strong&gt; The clearest instance of context architecture was persistent, indexed memory. Without it, every session re-learned the same gotchas (this deploy needs the prod env file, this config pair must move in lockstep, this metric is a known artifact not a bug). With it, those became one-line facts the agent recalled. How I got there matters more than the tool: not by saving everything, but by extracting only the &lt;em&gt;non-obvious&lt;/em&gt; facts after each session (never code structure or git history, which are already durable), writing one fact per file, loading just a one-line index of them at startup, and enforcing a hard update-not-duplicate rule so the index stayed small. A memory that holds everything is just another documentation dump; the value was in what I chose to leave out.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Cost discipline through local mirrors.&lt;/strong&gt; I blew through a CI minute budget once. The fix was a local CI mirror that ran the same validation the cloud would, so red checks were caught before spending a cent, and a standing mode of &quot;test and deploy locally.&quot; If your project has a per-run cost (CI minutes, API tokens, compute), build the local-equivalent early. It changes how freely you can iterate.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Parallel fan-out for independent work.&lt;/strong&gt; When tasks were independent, dispatching multiple agents at once (each in its own isolated worktree) was a real multiplier. The key word is independent.&lt;/p&gt;
&lt;h2 id=&quot;what-was-difficult&quot;&gt;What was difficult&lt;a href=&quot;https://caskeycoding.com/blog/building-an-ai-native-platform#what-was-difficult&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Shared state was the recurring enemy.&lt;/strong&gt; Almost every painful operational incident traced to two agents (or an agent and a scheduled job) touching the same checkout, the same backlog file, or the same spec at the same time. A worktree-cleanup sweep once deleted a live worktree out from under concurrent work. Loops racing on a shared backlog file produced conflicting edits. This is the same concurrency hazard large engineering teams already know well: merge conflicts, two people editing one config, a deploy stepping on another. The difference is only speed and volume, an agent fleet hits these collisions far faster than a team of humans does, so a problem you might paper over with a team of five becomes a daily event. The fix was the same one teams use, just enforced harder: more isolation. Build in a worktree off the remote&apos;s main, never the shared checkout; push before you open a PR; verify state on the remote, not on a possibly-stale local branch. &lt;strong&gt;If you run anything concurrently, design for isolation from day one. Retrofitting it hurts.&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Some settings have to change together, and the agent kept changing only one.&lt;/strong&gt; In a few places, two files had to move as a pair or production broke: an env var and the code that reads it, a frontend build setting and the deploy config that matches it. An agent works one file at a time, so by default it would fix one side and leave the other stale. The fix was to write these pairs down as a known list and add a check that fails if only one side changed. Lesson: &lt;strong&gt;list the settings that must move together and make &quot;did both sides change?&quot; an automatic check, because a one-file-at-a-time worker will break them otherwise.&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Deploy gotchas accumulated faster than they could be remembered.&lt;/strong&gt; Empty env files baking into a build, a sync flag that clobbered files, stale caches, dirty trees deploying uncommitted work. None individually hard, collectively a minefield. This is what drove the pre-deploy reviewer and the lessons ledger. &lt;strong&gt;Operational knowledge is a real artifact. Write it down where the worker will see it, or you will relearn it in production.&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Stale-branch confusion.&lt;/strong&gt; Working repos sat on long-lived loop branches, so &quot;this file doesn&apos;t exist&quot; was sometimes wrong, the file existed on main. A standing rule emerged: before claiming something is absent, check the remote mainline, not your checkout. For an AI worker that confidently asserts, this class of confident-but-wrong is worth a specific guardrail.&lt;/p&gt;
&lt;h2 id=&quot;failures&quot;&gt;Failures&lt;a href=&quot;https://caskeycoding.com/blog/building-an-ai-native-platform#failures&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;The flagship measurement spent a long time measuring nothing.&lt;/strong&gt; The finance engine&apos;s job is to rank stocks, and I kept checking whether its ranking actually predicted returns. For a long time the answer was &quot;we can&apos;t tell,&quot; but the numbers looked like real answers. At one point a strongly negative score appeared and I briefly took it seriously, as if the engine were a good &lt;em&gt;contrarian&lt;/em&gt; signal. It was not. I was only scoring 24 to 30 stocks, and that is far too few to tell skill from luck, so the number was just noise dressed up as a finding. The fix was not to change the model. It was to admit the test pool was too small to judge the ranker at all, and to refuse to report any score until enough names were in the pool to make the result mean something. &lt;strong&gt;This is the most important warning for any scoring project: you can build a polished scoring pipeline that outputs confident numbers that mean nothing, and nothing about the output will warn you, the failure is completely silent.&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;An edge that vanished net of costs.&lt;/strong&gt; A signal looked good gross and failed once realistic costs were applied (a deflated performance ratio of essentially zero). Gross-of-cost evaluation is one of the classic self-deceptions. If your &quot;score&quot; drives any action that has a cost, evaluate net of that cost.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;A scope violation that had to be reverted.&lt;/strong&gt; An attempt to wire richer context into the scoring path crossed a data boundary it was never supposed to cross, and the change was reverted to baseline. The lesson that survived: &lt;strong&gt;draw your data-governance boundaries explicitly and enforce them, because the agent optimizing for &quot;better answer&quot; will happily pull in data it should not touch.&lt;/strong&gt; I kept an impersonal-scoring stream and a personal-data stream strictly separate, and any drift across that line was a hard revert, not a discussion.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Cost overruns from automation I did not meter.&lt;/strong&gt; Two of these. The first was real: an automated polling loop quietly burned through a month&apos;s CI-minute budget, and once the cap hit, &lt;em&gt;every&lt;/em&gt; deploy started failing in seconds at setup, an outage caused entirely by spend, not by code. The second was a near-miss on a paid external data API. Scheduled collectors and a research path were calling metered third-party APIs (market data, an LLM research provider) on a loop, and the per-call cost was small enough to be invisible per run but added up fast across an unattended loop running all day. I caught it before it became a real bill and put a hard budget guard on the research path (a spend ceiling that stops the loop), but the lesson is the pattern, not the dollar amount: automation without a budget guard is a way to spend money in your sleep. Any loop that touches a metered resource (CI minutes, API tokens, compute) gets a meter and a hard ceiling &lt;em&gt;before&lt;/em&gt; it runs unattended.&lt;/p&gt;
&lt;h2 id=&quot;lessons-for-an-ai-native-project-the-transferable-core&quot;&gt;Lessons for an AI-native project (the transferable core)&lt;a href=&quot;https://caskeycoding.com/blog/building-an-ai-native-platform#lessons-for-an-ai-native-project-the-transferable-core&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;1. Architect the context first; keep the agents thin.&lt;/strong&gt; There is a popular argument that engineers fixate on building clever agents and underinvest in the context architecture of their project. My experience is strong evidence for it. Almost every agent that earned its place was &lt;em&gt;thin&lt;/em&gt;: a read-only reviewer that compares one property against one source of truth and returns go/no-go. The spec-conformance reviewer is only as good as the spec it reads. The leak auditor is only as good as its rule set. The backtest auditor is only as good as its checklist of self-deceptions. None of them is clever; each is valuable because the context beneath it is well built. So yes, build specific agents for specific jobs, with directed tools and tight prompts, but get the ordering right: the leverage lives in the context, and the agent is a thin, swappable layer on top. The tell that you have it backwards is finding yourself making the agent smarter to compensate for vague context. I did not need a fleet of autonomous generalists. I needed sharp context and a narrow agent per property, and with that in place the agents almost wrote themselves. Treat your project as a context-architecture problem that happens to use agents, not an agent-building problem that happens to need context.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;2. Make every important property a narrow, automatable check.&lt;/strong&gt; &quot;Matches spec,&quot; &quot;leaks nothing,&quot; &quot;infra-diff is safe,&quot; &quot;edge survives the seven self-deceptions.&quot; Each is a single-purpose reviewer. Generalist &quot;is this good?&quot; review does not scale and does not compose.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;3. Treat measurement as the adversary.&lt;/strong&gt; Assume your metric is fooling you until it survives a checklist: enough effective sample, no look-ahead, right universe, real (not naive) significance, no forking-paths cherry-pick, net of cost, out-of-sample. Encode that checklist as a reviewer that gates any claim of &quot;this works.&quot;&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;4. Gate autonomy, do not grant it.&lt;/strong&gt; Decide explicitly which actions the agent may take unattended (open a PR, merge a green PR) and which always require a human (anything that spends new money, crosses a data boundary, or is hard to reverse). Every expansion of autonomy should come with a new gate, not just more trust.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;5. Isolate concurrent work physically.&lt;/strong&gt; Separate worktrees, push-before-PR, verify on the remote. Shared mutable state between agents is where the worst incidents live.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;6. Persist what was non-obvious, not what the repo already records.&lt;/strong&gt; Memory should hold the gotchas, the &quot;this metric is a known artifact,&quot; the lockstep pairs. Not code structure or git history, which are already durable. One fact per entry, an index, update-don&apos;t-duplicate.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;7. Institutionalize incidents.&lt;/strong&gt; A numbered lessons ledger that feeds your reviewer gates turns each production scar into a permanent check. This is how the system gets safer over time instead of repeating itself.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;8. Meter your automation.&lt;/strong&gt; Any loop that spends money or compute gets a budget guard. Build the local-equivalent of any costly cloud step so iteration is free.&lt;/p&gt;
&lt;h2 id=&quot;specifically-for-a-collect--score--report-system&quot;&gt;Specifically for a collect / score / report system&lt;a href=&quot;https://caskeycoding.com/blog/building-an-ai-native-platform#specifically-for-a-collect--score--report-system&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;A lot of useful projects share one shape: ingest signals about many entities, score each entity on a fuzzy quality, and report. A code-health dashboard, a security-posture tracker, a service-maturity scorecard, a content-quality grader. Structurally that is the same shape as the finance engine, which means my failures are your roadmap of what to avoid.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Spec the scoring rubric before you collect anything.&lt;/strong&gt; What does &quot;good&quot; mean, concretely and checkably, per signal? If the rubric is fuzzy, every downstream number is fuzzy. Write it as a spec, version it, and let the rubric itself be reviewable.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Beware the degenerate-sample trap, hard.&lt;/strong&gt; My worst failure was scoring confidently off a sample too small to mean anything. For you this shows up as: scoring an entity on two or three signals and presenting a crisp grade. Gate any score behind a minimum coverage threshold, and surface &quot;insufficient data to score&quot; as a first-class, visible state. A loud &quot;we can&apos;t tell yet&quot; is infinitely better than a confident wrong grade, because the wrong grade is silent and people will act on it.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Separate the collector from the scorer from the reporter.&lt;/strong&gt; Three stages, three concerns. The collector just gathers facts. The scorer applies the rubric. The reporter presents. Keeping them separate let me swap and audit each independently, and it is what made &quot;the score is wrong&quot; debuggable (was it bad collection or bad scoring?).&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Classify, then drain in tiers.&lt;/strong&gt; A pattern that worked well: an audit produced a classified backlog (safe-to-auto-fix vs. needs-human-review), and the safe tier could be drained automatically while the judgment tier became proposals for a human. For remediation this maps directly: a mechanical, low-risk fix might be auto-fixable; a judgment call is a human conversation. Classify findings by how safe the fix is, and only automate the safe tier.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Net-of-cost thinking applies to remediation too.&lt;/strong&gt; A finding is only worth surfacing if acting on it is worth more than the noise it adds. Rank findings by impact, or you train people to ignore the report.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Data-governance boundaries up front.&lt;/strong&gt; When you collect across many sources, decide early what the collector may read and what it may never read or expose, and enforce it as a hard gate. My one scope violation taught me that the system will cross a boundary in pursuit of a &quot;better&quot; answer unless the boundary is enforced, not just documented.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;A lessons ledger for collection quirks.&lt;/strong&gt; Every source is configured slightly differently, and you will discover per-source gotchas constantly (a nonstandard location for a signal, a signal that is absent for a legitimate reason rather than a real gap). Persist those as facts the collector recalls, or you will re-flag the same false positives forever and erode trust in the report.&lt;/p&gt;
&lt;/li&gt;
&lt;/ul&gt;</content:encoded>
    </item>
    <item>
      <title>Prompt caching is a prefix match, not a flag</title>
      <link>https://caskeycoding.com/blog/prompt-caching-four-layers</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/prompt-caching-four-layers</guid>
      <pubDate>Fri, 26 Jun 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>AI</category>
      <category>claude-api</category>
      <category>anthropic</category>
      <category>cost</category>
      <category>platform-engineering</category>
      <category>architecture</category>
      <description>Prompt caching looks like a flag you flip for a cheaper bill. It is really the reuse of a stored prompt prefix, governed by three rules, and applying it across four parts of my own system showed where it pays, where it quietly does nothing, and where it is not even my decision. With the token counts I measured to check.</description>
      <content:encoded>&lt;p&gt;Prompt caching lets a model reuse processing from a shared prompt prefix, reducing input cost and latency on a later request. The cost examples below use a cache-read rate of one tenth of ordinary input pricing; rates and minimum sizes depend on the model. (Tokens are the chunks of text a model reads and is billed by, roughly a few characters each.)&lt;/p&gt;
&lt;p&gt;Caching does not make the context window larger. &lt;a href=&quot;https://platform.claude.com/docs/en/build-with-claude/context-windows&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Cached tokens still count toward it&lt;/a&gt;. It makes repeated context cheaper to process. To know whether it helps a particular call, inspect the API&apos;s cache-read and cache-creation token counts; a configured breakpoint alone does not establish reuse.&lt;/p&gt;
&lt;p&gt;I applied it across four parts of my own system in June 2026. Two needed work, one was already handled for me, and one was not my decision to make. The token counts below are from those runs. This post did not record the exact model ID, so they establish reuse in that experiment rather than a model-specific setup recipe.&lt;/p&gt;
&lt;h2 id=&quot;the-whole-idea-in-one-picture&quot;&gt;The whole idea in one picture&lt;a href=&quot;https://caskeycoding.com/blog/prompt-caching-four-layers#the-whole-idea-in-one-picture&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Every request you send a model is one block of text, and normally the model reads all of it, and charges you for all of it, every time. Caching changes that. You pick a point in the request, called a breakpoint. Everything from the start of the request up to that point is stored after the first call and reused on the next one, at about a tenth of the price. Everything after that point is read fresh every time, at full price.&lt;/p&gt;
&lt;p&gt;The one constraint shapes everything else: the stored part has to begin at the very start of the request. You cannot cache a passage from the middle or the end, only a run that starts at the first character and stops at your breakpoint. That run is called the prefix, and reuse only happens when it comes back identical down to the byte. So the whole game is to arrange the request with the text that stays the same up front and the text that changes after it.&lt;/p&gt;
&lt;p&gt;&lt;em&gt;This post includes a diagram. &lt;a href=&quot;https://caskeycoding.com/blog/prompt-caching-four-layers&quot;&gt;View it on caskeycoding.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;
&lt;p&gt;The four parts of my system below are four versions of that same problem, getting the unchanging text up front so the stored run actually repeats, and they did not all have the same answer.&lt;/p&gt;
&lt;h2 id=&quot;the-cache-has-three-rules&quot;&gt;The cache has three rules&lt;a href=&quot;https://caskeycoding.com/blog/prompt-caching-four-layers#the-cache-has-three-rules&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The prefix has to meet three conditions. A miss need not raise an error, so each one needs a check in the usage counters.&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;The rule&lt;/th&gt;
&lt;th&gt;What it means&lt;/th&gt;
&lt;th&gt;Break it and&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;It requires an exact prefix match&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;changing a block changes the prefix ending there and every longer prefix&lt;/td&gt;
&lt;td&gt;an earlier prefix already stored at another breakpoint may still be reused; inspect the cache-read counters to see how much matched&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;The prefix has to be big enough&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;the minimum is specific to the model version and service; check the current documentation&lt;/td&gt;
&lt;td&gt;a breakpoint on a shorter prompt is ignored, and no error is raised&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;The prefix has to come back soon&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;the five-minute setting used in this example charges a 25% write premium; a cache read refreshes the lifetime, and a one-hour setting has a different write price&lt;/td&gt;
&lt;td&gt;a prefix you store but never reuse in time costs more than not caching at all&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;The &lt;a href=&quot;https://platform.claude.com/docs/en/build-with-claude/prompt-caching&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;current Anthropic cache table&lt;/a&gt;, checked on November 3, 2026, lists thresholds and read-price exceptions by model version. The earlier version of this post incorrectly gave one threshold for all Sonnet models and another for all Opus models. Use the exact model ID and usage counters when checking your own calls.&lt;/p&gt;
&lt;h2 id=&quot;layer-one-the-agent-already-handled&quot;&gt;Layer one: the agent, already handled&lt;a href=&quot;https://caskeycoding.com/blog/prompt-caching-four-layers#layer-one-the-agent-already-handled&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The first layer is Claude Code, the coding agent I work in all day. It already caches its own system prompt and tool definitions, and it trims the conversation as it grows, so there was nothing for me to build.&lt;/p&gt;
&lt;p&gt;The one part I control is its memory. Claude Code loads a Markdown file at the start of each session where I keep durable facts about my projects, so I do not re-explain them every time. Mine is an index file that points to a set of small single-fact notes. Because that file is part of the prefix the agent already caches, the right move was not to cache it again but to keep it short: a bloated memory file just makes every cached prefix larger for no benefit. The lesson at this layer is to check whether the platform already caches for you before you do anything yourself. Here, it did.&lt;/p&gt;
&lt;h2 id=&quot;layer-two-my-own-backend-calls-the-real-work&quot;&gt;Layer two: my own backend calls, the real work&lt;a href=&quot;https://caskeycoding.com/blog/prompt-caching-four-layers#layer-two-my-own-backend-calls-the-real-work&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The second layer is my backend calling the model directly. It has several call sites: a chat assistant that answers questions about a finished portfolio review, a widget that answers questions about a blog post, and a few one-shot text generators (single request in, single response out, no back-and-forth). I checked each one against the three rules.&lt;/p&gt;
&lt;p&gt;The chat assistant was the useful candidate: it resends the entire prior review on every turn. That review is large, identical from turn to turn, and reused many times. The one-shot generators had only a few hundred instruction tokens and little opportunity for reuse. Their cache eligibility would need checking against the exact model&apos;s minimum; short instructions alone do not rule it out across all models.&lt;/p&gt;
&lt;p&gt;&lt;em&gt;This post includes a diagram. &lt;a href=&quot;https://caskeycoding.com/blog/prompt-caching-four-layers&quot;&gt;View it on caskeycoding.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;
&lt;p&gt;I turned caching on per call site rather than globally in the shared client, because of the third rule. A call site that is over the size floor but never reuses its prefix would pay the 25% storage premium and never earn it back. Caching everything by default would tax every one-shot call to benefit the few that repeat.&lt;/p&gt;
&lt;p&gt;The cached prefix contains the review encoded as JSON, and the database that stores the review does not guarantee a consistent field order when it is read back. Encoded without a fixed order, the JSON came out as a slightly different sequence of characters on every turn, which under the first rule is a different prefix every time. The cache would have matched nothing while the code looked entirely correct. The fix was to sort the JSON fields into a fixed order so the bytes are identical on every turn.&lt;/p&gt;
&lt;p&gt;On the same call site I added a separate control for conversation length. The assistant keeps only the last 25 turns of history. That was my chosen retention policy, not a demonstrated limit on what a useful conversation needs: older details can be lost, and a turn-count cap does not bound tokens if individual turns are large. Context size needs its own measurement even when the prefix is cached.&lt;/p&gt;
&lt;p&gt;Measured against a typical review, the cached prefix is 5,231 tokens. On the first turn the model stores those tokens. On the second turn it reuses all 5,231 and charges for 93 new input tokens instead of about 5,300. At a one-tenth cache-read rate, that makes this follow-up&apos;s input cost about 12% of the uncached input cost. Output tokens are billed separately.&lt;/p&gt;
&lt;h2 id=&quot;layer-three-retrieval-a-reason-not-to-build-a-vector-store&quot;&gt;Layer three: retrieval, a reason not to build a vector store&lt;a href=&quot;https://caskeycoding.com/blog/prompt-caching-four-layers#layer-three-retrieval-a-reason-not-to-build-a-vector-store&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The third layer answers plain-language questions over the archive of past reviews. It loads the relevant reviews, trims them, and sends the whole set to the model. The trimmed archive is the large, stable part, so it is what should be cached. The problem was ordering: the code put the question first and the archive second, and caching can only store a run that begins at the very start of the request, so an archive sitting at the end could not be stored at all. Once the archive moved to the front, a second question over the same archive reused 2,541 stored tokens instead of paying for them again.&lt;/p&gt;
&lt;p&gt;My archives still fit inside the model&apos;s context window, so sending the archive and caching it was simpler for this project than maintaining a vector database. I did not compare answer accuracy or end-to-end latency against a retrieval pipeline. The next step is to watch input size and answer quality: try a keyword filter if useful material becomes hard to find, and evaluate vector retrieval when the corpus or the questions justify it. Fitting inside the window is a capacity check, not proof that the model uses every passage well.&lt;/p&gt;
&lt;h2 id=&quot;layer-four-a-data-server-not-my-decision&quot;&gt;Layer four: a data server, not my decision&lt;a href=&quot;https://caskeycoding.com/blog/prompt-caching-four-layers#layer-four-a-data-server-not-my-decision&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The fourth layer is a private server that sends my own portfolio data to a separate model on request, over the Model Context Protocol (MCP, the open standard for exposing tools and data to a model). At this server-to-model boundary, the receiving side decides whether to cache. The server controls response size: cap the field that could grow without limit, stop sending duplicate copies of large results, and log each response&apos;s byte size. Those changes reduce context consumption. Caching separately reduces the cost of processing repeated context.&lt;/p&gt;
&lt;h2 id=&quot;what-it-saved&quot;&gt;What it saved&lt;a href=&quot;https://caskeycoding.com/blog/prompt-caching-four-layers#what-it-saved&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Surface&lt;/th&gt;
&lt;th&gt;Cached prefix&lt;/th&gt;
&lt;th&gt;New input charged, turn two&lt;/th&gt;
&lt;th&gt;Input it would have charged without caching&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Finance chat&lt;/td&gt;
&lt;td&gt;5,231 tokens&lt;/td&gt;
&lt;td&gt;93 tokens&lt;/td&gt;
&lt;td&gt;~5,300 tokens&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Corpus retrieval&lt;/td&gt;
&lt;td&gt;2,541 tokens&lt;/td&gt;
&lt;td&gt;a few dozen&lt;/td&gt;
&lt;td&gt;~2,600 tokens&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;The finance row in plain terms: at the example&apos;s one-tenth cache-read rate, the follow-up costs the equivalent of 93 + 523.1 ordinary input tokens, compared with 5,324 without caching. That is about 88% less input cost for this observed hit. The counters show that both prefixes qualified for caching in these runs; they do not establish a threshold for other model versions.&lt;/p&gt;
&lt;p&gt;Two caveats. First, volume. This is a low-traffic system, so the actual dollars saved are small, and I am not going to dress a small personal project up as a serious cost cut. The savings are real and would scale with traffic, but the traffic is not there yet.&lt;/p&gt;
&lt;p&gt;Second, and more important: I measured those reused prefixes with no delay between turns, one request sent the instant the previous one returned. A stored prefix lasts five minutes. In real use a person reads the answer, thinks, and then types the next question, and if that gap runs past five minutes the stored prefix is already gone and the next turn pays full price again. So my measurement proves the mechanism works, not that it works under real human timing. The token counter that will answer that is now running in the production logs. If the reuse is not happening, the fix is a longer storage window, which is a setting, not a redesign. I would rather read that number than guess it.&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>Composite What You Trust, Watch What You Don&apos;t: A Trust Boundary for Data With Money Attached</title>
      <link>https://caskeycoding.com/blog/composite-what-you-trust</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/composite-what-you-trust</guid>
      <pubDate>Wed, 17 Jun 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>AI</category>
      <category>finance</category>
      <category>AWS</category>
      <category>Python</category>
      <category>software-development</category>
      <category>side-projects</category>
      <description>Every system that fuses signals into one consequential number has a fault line: the data you trust enough to composite into a grade versus the data you only trust enough to watch. How I drew that boundary in my personal finance engine, and how a test keeps it honest.</description>
      <content:encoded>&lt;p&gt;A few times a quarter, one of my holdings lights up everywhere at once. StockTwits gets loud and lopsided. A prediction market reprices its next earnings overnight. The urge to act on it is immediate. So I pull up the position&apos;s &lt;a href=&quot;https://caskeycoding.com/finance/methodology&quot; class=&quot;internal-link&quot;&gt;health grade&lt;/a&gt;, the single number this whole system is built around, and it has not moved.&lt;/p&gt;
&lt;p&gt;It was built not to. That stillness is the most deliberate choice in the whole system.&lt;/p&gt;
&lt;p&gt;I wrote earlier about the first rule I gave this engine: the math decides, the AI only describes. The scoring is fixed and runs the same way every time, the AI writes the explanation, and it is never allowed to overrule a number. &lt;a href=&quot;https://caskeycoding.com/blog/building-an-ai-finance-app&quot; class=&quot;internal-link&quot;&gt;That post&lt;/a&gt; was deliberately narrow. This one is about a second rule, the one that kept the grade still while the crowd screamed: which data is allowed to touch the number, and which data only gets to sit beside it. Both rules come from the same place. There is real money attached, and the person I trust least with it is me, on a day when something is moving.&lt;/p&gt;
&lt;p&gt;This is an old trick from security engineering, where it goes by the name taint tracking: data from the outside world is treated as untrusted and kept away from the decisions that matter until something explicitly vouches for it. A grade with money riding on it is precisely the kind of decision you guard that way. Most of what I can pull off the internet has not earned that trust, so the architecture&apos;s one job at this boundary is to keep it out of the number while still keeping it in view.&lt;/p&gt;
&lt;p&gt;Here is the system on one screen. The solid arrows are the trusted core, the only data allowed to reach a grade. The dashed arrows are the watched perimeter: signals I want in front of me, wired so they can never move the number.&lt;/p&gt;
&lt;p&gt;&lt;em&gt;This post includes a diagram. &lt;a href=&quot;https://caskeycoding.com/blog/composite-what-you-trust&quot;&gt;View it on caskeycoding.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;
&lt;h2 id=&quot;one-grade-several-faces&quot;&gt;One grade, several faces&lt;a href=&quot;https://caskeycoding.com/blog/composite-what-you-trust#one-grade-several-faces&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The center of the system is a single health measurement for every position. It is composited only from sources I trust, and it is built so I can rotate it and read it from several angles: Quality, Valuation, Momentum, and Health. One number with several faces, not several numbers I have to reconcile by feel. It is the same engine whether I own the stock or am only researching an unheld name, with no special logic for the ones I happen to like.&lt;/p&gt;
&lt;p&gt;Those four factors are not the ones I started with. The first version of this engine graded modern companies against a value rubric written in 1949 and handed one of the most dominant firms in the market a D+. I rewrote it around modern factor research, and &lt;a href=&quot;https://caskeycoding.com/blog/when-the-spec-was-wrong&quot; class=&quot;internal-link&quot;&gt;that rewrite is its own story&lt;/a&gt;. What matters here is what feeds the result. &lt;a href=&quot;https://site.financialmodelingprep.com/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Financial Modeling Prep&lt;/a&gt; (FMP) is the source of truth underneath it: fundamentals, prices, analyst grades, and it is the only feed that flows directly into the composite.&lt;/p&gt;
&lt;p&gt;The rule from the first post still holds. A missing number never becomes a confident zero. If FMP cannot give me a real value for a factor, that factor is marked failed and its weight redistributes across the factors that still have real data, rather than scoring a hole as a zero and dragging the grade down.&lt;/p&gt;
&lt;p&gt;There is one deliberate exception, because even this rule can be gamed by absence. If the missing factor is Valuation, blind redistribution would let a company with terrible valuation slip out of the signal entirely, just by having a gap where its numbers should be. So a missing valuation is not redistributed away. It floors at a conservative default instead. The redistribution rule protects the grade from bad data; the floor protects it from absent data pretending to be neutral.&lt;/p&gt;
&lt;h2 id=&quot;the-watched-perimeter&quot;&gt;The watched perimeter&lt;a href=&quot;https://caskeycoding.com/blog/composite-what-you-trust#the-watched-perimeter&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Everything else I pull is there to be watched, not believed. I collect prediction-market data from Kalshi and Polymarket, and crowd sentiment from StockTwits. Polymarket carries most of the names, since Kalshi lists few individual tickers; the engine reads Kalshi only where it has a clean per-ticker contract and falls back to Polymarket for breadth. None of it touches the grade.&lt;/p&gt;
&lt;p&gt;That quarantine is a design decision, not an oversight. These are public signals I want to be aware of precisely because the composite is built to ignore them. The use case is narrow and specific: if prediction-market odds on a name start moving ahead of its price, I want to know before the fundamentals catch up. It is a tripwire on the edge of the system, wired to get my attention, not to move my grade. On the Today view it sits next to a position as context, never folded into it.&lt;/p&gt;
&lt;p&gt;I know the quarantine holds because a test enforces it. One of the checks in the suite swings the crowd sentiment on a ticker from cold to red hot and then asserts that the production grade comes out byte for byte identical. The watched signals can scream; the number does not flinch.&lt;/p&gt;
&lt;p&gt;In a separate experiment that never reaches the live grade, bullish chatter and high retail attention push the experimental score down. That negative sign is a hypothesis about crowd enthusiasm, not an established result for these feeds. Whether it predicts subsequent returns, over which horizon, and after costs still needs &lt;a href=&quot;https://caskeycoding.com/blog/backtesting-without-fooling-yourself&quot; class=&quot;internal-link&quot;&gt;forward testing without fooling myself&lt;/a&gt;.&lt;/p&gt;
&lt;h2 id=&quot;the-one-time-i-didnt-hold-the-line&quot;&gt;The one time I didn&apos;t hold the line&lt;a href=&quot;https://caskeycoding.com/blog/composite-what-you-trust#the-one-time-i-didnt-hold-the-line&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;I have made this mistake from the inside, which is part of why I am strict about it now.&lt;/p&gt;
&lt;p&gt;I wanted my positions to refresh onto the screen automatically instead of by hand, so I reached for Plaid. Before I built anything, I asked an AI coding assistant whether Plaid supported Fidelity, and it told me yes. I had just spent a whole post explaining that I built this system around never trusting a confident, unverified claim. Then I trusted exactly one.&lt;/p&gt;
&lt;p&gt;I did the real work on the strength of it. Getting application access to Plaid is not a weekend toy. I hardened the app to qualify, wrote terms-and-conditions pages, produced user guides for my own system, and stood up the consent surface a real integration needs. I got a sandbox working end to end. It felt close. Then I moved to production, logged in from the live side, and found that the only Fidelity entity supported was Fidelity Charitable, the donor-advised-fund arm. Not the brokerage. I lost a day or two.&lt;/p&gt;
&lt;p&gt;I call it a successful failure for two reasons. The integration and hardening work is real and reusable, so if I ever do want hands-free account linking I have already been through the approval gauntlet once. And the dead end clarified something I had not fully admitted to myself: I am not sure I want an AI reading my spending habits just yet. So today I enter positions and trades by hand. The failure turned the manual path into a deliberate choice instead of a fallback, and it left me a standing reminder of what a single unverified yes can cost.&lt;/p&gt;
&lt;h2 id=&quot;the-boundary-that-runs-through-me&quot;&gt;The boundary that runs through me&lt;a href=&quot;https://caskeycoding.com/blog/composite-what-you-trust#the-boundary-that-runs-through-me&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;There is one more boundary in here, and it is the one I am proudest of, because it runs between me and myself. When I open a position I pre-register the thesis: the catalyst, what I think is already priced in, a benchmark, a target, a stop, and a probability. Those fields freeze at commit time. The record is append-only and the row is never overwritten, so I cannot quietly edit yesterday&apos;s reasoning to match today&apos;s outcome. The storage layer simply will not let me. When a position resolves, it books the realized return against the frozen forecast and, on a loss, files a post-mortem.&lt;/p&gt;
&lt;p&gt;The difficulty is not the design, it is the upkeep: keeping the journal in step with the live portfolio as I trade. I am actively brainstorming systematic ways to capture it at stock-update time, so the pre-registration happens with as little manual friction as possible instead of being a separate chore I have to remember.&lt;/p&gt;
&lt;h2 id=&quot;where-the-line-is&quot;&gt;Where the line is&lt;a href=&quot;https://caskeycoding.com/blog/composite-what-you-trust#where-the-line-is&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The boundary is the right default, and like any default it is wrong in specific places.&lt;/p&gt;
&lt;p&gt;Quarantine too aggressively and you blind yourself to real information. Prediction markets and crowd attention are noisy, but they are not nothing, and a system that refused to even display them would miss the occasional moment when the edge of the network knows something before the fundamentals do. The answer is not to ignore the signal. It is to watch it without letting it vote.&lt;/p&gt;
&lt;p&gt;Composite too eagerly and you do the opposite damage: you launder a rumor into a number. The instant a soft signal earns a weight in the grade, it inherits all the authority of the hard ones, and a reader, including me, can no longer tell which part of the score they should actually believe. One authoritative number that secretly blends a balance sheet with a message board is worse than two honest numbers kept apart.&lt;/p&gt;
&lt;p&gt;Some data sits deliberately in between. My net worth is real and trusted, but it does not feed any grade. It sets context. A position that is 10% of the trading account might be 3% of everything I own and owe, and that changes how much the grade should worry me without changing the grade itself. Trusted enough to interpret the number, not to compute it.&lt;/p&gt;
&lt;p&gt;The same suspicion runs one level deeper, into the rules themselves. The weights that turn factors into a grade are not free to drift. No change to the scoring logic reaches production without a human signing off, because the recipe that converts data into a verdict deserves at least as much scrutiny as the data going into it.&lt;/p&gt;
&lt;h2 id=&quot;the-test&quot;&gt;The test&lt;a href=&quot;https://caskeycoding.com/blog/composite-what-you-trust#the-test&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;So here is the test I would hand anyone building a system that turns many signals into one consequential number. Point at the number and ask: can you separate the inputs you would stake money on from the ones you are only watching? If you cannot, the number is blending them, and it is lying to you with a straight face.&lt;/p&gt;
&lt;p&gt;This is not really about finance. Any system that fuses signals into a single verdict has the same fault line: a credit decision, an anomaly score, an incident severity, a model that ranks anything that matters. The durable move is the same one the rest of this engine is built on. Decide what gets to count before you are under pressure, keep the rest where you can see it but it cannot vote, and write the boundary down so a test can defend it when you are tempted to soften it later.&lt;/p&gt;
&lt;h3 id=&quot;related&quot;&gt;Related&lt;a href=&quot;https://caskeycoding.com/blog/composite-what-you-trust#related&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;https://caskeycoding.com/blog/building-an-ai-finance-app&quot; class=&quot;internal-link&quot;&gt;Building a Personal Finance Reviewer: What Survived the Rewrite&lt;/a&gt;: the first boundary, between the parts that decide and the parts that describe.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://caskeycoding.com/blog/when-the-spec-was-wrong&quot; class=&quot;internal-link&quot;&gt;When the Spec Was Wrong: Rewriting a Shipped Decision&lt;/a&gt;: why these four factors, and what grading modern companies against a 1949 rubric got wrong.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://caskeycoding.com/blog/backtesting-without-fooling-yourself&quot; class=&quot;internal-link&quot;&gt;How to Backtest Without Fooling Yourself&lt;/a&gt;: whether any of the watched signals actually predicts anything, tested forward without cheating.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Further reading, the sources behind the factors:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Asness, Frazzini, and Pedersen, &lt;a href=&quot;https://doi.org/10.1007/s11142-018-9470-2&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Quality Minus Junk&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;Bailey and Lopez de Prado, &lt;a href=&quot;https://papers.ssrn.com/sol3/papers.cfm?abstract_id=2460551&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;The Deflated Sharpe Ratio&lt;/a&gt;, on not mistaking a lucky backtest for an edge.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://pages.stern.nyu.edu/~adamodar/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Aswath Damodaran&lt;/a&gt; for valuation done seriously.&lt;/li&gt;
&lt;/ul&gt;</content:encoded>
    </item>
    <item>
      <title>Builder&apos;s Patience: The Knicks Are Champions Again</title>
      <link>https://caskeycoding.com/blog/knicks-champions-builders-patience</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/knicks-champions-builders-patience</guid>
      <pubDate>Sun, 14 Jun 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>basketball</category>
      <category>knicks</category>
      <category>personal</category>
      <category>patience</category>
      <category>building</category>
      <description>The Knicks won their first title since 1973, decades before I was born. A lifelong fan on the grandfather who handed down the wait, the lean years that taught patience, and the roster I half-built in my head a decade before it came true.</description>
      <content:encoded>&lt;p&gt;The New York Knicks are NBA champions. The last time that sentence was true, it was 1973. I have spent my whole life waiting for it, and I inherited the wait from my grandfather, who spent his.&lt;/p&gt;
&lt;p&gt;This is a personal one. The thread, if you want a professional one, is the same instinct that runs through everything I build: patience, long horizons, and the humility to know the best outcomes still surprise you. But mostly this is about a basketball team I have loved through a lot of losing.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/knicks-champions-builders-patience-arc.svg&quot; alt=&quot;A timeline from 1973, the last title, through the 1999 near-miss in red, to a green-ringed 2026, champions again, with the fifty-three-year span measured beneath the line.&quot;&gt;&lt;/p&gt;
&lt;h2 id=&quot;the-ball-on-the-shelf&quot;&gt;The ball on the shelf&lt;a href=&quot;https://caskeycoding.com/blog/knicks-champions-builders-patience#the-ball-on-the-shelf&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;My grandfather spent his days watching the championship Knicks, the ones with Walt Frazier and Willis Reed. He passed down an image of that team, and more than that he passed down the way he talked about them, the way Clyde controlled a game and the night Reed limped out of the tunnel and the building came apart. He gave me a basketball signed by Willis Reed. It has sat on a shelf my entire life as a kind of promise: this team was great once, and it could be again, and you should stick around to see it.&lt;/p&gt;
&lt;p&gt;He waited a long time for this one. I like to think he is watching tonight, keeping score the way he taught me to.&lt;/p&gt;
&lt;h2 id=&quot;the-lean-years-did-the-teaching&quot;&gt;The lean years did the teaching&lt;a href=&quot;https://caskeycoding.com/blog/knicks-champions-builders-patience#the-lean-years-did-the-teaching&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;I did not get the great Knicks. I got the ones that taught patience the hard way.&lt;/p&gt;
&lt;p&gt;I watched Latrell Sprewell and the 1999 Knicks claw out of the eight seed all the way to the Finals, then run into the Spurs and lose. Close enough to ache. After that came the years I followed the team mostly through box scores, reading about the Stephon Marbury trade and the Eddy Curry trade and convincing myself each one was the turn. They were not. I wrote during Linsanity, when Jeremy Lin made February feel like a playoff run. I remember being thrilled the night Chris Duhon broke the franchise single-game assist record, which tells you exactly how lean those years were. You learn to find the joy in the scraps when the meal never comes.&lt;/p&gt;
&lt;p&gt;That is the part that doesn&apos;t fit on a highlight reel. Most of being a Knicks fan was not winning. It was showing up anyway.&lt;/p&gt;
&lt;h2 id=&quot;the-roster-i-drafted-in-my-head&quot;&gt;The roster I drafted in my head&lt;a href=&quot;https://caskeycoding.com/blog/knicks-champions-builders-patience#the-roster-i-drafted-in-my-head&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;For years I built this team in NBA 2K, in GM mode, over and over, constructing dynasties out of a franchise that could not construct one in real life. And in those builds, two players were always on my board: OG Anunoby and Karl-Anthony Towns. OG for the pure athleticism, and because he played at Indiana, my favorite basketball school. KAT because he is from New Jersey, and because he might be the best three-point shooting big in the game while still doing the dirty work in the paint. A two-way wing and a skilled big who can shoot. I knew the shape of the team I wanted before the front office did.&lt;/p&gt;
&lt;p&gt;When the real Knicks traded for OG and then for KAT, I felt something strange, like watching a spec get implemented by someone else. I had foreseen those pieces. What I did not foresee was the engine that actually drives this title: the Villanova core, Jalen Brunson and Josh Hart and Mikal Bridges, a group of guys who already knew how to win together before they got here. That part reality wrote better than I did.&lt;/p&gt;
&lt;p&gt;And hats off to Leon Rose, because the real credit belongs to him. While I was running simulations, he was doing the actual work. A former agent took over a franchise that had been a punchline and built it one move at a time: Brunson, Hart, OG, Bridges, KAT. It was not without a bet on the future. The &lt;a href=&quot;https://www.nba.com/knicks/news/mikal-bridges-acquired-in-trade-with-brooklyn-nets&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Bridges trade cost five future first-round picks and a swap&lt;/a&gt;. Rose spent those assets on a player who fit the team he was assembling, and that decision carried risk. I admire the builder who made that call. It was something to watch an idea I had only ever run in a simulation get implemented for real, and then extended past anything I drew up, all the way to a title.&lt;/p&gt;
&lt;p&gt;Which is the whole lesson, and the one place this touches the day job. I build systems for a living, long-horizon ones, and the way you do it is patient and deliberate, no shortcuts, the pieces assembled over years. You spec what you can foresee. OG and KAT were the parts I could see coming. But the best outcomes always arrive with something you did not script, and the discipline is to leave room for it instead of forcing your old plan over the better one in front of you. I had a plan for thirty years. The version that won was partly mine and partly a gift.&lt;/p&gt;
&lt;h2 id=&quot;goodbye-to-the-waiting&quot;&gt;Goodbye to the waiting&lt;a href=&quot;https://caskeycoding.com/blog/knicks-champions-builders-patience#goodbye-to-the-waiting&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;So the wait is over. Fifty-three years, answered. Brunson and Hart and Bridges power it, OG and KAT anchor it, and a franchise that spent my entire life as a lesson in patience finally paid the patience back.&lt;/p&gt;
&lt;p&gt;I keep looking at the Willis Reed ball on the shelf. The promise on it came due. My grandfather handed me a team and a way of waiting for it, and tonight both of those finally make sense.&lt;/p&gt;
&lt;p&gt;Goodbye to the waiting. Hello, champions.&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>Hello Again, Opus</title>
      <link>https://caskeycoding.com/blog/hello-again-opus</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/hello-again-opus</guid>
      <pubDate>Sat, 13 Jun 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>AI</category>
      <category>claude</category>
      <category>models</category>
      <category>agents</category>
      <category>cost</category>
      <description>Four days after I said goodbye to Opus, an export-control directive pulled Fable 5 offline and the fallback became the workhorse again. What I shipped in the window, what it cost, and the model-tiering plan for when Fable comes back.</description>
      <content:encoded>&lt;p&gt;Four days ago I &lt;a href=&quot;https://caskeycoding.com/blog/goodbye-opus-hello-fable&quot; class=&quot;internal-link&quot;&gt;said goodbye to Opus&lt;/a&gt;. Fable 5 was the new top of the lineup, a config swap away, and I pointed my whole fleet at it. On Friday a &lt;a href=&quot;https://www.anthropic.com/news/fable-mythos-access&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;US export-control directive&lt;/a&gt; suspended Fable 5 and Mythos 5 globally. The fallback is the only model again. Hello again, Opus.&lt;/p&gt;
&lt;p&gt;Fable was fast and real, and running everything on it burned 90% of my usage in four days. Next time: Fable thinks, Opus builds.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/hello-again-opus-tiering.svg&quot; alt=&quot;Two routing rows: judgment-heavy work flows to a green Fable box for planning and review, while routine implementation volume flows to an Opus box that does the typing at scale.&quot;&gt;&lt;/p&gt;
&lt;h2 id=&quot;the-four-day-window&quot;&gt;The four-day window&lt;a href=&quot;https://caskeycoding.com/blog/hello-again-opus#the-four-day-window&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Fable went generally available Tuesday and reached my tier the same day; the directive hit Friday. Four days, one model doing nearly everything across four product lines. What landed:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;A live insider-buying signal.&lt;/strong&gt; A SEC EDGAR collector pulling real Form 4 insider-buying into the signal pipeline, first of four crowd-signal sources.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A new research-synthesis workstream.&lt;/strong&gt; Designed end to end and closed its first three items, including a methodology writeup now live on the public track record.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;An MCP server for the finance engine.&lt;/strong&gt; A single-user server that exposes the engine to Perplexity, behind an authenticated endpoint.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A deep-research pipeline.&lt;/strong&gt; Routes hard questions through Perplexity&apos;s Sonar, synthesizes with Claude behind a hard spend cap, and runs on a schedule.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Upgraded public demos.&lt;/strong&gt; Coach charts and chat, committee bars.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Account hardening, remediated the same day.&lt;/strong&gt; CloudTrail, GuardDuty, Access Analyzer, a spend budget, repo rulesets across ten repos, Dependabot and secret scanning, found and fixed in one pass.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A finished tooling epic.&lt;/strong&gt; Narration v2, portfolio briefs and narrative, automated board-brief generation, every item merged and flipped live.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;That is a lot of ground, most of it long-horizon, multi-repo work that used to need me re-anchoring the agent around hour three. Fable held the plot. The goodbye post predicted it: when the model stops losing invariants over long runs, the bottleneck moves to the harness. For four days, it did.&lt;/p&gt;
&lt;h2 id=&quot;what-it-cost&quot;&gt;What it cost&lt;a href=&quot;https://caskeycoding.com/blog/hello-again-opus#what-it-cost&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;It was also the most expensive four days I have run. Fable was included in my subscription, but it eats the usage cap roughly twice as fast as Opus 4.8 (the community&apos;s number, consistent with mine). By Friday I was at 90% of my allotment, before the directive even landed. If Anthropic had not pulled Fable, my own cap would have.&lt;/p&gt;
&lt;p&gt;I ran &lt;em&gt;everything&lt;/em&gt; on it, including work that did not need a frontier model. Much of the four days was autonomous backlog loops: &lt;code class=&quot;inline-code&quot;&gt;/loop /backlog&lt;/code&gt; picking the next item and implementing it, hour after hour. Most are routine. Wire a collector, add a tab, flip a flag, write the tests. That is implementation, not reasoning, and a model burning the cap at double rate bought me little on the easy items.&lt;/p&gt;
&lt;p&gt;The lesson is one I skipped in the rush to use the new model: match the model to the task, especially when the model is expensive and the loop is autonomous. An autonomous loop is a cost amplifier; it does not get tired and stop. Point a premium model at mostly-easy work and walk away, and its whole job becomes burning the cap fast. The cap resets next cycle; the habit that drained it does not. That is the part worth fixing.&lt;/p&gt;
&lt;h2 id=&quot;the-plan-for-next-time&quot;&gt;The plan for next time&lt;a href=&quot;https://caskeycoding.com/blog/hello-again-opus#the-plan-for-next-time&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Fable will come back. There is a timing wrinkle: on June 23 it leaves the subscription plans and becomes API usage credits only ($10/M input, $50/M output). But that looks temporary: Anthropic has reportedly signaled it may extend the date and return Fable to the plans, and the suspension is a separate, hopefully short, story. So I won&apos;t over-engineer around a metered window that may not last. Subscription or meter, the lesson is the same, because the burn rate is: Fable is a turbo mode, not a daily driver.&lt;/p&gt;
&lt;p&gt;I am not the only one doing this math. The loudest thread in the Claude Code community right now is not &quot;how good is Fable,&quot; it is &quot;&lt;a href=&quot;https://www.reddit.com/r/ClaudeCode/s/QtmOBX3RDQ&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;will you actually pay for Fable 5 via API usage credits after June 23rd?&lt;/a&gt;&quot; The answers circle one instinct: &quot;Fable orchestrates&quot; a cheaper model underneath, a &quot;temporal turbo mode&quot; to lean on while it lasts. Right, but half-formed. The missing half is a rule for &lt;em&gt;when&lt;/em&gt; you hit the boost.&lt;/p&gt;
&lt;p&gt;The principle holds regardless of platform. &lt;strong&gt;Fable thinks, Opus builds.&lt;/strong&gt; Reserve the frontier model for work where its judgment changes the outcome; let the workhorse carry the volume. Three changes make that a rule, not a good intention.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;1. Tier the work, not the fleet.&lt;/strong&gt; Opus by default: routine implementation, refactors, tests, the long tail of items that are clear once the design is settled. Fable for the hard stuff: architecture, spec design, ambiguous debugging, the planning step of an epic, the PR that scares me. The goodbye post had this shape as &lt;code class=&quot;inline-code&quot;&gt;human_gate&lt;/code&gt; placement, gates where the model lost the plot. The same idea works for cost, as a &lt;strong&gt;model gate&lt;/strong&gt;: most items run on Opus; an item tagged hard, or the plan-and-review bookends of an epic, get the boost.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;2. Make the backlog loop a plan-with-Fable, build-with-Opus pipeline.&lt;/strong&gt; The loop that ate my cap should not run end-to-end on the turbo model. Spend Fable once per epic on the expensive-but-rare parts: read the spec, sequence the items, flag the hard ones, write the design notes. Then let Opus grind the implementation. That is the community&apos;s &quot;Fable orchestrates, cheaper model executes,&quot; wired into the orchestrator instead of left to my discipline.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;3. Put the budget guard in the loop, not just my head.&lt;/strong&gt; A 90%-in-four-days burn should trip something automatic. Make the loop cap-aware: past a threshold, finish on Opus and escalate to Fable only on an explicit hard tag. Same pattern as the hard dollar guard already on my Perplexity path, and it works whichever way Fable is billed. I trust that guard because it is in code. My restraint mid-loop is not, and four days proved it.&lt;/p&gt;
&lt;h2 id=&quot;goodbye-again-for-now&quot;&gt;Goodbye again, for now&lt;a href=&quot;https://caskeycoding.com/blog/hello-again-opus#goodbye-again-for-now&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Opus is the default again, except now I have seen the ceiling and have a plan to reach it without burning the budget. The goodbye post ended with &quot;Fable, start telling.&quot; It told: a fifty-million-line migration in a day for Stripe, and four days of my backlog in four days. Then the directive cut it short, which is its own kind of fitting: the model that moved the long-horizon ceiling is the one a government most wants on a short leash.&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>Autonomy is mostly knowing when to stop</title>
      <link>https://caskeycoding.com/blog/autonomy-is-mostly-knowing-when-to-stop</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/autonomy-is-mostly-knowing-when-to-stop</guid>
      <pubDate>Tue, 09 Jun 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>AI</category>
      <category>claude-code</category>
      <category>claude-fable</category>
      <category>autonomous-agents</category>
      <category>orchestration</category>
      <category>spec-driven-development</category>
      <description>I handed a backlog to Claude Fable, told it once it could merge, and let it run. It shipped seventeen items across five repos. The line that mattered was not in the work it finished. It was in the work it refused to touch.</description>
      <content:encoded>&lt;p&gt;A couple of weeks ago I wrote that &lt;a href=&quot;https://caskeycoding.com/blog/an-orchestration-mode-is-only-as-good-as-its-backlog&quot; class=&quot;internal-link&quot;&gt;an orchestration mode is only as good as its backlog&lt;/a&gt;. That mode multiplies effort within a single task. Deciding which tasks exist, in what order, and where to stop is a different layer that sits above it, and that layer was on me. So I built it, handed the work-list to Claude Fable 5, told it once that it could merge its own pull requests, and let it run on a self-paced loop.&lt;/p&gt;
&lt;p&gt;It shipped seventeen items across five repositories, nineteen pull requests, all merged. The instinct is to read that number as the result. It is not. The number that mattered does not appear in the merged column at all. It is the count of items the agent refused to touch, and the reason it refused.&lt;/p&gt;
&lt;p&gt;The thesis I keep landing on: when execution gets cheap, the engineering moves to the edges. Not what the agent builds, but what you have told it building means, what it should ignore, and where it has to stop. A capable model will grind through any well-formed list. The scarce input is judgment about boundaries, and the sharpest form of that judgment is the stop.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/autonomy-is-mostly-knowing-when-to-stop-the-stops.svg&quot; alt=&quot;Backlog lanes flowing toward a dashed boundary line: the merged work, seventeen items across nineteen pull requests, crosses it, while two lanes stop exactly at the line in green, one blocked because the spec was missing and four deferred behind human gates.&quot;&gt;&lt;/p&gt;
&lt;h2 id=&quot;the-file-is-the-program&quot;&gt;The file is the program&lt;a href=&quot;https://caskeycoding.com/blog/autonomy-is-mostly-knowing-when-to-stop#the-file-is-the-program&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The setup is small. One file, &lt;code class=&quot;inline-code&quot;&gt;BACKLOG.md&lt;/code&gt;, and the prompt that drives the run is a single line: work the next eligible item per the loop protocol in &lt;code class=&quot;inline-code&quot;&gt;BACKLOG.md&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;The protocol lives inside the file. The header is the rules, written as six steps: take the lowest-numbered ready item whose dependencies are done, branch, do the work, verify, open a pull request, merge if you are authorized and the checks are green, update the status, repeat. Below it is the list of items, each with a status, its dependencies, and concrete acceptance criteria.&lt;/p&gt;
&lt;p&gt;Because the rules are in the file, the loop re-reads its own instructions every iteration. There is no harness holding state in memory between runs. The state is the file. Edit it mid-run and the next iteration picks up the change. That is what makes it safe to leave alone, because there is exactly one place to look to know what it thinks it is doing.&lt;/p&gt;
&lt;h2 id=&quot;one-iteration-end-to-end&quot;&gt;One iteration, end to end&lt;a href=&quot;https://caskeycoding.com/blog/autonomy-is-mostly-knowing-when-to-stop#one-iteration-end-to-end&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The discipline per item is deliberately boring. One item at a time, never a batch. The build can run as a subagent, but the loop does not take the subagent&apos;s word for it. It reruns the checks and reads the diff before merging, because a subagent reporting that tests pass is a claim, not a result.&lt;/p&gt;
&lt;p&gt;A few of the items, to make it concrete. One was porting a spend-cap design I had already validated in a throwaway sandbox into the real platform, the kind of well-specified, tedious work a loop is made for. Another was a single routing change that was listed as a dependency for four other items, so the moment it merged, the planner, the monitor, and two more agents all became eligible and the graph opened up on its own. The one I liked most was an egress sandbox: Fable built the allowlisting proxy, then reported that it could not enforce the restriction at the kernel level without root on the host, documented the actual threat model, added a startup check that warns when egress is open, and did not oversell what it had built.&lt;/p&gt;
&lt;h2 id=&quot;the-boundaries-you-write-down-once&quot;&gt;The boundaries you write down once&lt;a href=&quot;https://caskeycoding.com/blog/autonomy-is-mostly-knowing-when-to-stop#the-boundaries-you-write-down-once&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The first version flailed. Every iteration the agent re-derived the same facts. How do I run the tests here. Which branch is the default. Is this red test a regression or has it been broken forever. That rediscovery is slow, and it is where wrong guesses get in.&lt;/p&gt;
&lt;p&gt;So I added a block at the top of the file and made the first job of the run to fill it in by surveying the repos. The test and lint command. The default branch per repo, because one of my five uses &lt;code class=&quot;inline-code&quot;&gt;main&lt;/code&gt; while the rest use &lt;code class=&quot;inline-code&quot;&gt;master&lt;/code&gt;, and an agent that assumes wrong branches off nothing. The pre-existing failures to ignore, including one integration test that is red on a clean checkout, so the loop never once mistook it for damage it had caused. Whether merging is authorized. The hard rules that are enforced nowhere in the test suite: the privacy invariants, the config pairs that must ship together, the constraints you only learn by breaking them.&lt;/p&gt;
&lt;p&gt;Every line in that block is a boundary. It is me telling the agent what is true here so it does not have to guess, which is the same move as &lt;a href=&quot;https://caskeycoding.com/blog/context-architecture-beats-documentation-dumps&quot; class=&quot;internal-link&quot;&gt;context architecture&lt;/a&gt;: decide what a task is allowed to assume, then let it run inside that. Get the block right and the loop stops investigating and starts executing.&lt;/p&gt;
&lt;h2 id=&quot;the-stops&quot;&gt;The stops&lt;a href=&quot;https://caskeycoding.com/blog/autonomy-is-mostly-knowing-when-to-stop#the-stops&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Here is the part I came away thinking about.&lt;/p&gt;
&lt;p&gt;One item was to implement the encryption helpers for a privacy-sensitive feature. The agent went looking for the spec that defined the algorithms and the wire format. It searched the repos, the history, every plausible directory. The spec was not there; it lives on another machine of mine and was never synced, and the stub comments left in the repo contradicted each other on the decisions that matter. A looser setup would have stitched something plausible together. Fable marked the item blocked, wrote down exactly what it had searched and what it would need, and moved on. Refusing to invent a cryptographic design from contradictory hints was the best decision it made all day.&lt;/p&gt;
&lt;p&gt;Four more items carried a human gate: archiving a repository, spending money on cloud resources, deploying to production, anything that publishes outward. The loop is not allowed to start those. It surfaced each one, said why it was deferring, and took the next item it could actually finish.&lt;/p&gt;
&lt;p&gt;None of those were failures of the run. They were the run working. And every one of those stops was a boundary I had written into the file before it started: an acceptance criterion it could not meet, a dependency it could not reach, a gate it was not permitted to cross. The agent did not decide to stop. I had decided in advance, and it held the line.&lt;/p&gt;
&lt;p&gt;This is what spec-driven development was always for, and it took an autonomous run to make me see it plainly. The file recorded acceptance criteria, human approval gates, and known failures before the run began. SDD reads like a method for telling an agent what to build. It is at least as much a method for telling it what not to, and where the work ends. When execution was the expensive part, that second half was a nicety. Now that execution is cheap, the second half is the job.&lt;/p&gt;
&lt;h2 id=&quot;what-i-pulled-out-of-it&quot;&gt;What I pulled out of it&lt;a href=&quot;https://caskeycoding.com/blog/autonomy-is-mostly-knowing-when-to-stop#what-i-pulled-out-of-it&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Once the run was done the pattern was obviously reusable, so I extracted it into a small open tool: &lt;a href=&quot;https://github.com/CaskeyCoding/loop-harness&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;loop-harness&lt;/a&gt;. A versioned schema for the backlog and its loop protocol, and a skill that surveys a repository and writes the fitted backlog, boundary block and all. One level of generality up from a single project.&lt;/p&gt;
&lt;p&gt;But the tool is downstream of the idea. The leverage was never the loop, which is a dozen lines of protocol I could have written in an afternoon. It was the set of edges I drew before I ever started it. The model was not the bottleneck. It has not been the bottleneck for a while. What I bring now is the boundaries.&lt;/p&gt;
&lt;p&gt;A practical footnote, because it is the first question I get about a run like this: all of it happened on a regular Claude Code subscription, and I have not hit the plan&apos;s limits yet. Not during this run, not in the daily driving since. A self-paced loop working one item at a time turns out to live comfortably inside a subscription.&lt;/p&gt;
&lt;p&gt;Do not measure an autonomous run by what it finished. Measure it by whether it stopped where you would have.&lt;/p&gt;
&lt;p&gt;One more thread to pull, in a different direction. I extended a Perplexity trial for one specific job: a consultant view, a second model with its own finance APIs, pointed at my finance engine to cross-check the work and, where it earned it, influence the algorithms themselves. Why I pay for a second opinion when the first one is this good is the next post.&lt;/p&gt;
&lt;hr&gt;
&lt;p&gt;&lt;strong&gt;The setup this pays off:&lt;/strong&gt; &lt;a href=&quot;https://caskeycoding.com/blog/an-orchestration-mode-is-only-as-good-as-its-backlog&quot; class=&quot;internal-link&quot;&gt;An orchestration mode is only as good as its backlog&lt;/a&gt;&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;The method underneath it:&lt;/strong&gt; &lt;a href=&quot;https://caskeycoding.com/blog/context-architecture-beats-documentation-dumps&quot; class=&quot;internal-link&quot;&gt;Context architecture beats documentation dumps&lt;/a&gt;&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;The tool:&lt;/strong&gt; &lt;a href=&quot;https://github.com/CaskeyCoding/loop-harness&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;loop-harness&lt;/a&gt;, the backlog schema, the loop protocol, and the skill that generates both.&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>How to backtest without fooling yourself</title>
      <link>https://caskeycoding.com/blog/backtesting-without-fooling-yourself</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/backtesting-without-fooling-yourself</guid>
      <pubDate>Tue, 09 Jun 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>finance</category>
      <category>quant</category>
      <category>backtesting</category>
      <category>statistics</category>
      <category>Python</category>
      <category>software-development</category>
      <category>side-projects</category>
      <description>A backtest&apos;s job is not to find an edge. It is to stop you from believing in one that is not there. The toolkit I used to test my own trading engine, and the part where it killed my single best signal.</description>
      <content:encoded>&lt;p&gt;I have a personal trading engine. It scores stocks on &lt;a href=&quot;https://caskeycoding.com/finance/methodology&quot; class=&quot;internal-link&quot;&gt;a multi-factor model&lt;/a&gt; and ranks them, and for a while I wanted to answer the obvious question: does it actually predict anything? So I set out to backtest it properly.&lt;/p&gt;
&lt;p&gt;What I learned is that backtesting is not really about finding an edge. It is about not fooling yourself into believing in one. A backtest that looks great is the default outcome, not the exciting one, because almost every degree of freedom in the process bends toward a prettier number. The work is spending those degrees of freedom on honesty instead.&lt;/p&gt;
&lt;p&gt;The single best signal I found passed my in-sample checks, then failed to establish a durable out-of-sample edge. That was enough to stop me deploying it. The checks below explain how I reached that decision and what the evidence still could not settle.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/backtesting-without-fooling-yourself-gauntlet.svg&quot; alt=&quot;A signal line passing four in-sample gates, survivorship, look-ahead, significance, and costs, then stopping dead at a red out-of-sample gate, leaving only a faint remnant with an information coefficient of 0.004.&quot;&gt;&lt;/p&gt;
&lt;h2 id=&quot;score-the-dead-not-just-the-survivors&quot;&gt;Score the dead, not just the survivors&lt;a href=&quot;https://caskeycoding.com/blog/backtesting-without-fooling-yourself#score-the-dead-not-just-the-survivors&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The first distortion can be built into your list of stocks. Testing today&apos;s S&amp;#x26;P 500 members at past dates excludes companies that went bankrupt, were acquired, or left for other reasons, and includes companies before they joined. Those membership changes select a different population from the one available at the time. They can distort a ranker&apos;s result in either direction.&lt;/p&gt;
&lt;p&gt;The fix is point-in-time membership. I pulled the index&apos;s full add and remove history and reconstructed who was actually in it on each past date, then scored that set, dropouts included. Over my test window that recovered 73 names the naive approach would have silently deleted: failed banks, companies taken private, acquisition targets.&lt;/p&gt;
&lt;p&gt;Adding those names back made the reported result slightly better: the engine had assigned low scores to several companies that later failed. That sample change did not establish predictive skill. Reconstructing membership also does not prove the scored panel contains every delisting outcome. Scored-panel attrition is unquantified in this account, so the historical magnitudes below remain provisional upper-bound evidence rather than clean estimates of an edge.&lt;/p&gt;
&lt;h2 id=&quot;do-not-let-the-future-leak-in&quot;&gt;Do not let the future leak in&lt;a href=&quot;https://caskeycoding.com/blog/backtesting-without-fooling-yourself#do-not-let-the-future-leak-in&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The next lie is subtler: using information to score the past that did not exist in the past. This is look-ahead bias, and it hides in places you would never think to check.&lt;/p&gt;
&lt;p&gt;Mine was the risk-free rate. The scoring code fetched &lt;a href=&quot;https://fred.stlouisfed.org/series/DGS10&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;the current 10-year Treasury yield&lt;/a&gt;, perfectly reasonable in live scoring. But when I scored a stock as of early 2022, that fetch handed back today&apos;s rate of around 4.3 percent instead of the roughly 3 percent that actually prevailed in 2022, and that wrong rate fed straight into the valuation factor. Every historical score was contaminated by a number from the future.&lt;/p&gt;
&lt;p&gt;The fix was to force the rate that prevailed at each as-of date. Mundane, except that the same change cut the run time from eighty minutes to ten, because the live fetch had also been a per-cell network call. Removing a look-ahead leak and a performance bug turned out to be the same edit, once I started treating &quot;what did this code actually know, and when&quot; as the central question.&lt;/p&gt;
&lt;h2 id=&quot;pick-a-universe-that-can-answer-the-question&quot;&gt;Pick a universe that can answer the question&lt;a href=&quot;https://caskeycoding.com/blog/backtesting-without-fooling-yourself#pick-a-universe-that-can-answer-the-question&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;You can do everything above and still ask an unanswerable question. My engine is a ranker: its job is to say these stocks will beat those stocks. My first real test ran it on thirty large, familiar names, and the result was a flat nothing, an information coefficient indistinguishable from zero with confidence intervals wide enough to drive a truck through.&lt;/p&gt;
&lt;p&gt;Thirty familiar names gave me a narrow test with wide uncertainty. Shared market exposure does not make ranking impossible: stocks can move together and still have different returns. Varied scores did not prove that the engine worked, either. I needed to state which universe I intended to rank and measure its cross-sectional returns before interpreting the result.&lt;/p&gt;
&lt;p&gt;I expanded the research to the full index and then a point-in-time mid-cap universe of around 1,300 names. That changed the population and the research question. Because I made those choices after seeing earlier results, they belong to the exploratory history; a later confirmation needs a universe fixed in advance.&lt;/p&gt;
&lt;h2 id=&quot;correct-the-t-statistic-for-autocorrelation&quot;&gt;Correct the t-statistic for autocorrelation&lt;a href=&quot;https://caskeycoding.com/blog/backtesting-without-fooling-yourself#correct-the-t-statistic-for-autocorrelation&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;You compute an information coefficient per date, average it across dates, and calculate a t-statistic. The naive calculation assumes the per-date measurements are independent. Scores can be sticky month to month, factor performance can persist across regimes, and longer forward-return windows overlap. Positive serial correlation makes the independence-based standard error too small and can inflate the absolute t-statistic. The direction depends on the autocovariances; a correction does not always increase the standard error.&lt;/p&gt;
&lt;p&gt;The correction is &lt;a href=&quot;https://doi.org/10.2307/1913610&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;a Newey-West standard error&lt;/a&gt;, which accounts for that autocorrelation, and the difference is not academic. One of my factors showed a naive t-statistic of negative four, which looks like a screaming result. Its Newey-West t-statistic was negative 1.6, not significant at all. The &quot;signal&quot; was an artifact of treating forty autocorrelated months as forty independent facts.&lt;/p&gt;
&lt;p&gt;Correction, September 2026: those two numbers came from a scoring harness I later found had two defects, so the reading they describe is void. The mechanism stands; the worked example with clean numbers is in &lt;a href=&quot;https://caskeycoding.com/blog/newey-west-standard-errors-backtest&quot; class=&quot;internal-link&quot;&gt;What Newey-West does to a backtest t-statistic&lt;/a&gt;.&lt;/p&gt;
&lt;p&gt;The deeper lesson hiding in that number: your significance is bounded by your number of independent time periods, not your number of stocks. I could add thousands of names and tighten each date&apos;s measurement, but with roughly 45 monthly dates I had roughly 45 observations, and no amount of cross-sectional breadth changes that. More stocks make each dot more precise. Only more time gives you more dots.&lt;/p&gt;
&lt;h2 id=&quot;pre-register-or-you-will-cherry-pick&quot;&gt;Pre-register, or you will cherry-pick&lt;a href=&quot;https://caskeycoding.com/blog/backtesting-without-fooling-yourself#pre-register-or-you-will-cherry-pick&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;By this point I had looked at a lot of cells: four horizons, several factors, a couple of universes. Somewhere in that grid, something always looks good, the same way some lottery ticket always wins. If you run the whole grid and then report the prettiest cell as your finding, you have not found an edge. You have found the expected maximum of many noisy draws, and dressed it up as a result.&lt;/p&gt;
&lt;p&gt;The defense is to write the test down before you run it. Before the mid-cap run I wrote a short pre-registration: the hypothesis was that the momentum factor, which had been the most consistent signal across earlier runs, would show a positive information coefficient at the one-month and six-month horizons, with a magnitude of at least 0.03. I committed to that being the test, and to treating anything else that lit up as a new hypothesis to be tested later, not a confirmation. Real strategies have &lt;a href=&quot;https://doi.org/10.1093/rfs/hhv059&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;a t-statistic threshold of 3, not 2&lt;/a&gt;, for exactly this reason: when you have searched many candidates, the bar has to rise to account for the search.&lt;/p&gt;
&lt;h2 id=&quot;a-gross-signal-is-not-a-tradeable-one&quot;&gt;A gross signal is not a tradeable one&lt;a href=&quot;https://caskeycoding.com/blog/backtesting-without-fooling-yourself#a-gross-signal-is-not-a-tradeable-one&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;An information coefficient is a correlation, not a profit. I simulated a monthly-rebalanced long-short portfolio from the momentum signal and deducted modeled mid-cap transaction costs. The reported return remained positive under those assumptions. This was an undeployed research simulation; the cost model and unquantified scored-panel attrition limit what its figures establish.&lt;/p&gt;
&lt;p&gt;But then I computed the t-statistic of the portfolio&apos;s return itself. The Sharpe ratio was 0.42; using the simple independent-return relationship over fewer than four years gives a t-statistic of about 0.8. &lt;a href=&quot;https://doi.org/10.2469/faj.v58.n4.2453&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Serial dependence changes that relationship&lt;/a&gt;. The portfolio&apos;s mean return was not distinguishable from zero in this test. The IC and the portfolio return measure different outcomes: a cross-sectional association does not establish that a particular portfolio construction earns a positive return after costs.&lt;/p&gt;
&lt;h2 id=&quot;the-test-that-actually-matters&quot;&gt;The test that actually matters&lt;a href=&quot;https://caskeycoding.com/blog/backtesting-without-fooling-yourself#the-test-that-actually-matters&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Everything so far is in-sample: I formed my hypotheses on the same 2022-to-2025 data I was testing them on. The real test is whether a signal holds on data that played no part in finding it.&lt;/p&gt;
&lt;p&gt;So I rebuilt the pipeline on 2015 to 2021, a period I had never looked at. I had to fetch deeper price history to do it. The older universe was tilted toward survivors, an unresolved selection bias whose direction I had not measured. That limits what this test can establish.&lt;/p&gt;
&lt;p&gt;The in-sample momentum signal had been my crown jewel. It was pre-registered. It held up when I split the sample in half. It cleared the strict t-statistic-of-3 bar at the six-month horizon. It survived transaction costs. By every in-sample measure it looked like a real edge.&lt;/p&gt;
&lt;p&gt;Out of sample, the one-month information coefficient fell from 0.035 to 0.007 and the six-month from 0.075 to 0.004. Neither was distinguishable from zero in that test. I had not established a durable edge, so I did not have a basis for deploying the signal. That decision does not prove the true effect is zero. As the &lt;a href=&quot;https://www.amstat.org/asa/files/pdfs/P-ValueStatement.pdf&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;American Statistical Association explains&lt;/a&gt;, significance alone does not measure an effect&apos;s size or establish a hypothesis. A fuller result would report confidence intervals and address the older panel&apos;s selection bias.&lt;/p&gt;
&lt;h2 id=&quot;what-the-apparatus-is-for&quot;&gt;What the apparatus is for&lt;a href=&quot;https://caskeycoding.com/blog/backtesting-without-fooling-yourself#what-the-apparatus-is-for&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;I spent weeks backtesting a trading engine and did not establish a durable edge. That left me with a useful decision: the evidence did not justify trading this signal. Rejecting deployment did not require pretending I had proved the absence of every possible effect.&lt;/p&gt;
&lt;p&gt;In quantitative finance the base rate is no edge: most people who test carefully find nothing, and most people who &quot;find something&quot; found an overfit artifact and pay tuition to learn that later. The rare and uncomfortable skill is running the out-of-sample test that kills your own best idea and then believing it.&lt;/p&gt;
&lt;h2 id=&quot;what-the-work-actually-produced&quot;&gt;What the work actually produced&lt;a href=&quot;https://caskeycoding.com/blog/backtesting-without-fooling-yourself#what-the-work-actually-produced&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;A null result is not an empty hand. Three concrete outcomes outlived the conclusion.&lt;/p&gt;
&lt;p&gt;A reusable measurement rig: point-in-time scoring, reconstructed index membership, dependence-adjusted standard errors, cost-aware portfolio simulation, and an out-of-sample harness. Membership reconstruction still needs a scored-panel attrition check before I can call a result survivorship-controlled. Those components can support the next experiment without turning this one into proof of trading skill.&lt;/p&gt;
&lt;p&gt;A deployment stopped before I relied on an unconfirmed result. The momentum signal had a persuasive in-sample story, but the later test did not support taking it into live trading.&lt;/p&gt;
&lt;p&gt;The method itself, written down. The seven checks above are the real deliverable. The engine was just the example; the discipline transfers to any signal, any strategy, any claim that something predicts the future.&lt;/p&gt;
&lt;h2 id=&quot;what-runs-next&quot;&gt;What runs next&lt;a href=&quot;https://caskeycoding.com/blog/backtesting-without-fooling-yourself#what-runs-next&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The work is not finished. It has moved from history to the present. What I cannot test by replaying the past is the part of the engine that reads news and forms a qualitative view, because there is no honest way to reconstruct what a language model would have concluded in 2018 without leaking the future into it. That can only be measured forward.&lt;/p&gt;
&lt;p&gt;So the forward test is now live. A resolver logs every prediction the engine makes, dated and immutable, and grades it against realized returns when the future actually arrives, scoring the quantitative factors and the qualitative layer separately so I can finally see whether the judgment adds anything the numbers do not. It runs on a schedule and accumulates on its own.&lt;/p&gt;
&lt;p&gt;Significance is bounded by independent observations in time, not by the number of stocks, so a modest edge needs years, not months, to confirm or rule out. What the first year buys is not a verdict. It is a credible, dated, resolved track record, which in a field full of fabricated ones is its own kind of asset. So the next step is the least glamorous and most underrated one in all of this: wait, measure, and let the future grade the guesses. If the qualitative layer predicts nothing either, I would rather find that out in daylight than sell it in the dark. And if it predicts something, I will have what almost nobody selling an edge actually has, which is the receipts to prove it.&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>Goodbye Opus, Hello Fable</title>
      <link>https://caskeycoding.com/blog/goodbye-opus-hello-fable</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/goodbye-opus-hello-fable</guid>
      <pubDate>Tue, 09 Jun 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>AI</category>
      <category>claude</category>
      <category>models</category>
      <category>agents</category>
      <description>Anthropic shipped Claude Fable 5 and Mythos 5: same model, two names, one safeguard layer apart. What the new frontier model means for running agents in production.</description>
      <content:encoded>&lt;p&gt;Anthropic shipped &lt;a href=&quot;https://www.anthropic.com/news/claude-fable-5-mythos-5&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Claude Fable 5 and Mythos 5&lt;/a&gt; today, and Opus is no longer the top of the lineup. Fable 5 and Mythos 5 are the same underlying model. The difference is safeguards: Fable 5 ships with them on and is generally available now, while Mythos 5 has the cybersecurity safeguards removed and is restricted to Project Glasswing partners and vetted researchers. Even the names admit it. &lt;em&gt;Fable&lt;/em&gt; comes from the Latin &lt;em&gt;fabula&lt;/em&gt;, &quot;that which is told,&quot; the etymological sibling of the Greek &lt;em&gt;mythos&lt;/em&gt;. Same root, same model, two names. Naming the safety boundary instead of pretending it doesn&apos;t exist is the right call.&lt;/p&gt;
&lt;p&gt;For anyone running agents in production, this is the announcement that matters this year.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/goodbye-opus-hello-fable-two-doors.svg&quot; alt=&quot;One box labeled one underlying model, same weights, fanning out to a green Fable 5 door that is generally available and a purple Mythos 5 door for approved organizations, with a caption reading the bottleneck moves back to the harness around the model.&quot;&gt;&lt;/p&gt;
&lt;h2 id=&quot;what-changed&quot;&gt;What changed&lt;a href=&quot;https://caskeycoding.com/blog/goodbye-opus-hello-fable#what-changed&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Opus 4.x was already good enough that I delegated implementation authority to it across two product lines. Fable 5 moves the ceiling on what actually constrains agent platforms: &lt;strong&gt;long-horizon work&lt;/strong&gt;.&lt;/p&gt;
&lt;p&gt;The numbers worth caring about:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Pricing&lt;/strong&gt;: $10/M input, $50/M output. Less than half of Mythos Preview.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Scale&lt;/strong&gt;: Stripe ran a 50-million-line codebase migration in one day. Their manual estimate was two months.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Benchmarks&lt;/strong&gt;: state-of-the-art on essentially everything tested, including the top score among frontier models on Cognition&apos;s FrontierCode.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Vision&lt;/strong&gt;: Anthropic reports that it completed Pokémon FireRed with a minimal vision-only harness, without maps, navigation aids or extra game-state information. The harness still supplied the interaction with the game.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Context&lt;/strong&gt;: long-horizon reasoning across millions of tokens, with persistent memory improving outputs over time.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Research&lt;/strong&gt;: Anthropic calls Mythos 5 its first model to consistently produce novel molecular-biology hypotheses. Its internal protein-design experts reported roughly 10x acceleration in aspects of drug design. That is a vendor-reported result with a narrower scope than speeding up the whole process.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;One partner quote sums up the shift: long-horizon problems that were &quot;out of reach for earlier models&quot; are now in reach. That tracks with what I&apos;ve seen. Earlier models didn&apos;t fail on hard tasks, they failed on &lt;em&gt;long&lt;/em&gt; ones. Drift, lost invariants, forgotten constraints around hour three. If Fable 5 fixes that, the bottleneck moves from the model back to the harness.&lt;/p&gt;
&lt;p&gt;The safeguards, plainly. Fable 5 ships with three classifiers, and when one trips the response falls back to &lt;strong&gt;Opus 4.8&lt;/strong&gt;:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Cyber&lt;/strong&gt;: blocks exploitation assistance and offensive tasks.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Bio/chem&lt;/strong&gt;: blocks dual-use research with pandemic or weapons potential.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Distillation&lt;/strong&gt;: blocks capability-extraction attempts.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;They trigger in fewer than 5% of sessions, and there&apos;s a 30-day data retention requirement for safety monitoring (not training). For my workloads, agents writing TypeScript and Terraform, the practical impact rounds to zero. If you need the unguarded model for security research, Mythos 5 via Glasswing is the path. The rest of us don&apos;t get it, and that&apos;s fine.&lt;/p&gt;
&lt;p&gt;So Opus doesn&apos;t fully retire. It&apos;s the fallback model behind the classifiers.&lt;/p&gt;
&lt;h2 id=&quot;what-im-doing-about-it&quot;&gt;What I&apos;m doing about it&lt;a href=&quot;https://caskeycoding.com/blog/goodbye-opus-hello-fable#what-im-doing-about-it&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Caskey&apos;s Builder runs on Claude Code. These were my launch-day plans; the access terms below describe the June 9 announcement, not current subscription availability:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Try Builder and Critic on &lt;code class=&quot;inline-code&quot;&gt;claude-fable-5&lt;/code&gt; during the announced included-access window through June 22. The announcement said June 23 use would require usage credits unless the window was extended, with standard subscription access intended to return when capacity allowed.&lt;/li&gt;
&lt;li&gt;Re-run the dogfood specs and compare against the Opus baselines, particularly the multi-hour items that previously needed human re-anchoring.&lt;/li&gt;
&lt;li&gt;Re-evaluate &lt;code class=&quot;inline-code&quot;&gt;human_gate&lt;/code&gt; placement in the backlog. Gates exist where the model historically lost the plot. If Fable 5 holds invariants over long horizons, some of those gates are now just latency.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Goodbye, Opus. You opened a lot of PRs. Fable, start telling.&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>Context architecture beats documentation dumps</title>
      <link>https://caskeycoding.com/blog/context-architecture-beats-documentation-dumps</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/context-architecture-beats-documentation-dumps</guid>
      <pubDate>Mon, 08 Jun 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>AI</category>
      <category>context-architecture</category>
      <category>spec-driven-development</category>
      <category>multi-agent</category>
      <category>engineering-methodology</category>
      <description>Dumping the whole corpus into an AI agent makes it worse, not better. The fix is architectural: each task loads a curated slice, not everything you have. Here is the method, and the same move at three different layers: specs, sensor data, and evaluation lenses.</description>
      <content:encoded>&lt;p&gt;The instinct, when an AI agent gets something wrong, is to give it more. More docs, more examples, more of the codebase pasted into the prompt. It feels like the responsible move. It is almost always the wrong one.&lt;/p&gt;
&lt;p&gt;More context does not make an agent more correct. Past a point, it makes it worse. The agent loses the thread of the task, weights an irrelevant file as if it mattered, and produces code that is plausibly wrong in a way that is expensive to catch. The failure does not look like a refusal. It looks like a confident answer built on the wrong half of what you handed it.&lt;/p&gt;
&lt;p&gt;The thesis I keep coming back to: context architecture beats documentation dumps. The work is not writing more documentation; it is deciding what a given task is allowed to see.&lt;/p&gt;
&lt;p&gt;What makes that &lt;em&gt;architecture&lt;/em&gt; and not housekeeping is the constraint underneath it: the context window is finite, and it is the scarce resource everything else is competing for. Which also means the problem is not new. Reaching a store far larger than your working memory is one of the oldest problems in systems engineering, and the operating system solved its shape decades ago: directories to partition, paths to find what you need.&lt;/p&gt;
&lt;h2 id=&quot;why-more-makes-it-worse&quot;&gt;Why more makes it worse&lt;a href=&quot;https://caskeycoding.com/blog/context-architecture-beats-documentation-dumps#why-more-makes-it-worse&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;A coding agent does not read context the way a person skims a wiki and ignores the irrelevant parts. Everything in the window is a candidate signal. Give it the auth module, the billing service, three architecture decisions, and last quarter&apos;s migration notes, and ask it to fix a date-formatting bug, and you have not given it more help. You have given it more ways to be wrong. It can anchor on a convention from the billing service that does not apply, or reconcile two decisions that were never meant to be read together.&lt;/p&gt;
&lt;p&gt;There is also a hard ceiling, and it is the whole reason this is an engineering problem and not a filing preference: the context window is finite. It is the scarce resource every other concern is competing for. Every token spent on context the task does not need is a token not spent on the code it does, so loading a full spec package into every session crowds out the work itself. The corpus is not the asset. The right slice of it, in the window at the right moment, is.&lt;/p&gt;
&lt;p&gt;So the question stops being &quot;what does the agent need to know about the system&quot; and becomes &quot;what does &lt;em&gt;this task&lt;/em&gt; need to see, and nothing else.&quot; That is an architecture question, not a documentation one.&lt;/p&gt;
&lt;h2 id=&quot;the-method-partition-then-route&quot;&gt;The method: partition, then route&lt;a href=&quot;https://caskeycoding.com/blog/context-architecture-beats-documentation-dumps#the-method-partition-then-route&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The method has two halves. Partition the corpus, then route each task to its slice.&lt;/p&gt;
&lt;p&gt;Partitioning means the specs are organized so that a slice is a coherent, loadable unit: by service, by feature domain, by architecture layer. Not one monolithic document, and not a thousand undifferentiated files either. A partition is the amount of context one kind of task needs to be done well.&lt;/p&gt;
&lt;p&gt;Routing means a task arrives and something decides which slice it loads. The cheapest version of this is a router file at the root of each repo, a &lt;code class=&quot;inline-code&quot;&gt;CLAUDE.md&lt;/code&gt; that is forty to fifty lines, not four hundred. Identity, folder structure, and a table that maps task types to the workspace and the context file they read first. That file is the most expensive real estate in the system, because every token in it is spent on every turn of every session, forever. So it holds routing and nothing else. The heavy context lives in workspace files that load only when a task enters that workspace.&lt;/p&gt;
&lt;p&gt;Concretely, this is the filesystem, and it solves the same half the OS always did, addressing rather than relevance. A disk holds far more than memory can, so a process never maps the whole disk into itself; the OS exposes a hierarchical namespace and the process opens the path it needs. Partitioning is directories. Routing is path resolution. The &lt;code class=&quot;inline-code&quot;&gt;CLAUDE.md&lt;/code&gt; is a resolver, a workspace is a directory, and a session opens the slice it needs and leaves the rest on disk. The context window is the new scarce memory, and the discipline for reaching a large store through a small window is as old as the filesystem.&lt;/p&gt;
&lt;p&gt;The routing gives planning and implementation separate starting context and directs a session to the relevant client&apos;s specs. It still depends on the agent following those instructions. Keeping one client&apos;s files inaccessible to another session also requires access controls and checks of those controls, as &lt;a href=&quot;https://caskeycoding.com/blog/lesson-4-boundaries&quot; class=&quot;internal-link&quot;&gt;Lesson 4 explains&lt;/a&gt;. I wrote up the routing mechanics in &lt;a href=&quot;https://caskeycoding.com/blog/sdd-is-context-management&quot; class=&quot;internal-link&quot;&gt;SDD isn&apos;t about managing AI agents, it&apos;s about managing context&lt;/a&gt;.&lt;/p&gt;
&lt;h2 id=&quot;partitioning-needs-linking-or-its-just-silos&quot;&gt;Partitioning needs linking, or it&apos;s just silos&lt;a href=&quot;https://caskeycoding.com/blog/context-architecture-beats-documentation-dumps#partitioning-needs-linking-or-its-just-silos&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Partitioning has an obvious failure mode. You cut the corpus into clean slices, and then the slices stop knowing about each other. The value was never the cutting: it was that the right slice loads with the right connections still attached.&lt;/p&gt;
&lt;p&gt;So linking matters as much as partitioning, in a specific way: a link is how a task learns it needs a second slice. The routing table is itself the first and most important link: task to slice. Without it a bounded slice is an orphan, because nothing connects the work to the context. Partitioning makes the slices small. The router is what makes them findable.&lt;/p&gt;
&lt;p&gt;The sharper case is the seam between two slices that have to move together. I have hit this on my own stack. A CloudFront rewrite function was pinned to one trailing-slash setting while the framework config flipped to the other, and for a few hours every sub-route on the site served the home page. Two partitions, two sides of one contract, no explicit link between them, so they drifted, and production broke. (&lt;a href=&quot;https://caskeycoding.com/blog/phone-first-production-from-a-phone&quot; class=&quot;internal-link&quot;&gt;I wrote that incident up here.&lt;/a&gt;) The lesson is not &quot;stop partitioning.&quot; It is &quot;name the link.&quot; The fix was to make the two sides reference each other as a pair that changes in lockstep, so the next person editing one is pointed straight at the other.&lt;/p&gt;
&lt;p&gt;Linking is sparse and directional. The router points a task at its slice. A spec cites the decision that governs it. A config pair names its counterpart. What you do not do is wire everything to everything: that just reconstitutes the corpus you partitioned away, and you are back to dumping. The skill is choosing which seams get a link and leaving the rest unconnected, on purpose.&lt;/p&gt;
&lt;p&gt;&lt;em&gt;This post includes a diagram. &lt;a href=&quot;https://caskeycoding.com/blog/context-architecture-beats-documentation-dumps&quot;&gt;View it on caskeycoding.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;
&lt;p&gt;The solid edges are routing: each task drops into one slice. The dotted edges are the links between slices: shared conventions inherited from the hub, and the named seam between two partitions that must change together. Subtract everything else.&lt;/p&gt;
&lt;h2 id=&quot;the-same-move-three-different-layers&quot;&gt;The same move, three different layers&lt;a href=&quot;https://caskeycoding.com/blog/context-architecture-beats-documentation-dumps#the-same-move-three-different-layers&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The reason I trust this is repetition. The same move keeps paying off where the scale, the corpus, and even the &lt;em&gt;kind&lt;/em&gt; of context are completely different.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;At enterprise scale, the curated layer is specs.&lt;/strong&gt; The largest instance is around 138 spec files partitioned across roughly a dozen services by feature domain and architecture layer. The agents are not one generalist that has read everything; they are a small set of specialist agents (on the order of seven) each scoped to a layer and inheriting shared conventions from a central hub. A specialist loads something like five to eight thousand tokens of relevant context per task, not the whole corpus. The same specs serve three audiences from one source: the agents that build, the engineers who review at design time, and a generated wiki for everyone downstream. A monolithic dump could not serve any one of those well, let alone all three.&lt;/p&gt;
&lt;p&gt;That is the version with a spec corpus and a team of agents behind it, and the scale is the part that is easiest to dismiss as a big-company luxury. So strip the scale away. Two of my own projects run on the same move, and neither has a spec corpus at all. That is the actual claim: context architecture is not a discipline you earn at 138 specs. It reappears the moment an agent has to decide anything from data, which is to say almost immediately.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;In my marathon coach, the curated layer is sensor data.&lt;/strong&gt; The coach makes a go or no-go call on every workout, and the context that decides it is not my entire Garmin history. It is a deliberately narrow slice: the recovery signals that actually gate a hard session (resting heart rate, heart-rate variability, last night&apos;s sleep, training readiness) read against recent training load. That slice &lt;em&gt;is&lt;/em&gt; the architecture. When the coach tells me to back off a tempo run, it is weighing this morning&apos;s recovery against the plan; a generic plan handed the full firehose of every metric a watch emits would just run the calendar and tell me to do the tempo because it is tempo day. The curation is defensive, too: a wellness metric that fails to load stays empty rather than becoming a fake zero, because a wrong number in that slice would poison the recommendation without ever showing up as missing. I wrote that integration up &lt;a href=&quot;https://caskeycoding.com/blog/wiring-garmin-into-my-marathon-coach-live-data-integration&quot; class=&quot;internal-link&quot;&gt;here&lt;/a&gt;. It is the platform pattern one layer down: bound what the agent sees to what the decision needs.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;In my investment review tool, the curated layer is perspective.&lt;/strong&gt; A five-persona committee evaluates a position, and each persona receives only the financial dimensions relevant to its lens: the growth view is not handed the same inputs as the balance-sheet view, and none of them gets the whole dump. The scoping is the design, not a formatting choice: a moat read is grounded in the current financial indicators that bear on it, not in free-form commentary over everything at once. Give every persona the whole dump and they converge into one mushy averaged take; give each one its slice and the disagreement between them becomes the signal you were actually after.&lt;/p&gt;
&lt;p&gt;Three layers (specs, sensor data, evaluation lenses) and the same result every time. The corpus changes. The move does not: bound what the agent sees to what the task needs, and the output gets sharper, not poorer.&lt;/p&gt;
&lt;h2 id=&quot;something-has-to-read-the-slice&quot;&gt;Something has to read the slice&lt;a href=&quot;https://caskeycoding.com/blog/context-architecture-beats-documentation-dumps#something-has-to-read-the-slice&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Partitioning, routing, and linking are all about &lt;em&gt;organizing&lt;/em&gt; context. They say nothing about what consumes a slice once it loads, and that is the other half. A slice can be read by a script, a skill, an agent, or a guardrail that fires in CI, and the choice matters as much as the partition did. The test I use is determinism: push each slice to the leanest mechanism that can handle it. Deterministic, mechanical work is a script. Deterministic &lt;em&gt;enforcement&lt;/em&gt; (the checks that must never be skipped) is a hook that runs without anyone remembering to invoke it. Fixed steps with a little judgment are a skill, which is really a curated slice made executable: it loads one procedure and the minimal context that procedure needs, not the whole repo. Only open-ended judgment gets an agent.&lt;/p&gt;
&lt;p&gt;That ordering is the same discipline as the rest of this post, one level up. Routing every task to a single all-powerful agent is the execution-layer version of dumping the whole corpus: too much latitude over too much context. So you bound it (determinism down, judgment up) and you scope each agent to its slice the way you scoped the spec to its task. A standard procedure, an SOP, a deploy runbook, the written constitution I handed &lt;a href=&quot;https://caskeycoding.com/blog/orange-pi-ollama-homelab&quot; class=&quot;internal-link&quot;&gt;my Orange Pi&apos;s resident agent&lt;/a&gt;, is itself a curated slice, loaded when its task fires and not before. The strictest version of the idea is a guardrail that can only pattern-match a command, a partition of &lt;em&gt;authority&lt;/em&gt; rather than context (file permissions are the fifty-year-old version), but the same move. Which work becomes a skill, which an agent, which a hook is its own essay. The principle is the one you already have: curate what each piece sees, and curate what each piece is allowed to do.&lt;/p&gt;
&lt;h2 id=&quot;what-it-costs&quot;&gt;What it costs&lt;a href=&quot;https://caskeycoding.com/blog/context-architecture-beats-documentation-dumps#what-it-costs&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;This is not free, and pretending it is would undercut the point. The cost is the links. A task that spans partitions has to load more than one slice, and the link between them has to exist and stay current: that is real maintenance, and it carries the same drift risk a spec does. A cross-cutting change, one that touches the orchestration layer and the monitoring layer at once, only stays safe as long as the seam between them is named and both sides move together. At a dozen services that overhead is manageable. I would not claim it scales linearly forever, and I would be suspicious of anyone who did.&lt;/p&gt;
&lt;p&gt;You are trading the comfort of &quot;it&apos;s all in there somewhere&quot; for the discipline of deciding, per task, what &lt;em&gt;there&lt;/em&gt; means. That trade is worth making because the comfort was an illusion. &quot;It&apos;s all in there&quot; is exactly the condition that produces confident, wrong output.&lt;/p&gt;
&lt;h2 id=&quot;the-shape-of-it&quot;&gt;The shape of it&lt;a href=&quot;https://caskeycoding.com/blog/context-architecture-beats-documentation-dumps#the-shape-of-it&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The next time an agent gets it wrong, resist the urge to add. Ask what it should not have been looking at.&lt;/p&gt;
&lt;hr&gt;
&lt;p&gt;&lt;strong&gt;The methodology underneath this:&lt;/strong&gt; &lt;a href=&quot;https://caskeycoding.com/blog/sdd-is-context-management&quot; class=&quot;internal-link&quot;&gt;SDD isn&apos;t about managing AI agents, it&apos;s about managing context&lt;/a&gt;&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;See the shape of the system:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;https://github.com/Caskey-Coding/caskeycoding-specs-demo&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;&lt;code class=&quot;inline-code&quot;&gt;caskeycoding-specs-demo&lt;/code&gt;&lt;/a&gt;: two example spec packages and a sample &lt;code class=&quot;inline-code&quot;&gt;CLAUDE.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://github.com/Caskey-Coding/caskeycoding-specs-demo/blob/main/decision/ADR-001-spec-driven-development.md&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;ADR-001, Spec-Driven Development&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://github.com/Caskey-Coding/caskeycoding-specs-demo/blob/main/decision/ADR-002-sdd-file-structure.md&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;ADR-002, SDD File Structure&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;</content:encoded>
    </item>
    <item>
      <title>Ollama on Orange Pi 6 Plus: Setup, Speed, and Limits</title>
      <link>https://caskeycoding.com/blog/orange-pi-ollama-homelab</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/orange-pi-ollama-homelab</guid>
      <pubDate>Sat, 06 Jun 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>AI</category>
      <category>ollama</category>
      <category>local-llm</category>
      <category>homelab</category>
      <category>rag</category>
      <category>agents</category>
      <category>side-projects</category>
      <description>My Orange Pi 6 Plus setup for Ollama and local RAG: the recorded hardware, a small first test, CPU speed limits, and unresolved reliability work.</description>
      <content:encoded>&lt;p&gt;My Orange Pi 6 Plus could answer questions about my blog, but a 14B model made long answers painful. I saw roughly one or two tokens per second in the original runs. Asking it to find a passage and write a short answer gave the machine a useful job.&lt;/p&gt;
&lt;p&gt;This account draws on my June 2026 build notes, including failures recorded after the original publication. I have not rerun the board for this revision. The speeds are observations from that build, and the setup check below is a proposed starting point for a new install.&lt;/p&gt;
&lt;h2 id=&quot;the-setup-i-actually-recorded&quot;&gt;The setup I actually recorded&lt;a href=&quot;https://caskeycoding.com/blog/orange-pi-ollama-homelab#the-setup-i-actually-recorded&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Component&lt;/th&gt;
&lt;th&gt;June 2026 record&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Board&lt;/td&gt;
&lt;td&gt;Orange Pi 6 Plus, twelve ARM CPU cores&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Memory&lt;/td&gt;
&lt;td&gt;32GB tier, about 30 GiB usable&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Storage&lt;/td&gt;
&lt;td&gt;465.8GB NVMe drive&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Operating system&lt;/td&gt;
&lt;td&gt;Ubuntu 26.04 LTS&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Kernel&lt;/td&gt;
&lt;td&gt;&lt;code class=&quot;inline-code&quot;&gt;7.0.0-37-cix&lt;/code&gt;, &lt;code class=&quot;inline-code&quot;&gt;aarch64&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Ollama&lt;/td&gt;
&lt;td&gt;Version &lt;code class=&quot;inline-code&quot;&gt;0.30.4&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Inference backend&lt;/td&gt;
&lt;td&gt;CPU; logs showed &lt;code class=&quot;inline-code&quot;&gt;library=cpu&lt;/code&gt; and tensors in CPU buffers&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Original larger model&lt;/td&gt;
&lt;td&gt;&lt;code class=&quot;inline-code&quot;&gt;qwen2.5-coder:14b&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Retrieval models&lt;/td&gt;
&lt;td&gt;&lt;code class=&quot;inline-code&quot;&gt;nomic-embed-text&lt;/code&gt; for embeddings; &lt;code class=&quot;inline-code&quot;&gt;qwen2.5-coder:7b&lt;/code&gt; for answers&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;The OS and kernel identify the machine I used. They are historical configuration, not a recommendation to install those versions today. I am also not providing a tested OS-image flashing recipe. Getting a working ARM64 Linux installation on this board comes before the Ollama check.&lt;/p&gt;
&lt;p&gt;Neither the GPU nor the NPU contributed to the inference described here. Installed drivers and advertised accelerator capability would not establish otherwise. For this workload, the useful question was which backend Ollama actually loaded.&lt;/p&gt;
&lt;h2 id=&quot;start-with-one-short-local-request&quot;&gt;Start with one short local request&lt;a href=&quot;https://caskeycoding.com/blog/orange-pi-ollama-homelab#start-with-one-short-local-request&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;For a fresh attempt, I would follow the ARM64 section of &lt;a href=&quot;https://docs.ollama.com/linux&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Ollama&apos;s Linux installation instructions&lt;/a&gt;. After the server is running, I would keep its listener and the CLI client on localhost for the first check. A chat interface and access from another computer can wait until one local request works.&lt;/p&gt;
&lt;p&gt;The commands below are for a terminal on the Linux board, using the default local Ollama server. They are an instructional example, not a fresh successful run on mine. &lt;code class=&quot;inline-code&quot;&gt;gemma2:2b&lt;/code&gt; was among the smaller models installed during the June build; it gives this check a specific model tag without starting at 14B.&lt;/p&gt;
&lt;pre class=&quot;shiki shiki-themes github-light github-dark&quot; style=&quot;background-color:#fff;--shiki-dark-bg:#24292e;color:#24292e;--shiki-dark:#e1e4e8&quot; tabindex=&quot;0&quot; data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;uname&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -m&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;ollama&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; --version&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;ollama&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; pull&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; gemma2:2b&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;timeout&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; 300s&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; ollama&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; run&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; gemma2:2b&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; \&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;  &quot;In two sentences, explain why backups should be tested.&quot;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;I would expect &lt;code class=&quot;inline-code&quot;&gt;aarch64&lt;/code&gt; from the architecture check. The prompt requests a short answer, and the Linux &lt;code class=&quot;inline-code&quot;&gt;timeout&lt;/code&gt; command limits the CLI run to five minutes. That bounds the command&apos;s wait; it is not a server-side cancellation guarantee. A timeout would call for inspecting the service and its logs before adding more work. The &lt;a href=&quot;https://docs.ollama.com/cli&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Ollama CLI reference&lt;/a&gt; documents the pull and run commands.&lt;/p&gt;
&lt;p&gt;While the model is loaded, a second terminal can show its placement:&lt;/p&gt;
&lt;pre class=&quot;shiki shiki-themes github-light github-dark&quot; style=&quot;background-color:#fff;--shiki-dark-bg:#24292e;color:#24292e;--shiki-dark:#e1e4e8&quot; tabindex=&quot;0&quot; data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;ollama&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; ps&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt;journalctl&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -u&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt; ollama&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; --no-pager&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; -n&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; 100&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;In &lt;code class=&quot;inline-code&quot;&gt;ollama ps&lt;/code&gt;, the &lt;code class=&quot;inline-code&quot;&gt;PROCESSOR&lt;/code&gt; column distinguishes CPU, GPU, and mixed placement. &lt;a href=&quot;https://docs.ollama.com/faq#how-can-i-tell-if-my-model-was-loaded-onto-the-gpu&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Ollama&apos;s FAQ explains these values&lt;/a&gt;. The log command assumes a systemd service and permission to read its journal. My historical logs established CPU inference; these commands let a reader inspect their own installation.&lt;/p&gt;
&lt;p&gt;For a later timed test, the &lt;a href=&quot;https://docs.ollama.com/api/generate&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;generation API&lt;/a&gt; returns timing fields alongside the answer. &lt;code class=&quot;inline-code&quot;&gt;eval_count / (eval_duration / 1e9)&lt;/code&gt; gives generated tokens per second for a completed request. I would also record total wall-clock time, since model loading and prompt processing affect the wait at the keyboard. An answer confirms one request worked. It says little about sustained load or recovery after reboot.&lt;/p&gt;
&lt;h2 id=&quot;retrieval-gave-the-slow-model-less-to-write&quot;&gt;Retrieval gave the slow model less to write&lt;a href=&quot;https://caskeycoding.com/blog/orange-pi-ollama-homelab#retrieval-gave-the-slow-model-less-to-write&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The useful experiment was asking a question about my own writing: what rule do I use for letting an LLM make decisions, and how is it enforced? The retrieval program printed matching passages from my posts before asking the local model to compose an answer. I could inspect the source text directly.&lt;/p&gt;
&lt;p&gt;The June record says the index held seventeen posts and 171 chunks. The saved code makes the path straightforward:&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Stage&lt;/th&gt;
&lt;th&gt;Configuration in the saved implementation&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Split documents&lt;/td&gt;
&lt;td&gt;Group paragraphs toward a 900-character target; a long paragraph can exceed it&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Embed&lt;/td&gt;
&lt;td&gt;Send each chunk to local &lt;code class=&quot;inline-code&quot;&gt;nomic-embed-text&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Retrieve&lt;/td&gt;
&lt;td&gt;Embed the question and rank chunks by cosine similarity&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Build context&lt;/td&gt;
&lt;td&gt;Take the four highest-ranked chunks with their source filenames&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Generate&lt;/td&gt;
&lt;td&gt;Ask local &lt;code class=&quot;inline-code&quot;&gt;qwen2.5-coder:7b&lt;/code&gt; for an answer, capped at 200 tokens&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/orange-pi-rag.png&quot; alt=&quot;A local RAG query displays matching blog passages and an answer generated from the retrieved context&quot;&gt;
&lt;em&gt;A saved query from the build. The displayed sources make this answer inspectable; they do not establish accuracy across other questions.&lt;/em&gt;&lt;/p&gt;
&lt;p&gt;The prompt asks the model to use only the supplied context and say when it lacks the answer. The code does not validate that instruction, enforce citations, or check whether every assertion follows from a passage. I still have to read the result.&lt;/p&gt;
&lt;p&gt;Short answers made the generation delay tolerable for this use. Retrieval also let me find the passage without depending on the generated summary. For a first corpus, I would choose a few documents with known answers and include a question they cannot answer. That tests whether the search finds useful evidence and whether the model invents an answer when the evidence is missing.&lt;/p&gt;
&lt;h2 id=&quot;the-tuning-notes-do-not-prove-a-twofold-speedup&quot;&gt;The tuning notes do not prove a twofold speedup&lt;a href=&quot;https://caskeycoding.com/blog/orange-pi-ollama-homelab#the-tuning-notes-do-not-prove-a-twofold-speedup&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;I originally attributed a slowdown to KV-cache quantization. The record is less tidy: &lt;code class=&quot;inline-code&quot;&gt;q8_0&lt;/code&gt; cache quantization and flash attention changed together. The notes report a 7B rate moving between 1.2 and 3.1 tokens per second, but they also disagree about whether the measurements were taken on an idle or contended machine.&lt;/p&gt;
&lt;p&gt;Those numbers cannot isolate quantization overhead or establish a repeatable speedup. I removed the earlier causal claim. The roughly one-to-two-token rate for the 14B model remains an anecdotal reason I preferred short answers, rather than a benchmark another owner should expect to reproduce.&lt;/p&gt;
&lt;p&gt;For another tuning attempt, I would save the prompt, model digest, context length, output cap, thread settings, and runtime version. I would measure repeated warm runs with the machine otherwise idle, changing one setting at a time. The old provisioning settings are not a reliable recipe to copy forward.&lt;/p&gt;
&lt;p&gt;I have no controlled power, thermal, or price comparison from this build. It does not support a claim that this board is the fastest or cheapest way to run the workload.&lt;/p&gt;
&lt;h2 id=&quot;remote-access-was-still-a-problem-in-june&quot;&gt;Remote access was still a problem in June&lt;a href=&quot;https://caskeycoding.com/blog/orange-pi-ollama-homelab#remote-access-was-still-a-problem-in-june&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The board sometimes answered ping while SSH could not complete a session. Early notes attributed that to CPU starvation and recorded a login-service priority change and watchdog configuration. Later failures outlasted that explanation.&lt;/p&gt;
&lt;p&gt;The June 23 audit recorded restored access after a power-cycle. The June 24 audit recorded another SSH hang, with Ollama also accepting a TCP connection but failing to return an HTTP response. Power-cycling had cleared symptoms; it had not established a cause or a durable fix. These are dated observations, not a claim about the board&apos;s current condition.&lt;/p&gt;
&lt;p&gt;That changes what I would verify before leaving it unattended. I would test a new SSH login during inference, check that the intended services return after reboot, and confirm monitoring output can be read afterward. The June record never established the monitoring task&apos;s effect end to end. A queued task and a reachable port were insufficient evidence.&lt;/p&gt;
&lt;h2 id=&quot;the-hosted-maintainer-had-a-separate-boundary&quot;&gt;The hosted maintainer had a separate boundary&lt;a href=&quot;https://caskeycoding.com/blog/orange-pi-ollama-homelab#the-hosted-maintainer-had-a-separate-boundary&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;I also added a resident Claude Code agent that called a hosted model. The local retrieval path kept its documents, embeddings, and generation on the board. Running the maintainer process there did not make its inference local; context sent to that model crossed a separate data boundary.&lt;/p&gt;
&lt;p&gt;The maintainer ran under a restricted account with command checks and an approval queue. Those checks covered recognized commands on the intercepted action channel. Unrecognized command forms and other channels remained outside their coverage.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/orange-pi-control-plane.png&quot; alt=&quot;The agent control plane shows recognized privileged requests waiting for a human decision&quot;&gt;
&lt;em&gt;The approval queue for requests routed through the command checks.&lt;/em&gt;&lt;/p&gt;
&lt;p&gt;Its scheduled audit could compare observed state with the written record and update a backlog. That was useful bookkeeping. It did not establish that proposed repairs completed or that the board could recover itself.&lt;/p&gt;
&lt;p&gt;I use the same written-rule approach in my software projects. &lt;a href=&quot;https://caskeycoding.com/blog/lesson-1-the-spec-directory&quot; class=&quot;internal-link&quot;&gt;The spec-directory lesson&lt;/a&gt; shows how I keep intent, acceptance criteria, and approval in files that a fresh coding session can read.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/orange-pi-nightly-audit.png&quot; alt=&quot;A saved nightly audit shows observations, reconciled backlog items, and a commit&quot;&gt;
&lt;em&gt;One recorded audit. The later access failures limited what subsequent audits could inspect.&lt;/em&gt;&lt;/p&gt;
&lt;p&gt;Before expanding that agent&apos;s authority, I would require a monitoring task to finish, leave durable output, and have that output confirmed after a reboot. The next useful result from this build is a recovery record I can repeat.&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>Tell Me Everything That&apos;s Wrong: Validation as a Batch Operation</title>
      <link>https://caskeycoding.com/blog/tell-me-everything-thats-wrong</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/tell-me-everything-thats-wrong</guid>
      <pubDate>Thu, 04 Jun 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>validation</category>
      <category>api-design</category>
      <category>developer-experience</category>
      <category>error-handling</category>
      <category>platform-engineering</category>
      <description>Why good validation reports every problem at once instead of failing on the first one, and how to build the accumulator, phasing, and structured errors that make it work.</description>
      <content:encoded>&lt;p&gt;There is a particular kind of slow torture that software inflicts on its users, and most of us have stopped noticing it. You submit a form, a config file, a deploy. It rejects the first error it finds. You fix that one and submit again. It rejects the second. You fix that. It rejects the third. Each round trip costs you a context switch, and if the feedback loop runs over a network or a build, each one costs you minutes you will not get back.&lt;/p&gt;
&lt;p&gt;The system knew about all three problems the first time. It just didn&apos;t tell you.&lt;/p&gt;
&lt;p&gt;I keep coming back to CloudFormation as the counter-example. When you submit a template with ten mistakes, it does not stop at the first missing property. It validates the entire template and hands you back the full set. You fix ten mistakes in one pass and move on. That is a design decision about whose time matters, and it is the difference between a tool people trust and a tool people dread.&lt;/p&gt;
&lt;h2 id=&quot;the-cost-youre-actually-optimizing&quot;&gt;The Cost You&apos;re Actually Optimizing&lt;a href=&quot;https://caskeycoding.com/blog/tell-me-everything-thats-wrong#the-cost-youre-actually-optimizing&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The instinct to fail on the first error comes from a good place. In a hot request path, &lt;strong&gt;fail-fast&lt;/strong&gt; is correct: stop early, shed load, don&apos;t waste cycles on work you&apos;re going to throw away. But validation is not a hot path, and the resource you&apos;re spending is not CPU. It&apos;s human attention.&lt;/p&gt;
&lt;p&gt;The cost model is the whole argument. When you fail fast, you are optimizing for the machine&apos;s time on the unhappy path. When you collect every error, you are optimizing for the human&apos;s time across the &lt;em&gt;entire&lt;/em&gt; fix cycle. A first-error-only validator turns a single ten-second review into ten separate submit-wait-read-fix loops, and the wait in the middle is where trust goes to die. People start to experience your system as flaky even when it is behaving deterministically. The real problem is &lt;strong&gt;partial reporting&lt;/strong&gt;, but that is not how it feels from the outside.&lt;/p&gt;
&lt;p&gt;This is the same principle that makes fail-fast the wrong default for &lt;a href=&quot;https://caskeycoding.com/blog/designing-safety-guardrails-for-distributed-workflow-orchestration&quot; class=&quot;internal-link&quot;&gt;safety guardrails&lt;/a&gt;: the goal is not to exit quickly, it is to surface the full set of blocking issues so a person can fix them in one pass. Validation is that idea pointed at the user instead of the operator.&lt;/p&gt;
&lt;h2 id=&quot;collect-then-decide&quot;&gt;Collect, Then Decide&lt;a href=&quot;https://caskeycoding.com/blog/tell-me-everything-thats-wrong#collect-then-decide&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The structural change is small and it is always the same shape. Instead of returning the moment a check fails, you run every independent check, accumulate the failures, and make the proceed-or-reject decision once, at the end, against the complete set.&lt;/p&gt;
&lt;pre class=&quot;shiki shiki-themes github-light github-dark&quot; style=&quot;background-color:#fff;--shiki-dark-bg:#24292e;color:#24292e;--shiki-dark:#e1e4e8&quot; tabindex=&quot;0&quot; data-language=&quot;python&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;def&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; validate_order&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;(order):&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;    # Structural/type validation has already established a numeric quantity&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;    # and a parsed date (or no date). Batch semantic checks only here.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;    errors &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; []&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;    if&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; not&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; order.get(&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;customer_id&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;):&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;        errors.append(Error(&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;customer_id&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;, &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;required&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;, &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;Customer ID is missing&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;))&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;    if&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; order.get(&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;quantity&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;, &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;0&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;) &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;&amp;#x3C;=&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; 0&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;:&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;        errors.append(Error(&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;quantity&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;, &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;out_of_range&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;,&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;                            &quot;Quantity must be greater than 0&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;))&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;    if&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; order.get(&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;ship_date&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;) &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;and&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; order[&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;ship_date&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;] &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;&amp;#x3C;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; today():&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;        errors.append(Error(&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;ship_date&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;, &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;in_past&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;,&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;                            &quot;Ship date cannot be in the past&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;))&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;    if&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; errors:&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;        raise&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; ValidationError(errors)   &lt;/span&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;# all of them, not the first&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;    return&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; order&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The trap to avoid is the early &lt;code class=&quot;inline-code&quot;&gt;return&lt;/code&gt; or &lt;code class=&quot;inline-code&quot;&gt;raise&lt;/code&gt; buried inside each check. The instant one check can short-circuit the function, you are back to first-error-only and you have recreated the torture. Independent checks must not be allowed to serialize the user&apos;s time.&lt;/p&gt;
&lt;p&gt;&lt;em&gt;This post includes a diagram. &lt;a href=&quot;https://caskeycoding.com/blog/tell-me-everything-thats-wrong&quot;&gt;View it on caskeycoding.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;
&lt;h2 id=&quot;dont-drown-them-in-cascades&quot;&gt;Don&apos;t Drown Them in Cascades&lt;a href=&quot;https://caskeycoding.com/blog/tell-me-everything-thats-wrong#dont-drown-them-in-cascades&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;There is a failure mode on the other side, and it scares people away from batching in the first place. If you naively run every check against malformed input, one root cause can spawn fifty downstream errors. A single missing closing brace in a config file, reported as forty &quot;unexpected token&quot; errors, is &lt;em&gt;worse&lt;/em&gt; than failing fast. You have traded a short loop for a wall of noise that buries the root cause.&lt;/p&gt;
&lt;p&gt;The answer is &lt;strong&gt;phased validation&lt;/strong&gt;. You validate in layers, and you only advance to the next layer once the current one is clean. Parse first. If the syntax is broken, report the syntax errors and stop, because nothing downstream is trustworthy yet. Once it parses, run the structural and type checks as a batch. Once the shape is valid, run the semantic and cross-reference checks as a batch. Within each phase you report everything; between phases you gate, because errors in a later phase are only meaningful when the earlier phase held.&lt;/p&gt;
&lt;p&gt;Compilers have done this for decades, and it&apos;s why a good one gives you a screen of real errors instead of one cryptic line or a thousand garbage ones. The skill is knowing which checks are independent, so they can be batched, and which are derived, so they should be suppressed until their precondition holds.&lt;/p&gt;
&lt;h2 id=&quot;make-each-error-worth-reading&quot;&gt;Make Each Error Worth Reading&lt;a href=&quot;https://caskeycoding.com/blog/tell-me-everything-thats-wrong#make-each-error-worth-reading&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Batching only pays off if the batch is legible. Ten errors that each say &lt;code class=&quot;inline-code&quot;&gt;&quot;invalid input&quot;&lt;/code&gt; are not ten times more useful than one. A useful error answers three questions: &lt;em&gt;what&lt;/em&gt; is wrong, &lt;em&gt;where&lt;/em&gt; it is, and &lt;em&gt;what would make it pass&lt;/em&gt;. If a check can&apos;t answer those, it is only a boolean.&lt;/p&gt;
&lt;p&gt;That means structured errors, not concatenated strings. Give each one a stable machine-readable code, a path or pointer to the exact location, and a human-readable message. The structure is what lets a UI highlight all the bad fields at once, a CLI print a tidy table, and a CI job fail with a diagnostic someone can act on without re-running anything.&lt;/p&gt;
&lt;pre class=&quot;shiki shiki-themes github-light github-dark&quot; style=&quot;background-color:#fff;--shiki-dark-bg:#24292e;color:#24292e;--shiki-dark:#e1e4e8&quot; tabindex=&quot;0&quot; data-language=&quot;json&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;{&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;  &quot;valid&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;false&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;,&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;  &quot;errors&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;: [&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;    { &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;&quot;path&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;items[2].quantity&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;, &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;&quot;code&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;out_of_range&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;,&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;      &quot;message&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;Quantity must be greater than 0&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;, &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;&quot;got&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;-1&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; },&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;    { &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;&quot;path&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;ship_date&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;, &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;&quot;code&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;in_past&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;,&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;      &quot;message&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;Ship date cannot be in the past&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;, &lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;&quot;got&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;2026-06-01&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; }&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;  ]&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;}&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;A path like &lt;code class=&quot;inline-code&quot;&gt;items[2].quantity&lt;/code&gt; is the difference between &quot;your order is invalid&quot; and a cursor the user can jump straight to. Multiply that across a batch and you&apos;ve turned a guessing game into a checklist.&lt;/p&gt;
&lt;h2 id=&quot;where-the-line-is&quot;&gt;Where the Line Is&lt;a href=&quot;https://caskeycoding.com/blog/tell-me-everything-thats-wrong#where-the-line-is&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Batching is the right default for validation, and it is wrong in a few places. Authentication should fail fast and say little; enumerating everything wrong with a login attempt is a gift to an attacker. Anything with side effects that compound, or any check that is expensive and gated behind a cheap one, belongs in a later phase or behind fail-fast on purpose. And when checks are truly dependent, suppress the derived ones rather than reporting noise.&lt;/p&gt;
&lt;p&gt;But for the ordinary case, the form, the config, the API payload, the deploy, the bar is simple. Before you ship a validator, submit something with three mistakes in it. If it only tells you about one, you haven&apos;t finished building it. You&apos;ve just moved the rest of the work onto whoever has to use it.&lt;/p&gt;
&lt;hr&gt;
&lt;h3 id=&quot;related&quot;&gt;Related&lt;a href=&quot;https://caskeycoding.com/blog/tell-me-everything-thats-wrong#related&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;https://caskeycoding.com/blog/designing-safety-guardrails-for-distributed-workflow-orchestration&quot; class=&quot;internal-link&quot;&gt;Designing Safety Guardrails for Distributed Workflow Orchestration&lt;/a&gt;: why fail-fast is the wrong default for safety systems, and parallel evaluation with aggregation&lt;/li&gt;
&lt;/ul&gt;</content:encoded>
    </item>
    <item>
      <title>An orchestration mode is only as good as its backlog</title>
      <link>https://caskeycoding.com/blog/an-orchestration-mode-is-only-as-good-as-its-backlog</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/an-orchestration-mode-is-only-as-good-as-its-backlog</guid>
      <pubDate>Sun, 31 May 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>AI</category>
      <category>claude-code</category>
      <category>claude-api</category>
      <category>orchestration</category>
      <category>multi-agent</category>
      <category>spec-driven-development</category>
      <description>Anthropic published a guide on building a session-level orchestration mode. I built it two ways, on the CLI and on the API, and then hit the part the guide does not cover: an orchestrator that fans out is useless without a backlog of real work to fan out over.</description>
      <content:encoded>&lt;p&gt;Anthropic published a guide on &lt;a href=&quot;https://platform.claude.com/docs/en/build-with-claude/mid-conversation-effort-example&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;building an orchestration mode&lt;/a&gt;: a session-level mode that grants the model standing consent to fan out to parallel subagents, switched on and off with mid-conversation system messages. No special API parameter, just three documented pieces stacked together. I read it, built it, and then hit the input it does not supply: a queue of real, independent work for the orchestrator to fan out over.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/an-orchestration-mode-is-only-as-good-as-its-backlog-fuel.svg&quot; alt=&quot;An engine box holding the orchestration mode&amp;#x27;s three primitives, fed by a green arrow from a real backlog of independent verifiable items, with a red warning that without fuel it invents busywork.&quot;&gt;&lt;/p&gt;
&lt;h2 id=&quot;what-the-mode-actually-is&quot;&gt;What the mode actually is&lt;a href=&quot;https://caskeycoding.com/blog/an-orchestration-mode-is-only-as-good-as-its-backlog#what-the-mode-actually-is&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The clever part of the guide is that &quot;orchestration mode&quot; is an emergent behavior you assemble from three primitives:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;High effort.&lt;/strong&gt; Every request runs at a high effort level so the model optimizes for the most thorough answer rather than the cheapest one.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Mode reminders.&lt;/strong&gt; Mid-conversation system messages carry the state: a full instruction block when the mode turns on, a one-line refresher every few turns, an exit notice when it turns off. They are placed after the user turn so the cached prefix ahead of them stays intact.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Standing consent.&lt;/strong&gt; The fan-out tool&apos;s own description says that while a system message confirms the mode is on, the model should author and run a workflow by default, without stopping to ask each time.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Turn those three on together and the agent stops being polite about parallelism. It decomposes the task, spins up a wave of subagents, and synthesizes the results, every time, until you tell it to stop.&lt;/p&gt;
&lt;h2 id=&quot;our-setup-two-backends-same-pattern&quot;&gt;Our setup: two backends, same pattern&lt;a href=&quot;https://caskeycoding.com/blog/an-orchestration-mode-is-only-as-good-as-its-backlog#our-setup-two-backends-same-pattern&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;I wanted this both ways. The API version bills per token. The CLI version runs on a Claude Code subscription, which is the one I actually wanted to lean on. So I built both as one-shot tools that share the same shape.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;API.&lt;/strong&gt; A faithful port of the guide&apos;s reference implementation into a single &lt;code class=&quot;inline-code&quot;&gt;orchestration_mode.py&lt;/code&gt;. A &lt;code class=&quot;inline-code&quot;&gt;ModeAgent&lt;/code&gt; loop holds the message history and toggles the mode with &lt;code class=&quot;inline-code&quot;&gt;set_mode()&lt;/code&gt;. A &lt;code class=&quot;inline-code&quot;&gt;Workflow&lt;/code&gt; tool fans subtasks across a thread pool, capped at ten. Each subagent is its own nested loop with a shell tool and a structured &lt;code class=&quot;inline-code&quot;&gt;report_findings&lt;/code&gt; tool, isolated so one failure returns an error string instead of crashing the run. One command, one orchestrated turn, one synthesized report.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;CLI.&lt;/strong&gt; A custom &lt;code class=&quot;inline-code&quot;&gt;/orchestrate&lt;/code&gt; slash command for Claude Code. Same pattern, different plumbing:&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;API version&lt;/th&gt;
&lt;th&gt;CLI equivalent&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Custom &lt;code class=&quot;inline-code&quot;&gt;Workflow&lt;/code&gt; tool that fans out&lt;/td&gt;
&lt;td&gt;The built-in Agent / Task tool, parallel subagents&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;High effort level (&lt;code class=&quot;inline-code&quot;&gt;xhigh&lt;/code&gt;)&lt;/td&gt;
&lt;td&gt;Opus plus extended thinking (&quot;ultrathink&quot;); the exact analog is Claude Code&apos;s &lt;code class=&quot;inline-code&quot;&gt;ultracode&lt;/code&gt; mode, which pairs &lt;code class=&quot;inline-code&quot;&gt;xhigh&lt;/code&gt; with standing multi-agent consent&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Standing consent in the tool description&lt;/td&gt;
&lt;td&gt;The instructions inside the slash command&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;The command scouts the task inline first, decomposes it into independent subtasks, fans out a wave of parallel subagents, runs a second adversarial wave that checks the first wave&apos;s findings against the source, and then synthesizes. Invoking the command is itself the standing consent, which matters because the default posture is to not spawn agents unasked.&lt;/p&gt;
&lt;p&gt;Both are one-shots. You point them at a task, they multiply effort across it, you get one consolidated answer back.&lt;/p&gt;
&lt;h2 id=&quot;the-part-the-guide-leaves-out&quot;&gt;The part the guide leaves out&lt;a href=&quot;https://caskeycoding.com/blog/an-orchestration-mode-is-only-as-good-as-its-backlog#the-part-the-guide-leaves-out&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Here is where I got stuck, and it is a purpose problem, not a technical one.&lt;/p&gt;
&lt;p&gt;An orchestrator is an engine for multiplying effort across a work-list. That is the whole value: take N independent units of work, run them at once, verify them against each other, synthesize. The mode is built to treat cost as a non-constraint precisely because the payoff is supposed to be a lot of real work done in parallel.&lt;/p&gt;
&lt;p&gt;But an engine with no work-list is just an expensive way to answer one question with ten agents instead of one. If I fire &lt;code class=&quot;inline-code&quot;&gt;/orchestrate&lt;/code&gt; at a vague prompt, the model spends its first move inventing subtasks, and invented subtasks are exactly the low-value, overlapping busywork the fan-out was supposed to avoid. The mode does not supply purpose. It assumes you already have it.&lt;/p&gt;
&lt;p&gt;So the missing input is a backlog. Not a vague intention, an actual queue of independent, verifiable units of work the orchestrator can pull from and grind through. The quality of the run is bounded by the quality of that list.&lt;/p&gt;
&lt;p&gt;This lands in a familiar place for how I already work. Spec-driven development is also a backlog generator. A specs repo full of feature specs, each with acceptance criteria, is a work-list that is already decomposed into independent and verifiable units. The followups files I leave at the end of a session do the same at a smaller grain. The orchestrator does not need me to think up tasks on the spot. It needs me to keep a good backlog, and then it works through it.&lt;/p&gt;
&lt;p&gt;That is the next build.&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>Wiring Garmin Into My Marathon Coach: A Live Data Integration Without an Official API</title>
      <link>https://caskeycoding.com/blog/wiring-garmin-into-my-marathon-coach-live-data-integration</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/wiring-garmin-into-my-marathon-coach-live-data-integration</guid>
      <pubDate>Sun, 31 May 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>AI</category>
      <category>marathon</category>
      <category>running</category>
      <category>AWS</category>
      <category>Python</category>
      <category>data-integration</category>
      <category>side-projects</category>
      <description>How I replaced manual CSV exports with a live Garmin data feed for my AI marathon coach: a scheduled unofficial-API poller, resilient session handling, and the design calls that keep training and recovery data fresh and trustworthy.</description>
      <content:encoded>&lt;p&gt;I built &lt;a href=&quot;https://caskeycoding.com/coach&quot; class=&quot;internal-link&quot;&gt;an AI marathon coach&lt;/a&gt; for my 2026 NYC training block. The first version ran on manual data. I exported a CSV from Garmin Connect, uploaded it, and the coach scored my training load and recovery from that snapshot. It worked, but it had one fatal flaw for a daily-use tool: it was always stale, and keeping it fresh was my job.&lt;/p&gt;
&lt;p&gt;A coach that only knows last week&apos;s runs cannot make today&apos;s call. So I replaced the manual export with a live integration that pulls my runs and my daily recovery signals from Garmin automatically.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/wiring-garmin-into-my-marathon-coach-live-pipe.svg&quot; alt=&quot;Two rows from watch to coach: the top connected by a red dashed manual CSV export that runs when I remember, the bottom by a solid green pipe polled every 15 minutes that never turns a failed metric into a zero.&quot;&gt;&lt;/p&gt;
&lt;h2 id=&quot;the-two-feeds-that-drive-a-go-or-no-go&quot;&gt;The two feeds that drive a go or no-go&lt;a href=&quot;https://caskeycoding.com/blog/wiring-garmin-into-my-marathon-coach-live-data-integration#the-two-feeds-that-drive-a-go-or-no-go&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Every fifteen minutes, a small service wakes up, talks to Garmin, and brings two kinds of data into the coach:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Activities.&lt;/strong&gt; Each run, with date, distance, duration, average and max heart rate, elevation, and cadence. From these the coach derives pace and training load.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Daily wellness.&lt;/strong&gt; Resting heart rate, heart rate variability, sleep duration and score, body battery, stress, and training readiness. These are the recovery signals that gate whether a hard session is a good idea.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Successful polls bring the data into the dashboard without a manual export or upload. The fifteen-minute schedule describes how often the poller asks; each metric still has its own source date and availability delay.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/marathon-coach-demo-charts.webp&quot; alt=&quot;Weekly volume bars across a 16-week build with a deliberate cutback dip every fourth week, above a training calendar of daily squares shaded by distance, both rendered from the demo&amp;#x27;s sample block&quot;&gt;&lt;/p&gt;
&lt;p&gt;These are the same charts the real dashboard renders, shown here from &lt;a href=&quot;https://caskeycoding.com/lab/coach&quot; class=&quot;internal-link&quot;&gt;the public demo&lt;/a&gt; with its sample athlete. The feeds above are what keep them current without my touching anything.&lt;/p&gt;
&lt;h2 id=&quot;why-it-mattered&quot;&gt;Why it mattered&lt;a href=&quot;https://caskeycoding.com/blog/wiring-garmin-into-my-marathon-coach-live-data-integration#why-it-mattered&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The coach makes go or no-go recommendations, so I need to know which day&apos;s recovery data it used. The wellness pass described below reads finalized prior days. That does not establish that last night&apos;s sleep or this morning&apos;s resting heart rate is available for today&apos;s recommendation. Before relying on it for a hard session, I need to inspect the source dates and whether newer signals are missing.&lt;/p&gt;
&lt;p&gt;Automating the feed removes a manual step, but freshness needs its own rule: identify the source date, set an acceptable age for each metric, and withhold a current-recovery judgment when the required inputs are missing or too old. This account does not establish that the deployed coach enforces that rule.&lt;/p&gt;
&lt;h2 id=&quot;designing-for-an-api-garmin-does-not-offer&quot;&gt;Designing for an API Garmin does not offer&lt;a href=&quot;https://caskeycoding.com/blog/wiring-garmin-into-my-marathon-coach-live-data-integration#designing-for-an-api-garmin-does-not-offer&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Garmin does not offer a simple personal data API for this kind of project. There is a partner program for companies, but nothing turnkey for an individual who just wants their own numbers. So the integration stands on two community libraries that do the hard part of talking to Garmin: &lt;a href=&quot;https://github.com/matin/garth&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;garth&lt;/a&gt; for the Garmin SSO login and token refresh, and &lt;a href=&quot;https://github.com/cyberjunky/python-garminconnect&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;python-garminconnect&lt;/a&gt; for the activity and daily-wellness endpoints. Both speak to the same web endpoints the Garmin Connect site uses. It is an unofficial path, and I designed around that constraint deliberately.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;A scheduled poller, not a webhook.&lt;/strong&gt; Garmin does not push to me, so I pull. A scheduled job runs every fifteen minutes. It authenticates, lists recent activities, and writes any new ones to a database. A separate pass pulls the previous few finalized days of wellness data, because today&apos;s sleep and stress numbers are not complete until the day ends.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Reuse the session, do not re-login.&lt;/strong&gt; Logging in to Garmin repeatedly is the fastest way to get rate limited or locked out. The poller authenticates once, stores the session securely, and reuses it on every subsequent run. Re-authentication only happens when the session expires. This single decision removed almost all of the flakiness from the integration.&lt;/p&gt;
&lt;pre class=&quot;shiki shiki-themes github-light github-dark&quot; style=&quot;background-color:#fff;--shiki-dark-bg:#24292e;color:#24292e;--shiki-dark:#e1e4e8&quot; tabindex=&quot;0&quot; data-language=&quot;python&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;def&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; ensure_authenticated&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;(self):&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;    # Resume the saved session instead of logging in on every poll.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;    session &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; self&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;.session_store.load(&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;self&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;.athlete_id)&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;    if&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; session &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;and&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; not&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; session.expired:&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;        return&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; GarminConnect(session)&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;    # Only run the SSO login flow when the session is actually gone.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;    client &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; GarminConnect.login(&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;self&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;.credentials())&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;    self&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;.session_store.save(&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;self&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;.athlete_id, client.session)&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;    return&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; client&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;A rolling lookback window, not a strict cursor.&lt;/strong&gt; My instinct was to fetch only activities newer than the last successful poll. That dropped runs. A run can sync from the watch to the Garmin cloud minutes or hours after it finished, so its start time may precede the last successful poll. Fetching a recent window and deduplicating by Garmin&apos;s activity id recovers delayed syncs whose start dates remain inside that window. An older upload can still be missed; periodic deeper reconciliation would be needed to cover those uploads and older edits.&lt;/p&gt;
&lt;pre class=&quot;shiki shiki-themes github-light github-dark&quot; style=&quot;background-color:#fff;--shiki-dark-bg:#24292e;color:#24292e;--shiki-dark:#e1e4e8&quot; tabindex=&quot;0&quot; data-language=&quot;python&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;def&lt;/span&gt;&lt;span style=&quot;color:#6F42C1;--shiki-dark:#B392F0&quot;&gt; list_recent_activities&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;(self, since, until):&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;    # A run can reach Garmin&apos;s cloud after the poll that follows it, so its&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;    # start time predates the &quot;last sync&quot; watermark. Filtering on&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;    # start_time &gt; since would drop it forever. Fetch a fixed window and&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;    # dedupe by Garmin&apos;s activity id instead.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;    lookback &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; timedelta(&lt;/span&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;days&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;90&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;) &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;if&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; since &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;is&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; None&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; else&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; timedelta(&lt;/span&gt;&lt;span style=&quot;color:#E36209;--shiki-dark:#FFAB70&quot;&gt;days&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt;7&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;)&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;    window_start &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; (until &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; lookback) &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;if&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; since &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;is&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; None&lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt; else&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; min&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;(since, until &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;-&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; lookback)&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;    return&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; client.get_activities_by_date(window_start.date(), until.date())&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;Never collapse a failure to zero.&lt;/strong&gt; If a single wellness metric fails to load on a given day, that field stays empty rather than silently becoming a zero. A fake zero would poison every downstream calculation that reads it: training load, the acute to chronic workload ratio, the recommendation itself.&lt;/p&gt;
&lt;pre class=&quot;shiki shiki-themes github-light github-dark&quot; style=&quot;background-color:#fff;--shiki-dark-bg:#24292e;color:#24292e;--shiki-dark:#e1e4e8&quot; tabindex=&quot;0&quot; data-language=&quot;python&quot;&gt;&lt;code&gt;&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;# One failed metric leaves that field None, never 0. A real-looking zero&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;# would poison load, the acute:chronic ratio, and the recommendation.&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;try&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;:&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;    hrv &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt; client.get_hrv_data(day)[&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;hrvSummary&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;][&lt;/span&gt;&lt;span style=&quot;color:#032F62;--shiki-dark:#9ECBFF&quot;&gt;&quot;lastNightAvg&quot;&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;]&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;except&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; Exception&lt;/span&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;:&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;line&quot;&gt;&lt;span style=&quot;color:#24292E;--shiki-dark:#E1E4E8&quot;&gt;    hrv &lt;/span&gt;&lt;span style=&quot;color:#D73A49;--shiki-dark:#F97583&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;color:#005CC5;--shiki-dark:#79B8FF&quot;&gt; None&lt;/span&gt;&lt;span style=&quot;color:#6A737D;--shiki-dark:#6A737D&quot;&gt;  # absent, not zero&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;strong&gt;Compute load at read time, from one formula.&lt;/strong&gt; Training load is derived, not stored as ground truth. Whether a run came from the live poller or an old CSV import, the dashboard computes its load the same way when it renders. One formula, no drift between sources. This also meant that when I later fixed how load is computed, every run updated at once, with no backfill.&lt;/p&gt;
&lt;h2 id=&quot;the-bug-that-wasnt&quot;&gt;The bug that wasn&apos;t&lt;a href=&quot;https://caskeycoding.com/blog/wiring-garmin-into-my-marathon-coach-live-data-integration#the-bug-that-wasnt&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Recently a run looked missing on the dashboard and I braced for a pipeline bug. I compared two different Garmin endpoints directly, and both returned the same set the dashboard was already showing. The pipeline was faithful. The run was there the whole time. I had simply overlooked it.&lt;/p&gt;
&lt;p&gt;That is worth admitting, because the reflex when data looks wrong is to assume the system is broken. Usually it is fine, and the real gap is visibility: I could not quickly see what I did and did not have. So the fix was not in the pipeline at all. I added a run log to the dashboard with a clickable calendar, so every day reads at a glance as either a run or clearly empty.&lt;/p&gt;
&lt;p&gt;A pulled integration can only ever surface what the source actually has, so when something is missing from the source it usually points upstream, to a watch that has not finished syncing. But before blaming the platform, build the visibility to tell &quot;never recorded&quot; apart from &quot;I just missed it.&quot; This time it was the second one.&lt;/p&gt;
&lt;h2 id=&quot;where-the-pieces-came-from&quot;&gt;Where the pieces came from&lt;a href=&quot;https://caskeycoding.com/blog/wiring-garmin-into-my-marathon-coach-live-data-integration#where-the-pieces-came-from&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;If you want to build something similar, start with the two libraries that do the heavy lifting:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;https://github.com/matin/garth&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;garth&lt;/a&gt; by Matin Tamizi: the Garmin SSO login and OAuth token handling.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://github.com/cyberjunky/python-garminconnect&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;python-garminconnect&lt;/a&gt; by cyberjunky: a clean wrapper over the activity and daily-wellness endpoints.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Both are community projects that reverse-engineer the same calls the Garmin Connect web app makes, so treat the surface as unofficial and subject to change. The acute to chronic workload ratio the coach computes on top of this data comes from the sports-science literature on training load and injury risk, which is the load metric most worth getting right. The snippets above are simplified for the post; the real code adds retries, audit logging, and per-metric error handling.&lt;/p&gt;
&lt;p&gt;The coach is now reading my real training and recovery on its own, every fifteen minutes, all the way to the start line in November.&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>A Boring Design Let Me Run a Black Swan on a Tuesday</title>
      <link>https://caskeycoding.com/blog/black-swan-on-a-tuesday</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/black-swan-on-a-tuesday</guid>
      <pubDate>Thu, 28 May 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>AI</category>
      <category>finance</category>
      <category>Python</category>
      <category>risk</category>
      <category>software-development</category>
      <category>side-projects</category>
      <description>Keeping my portfolio reviewer&apos;s engine deterministic let me replay a synthetic market crash through its scoring code. The run exposed a potentially costly interaction, with a harness shortcut that limits what the result says about live behavior.</description>
      <content:encoded>&lt;p&gt;Two posts ago I made an argument that sounded a little puritanical: keep the scoring and the rules &lt;a href=&quot;https://caskeycoding.com/blog/building-an-ai-finance-app&quot; class=&quot;internal-link&quot;&gt;deterministic&lt;/a&gt; (same inputs, same outputs, no AI anywhere near the deciding seat) because the part of this that touches my money has to stay inspectable. The &lt;a href=&quot;https://caskeycoding.com/blog/when-the-spec-was-wrong&quot; class=&quot;internal-link&quot;&gt;second post&lt;/a&gt; was that same discipline throwing out a scoring model after it graded one of the best companies in the market a D+. Both were about getting an ordinary day right.&lt;/p&gt;
&lt;p&gt;That bet paid off in a way I had not planned for. I could feed a synthetic crash to the production engine and reproduce its decisions under the replay&apos;s inputs and assumptions. So one Tuesday afternoon I ran a rebuilt March 2020 through my portfolio reviewer. The replay used the real scoring code, but simplified some of the rules that make the live system wait before acting.&lt;/p&gt;
&lt;p&gt;It handed me a flaw. A real one, the kind that loses money while every test still passes, except it lost that money on paper, in a crash I made up, instead of in a real one with my savings inside it. A boring, auditable design was the only reason I could go looking for the flaw at all, and find it somewhere it could not cost me anything.&lt;/p&gt;
&lt;h2 id=&quot;what-the-reviewer-actually-grades&quot;&gt;What the reviewer actually grades&lt;a href=&quot;https://caskeycoding.com/blog/black-swan-on-a-tuesday#what-the-reviewer-actually-grades&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;A quick refresher, because the rest only makes sense if you know what the tool does. Every week it grades each holding I own, and it does not hand back a single number. It scores a stock on several separate dimensions (how good the business is, how cheap it is, how it has been trending, how solid the balance sheet looks) and shows me each of those before blending them into one letter grade.&lt;/p&gt;
&lt;p&gt;A blended B+ tells me nothing I can act on. A great business getting cheaper with collapsing momentum is a completely different situation from a weak business trading flat, even when both land on a B+. I want to see every side of a stock, not an average that hides them. The grade is the headline; the dimensions underneath it are the story.&lt;/p&gt;
&lt;h2 id=&quot;the-gate-i-was-worried-about&quot;&gt;The gate I was worried about&lt;a href=&quot;https://caskeycoding.com/blog/black-swan-on-a-tuesday#the-gate-i-was-worried-about&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;On top of those grades sits a safety gate. When the market is falling hard and fear has stayed high for a while, the gate steps in and quiets most of the sell and trim signals. The reasoning sounds obviously right when you write it down: a grading system fed nothing but falling prices will want to sell everything at the bottom, and selling everything at the bottom is the most expensive mistake a normal investor makes. So the gate holds the system&apos;s hand in exactly the moment its instincts are worst.&lt;/p&gt;
&lt;p&gt;I had tested that the gate fires. I had never tested whether it helps. Those are not the same question. Firing is one moment; helping is the whole crash and the recovery that comes after it, and I had only ever looked at the moment.&lt;/p&gt;
&lt;h2 id=&quot;a-crash-i-could-run-on-purpose&quot;&gt;A crash I could run on purpose&lt;a href=&quot;https://caskeycoding.com/blog/black-swan-on-a-tuesday#a-crash-i-could-run-on-purpose&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;A black swan is, by definition, something you have not lived through yet, so I could not sit and wait for one. But I did not have to. I had an AI agent build me a replay: a rebuilt March 2020: twelve weeks, a third of the market gone by week five, fear spiking to levels you see maybe once a decade, then a sharp bounce back toward where it started. I ran a sample portfolio through it week by week, a spicy mix with a sleeve of speculative names, the kind of allocation that makes a crash interesting.&lt;/p&gt;
&lt;p&gt;The test had to drive the actual production engine that produces buy, sell, and trim signals. Each week the replay handed it the same kind of data it sees in real life, acted on qualifying signals, and did the same for a do-nothing version that just held everything. Then it compared the two. The deterministic design made those decisions reproducible; the synthetic prices and the harness&apos;s execution rules determined how closely the run resembled a live crash.&lt;/p&gt;
&lt;h2 id=&quot;in-the-replay-doing-nothing-won&quot;&gt;In the replay, doing nothing won&lt;a href=&quot;https://caskeycoding.com/blog/black-swan-on-a-tuesday#in-the-replay-doing-nothing-won&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;In the replay, holding everything untouched through the crash and the bounce preserved more of the portfolio than running my tool did. The reviewer came out about two and a half percent behind doing nothing at all, on paper, in a crash I made up. That comparison used a harness that skipped some of the live requirement for a signal to appear two weeks running. It exposed an interaction to investigate, without measuring the full live policy&apos;s performance.&lt;/p&gt;
&lt;p&gt;The why is the part that stuck with me, because it is not what I expected. The gate is reactive by design: it watches for a drop that is already underway and fear that has already spiked, so it does not trip until the market is a week or two into falling. I assumed that lag would be its undoing, that it would kick in too late, after the system had already panic-sold near the bottom. The opposite happened. The gate tripped in week two and stayed on the whole way down, clamping most of the sell signals shut. At the very bottom, in week five, my tool was a full six percent ahead of doing nothing.&lt;/p&gt;
&lt;p&gt;Six percent ahead, but not quite for the reason the gate gets to take credit for. The tool was ahead at the bottom because it had trimmed a little into cash in the first week, before the gate clamped down, and in a crash cash beats falling stocks. What the gate itself did was stop it from trimming the rest. It refused to let the system dump the whole portfolio into the panic, which is the one mistake it exists to prevent. On the way down, that is exactly the behavior I wanted.&lt;/p&gt;
&lt;p&gt;Then the market recovered, and the system gave all of it back and then some. The gate clamps most sells, but a handful of trims are exempt, flagged important enough to fire even in a crash, and those fired every single week. Twelve weeks, twelve trims into the speculative sleeve. By the time the bounce came I was holding far less of exactly the stuff that bounced hardest. So the gate did its job on the way down, and then a side door I had left open sold off my upside on the way back up.&lt;/p&gt;
&lt;p&gt;That is worse than a bug. A bug I could fix. This was every piece working exactly as designed, and the pieces together producing something none of them intended. I had a passing test proving the gate fires when it should (drop and fear in, sell signals clamped out) and that firing was all I had ever proven. What it costs over a full round trip, once the market climbs back out, I had simply assumed.&lt;/p&gt;
&lt;h2 id=&quot;what-i-am-not-claiming&quot;&gt;What I am not claiming&lt;a href=&quot;https://caskeycoding.com/blog/black-swan-on-a-tuesday#what-i-am-not-claiming&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;This is one crash, run once. I rebuilt March 2020; I have not yet run 2008 or the dot-com unwind. Roll the dice differently and the two and a half percent could shift a point or two either way. I would not bet anything on the exact figure.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/drawdown-fattail.webp&quot; alt=&quot;A fan of simulated price paths hanging in 3D space, colored by drawdown depth, with fat-tailed runs dangling deep below the rest in yellow&quot;&gt;
&lt;em&gt;What rolling the dice looks like. This is the &lt;a href=&quot;https://caskeycoding.com/lab/drawdown-topology?regime=student-t&quot; class=&quot;internal-link&quot;&gt;drawdown topology&lt;/a&gt; from the playground, switched to fat-tailed returns: every strand is one simulated run, and the yellow ones are the runs that dig deep. My replay is one strand of a fan like this.&lt;/em&gt;&lt;/p&gt;
&lt;p&gt;And there is a bigger caveat. In real life the system makes itself wait: a signal has to show up two weeks running before it acts on it, which slows it down, especially early in a crash. My replay skipped some of that patience, so it almost certainly traded more aggressively than the real tool would. The number itself does not matter much. What matters is that a stress test surfaced a money-losing interaction between three features that each looked correct on their own, and it did it without my having to lose a real dollar in a real crash to find out.&lt;/p&gt;
&lt;h2 id=&quot;what-the-boring-design-actually-bought-me&quot;&gt;What the boring design actually bought me&lt;a href=&quot;https://caskeycoding.com/blog/black-swan-on-a-tuesday#what-the-boring-design-actually-bought-me&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Keeping the scoring and the rules deterministic (same inputs, same outputs, no AI in the deciding seat) gave me inspectability on ordinary days: the ability to ask why a stock got the grade it got. It also let me revisit the same synthetic crash and trace each decision. Matching live behavior still requires matching the inputs, state, and execution rules, including the waiting rule this replay simplified.&lt;/p&gt;
&lt;p&gt;It is also the role I keep wanting AI to play. The agent did not decide whether the gate was good or bad. It built the test rig, ran the crash, flagged where its own shortcuts fell short, and handed me the result to judge. The judgment about what to do with a tool that sells the recovery is mine, and it should be. The slow, careful plumbing is the part I am happy to hand off.&lt;/p&gt;
&lt;p&gt;So I have not shipped a fix, and that is the same discipline talking. The fix is easy to describe: teach those exempt trims that they are firing into a recovery, the same way the gate already knows it is firing into a crash, so the system stops selling the bounce. I could write it this afternoon. What I cannot write this afternoon is proof that it helps. I have watched the current behavior fail against one crash, run once, and shipping a fix on that much evidence would be the exact mistake this whole project is built to avoid: confirming that the new behavior fires and calling that proof it is better. So the fix waits until I have run it against more than one crash (the 2008 grind and the dot-com unwind among them) with the dice rolled enough times that I trust the answer. The design that let me catch the problem is the same design that lets me test the fix properly.&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>The caskeycoding.com tech stack at a glance</title>
      <link>https://caskeycoding.com/blog/architecting-caskeycoding-com</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/architecting-caskeycoding-com</guid>
      <pubDate>Mon, 25 May 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>platform</category>
      <category>aws-cdk</category>
      <category>architecture</category>
      <category>nextjs</category>
      <category>dynamodb</category>
      <category>anthropic</category>
      <description>A high-level tour of the technologies running this site: Next.js on CloudFront, Python Lambdas behind API Gateway, DynamoDB plus S3, Anthropic&apos;s API with a Bedrock fallback, and AWS CDK wiring it together.</description>
      <content:encoded>&lt;p&gt;This site is a Next.js static export on CloudFront, a small Python service on Lambda, a single DynamoDB table, an S3 content bucket, and two AI agents calling Anthropic directly. Everything is wired up with AWS CDK across four stacks split by deploy cadence: auth, agents, backend, frontend.&lt;/p&gt;
&lt;p&gt;Here is the stack, layer by layer.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/architecting-caskeycoding-com-stack.svg&quot; alt=&quot;Four stacked layers of the site, from the static frontend down to the AI agents, with a green bracket beside them labeled four CDK stacks, split by deploy cadence.&quot;&gt;&lt;/p&gt;
&lt;h2 id=&quot;frontend&quot;&gt;Frontend&lt;a href=&quot;https://caskeycoding.com/blog/architecting-caskeycoding-com#frontend&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Next.js&lt;/strong&gt; with static export, TypeScript, &lt;code class=&quot;inline-code&quot;&gt;trailingSlash&lt;/code&gt; aligned with the edge rewrite&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Playwright&lt;/strong&gt; for end-to-end tests&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Lighthouse CI&lt;/strong&gt; for performance budgets&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;edge--cdn&quot;&gt;Edge / CDN&lt;a href=&quot;https://caskeycoding.com/blog/architecting-caskeycoding-com#edge--cdn&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;CloudFront&lt;/strong&gt; distribution fronting a private S3 site bucket via origin access, HTTPS-only&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;CloudFront Functions&lt;/strong&gt; at viewer-request for extensionless URI rewrites and one retired-slug 301&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Route53&lt;/strong&gt; hosted zone with apex / &lt;code class=&quot;inline-code&quot;&gt;www&lt;/code&gt; aliases plus Google Workspace MX, SPF, and DMARC (&lt;code class=&quot;inline-code&quot;&gt;p=quarantine&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;ACM&lt;/strong&gt; for the TLS certificate&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;api--compute&quot;&gt;API &amp;#x26; compute&lt;a href=&quot;https://caskeycoding.com/blog/architecting-caskeycoding-com#api--compute&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Amazon API Gateway&lt;/strong&gt; for the dynamic surface&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;AWS Lambda&lt;/strong&gt; (Python) for the blog handler, the public demo handlers, the agent API, and the long-running orchestrator&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;AWS WAF&lt;/strong&gt; with regional, per-route rate rules on the unauthenticated &lt;code class=&quot;inline-code&quot;&gt;/public/*&lt;/code&gt; endpoints&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;data&quot;&gt;Data&lt;a href=&quot;https://caskeycoding.com/blog/architecting-caskeycoding-com#data&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Amazon DynamoDB&lt;/strong&gt;: single-table design, &lt;code class=&quot;inline-code&quot;&gt;postId&lt;/code&gt; + &lt;code class=&quot;inline-code&quot;&gt;type&lt;/code&gt; keys, &lt;code class=&quot;inline-code&quot;&gt;post&lt;/code&gt; and &lt;code class=&quot;inline-code&quot;&gt;agent_task&lt;/code&gt; items&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Amazon S3&lt;/strong&gt;: transparent content offload at 2KB so DynamoDB items stay small and read-cheap&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;auth&quot;&gt;Auth&lt;a href=&quot;https://caskeycoding.com/blog/architecting-caskeycoding-com#auth&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Amazon Cognito&lt;/strong&gt; user pool, shared via cross-stack reference to the backend&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;ai--llm&quot;&gt;AI / LLM&lt;a href=&quot;https://caskeycoding.com/blog/architecting-caskeycoding-com#ai--llm&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Anthropic API&lt;/strong&gt; (direct, official Python SDK) as the primary path
&lt;ul&gt;
&lt;li&gt;Sonnet 4.6, workhorse: generation, polish, tool loops&lt;/li&gt;
&lt;li&gt;Opus 4.7: synthesis and multi-source reasoning&lt;/li&gt;
&lt;li&gt;Haiku 4.5: routing, classification, eval-judge&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Amazon Bedrock&lt;/strong&gt;: fallback only, via a cross-region inference profile, with a Discord webhook alert when it engages&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Shared client&lt;/strong&gt; (&lt;code class=&quot;inline-code&quot;&gt;anthropic_client.py&lt;/code&gt;) owns retries, fallback, secrets, and cost accounting; agents stay thin&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;secrets--config&quot;&gt;Secrets &amp;#x26; config&lt;a href=&quot;https://caskeycoding.com/blog/architecting-caskeycoding-com#secrets--config&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;AWS Secrets Manager&lt;/strong&gt; for the Anthropic API key: no env-var secrets in prod&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;AWS Systems Manager / CDK context&lt;/strong&gt; for non-secret config&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;observability&quot;&gt;Observability&lt;a href=&quot;https://caskeycoding.com/blog/architecting-caskeycoding-com#observability&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Amazon CloudWatch&lt;/strong&gt; logs, metrics, and alarms (5xx on the static path → SNS topic)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Amazon SNS&lt;/strong&gt; for paging&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Discord webhooks&lt;/strong&gt; for human-in-the-loop alerts (LLM fallback, eval drift)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Structured &lt;code class=&quot;inline-code&quot;&gt;llm_call&lt;/code&gt; JSON logs&lt;/strong&gt;: full payloads only in non-prod; prod carries metadata plus a &lt;code class=&quot;inline-code&quot;&gt;prompt_sha256&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;testing--ci&quot;&gt;Testing &amp;#x26; CI&lt;a href=&quot;https://caskeycoding.com/blog/architecting-caskeycoding-com#testing--ci&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;pytest&lt;/strong&gt; for the Python service&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Replay / eval harness&lt;/strong&gt;: YAML cases with cached completions, runs on every PR with no API spend; a &lt;code class=&quot;inline-code&quot;&gt;--live&lt;/code&gt; mode for capturing new fixtures&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;CI pricing check&lt;/strong&gt;: fails the build if the in-repo per-model pricing table is older than 90 days&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;infrastructure-as-code&quot;&gt;Infrastructure as code&lt;a href=&quot;https://caskeycoding.com/blog/architecting-caskeycoding-com#infrastructure-as-code&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;AWS CDK&lt;/strong&gt; (TypeScript), four stacks split by blast radius:
&lt;ul&gt;
&lt;li&gt;&lt;code class=&quot;inline-code&quot;&gt;AuthStack&lt;/code&gt;: Cognito&lt;/li&gt;
&lt;li&gt;&lt;code class=&quot;inline-code&quot;&gt;AgentStack&lt;/code&gt;: agent and orchestrator Lambdas, Bedrock IAM&lt;/li&gt;
&lt;li&gt;&lt;code class=&quot;inline-code&quot;&gt;BackendStack&lt;/code&gt;: API Gateway, blog Lambda, DynamoDB, S3 content bucket&lt;/li&gt;
&lt;li&gt;&lt;code class=&quot;inline-code&quot;&gt;FrontendStack&lt;/code&gt;: CloudFront, site bucket, Route53, ACM&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The specs that drive this site, including the architecture decisions behind each of these choices, are public in the &lt;a href=&quot;https://github.com/Caskey-Coding/caskeycoding-specs-demo&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;specs demo repo&lt;/a&gt;.&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>Building a Personal Finance Reviewer: What Survived the Rewrite</title>
      <link>https://caskeycoding.com/blog/building-an-ai-finance-app</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/building-an-ai-finance-app</guid>
      <pubDate>Tue, 19 May 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>AI</category>
      <category>finance</category>
      <category>AWS</category>
      <category>Python</category>
      <category>software-development</category>
      <category>side-projects</category>
      <description>A personal portfolio reviewer where the scoring is deterministic and the AI only narrates. The architecture that held up after I had to rewrite the model it was built on, and why that boundary is the whole point.</description>
      <content:encoded>&lt;p&gt;I run a personal &lt;a href=&quot;https://caskeycoding.com/finance&quot; class=&quot;internal-link&quot;&gt;portfolio reviewer&lt;/a&gt;. It takes a position export, scores every holding on a deterministic multi-factor model, flags allocation and risk breaches against hard thresholds, and produces a written review I can act on in a few minutes instead of a Saturday morning.&lt;/p&gt;
&lt;p&gt;An earlier version of this post described that scoring model as a value-investing rubric. That was wrong, and not in a small way: the rubric graded one of the most dominant companies in the market a D+. I rebuilt the model. The story of how it was wrong, how I caught it, and what the rewrite cost is its own post, &lt;a href=&quot;https://caskeycoding.com/blog/when-the-spec-was-wrong&quot; class=&quot;internal-link&quot;&gt;When the Spec Was Wrong&lt;/a&gt;, and I would rather link to it than edit the old claim out of existence.&lt;/p&gt;
&lt;p&gt;The model got replaced. The architecture around it did not, and that is what made the rewrite survivable.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/building-an-ai-finance-app-boundary.svg&quot; alt=&quot;A green zone labeled decides, holding factor scoring and hard-threshold rules, with a one-way arrow to an LLM box that only narrates, and a red note that nothing flows the other way.&quot;&gt;&lt;/p&gt;
&lt;h2 id=&quot;the-one-boundary-that-matters&quot;&gt;The one boundary that matters&lt;a href=&quot;https://caskeycoding.com/blog/building-an-ai-finance-app#the-one-boundary-that-matters&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The system has three layers and a rule about which one is allowed to decide anything.&lt;/p&gt;
&lt;p&gt;A deterministic scoring layer reads the positions and the market data and produces scores. Same inputs, same outputs, no model in the loop. A rules layer applies non-negotiable thresholds: concentration limits, sleeve caps, drift bounds. These are not advice; they fire or they do not. Only then does an LLM see the result, and its job is strictly to narrate: explain the scores, surface the breaches, write the review a careful investor would recognize as coherent. It does not compute a score. It does not overrule a threshold. It is told the numbers; it is never asked to derive them.&lt;/p&gt;
&lt;p&gt;Everything load-bearing is deterministic and auditable; the model is a writing layer on top of facts it cannot change. When I had to throw out the scoring model, the blast radius stopped at the deterministic layer. The rules did not move. The narration did not move. The audit trail did not move. A rewrite that would have been frightening in a system where the AI decided the numbers was a contained change in a system where it only describes them.&lt;/p&gt;
&lt;h2 id=&quot;never-let-a-missing-number-become-a-confident-one&quot;&gt;Never let a missing number become a confident one&lt;a href=&quot;https://caskeycoding.com/blog/building-an-ai-finance-app#never-let-a-missing-number-become-a-confident-one&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The failure mode I care most about in a system with money attached is not a wrong opinion. It is a fabricated fact presented with the same confidence as a real one.&lt;/p&gt;
&lt;p&gt;The concrete version: a price fetch fails for one holding. The lazy behavior is to fall back to zero, multiply it through, and emit a portfolio that looks complete and is quietly wrong, with a sell recommendation on a position that did not actually crater. The reviewer does not do that. A price fetch resolves to one of three states: a fresh value, a stale-but-real cached value with its age attached, or an explicit failure. A failed fetch is excluded from totals, weights, grades, and recommendations rather than silently coerced into a number. Stale-by-a-day, clearly labeled, is a far better signal to a human than a confident zero.&lt;/p&gt;
&lt;p&gt;This principle is enforced on the price path and not yet everywhere. The sparse-fundamentals case, where a data provider returns nothing for a thinly covered instrument, is harder than the price case and is the edge I am still tightening. The principle is settled; the coverage is not yet complete.&lt;/p&gt;
&lt;h2 id=&quot;the-audit-trail-keeps-the-system-honest-over-time&quot;&gt;The audit trail keeps the system honest over time&lt;a href=&quot;https://caskeycoding.com/blog/building-an-ai-finance-app#the-audit-trail-keeps-the-system-honest-over-time&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Every review is written as an immutable record: the scored output, the recommendations, and hashes of the inputs and configuration that produced them. Reviews are not overwritten and not expired. The hashes let me compare recovered inputs with the recorded ones. Replaying a recommendation also requires the original input bytes, configuration, and engine version; a hash cannot recover a missing snapshot. Keeping those artifacts retrievable is a separate requirement from retaining the review.&lt;/p&gt;
&lt;p&gt;I used the same deterministic boundary for &lt;a href=&quot;https://caskeycoding.com/blog/black-swan-on-a-tuesday&quot; class=&quot;internal-link&quot;&gt;a synthetic crash replay&lt;/a&gt;. It exposed an interaction between rules, while the replay&apos;s simplified waiting policy limited what the result could say about live behavior.&lt;/p&gt;
&lt;p&gt;This sounds like compliance theater for a one-user tool. A reviewer I cannot reconstruct is a reviewer I have to trust on feel, and the entire reason the reviewer exists is that I do not trust my own recency bias with real money. The immutability is the same instinct as the deterministic boundary: keep the parts with consequences inspectable, and keep the AI on the side of the system where being inspectable is not required.&lt;/p&gt;
&lt;h2 id=&quot;what-the-rewrite-actually-taught-me&quot;&gt;What the rewrite actually taught me&lt;a href=&quot;https://caskeycoding.com/blog/building-an-ai-finance-app#what-the-rewrite-actually-taught-me&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Because the scoring layer was deterministic, isolated, and specified separately from the code, replacing it was a bounded edit with a written decision record behind it. Because the AI was a narrator and not a judge, none of the rewrite touched it. The expensive version of this mistake, the one where the model is fused into the recommendations and the recommendations are fused into the prompt, is a system you cannot rewrite without rebuilding. I did not have that system, by deliberate choice, and that choice was worth more than any single call the original model got right.&lt;/p&gt;
&lt;p&gt;If you are building anything that scores or grades where the output has consequences, the durable question is not which model. It is: when the model turns out to be wrong, and it will, how much of the system has to move with it? Keep that number small on purpose. Ship the deterministic version first, write down why, and assume the first model is a placeholder for the second one.&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>When the Spec Was Wrong: Rewriting a Shipped Decision</title>
      <link>https://caskeycoding.com/blog/when-the-spec-was-wrong</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/when-the-spec-was-wrong</guid>
      <pubDate>Sun, 26 Apr 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>software-development</category>
      <category>spec-driven-development</category>
      <category>AI</category>
      <category>side-projects</category>
      <category>finance</category>
      <description>Two weeks after I shipped a post about a scoring engine I&apos;d built, I rewrote the spec it was based on. Here&apos;s what I learned, and why I had an AI agent do the literature review.</description>
      <content:encoded>&lt;p&gt;Two weeks ago I wrote a post about a personal finance app I&apos;d built. The part I was proudest of was the scoring engine: a six-dimension rubric based on Graham&apos;s value framework, with clear thresholds and transparent logic. The LLM only narrated the results; it didn&apos;t decide them. The argument was that structure mattered more than intelligence for a system with real money on the line.&lt;/p&gt;
&lt;p&gt;A week later I ran the rubric against my actual portfolio. NVDA scored a D+.&lt;/p&gt;
&lt;p&gt;That result made me inspect the rubric. A dominant business can still deserve a poor value score, so NVDA&apos;s grade alone did not establish a defect. The audit exposed a mismatch between the question I wanted the engine to answer and the rules I had given it. That was the reason to rewrite it.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/when-the-spec-was-wrong-supersession.svg&quot; alt=&quot;Three spec versions in a row: Graham&amp;#x27;s rubric superseded when reality graded NVDA a D+, the factor rewrite superseded when review caught the same signal scored up to three times, and the surviving spec highlighted in green.&quot;&gt;&lt;/p&gt;
&lt;h2 id=&quot;the-shipped-spec-accumulates-assumptions-you-stop-questioning&quot;&gt;The shipped spec accumulates assumptions you stop questioning&lt;a href=&quot;https://caskeycoding.com/blog/when-the-spec-was-wrong#the-shipped-spec-accumulates-assumptions-you-stop-questioning&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;I chose Graham&apos;s framework because I&apos;d read &lt;em&gt;The Intelligent Investor&lt;/em&gt; and Graham was what I knew. The v1 rubric was a faithful operationalization of his principles: P/E thresholds, P/B as a primary signal, current-ratio screens, dividend continuity. Every grade reproducible.&lt;/p&gt;
&lt;p&gt;Then I ran it against modern stocks. Every one of them failed. Not just NVDA. The intangibles-heavy S&amp;#x26;P names came in the same way: D&apos;s and F&apos;s where I expected B&apos;s. The rubric was reliably grading every modern stock as a failure, which is another way of saying it was grading them against 1949.&lt;/p&gt;
&lt;p&gt;The previous post argued that the spec is the product, and I still believe that. But shipping a spec is also when you start defending it. The deterministic engine was the right call, and I&apos;d ship it again. The deterministic &lt;em&gt;rules&lt;/em&gt; inside it are a separate question, and that distinction is easy to miss once a system is live. Consistency feels like correctness. A rubric that produces the same output every time looks like it&apos;s working. But reproducible isn&apos;t the same as right; it just means the same answer every time, whether the answer is any good or not.&lt;/p&gt;
&lt;h2 id=&quot;what-was-actually-broken&quot;&gt;What was actually broken&lt;a href=&quot;https://caskeycoding.com/blog/when-the-spec-was-wrong#what-was-actually-broken&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Three structural problems, all of them obvious in retrospect.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;The framework excluded most of my portfolio by design.&lt;/strong&gt; Graham wrote in an industrial economy, and he explicitly bracketed companies where intangible assets dominate value. That&apos;s roughly the top 40% of the S&amp;#x26;P 500 by market cap today. Using absolute P/E thresholds against that universe doesn&apos;t fix the mismatch; it bakes it in.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;I was craving more quant practice than Graham could give me.&lt;/strong&gt; Graham gave me a rubric I could operationalize because I&apos;d been reading him for years. But Graham doesn&apos;t have factor models, sector-relative scoring, or any of the toolkit modern quants actually use. The v1 spec was a personal reading list dressed up as a spec, and nothing on the reading list was post-1949.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Two scoring systems had grown in parallel.&lt;/strong&gt; A &quot;committee&quot; of investor personas had been added on top of the factor scorers, and each persona computed its own weighted score. Same position, different grades, no defensible way to reconcile them. The spec said &quot;deterministic scoring,&quot; but the implementation had drifted into two deterministic systems that disagreed.&lt;/p&gt;
&lt;p&gt;Each of these was a shipped assumption I&apos;d stopped questioning. None of them needed new evidence to surface. They needed someone reading the spec who wasn&apos;t me.&lt;/p&gt;
&lt;h2 id=&quot;perplexity-computer-did-the-literature-review&quot;&gt;Perplexity Computer did the literature review&lt;a href=&quot;https://caskeycoding.com/blog/when-the-spec-was-wrong#perplexity-computer-did-the-literature-review&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Before I rewrote a single line of the rubric, I had Perplexity Computer run a deep-research pass on modern factor frameworks. AQR&apos;s quality-value-momentum work, MSCI&apos;s factor model documentation, JP Morgan&apos;s factor views, the Russell research notes: what institutional quants actually use to evaluate equities in 2026, sourced and synthesized into a report I could read in an evening.&lt;/p&gt;
&lt;p&gt;This is the part I want to draw out for engineers, because it changes what spec-driven development is tractable for. The first version of the spec was Graham-aligned because Graham is what I&apos;d read. The rewrite is grounded in modern factor research because an agent did the literature review for me. What would have been a week of reading on my own showed up as a synthesis I could absorb between dinner and bed, with sources cited so I could chase any claim I wanted to verify.&lt;/p&gt;
&lt;p&gt;Computer wasn&apos;t writing the spec. I was. But the work that has to happen &lt;em&gt;before&lt;/em&gt; you can write a defensible spec, surveying current practice, comparing approaches, finding the dead ends, is exactly what an agent is good at. It runs sub-agents in parallel across different sources, summarizes where they conflict, and hands you something concrete to argue with.&lt;/p&gt;
&lt;p&gt;Spec-driven development assumes you can write specs. AI-assisted research is what makes it tractable to write specs about domains you&apos;re not already an expert in, and that&apos;s the loop that&apos;s going to drive every rewrite from here.&lt;/p&gt;
&lt;h2 id=&quot;the-rewrite-and-the-decision-that-made-it-cheap&quot;&gt;The rewrite, and the decision that made it cheap&lt;a href=&quot;https://caskeycoding.com/blog/when-the-spec-was-wrong#the-rewrite-and-the-decision-that-made-it-cheap&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The replacement is a three-factor composite: Quality, Value, Momentum. The personas got demoted from parallel scorers to factor narrators. Each persona owns one factor and explains its score in their voice instead of computing a competing one. That collapses the dual-scoring problem: the committee output now follows from the factor output, not against it.&lt;/p&gt;
&lt;p&gt;The non-obvious decision in the rewrite was a negative one. Keeping the implementation in Python.&lt;/p&gt;
&lt;p&gt;The new spec used TypeScript pseudocode for readability, and there was real temptation to &quot;modernize&quot; the backend alongside the algorithmic change. Same blast radius, same deploy, why not. The answer is that none of the working pieces would have been better in another language: not the FMP client, not the caching layer, not the Lambda handlers, not the Pydantic models. The algorithm changes were independent of the host language, and combining the two would have doubled the surface area for new bugs. I&apos;d have spent a week debugging serialization instead of validating scoring behavior.&lt;/p&gt;
&lt;p&gt;The cheapest rewrite is the one that touches one axis at a time. Language migrations alongside algorithmic changes are the most expensive form of yak-shaving I know.&lt;/p&gt;
&lt;h2 id=&quot;then-a-review-caught-what-id-already-convinced-myself-was-right&quot;&gt;Then a review caught what I&apos;d already convinced myself was right&lt;a href=&quot;https://caskeycoding.com/blog/when-the-spec-was-wrong#then-a-review-caught-what-id-already-convinced-myself-was-right&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The first version of the new rubric kept Growth as a separate factor at 20%. A soundness review pass caught what I hadn&apos;t: Growth overlaps with Quality through earnings persistence, and with Momentum through earnings momentum. Keeping it separate risked giving the same underlying information weight in several buckets.&lt;/p&gt;
&lt;p&gt;Growth was removed as a separate bucket, and its sub-signals folded into Quality and Momentum. The same review caught a second problem: the new valuation formula softened the intangibles bias it was advertised to solve without eliminating it. The replacement uses free cash flow and owner-earnings yield. Those measures need their own scrutiny: cash-flow reporting can add back stock compensation even though issuing equity has a cost to shareholders. &lt;a href=&quot;https://pages.stern.nyu.edu/~adamodar/pdfiles/blog/FreeCF.pdf&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Damodaran&apos;s free-cash-flow primer&lt;/a&gt; explains that distinction. Without specifying the adjustments for compensation and reinvestment, I cannot claim that switching measures removes the distortion.&lt;/p&gt;
&lt;p&gt;&lt;em&gt;Correction, November 3, 2026: the original account mixed three-, four-, and five-factor counts. The initial pivot described here names Quality, Value, and Momentum; the &lt;a href=&quot;https://caskeycoding.com/blog/composite-what-you-trust&quot; class=&quot;internal-link&quot;&gt;June 17 account&lt;/a&gt; names Quality, Valuation, Momentum, and Health. These published accounts do not establish exactly when Health joined the rubric, so I have removed the unsupported intermediate counts.&lt;/em&gt;&lt;/p&gt;
&lt;p&gt;Two structural problems, both shipped under &quot;Accepted,&quot; both caught by an external read of the spec. The review pass is part of the spec-driven loop, not an afterthought to it. ADRs are cheap. Reviews of ADRs are what make them survive.&lt;/p&gt;
&lt;h2 id=&quot;what-this-means-for-spec-driven-development&quot;&gt;What this means for spec-driven development&lt;a href=&quot;https://caskeycoding.com/blog/when-the-spec-was-wrong#what-this-means-for-spec-driven-development&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Three rules I&apos;d carry over to any project where a deterministic spec drives a system with consequences.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Specs are versioned, not eternal.&lt;/strong&gt; ADRs that supersede other ADRs aren&apos;t a failure mode; they&apos;re the system working. The original rubric was superseded by the factor pivot, then revised again after review. Each supersession is a record of what changed and why. The cost of writing those records is low. The cost of skipping them is silent drift between what the code does and what anyone thinks it does.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Have an agent do the literature review.&lt;/strong&gt; The strongest single decision in the rewrite, before any code, was running Perplexity Computer against the current factor literature instead of writing the spec from memory. Specs grounded in &quot;what I happen to have read&quot; stop scaling the moment you cross out of your own depth. Specs grounded in &quot;what an agent surveyed last week&quot; can be written about almost anything you&apos;re willing to argue with.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Touch one axis at a time.&lt;/strong&gt; The rewrite most likely to fail is the one that changes the algorithm, the language, and the deployment model in the same PR. Every axis you change multiplies the surface area for new bugs. The Python decision was worth more than any single algorithmic improvement in the rewrite.&lt;/p&gt;
&lt;p&gt;If you&apos;re building anything that scores or grades with real consequences, ship the deterministic version first. That covers risk scores for transactions, severity grades for incidents, factor models for portfolios. Then commit to revisiting it the moment it touches reality. The first version will be wrong about something specific. The second version will be wrong about something different. That&apos;s the loop.&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>SDD isn&apos;t about managing AI agents, it&apos;s about managing context</title>
      <link>https://caskeycoding.com/blog/sdd-is-context-management</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/sdd-is-context-management</guid>
      <pubDate>Sun, 19 Apr 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>AI</category>
      <category>spec-driven-development</category>
      <category>claude-code</category>
      <category>context-management</category>
      <category>engineering-methodology</category>
      <description>Spec-driven development reads like a methodology for controlling AI agents. It isn&apos;t. It&apos;s a methodology for managing context across stateless sessions. The spec is the persistent memory.</description>
      <content:encoded>&lt;p&gt;The last post ended on a claim: the reason I can ship production software from a phone is that the thinking happens in specs and the typing happens elsewhere.&lt;/p&gt;
&lt;p&gt;Spec-Driven Development is a methodology for managing context. The specs are the persistent memory that makes a stateless AI useful across sessions.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/sdd-is-context-management-external-memory.svg&quot; alt=&quot;Three stateless sessions in a row, each dropping context at its boundary, all connected by double-headed arrows to one green spec box outside them: the persistent memory every session reads on turn one and writes back to when code ships.&quot;&gt;&lt;/p&gt;
&lt;h2 id=&quot;why-stateless-is-the-real-problem&quot;&gt;Why stateless is the real problem&lt;a href=&quot;https://caskeycoding.com/blog/sdd-is-context-management#why-stateless-is-the-real-problem&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;In the fresh-session workflow I used for this April account, I supplied prior decisions through files. A fresh context window needs a way to recover the stack, conventions, and reasons behind earlier choices.&lt;/p&gt;
&lt;p&gt;&lt;em&gt;Update, November 3, 2026: Claude Code supports &lt;a href=&quot;https://code.claude.com/docs/en/memory&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;persistent instructions and auto memory&lt;/a&gt;, as well as &lt;a href=&quot;https://code.claude.com/docs/en/cli-reference&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;continuing and resuming sessions&lt;/a&gt;. Starting a fresh model context does not mean the application has no persistence. Specs give me a reviewed record of requirements that remains useful alongside those mechanisms.&lt;/em&gt;&lt;/p&gt;
&lt;p&gt;In the fresh-session workflow I used in April, a session without specs or relevant saved context had to reconstruct the project&apos;s intent. The agent read the codebase, guessed at conventions, and inferred decisions from whichever files it opened first. Small changes could land fine while larger changes exposed the missing context.&lt;/p&gt;
&lt;p&gt;With specs, a session that opens with &quot;continue the contact form work&quot; already has the stack, the conventions, the prior decisions, and the acceptance criteria. The spec is the handoff. Point a fresh session at it and the session is at full speed in one read.&lt;/p&gt;
&lt;p&gt;The stateless/persistent split is the actual architecture:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Claude Code&lt;/strong&gt;, implementation. In this workflow, a fresh session gets its requirements and prior decisions from the spec.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Perplexity Computer&lt;/strong&gt;, persistent decisions. It remembers across sessions. It is where the thinking happens, where decisions are made, where specs get written.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;That division was how I used the tools. Keeping the decisions in reviewed files made the handoff explicit and let me change the implementation tool without losing the requirements.&lt;/p&gt;
&lt;h2 id=&quot;the-spec-structure&quot;&gt;The spec structure&lt;a href=&quot;https://caskeycoding.com/blog/sdd-is-context-management#the-spec-structure&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Three components do almost all the work:&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;A specs repo, separate from code, readable by both tools.&lt;/strong&gt; This is not a &lt;code class=&quot;inline-code&quot;&gt;/docs&lt;/code&gt; folder. It is its own repository, version-controlled, review-gated. See the public &lt;a href=&quot;https://github.com/Caskey-Coding/caskeycoding-specs-demo&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;demo repo&lt;/a&gt; for a guided walkthrough of both package shapes, it is the public teaching artifact for the methodology behind my private work.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Two package shapes, chosen per project.&lt;/strong&gt; An integration package (&lt;code class=&quot;inline-code&quot;&gt;steering/&lt;/code&gt; + &lt;code class=&quot;inline-code&quot;&gt;feature/&lt;/code&gt; + &lt;code class=&quot;inline-code&quot;&gt;decision/&lt;/code&gt;) for evolving platform work where each feature lands into a live system with existing conventions. A domain package (&lt;code class=&quot;inline-code&quot;&gt;product/&lt;/code&gt; + &lt;code class=&quot;inline-code&quot;&gt;domain/&lt;/code&gt; + &lt;code class=&quot;inline-code&quot;&gt;contracts/&lt;/code&gt; + &lt;code class=&quot;inline-code&quot;&gt;delivery/&lt;/code&gt;) for bounded greenfield apps where you are defining the domain as you go. One of each lives in the demo repo.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;&lt;code class=&quot;inline-code&quot;&gt;CLAUDE.md&lt;/code&gt; at every code repo root.&lt;/strong&gt; The first file any AI session reads. It is a router, identity, folder structure, and a routing table that maps task types to the right specs. Forty to fifty lines, not four hundred. Routing table columns: &lt;em&gt;task&lt;/em&gt;, &lt;em&gt;go to&lt;/em&gt;, &lt;em&gt;read first&lt;/em&gt;. That is the whole shape. A sample &lt;code class=&quot;inline-code&quot;&gt;CLAUDE.md&lt;/code&gt; is in the demo repo.&lt;/p&gt;
&lt;p&gt;The &lt;code class=&quot;inline-code&quot;&gt;CLAUDE.md&lt;/code&gt; file is the most expensive real estate in the whole system. Every token in it is spent on every turn, in every session, forever. Treat it like one. Put routing there. Put everything else in workspace-level &lt;code class=&quot;inline-code&quot;&gt;CONTEXT.md&lt;/code&gt; files that only load when the agent enters that workspace.&lt;/p&gt;
&lt;h2 id=&quot;what-breaks&quot;&gt;What breaks&lt;a href=&quot;https://caskeycoding.com/blog/sdd-is-context-management#what-breaks&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Three failure modes are worth naming.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Spec rot against a stateless reader.&lt;/strong&gt; A spec describing a design that shipped differently becomes a wrong answer the AI trusts. The fix is not more process, it is a discipline to either update the spec when the code changes, or mark the spec deprecated. Drift is the single biggest risk.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Context window limits.&lt;/strong&gt; Loading a full package into every session crowds out the code itself. The &lt;code class=&quot;inline-code&quot;&gt;CLAUDE.md&lt;/code&gt; routing table exists precisely to avoid this. The agent reads the router, goes to the right workspace, loads &lt;em&gt;only that workspace&apos;s context&lt;/em&gt;, and works. Planning context doesn&apos;t contaminate implementation context. Client A doesn&apos;t leak into Client B.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Treating the spec like documentation.&lt;/strong&gt; Documentation describes something that exists. A spec describes something to build. When a spec turns into a write-up of the finished code, it has stopped doing its job. Specs are forward-looking artifacts that happen to survive as a record. The record is a side effect.&lt;/p&gt;
&lt;h2 id=&quot;the-persistent-memory-lives-outside-the-agent&quot;&gt;The persistent memory lives outside the agent&lt;a href=&quot;https://caskeycoding.com/blog/sdd-is-context-management#the-persistent-memory-lives-outside-the-agent&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;What lets a stateless agent ship reliable production code is the context it loads on turn one. Spec-driven development gives a stateless tool a persistent memory that lives outside it, on purpose, where humans can review it, gate it, and change it.&lt;/p&gt;
&lt;p&gt;That external memory is only as good as its upkeep. The moment a spec describes a design that shipped differently, the agent trusts a wrong answer with full confidence, and a stateless reader has no way to catch that the memory rotted. The discipline holds the whole system up, and it is never finished.&lt;/p&gt;
&lt;p&gt;The next post is the numbers. Same week, same workflow, pulled straight from GitHub.&lt;/p&gt;
&lt;hr&gt;
&lt;p&gt;&lt;strong&gt;Previous in the series:&lt;/strong&gt; &lt;a href=&quot;https://caskeycoding.com/blog/phone-first-production-from-a-phone&quot; class=&quot;internal-link&quot;&gt;I shipped two production sites and a blog from my phone&lt;/a&gt;&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Read the methodology:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;https://github.com/Caskey-Coding/caskeycoding-specs-demo&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;&lt;code class=&quot;inline-code&quot;&gt;caskeycoding-specs-demo&lt;/code&gt;&lt;/a&gt;, public teaching artifact&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://github.com/Caskey-Coding/caskeycoding-specs-demo/blob/main/decision/ADR-001-spec-driven-development.md&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;ADR-001, Spec-Driven Development&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://github.com/Caskey-Coding/caskeycoding-specs-demo/blob/main/decision/ADR-002-sdd-file-structure.md&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;ADR-002, SDD File Structure&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;</content:encoded>
    </item>
    <item>
      <title>Specs in, deploys out, no keyboard</title>
      <link>https://caskeycoding.com/blog/phone-first-production-from-a-phone</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/phone-first-production-from-a-phone</guid>
      <pubDate>Sat, 18 Apr 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>AI</category>
      <category>spec-driven-development</category>
      <category>claude-code</category>
      <category>perplexity</category>
      <category>workflow</category>
      <description>Two production sites, a blog, and two personal AI projects, shipped this week from a phone. The chain is voice dictation into Perplexity Computer, a spec, then Claude Code on the web. The interaction model is the story.</description>
      <content:encoded>&lt;p&gt;This week I shipped two production websites, ericcaskey.com and caskeycoding.com, and moved two personal projects forward: &lt;a href=&quot;https://caskeycoding.com/blog/building-an-ai-marathon-coach-deterministic-rules-llm-narratives-2026-nyc-marathon&quot; class=&quot;internal-link&quot;&gt;Marathon Coach&lt;/a&gt; and &lt;a href=&quot;https://caskeycoding.com/blog/building-an-ai-finance-app&quot; class=&quot;internal-link&quot;&gt;Finance Reviewer&lt;/a&gt;. All from a phone: real sites with CI/CD pipelines, CloudFront distributions, GitHub Actions, and spec packages that drive every session, not prototypes. I wrote no code. I wrote specs.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/phone-first-production-from-a-phone-pipeline.svg&quot; alt=&quot;A four-stage pipeline from voice dictation through a green spec box and a code box to production, with a note that zero lines were hand-typed.&quot;&gt;&lt;/p&gt;
&lt;p&gt;The pipeline:&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;voice dictation → Perplexity Computer → spec → Claude Code → PR → GitHub Actions → deploy
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The chain runs like this. Voice dictation into Perplexity Computer opens a session. That session writes a spec and opens a PR on GitHub against a private specs repo. A second session in Claude Code on the web, also voice-driven, reads the spec and opens a PR on the code repo with the implementation. GitHub Actions validates. I review. Merge. CloudFront invalidates. The change is live.&lt;/p&gt;
&lt;p&gt;The tools earn naming. &lt;strong&gt;Perplexity Computer&lt;/strong&gt; handles planning, research, and spec writing. It has a GitHub connector that reads repos and opens PRs directly, and it has memory across sessions: the one I start tomorrow morning knows what last night&apos;s session decided. That persistence is what lets specs evolve instead of starting from scratch every conversation. Perplexity is also particularly strong on finance and stocks research, which is why the specs behind &lt;a href=&quot;https://caskeycoding.com/blog/building-an-ai-finance-app&quot; class=&quot;internal-link&quot;&gt;Finance Reviewer&lt;/a&gt; were written there specifically. Pick the tool for the domain.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Claude Code on the web&lt;/strong&gt; handles implementation. It reads a spec and opens a PR with working code. I review asynchronously, typically from the same phone, in a commute or between calls. When CI is green and the diff matches what the spec asked for, I merge. The two tools are complementary by design: one stateful and deliberative, one stateless and fast.&lt;/p&gt;
&lt;p&gt;No IDE and no keyboard. A session is a conversation, literally, via voice dictation. It is what these tools make possible once the specs are good enough to carry the intent. In &lt;a href=&quot;https://caskeycoding.com/blog/book-review-enterprise-vibe-coding-playbook-building-real-software-with-ai&quot; class=&quot;internal-link&quot;&gt;my review of the Enterprise Vibe Coding Playbook&lt;/a&gt;, I wrote that I had tried voice dictation and felt self-conscious about it. By the week described here, it had become the entry point of the workflow.&lt;/p&gt;
&lt;p&gt;A CloudFront function was pinned to &lt;code class=&quot;inline-code&quot;&gt;trailingSlash: false&lt;/code&gt; while the Next.js config flipped to &lt;code class=&quot;inline-code&quot;&gt;true&lt;/code&gt;, and for a few hours every sub-route on caskeycoding.com served the home page. The fix landed in the right order: a spec change first, amending the architecture decision in the infra and frontend specs, and then one-line code changes in both repos behind those specs. The discipline is that the spec leads. The code follows.&lt;/p&gt;
&lt;p&gt;The framing matters. I made the decisions, wrote them down, and AI implemented them reliably. The trailing-slash break above is the proof: what fixed it was changing the spec first and letting the one-line code edits follow, a decision no agent made for me. The implementation is reproducible because the spec makes it so.&lt;/p&gt;
&lt;p&gt;The two personal projects, Marathon Coach and Finance Reviewer, run on the same workflow, specs kept in private development. The interaction model is the portable part.&lt;/p&gt;
&lt;p&gt;The methodology under this is &lt;a href=&quot;https://caskeycoding.com/blog/spec-driven-development-and-the-folder-architecture-that-makes-it-work&quot; class=&quot;internal-link&quot;&gt;spec-driven development and the folder architecture that makes it work&lt;/a&gt;, which I wrote up last month. The next post in this series is the follow-up: what a month of running that system in production surfaced that the March essay did not cover. Alongside both, browse &lt;a href=&quot;https://github.com/Caskey-Coding/caskeycoding-specs-demo&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;caskeycoding-specs-demo&lt;/a&gt; to see the shape of the system: two example spec packages, the two ADRs that govern the methodology, and a sample &lt;code class=&quot;inline-code&quot;&gt;CLAUDE.md&lt;/code&gt;.&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>Building an AI Marathon Coach: Deterministic Rules, LLM Narratives, and the 2026 NYC Marathon</title>
      <link>https://caskeycoding.com/blog/building-an-ai-marathon-coach-deterministic-rules-llm-narratives-2026-nyc-marathon</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/building-an-ai-marathon-coach-deterministic-rules-llm-narratives-2026-nyc-marathon</guid>
      <pubDate>Mon, 13 Apr 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>AI</category>
      <category>marathon</category>
      <category>running</category>
      <category>AWS</category>
      <category>Python</category>
      <category>software-development</category>
      <category>side-projects</category>
      <description>How I built a personal AI coaching system for marathon training, layering deterministic guardrails over an LLM narrative engine, ingesting Garmin FIT files, and designing for my own injury history.</description>
      <content:encoded>&lt;p&gt;I&apos;m running the 2026 TCS New York City Marathon. The training cycle starts now. And I&apos;m building &lt;a href=&quot;https://caskeycoding.com/coach&quot; class=&quot;internal-link&quot;&gt;the coaching tool&lt;/a&gt; as I go.&lt;/p&gt;
&lt;p&gt;&lt;a href=&quot;https://caskeycoding.com/blog/the-marathon-i-wanted-my-kids-to-see&quot; class=&quot;internal-link&quot;&gt;The race-day follow-up&lt;/a&gt; records the finish and my family&apos;s role in the last stretch.&lt;/p&gt;
&lt;p&gt;This is not an AI experiment in the abstract. It&apos;s a real system, for a real race, trained on my actual runs, with my actual injury history, including a calf issue that has derailed training blocks before. If the system makes bad recommendations, I show up to the start line underprepared or injured. That sharpens the design criteria considerably.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/building-an-ai-marathon-coach-guardrails.svg&quot; alt=&quot;Fourteen deterministic guardrails in green emit a typed outcome chip reading REDUCE_INTENSITY, one of seven, which an LLM box then explains in plain language, with a note that the model never makes the call.&quot;&gt;&lt;/p&gt;
&lt;h2 id=&quot;the-problem-with-generic-training-plans&quot;&gt;The Problem With Generic Training Plans&lt;a href=&quot;https://caskeycoding.com/blog/building-an-ai-marathon-coach-deterministic-rules-llm-narratives-2026-nyc-marathon#the-problem-with-generic-training-plans&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Standard marathon training plans are reasonable starting points. Eighteen weeks, periodized volume, taper protocol. The problem is they don&apos;t know anything about you: that you ran sixty miles last week on strong legs, that you had two poor nights of sleep and your resting heart rate is elevated, that your calf is talking to you.&lt;/p&gt;
&lt;p&gt;Good human coaches read those signals and adjust the week around them.&lt;/p&gt;
&lt;p&gt;AI is a plausible substitute for that coaching intelligence, but only if it&apos;s given the right data and the right constraints. An LLM alone won&apos;t do it. You need structure.&lt;/p&gt;
&lt;h2 id=&quot;architecture-two-layers-one-pipeline&quot;&gt;Architecture: Two Layers, One Pipeline&lt;a href=&quot;https://caskeycoding.com/blog/building-an-ai-marathon-coach-deterministic-rules-llm-narratives-2026-nyc-marathon#architecture-two-layers-one-pipeline&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The system has two distinct layers that must not be confused:&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Layer 1: Deterministic rules engine.&lt;/strong&gt; This layer ingests training data, runs from Garmin FIT file exports, manual recovery signals (resting HR, sleep quality, soreness, pain flags), and computes objective training metrics: Acute:Chronic Workload Ratio (ACWR), weekly volume, fatigue indicators, trend. It then evaluates fourteen defined guardrails. These guardrails produce a typed recommendation: &lt;code class=&quot;inline-code&quot;&gt;PROCEED&lt;/code&gt;, &lt;code class=&quot;inline-code&quot;&gt;REDUCE_INTENSITY&lt;/code&gt;, &lt;code class=&quot;inline-code&quot;&gt;REDUCE_VOLUME&lt;/code&gt;, &lt;code class=&quot;inline-code&quot;&gt;CROSS_TRAIN_OR_REST&lt;/code&gt;, &lt;code class=&quot;inline-code&quot;&gt;FULL_REST&lt;/code&gt;, &lt;code class=&quot;inline-code&quot;&gt;RECOVERY_RUN&lt;/code&gt;, or &lt;code class=&quot;inline-code&quot;&gt;NEEDS_MORE_DATA&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;The rules are hard. If a pain flag is set, the system returns &lt;code class=&quot;inline-code&quot;&gt;FULL_REST&lt;/code&gt;, regardless of any other metric. If ACWR exceeds 1.8, the system returns &lt;code class=&quot;inline-code&quot;&gt;CROSS_TRAIN_OR_REST&lt;/code&gt; or &lt;code class=&quot;inline-code&quot;&gt;FULL_REST&lt;/code&gt;. That threshold is my experimental caution rule; it is not a validated boundary between safe training and injury for me or another runner. If there are fewer than three activities in the past fourteen days, the system returns &lt;code class=&quot;inline-code&quot;&gt;NEEDS_MORE_DATA&lt;/code&gt; rather than producing an unreliable estimate.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Layer 2: LLM narrative engine.&lt;/strong&gt; Once the rules engine has produced a typed recommendation and the guardrail outcomes, the LLM receives that structured output and writes a coaching narrative. Two to four sentences. Plain language. Actionable. Grounded in the data the rules engine processed.&lt;/p&gt;
&lt;p&gt;The LLM does not choose the recommendation type. That is the rules engine&apos;s job. The LLM explains the recommendation in human terms.&lt;/p&gt;
&lt;p&gt;This separation is the load-bearing design decision. The boundary between what the LLM can do and what it must not do is explicit and enforced.&lt;/p&gt;
&lt;h2 id=&quot;why-the-llm-must-not-decide-safety-critical-outcomes&quot;&gt;Why the LLM Must Not Decide Safety-Critical Outcomes&lt;a href=&quot;https://caskeycoding.com/blog/building-an-ai-marathon-coach-deterministic-rules-llm-narratives-2026-nyc-marathon#why-the-llm-must-not-decide-safety-critical-outcomes&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;There&apos;s a category error that shows up in a lot of AI system designs: giving the LLM responsibility for decisions that require consistent, auditable reasoning and then hoping the model stays calibrated.&lt;/p&gt;
&lt;p&gt;For a coaching system, a consistently applied rule can still be wrong. ACWR is a contested way to turn training load into advice: a &lt;a href=&quot;https://pubmed.ncbi.nlm.nih.gov/32502973/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;critical analysis of its statistical and causal assumptions&lt;/a&gt; explains why an observed association does not establish that manipulating the ratio prevents injury. My 1.8 trigger makes the software&apos;s response inspectable. It does not establish a medical risk threshold, and the exact load measure and averaging windows would need to accompany any attempt to validate or reuse it.&lt;/p&gt;
&lt;p&gt;Language models are not deterministic. They can reason well about training principles in general, but they will not reliably apply the same rules to the same inputs across sessions. They can be influenced by how context is framed. They can hallucinate confidence about edge cases.&lt;/p&gt;
&lt;p&gt;Deterministic code has none of these problems. A rule that says &quot;if pain flag is set, return FULL_REST&quot; executes identically every time. You can test it. You can audit it. You can explain exactly why the system made the call it made.&lt;/p&gt;
&lt;p&gt;The LLM&apos;s value is in the narrative: taking the rules engine&apos;s recommendation and explaining the inputs and triggered guardrails in language I can inspect. Fluency cannot establish that the recommendation is medically sound. That judgment still depends on the rules and their evidence.&lt;/p&gt;
&lt;h2 id=&quot;garmin-fit-files-and-the-unglamorous-data-layer&quot;&gt;Garmin FIT Files and the Unglamorous Data Layer&lt;a href=&quot;https://caskeycoding.com/blog/building-an-ai-marathon-coach-deterministic-rules-llm-narratives-2026-nyc-marathon#garmin-fit-files-and-the-unglamorous-data-layer&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The first engineering problem is getting run data in. Garmin&apos;s full API requires developer program approval and user OAuth. For a personal MVP, that&apos;s a month of setup for one athlete. The practical choice is FIT file exports, Garmin lets you export any activity as a &lt;code class=&quot;inline-code&quot;&gt;.fit&lt;/code&gt; file from Garmin Connect.&lt;/p&gt;
&lt;p&gt;FIT files contain everything: GPS track, lap splits, cadence, heart rate, elevation. The &lt;code class=&quot;inline-code&quot;&gt;fitparse&lt;/code&gt; Python library handles parsing. The Lambda reads the uploaded file, extracts the relevant training metrics, and writes an activity record to DynamoDB.&lt;/p&gt;
&lt;p&gt;Manual recovery signals, resting HR, sleep quality, soreness level, pain flags, are entered via an API endpoint. No automated wearable integration in v1. That&apos;s a deliberate constraint: I want the data ingestion path to be reliable and understood before I add the complexity of real-time API sync.&lt;/p&gt;
&lt;p&gt;Garmin Connect API integration is on the roadmap for post-MVP. But MVP ships with file-based ingestion, and the system is useful immediately.&lt;/p&gt;
&lt;h2 id=&quot;designing-for-my-own-injury-history&quot;&gt;Designing for My Own Injury History&lt;a href=&quot;https://caskeycoding.com/blog/building-an-ai-marathon-coach-deterministic-rules-llm-narratives-2026-nyc-marathon#designing-for-my-own-injury-history&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;One of the more interesting design challenges: the system needs to know about my calf injury history and apply calf-specific caution in its guardrails.&lt;/p&gt;
&lt;p&gt;In a generic coaching system, this is handled by user profile fields that parameterize the rules. My system does this, but it also surfaces calf-specific guardrail outputs in the narrative context, so when the LLM writes the coaching explanation, it has explicit signal to reference: &quot;your recent history with the left calf warrants extra caution here.&quot;&lt;/p&gt;
&lt;p&gt;A coaching system that does not know your injury history is just a generic training calculator.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/marathon-coach-demo-sample-block.webp&quot; alt=&quot;The sample block from the public coach demo: an athlete card with weekly target and injury history, a recovery card dated the morning of the decision with a red right-calf pain flag and 6/10 soreness, and a last-seven-days table whose notes read like a real training log&quot;&gt;&lt;/p&gt;
&lt;p&gt;That block is from &lt;a href=&quot;https://caskeycoding.com/lab/coach&quot; class=&quot;internal-link&quot;&gt;the public demo&lt;/a&gt;, which runs the same charts and recommendation path against a sample athlete. The pain flag, the soreness score, and the run notes are exactly the inputs the guardrails read before the LLM writes a word.&lt;/p&gt;
&lt;h2 id=&quot;if-you-cant-inspect-it-you-cant-trust-it&quot;&gt;If You Can&apos;t Inspect It, You Can&apos;t Trust It&lt;a href=&quot;https://caskeycoding.com/blog/building-an-ai-marathon-coach-deterministic-rules-llm-narratives-2026-nyc-marathon#if-you-cant-inspect-it-you-cant-trust-it&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Every recommendation pipeline run writes an audit record: inputs (activities, recovery signals, computed metrics), guardrail outcomes, final recommendation type, LLM prompt sent, LLM response received, timestamp.&lt;/p&gt;
&lt;p&gt;This is foundational infrastructure.&lt;/p&gt;
&lt;p&gt;When the system tells me to rest and I disagree, I want to be able to look at exactly what data it had, exactly which guardrails fired, and exactly why. For any system that influences decisions you care about, the ability to inspect the reasoning is a requirement.&lt;/p&gt;
&lt;p&gt;The audit records also let me evaluate recommendation quality over time. I journal my independent assessment alongside each recommendation. After four weeks of training, I can see whether the system&apos;s calls match what I would have chosen. That feedback loop is how you tune the guardrails.&lt;/p&gt;
&lt;h2 id=&quot;shipping-it-while-training&quot;&gt;Shipping It While Training&lt;a href=&quot;https://caskeycoding.com/blog/building-an-ai-marathon-coach-deterministic-rules-llm-narratives-2026-nyc-marathon#shipping-it-while-training&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The interesting meta-challenge: I&apos;m building this system while the training cycle I&apos;m building it for has already started. That creates a useful constraint. I can&apos;t spend six months on perfect architecture and ship after the race. I need something useful now, even if it&apos;s incomplete.&lt;/p&gt;
&lt;p&gt;This is a productive way to scope an MVP. What does the system need to do to be useful for this week&apos;s training? That&apos;s the scope. Everything else is v2.&lt;/p&gt;
&lt;p&gt;For week one: ingest FIT files, compute ACWR, surface recovery signals, produce a typed recommendation with a narrative. That&apos;s it. The dashboard, the trend visualization, the automatic Garmin sync, those can wait.&lt;/p&gt;
&lt;p&gt;The CoachStack is live in the same CDK infrastructure as the finance app and this site. The backend Lambda is deployed. The API is wired. The data is flowing.&lt;/p&gt;
&lt;p&gt;Now I just have to train.&lt;/p&gt;
&lt;h2 id=&quot;where-the-risk-moved&quot;&gt;Where the Risk Moved&lt;a href=&quot;https://caskeycoding.com/blog/building-an-ai-marathon-coach-deterministic-rules-llm-narratives-2026-nyc-marathon#where-the-risk-moved&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The two-layer split relocates the safety risk rather than removing it. The obvious danger was an LLM hallucinating a training call, so I moved every call into fourteen hand-written guardrails. Now the model narrates those calls with equal confidence whether the rule behind them is right or wrong. The failure I watch for is a guardrail I wrote badly, delivered in fluent, convincing prose.&lt;/p&gt;
&lt;p&gt;The 2026 NYC Marathon is in November. I&apos;ll be sharing updates on how the coaching system performs across the training cycle, where it nails the calls, where it misses, and how the architecture evolves.&lt;/p&gt;
&lt;p&gt;If you&apos;re building something similar, personal coaching tools, adaptive recommendation systems, anything where AI-generated advice has real consequences, I&apos;m interested in comparing notes.&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>Designing Safety Guardrails for Distributed Workflow Orchestration</title>
      <link>https://caskeycoding.com/blog/designing-safety-guardrails-for-distributed-workflow-orchestration</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/designing-safety-guardrails-for-distributed-workflow-orchestration</guid>
      <pubDate>Fri, 10 Apr 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>workflow</category>
      <category>orchestration</category>
      <category>distributed-systems</category>
      <category>safety</category>
      <category>platform-engineering</category>
      <description>Patterns for pre-execution safety checks, parallel validation, opt-out design, and extensible guardrail architecture on workflow platforms.</description>
      <content:encoded>&lt;p&gt;By the time a monitoring alert fires on a distributed workflow, you may already be committed to a path that cannot be cleanly reversed. Pre-execution guardrails are how you close that gap before execution starts. This is a pattern I designed for infrastructure workflow changes and drove to adoption across an engineering organization, where every execution passes concurrent safety checks before it begins.&lt;/p&gt;
&lt;p&gt;Post-hoc monitoring is necessary and not sufficient. Guardrails are the contract on the other side of it: &lt;em&gt;we will not begin work until we have evidence that starting work is responsible.&lt;/em&gt;&lt;/p&gt;
&lt;p&gt;The tension is familiar. Teams want speed and self-service. Operators want confidence that automation will not amplify mistakes. Platform owners want a system that is explainable when something blocks, because &quot;computer says no&quot; without detail loses trust faster than incidents do. The default compromise (ship fast, let monitoring catch it) breaks down when orchestration runs at scale and failures compound.&lt;/p&gt;
&lt;h2 id=&quot;what-to-check-before-you-execute&quot;&gt;What to Check Before You Execute&lt;a href=&quot;https://caskeycoding.com/blog/designing-safety-guardrails-for-distributed-workflow-orchestration#what-to-check-before-you-execute&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Pre-execution validation covers distinct categories of risk. The exact names matter less than the coverage; separating them keeps failure messages legible and lets you tune severity and ownership independently.&lt;/p&gt;
&lt;p&gt;The questions worth asking, at minimum: &lt;em&gt;Is now an acceptable time to run? Is something else already modifying this target? Are the right health signals present? Is the target itself in a known-good state? Is there conflicting in-flight activity that makes this execution unsafe right now?&lt;/em&gt;&lt;/p&gt;
&lt;p&gt;If you cannot map a proposed check onto one of those questions, you are probably mixing concerns, and mixed concerns turn guardrails into mystery meat. Separated, a timing violation reads differently than a concurrency conflict. Operators deserve that clarity.&lt;/p&gt;
&lt;p&gt;The bar I held every check to: if it cannot explain &lt;em&gt;why&lt;/em&gt; it failed, &lt;em&gt;what&lt;/em&gt; would make it pass, and &lt;em&gt;which&lt;/em&gt; team owns remediation, it is not yet a guardrail.&lt;/p&gt;
&lt;h2 id=&quot;why-fail-fast-is-the-wrong-default-for-safety-systems&quot;&gt;Why Fail-Fast Is the Wrong Default for Safety Systems&lt;a href=&quot;https://caskeycoding.com/blog/designing-safety-guardrails-for-distributed-workflow-orchestration#why-fail-fast-is-the-wrong-default-for-safety-systems&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;In most request paths, fail-fast is a virtue. You stop early, shed load, and protect downstream dependencies. Safety validation optimizes for something else entirely: surfacing the full set of blocking issues so a human can fix them in one pass.&lt;/p&gt;
&lt;p&gt;Stop at the first failure and you train operators into a loop: fix one problem, re-run, hit the next failure, repeat. That burns time, increases toil, and shows up on dashboards as &quot;flaky automation&quot; when the real problem is partial reporting.&lt;/p&gt;
&lt;p&gt;Worse, correlated failures do not surface in a stable order. In one incident review, the first failure we reported was a timing window violation. The root cause, a stale deployment lock from an unrelated workflow, only surfaced on the third re-run. If the system had reported both on the first pass, the operator would have fixed the right problem first.&lt;/p&gt;
&lt;p&gt;The pattern that fixes this is parallel evaluation with aggregation. Safety checks run concurrently. Results roll up into a single decision: proceed or block, with a complete explanation of what failed. You are optimizing for clarity under stress, not for minimal CPU time on the happy path.&lt;/p&gt;
&lt;p&gt;Parallelism here is a product decision, not a performance one: independent checks should not serialize human time. If two checks both fail, the operator sees both failures immediately, not after re-running and re-waiting. Under incident pressure, every minute of that churn converts directly into lost trust in the platform.&lt;/p&gt;
&lt;p&gt;&lt;em&gt;This post includes a diagram. &lt;a href=&quot;https://caskeycoding.com/blog/designing-safety-guardrails-for-distributed-workflow-orchestration&quot;&gt;View it on caskeycoding.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;
&lt;p&gt;Real systems add dependencies, caching, and policy on top, but the core stays stable: fan out, fan in, decide once.&lt;/p&gt;
&lt;h2 id=&quot;the-opt-out-spectrum&quot;&gt;The Opt-Out Spectrum&lt;a href=&quot;https://caskeycoding.com/blog/designing-safety-guardrails-for-distributed-workflow-orchestration#the-opt-out-spectrum&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Guardrails that cannot be overridden in any circumstance will eventually block a legitimate emergency. Guardrails that can be overridden without friction will eventually be overridden for convenience. The design problem is where opt-out lives and who may use it.&lt;/p&gt;
&lt;p&gt;Opt-out must also be traceable. If someone bypasses a guardrail, the system should still answer: who, when, and under what policy. Convenience without auditability becomes shadow risk management, and shadow risk management does not survive your next serious incident review.&lt;/p&gt;
&lt;p&gt;The clearest candidates for the non-opt-outable bucket are checks where a mistake crosses an environment boundary or creates damage that cannot be cleanly reversed. When blast radius and irreversibility stack, operator convenience is a losing argument.&lt;/p&gt;
&lt;h2 id=&quot;calibrating-monitoring-response&quot;&gt;Calibrating Monitoring Response&lt;a href=&quot;https://caskeycoding.com/blog/designing-safety-guardrails-for-distributed-workflow-orchestration#calibrating-monitoring-response&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Not every bad signal deserves the same response. A naive policy (&quot;any red monitor triggers automatic rollback&quot;) creates churn. Some signals mean real degradation and should drive a strong response. Others mean wait: a change window has not cleared, an alarm is still recovering, or data is temporarily insufficient to decide. Those situations need time, human judgment, or a follow-up check. An immediate rollback there adds motion without reducing risk.&lt;/p&gt;
&lt;p&gt;Match the response to the signal. Using a rollback when the right move is &quot;pause and page&quot; can make incidents worse. In practice this meant configurable response severity, so teams could map signal type to action without forking the engine.&lt;/p&gt;
&lt;h2 id=&quot;a-plug-in-architecture-for-guardrails&quot;&gt;A Plug-In Architecture for Guardrails&lt;a href=&quot;https://caskeycoding.com/blog/designing-safety-guardrails-for-distributed-workflow-orchestration#a-plug-in-architecture-for-guardrails&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;If every new safety rule requires editing the core orchestration engine, you get one of two failure modes: slow innovation, because reviews are heavy, or unsafe shortcuts, because teams route around the platform. We chose a plug-in model instead, and that choice is most of why the pattern spread beyond the team that built it:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;A &lt;strong&gt;contract&lt;/strong&gt; every guardrail implements: what it checks, how it reports success or failure, and what metadata it needs for observability and policy.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Configuration-driven registration&lt;/strong&gt;, so the engine discovers which guardrails apply to which workflows or targets without hard-coding a growing list in one place.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Adding a guardrail becomes: implement the contract, register it, ship. The engine stays stable. Teams onboarded their own checks without waiting on the platform&apos;s review queue, which is what organizational adoption actually requires; a safety system that only its authors can extend stays a team tool, never an org standard. The cost was real: a contract is a public API, and we paid for it in versioning discipline and in saying no to checks that wanted engine internals. It was the right trade.&lt;/p&gt;
&lt;p&gt;Structure scales when humans and tools share the same source of truth. In &lt;em&gt;&lt;a href=&quot;https://caskeycoding.com/blog/spec-driven-development-and-the-folder-architecture-that-makes-it-work&quot; class=&quot;internal-link&quot;&gt;Spec-Driven Development and the Folder Architecture That Makes It Work&lt;/a&gt;&lt;/em&gt; I made the same argument for AI-assisted engineering: partitioned context and explicit specs beat one undifferentiated dump. Guardrails want the same boundary. Policy and implementation meet at a contract, not in a monolith where every change is everyone&apos;s emergency.&lt;/p&gt;
&lt;p&gt;&lt;em&gt;This post includes a diagram. &lt;a href=&quot;https://caskeycoding.com/blog/designing-safety-guardrails-for-distributed-workflow-orchestration&quot;&gt;View it on caskeycoding.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;
&lt;p&gt;Discovery and dispatch stay separate from each guardrail&apos;s business logic. That separation is what keeps the platform extensible after the original authors move on.&lt;/p&gt;
&lt;h2 id=&quot;the-test-that-decides-if-you-built-one&quot;&gt;The Test That Decides If You Built One&lt;a href=&quot;https://caskeycoding.com/blog/designing-safety-guardrails-for-distributed-workflow-orchestration#the-test-that-decides-if-you-built-one&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;One rule carries out of all of this. Before a check ships, make it answer three questions in its failure output: why it failed, what would make it pass, and who owns remediation. Answer all three and you built a guardrail that operators will defend. Answer none and you built a boolean that operators will route around, and a routed-around safety system is worse than no safety system, because it still shows up green on someone&apos;s compliance dashboard.&lt;/p&gt;
&lt;p&gt;The open question I carried out of this pattern: guardrails protect execution, but nothing here protects the &lt;em&gt;checks themselves&lt;/em&gt; from rotting. A check that never fires is indistinguishable from a check that is dead. Auditing guardrail liveness is its own discipline: verify the checker can still say no, on a schedule, or its silence will read as health.&lt;/p&gt;
&lt;hr&gt;
&lt;p&gt;&lt;em&gt;This article describes the pattern in generalized form. It does not name any specific internal system or tool, and all scale figures are ones already published on this site.&lt;/em&gt;&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>Spec-Driven Development and the Folder Architecture That Makes It Work</title>
      <link>https://caskeycoding.com/blog/spec-driven-development-and-the-folder-architecture-that-makes-it-work</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/spec-driven-development-and-the-folder-architecture-that-makes-it-work</guid>
      <pubDate>Thu, 09 Apr 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>AI</category>
      <category>spec-driven-development</category>
      <category>folder-architecture</category>
      <category>engineering-methodology</category>
      <description>Why spec-driven development and structured folder architecture are the missing infrastructure for AI-assisted engineering: methodology, common mistakes, and where to start.</description>
      <content:encoded>&lt;p&gt;You open a chat, describe what you want, and get code back that looks right, until it doesn&apos;t. The stack is wrong. The edge cases are missing. The auth module doesn&apos;t match the patterns in the rest of your codebase. You correct, re-prompt, correct again, and eventually the context window degrades to the point where you&apos;re fighting the AI more than collaborating with it. Most AI-assisted development fails this same way.&lt;/p&gt;
&lt;p&gt;The AI can code. What is missing is the structure around it.&lt;/p&gt;
&lt;p&gt;I wrote recently about Doug Kerwin&apos;s &lt;em&gt;&lt;a href=&quot;https://caskeycoding.com/blog/book-review-enterprise-vibe-coding-playbook-building-real-software-with-ai&quot; class=&quot;internal-link&quot;&gt;Enterprise Vibe Coding Playbook&lt;/a&gt;&lt;/em&gt; and his central argument: AI should write most of your code, but you must remain the architect, reviewer, and course-corrector. Design before you dive in. Think before you prompt. That&apos;s the philosophy. This piece is about the methodology and infrastructure that make it operational: spec-driven development and structured folder architecture for AI agents.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/spec-driven-folder-architecture-layers.svg&quot; alt=&quot;Three stacked layers: a green CLAUDE.md router read every turn, workspace CONTEXT.md files that load per room, and skills picked up on demand, captioned chat is not a source of truth; structure is.&quot;&gt;&lt;/p&gt;
&lt;h2 id=&quot;the-problem-chat-as-source-of-truth&quot;&gt;The Problem: Chat as Source of Truth&lt;a href=&quot;https://caskeycoding.com/blog/spec-driven-development-and-the-folder-architecture-that-makes-it-work#the-problem-chat-as-source-of-truth&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;When you let an AI jump straight to code, you&apos;re asking it to figure out &lt;em&gt;what&lt;/em&gt; to build, &lt;em&gt;how&lt;/em&gt; to build it, and actually build it, all in one context window. That&apos;s three jobs. It does a mediocre version of all three instead of a good version of any one.&lt;/p&gt;
&lt;p&gt;Worse, the design decisions live in chat history. Close the session, and they&apos;re gone. Start a new conversation, and the AI re-derives context from code that may not reflect the original intent, or it hallucates conventions that contradict decisions you made last week. For quick prototypes, this is fine. For anything you have to maintain, it&apos;s a liability.&lt;/p&gt;
&lt;p&gt;The &lt;a href=&quot;https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;GitHub Engineering blog&lt;/a&gt; put it well: &lt;em&gt;&quot;We treat coding agents like search engines when we should be treating them more like literal-minded pair programmers. They excel at pattern recognition but still need unambiguous instructions.&quot;&lt;/em&gt;&lt;/p&gt;
&lt;p&gt;Spec-driven development is how you give those unambiguous instructions.&lt;/p&gt;
&lt;h2 id=&quot;the-methodology-specs-as-source-of-truth&quot;&gt;The Methodology: Specs as Source of Truth&lt;a href=&quot;https://caskeycoding.com/blog/spec-driven-development-and-the-folder-architecture-that-makes-it-work#the-methodology-specs-as-source-of-truth&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The core idea is straightforward: before the AI writes a line of code, you write a specification, a persistent markdown file that captures what you&apos;re building, why, the design decisions, API contracts, edge cases, and a decomposed task list. The spec becomes the source of truth, a version-controlled file rather than a decision buried in chat history you will close and lose.&lt;/p&gt;
&lt;p&gt;GitHub recently open-sourced &lt;a href=&quot;https://github.com/github/spec-kit&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Spec Kit&lt;/a&gt;, a toolkit that formalizes this into four phases:&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Specify&lt;/strong&gt;: Describe requirements as user journeys and success criteria. Focus on what and why, not technology choices. Who uses this? What outcomes matter? What does success look like? This is the &quot;hard thinking&quot; that Kerwin insists on, externalized into an artifact instead of locked in your head.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Plan&lt;/strong&gt;: Add architecture constraints, stack preferences, and non-functional requirements. If your company standardizes on certain technologies, if you&apos;re integrating with legacy systems, if you have compliance or performance targets, all of that goes here. The AI designs within your constraints instead of guessing at them.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Tasks&lt;/strong&gt;: Decompose the plan into small, reviewable, testable units. Each task is concrete and independently verifiable: &quot;create a user registration endpoint that validates email format,&quot; not &quot;build the auth system.&quot; This is test-driven development applied to the planning layer.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Implement&lt;/strong&gt;: Execute tasks sequentially with focused review at each step. Instead of reviewing thousand-line code dumps, you review focused changes that solve specific problems.&lt;/p&gt;
&lt;p&gt;The insight is that each phase has a specific job, and you don&apos;t move to the next one until the current phase is fully validated. The spec captures intent. The plan captures constraints. The tasks capture scope. The implementation follows all three.&lt;/p&gt;
&lt;h3 id=&quot;in-practice-a-four-phase-workflow&quot;&gt;In Practice: A Four-Phase Workflow&lt;a href=&quot;https://caskeycoding.com/blog/spec-driven-development-and-the-folder-architecture-that-makes-it-work#in-practice-a-four-phase-workflow&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h3&gt;
&lt;p&gt;Practitioners like &lt;a href=&quot;https://gahmed.com/blog/spec-driven-development-claude-code/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Ghazi Ahmed&lt;/a&gt; have adapted this into a hands-on workflow specifically for Claude Code that&apos;s worth studying:&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Phase 1: Explore.&lt;/strong&gt; Before the AI writes a single line, it reads. You&apos;re explicit about this: &quot;Read the auth module, user model, and existing middleware. Understand the patterns. Do NOT write code.&quot; Without that last line, the AI will start drafting implementations mid-research. You don&apos;t want that yet.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Phase 2: Write the spec.&lt;/strong&gt; Draft a three-layer specification: &lt;em&gt;Requirements&lt;/em&gt; (the what and why: problem statement, goals, acceptance criteria, constraints), &lt;em&gt;Design&lt;/em&gt; (the how: architecture decisions, data model changes, API contracts with actual request/response examples, edge cases), and &lt;em&gt;Tasks&lt;/em&gt; (the implementation plan: small, atomic steps, each touching three files or fewer, with explicit dependencies and definitions of done). Save it as &lt;code class=&quot;inline-code&quot;&gt;docs/spec-feature-name.md&lt;/code&gt; in your repo.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Phase 3: Implement with subagents.&lt;/strong&gt; Delegate each task to a subagent so it gets a fresh context window scoped to just its slice of work. The orchestrator tracks progress without filling up on implementation details. Each subagent produces one commit. If Task 4 breaks something Task 2 built, the git history tells you exactly where to look.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Phase 4: Verify.&lt;/strong&gt; Tests are inline with tasks, not a separate phase tacked on at the end. Every task compiles and passes tests before the next one starts. For bugs, the loop is strict TDD: write a failing test, confirm it fails, fix the code, confirm it passes.&lt;/p&gt;
&lt;p&gt;The key discipline: the spec file is your recovery point. Context degrades. It always does. When it happens, you clear the session, point a fresh conversation at the spec file, and you&apos;re back to full speed. The spec persists intent across context resets. It serves as an onboarding document when new engineers (or new AI sessions) join a feature. It decomposes large ambiguous work into small testable units.&lt;/p&gt;
&lt;p&gt;For teams at scale, this solves a problem that rarely gets addressed: where do security policies, compliance rules, design system constraints, and integration requirements live? Often they&apos;re buried in wikis nobody reads or scattered across Slack. In a spec-driven workflow, they live in the specification and the plan, where the AI actually uses them.&lt;/p&gt;
&lt;h2 id=&quot;the-infrastructure-folder-architecture-as-agentic-architecture&quot;&gt;The Infrastructure: Folder Architecture as Agentic Architecture&lt;a href=&quot;https://caskeycoding.com/blog/spec-driven-development-and-the-folder-architecture-that-makes-it-work#the-infrastructure-folder-architecture-as-agentic-architecture&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Spec-driven development gives you the methodology. There&apos;s still a question of infrastructure: how do you organize the specs, context files, and project knowledge so the AI reads the right information at the right time without burning tokens on everything else?&lt;/p&gt;
&lt;p&gt;This is where Jake Van Clief&apos;s work with &lt;a href=&quot;https://www.skool.com/quantum-quill-lyceum-1116&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Clief Notes&lt;/a&gt; deserves attention. Van Clief has built a community of 6,000+ members around what he calls &lt;strong&gt;Interpretable Context Methodology (ICM)&lt;/strong&gt;, a system where folder structure itself becomes the agentic architecture. No frameworks. No multi-agent orchestration code. Just folders, markdown files, and naming conventions.&lt;/p&gt;
&lt;p&gt;The premise is simple and well-grounded: tokens are finite, and every token the AI spends reading irrelevant context is a token not spent on the task at hand. If you dump everything into one conversation (your blog post drafts, your video production notes, your deployment configs) the AI writing your blog post is also reading your Kubernetes manifests. The folder structure solves this by separating work into areas and only loading what&apos;s needed.&lt;/p&gt;
&lt;h3 id=&quot;three-layers-plain-english&quot;&gt;Three Layers, Plain English&lt;a href=&quot;https://caskeycoding.com/blog/spec-driven-development-and-the-folder-architecture-that-makes-it-work#three-layers-plain-english&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Layer 1: The Map (&lt;code class=&quot;inline-code&quot;&gt;CLAUDE.md&lt;/code&gt;)&lt;/strong&gt;: A minimal top-level file at the root of your project. It tells the AI what the project is, what the folder structure looks like, and includes a routing table that maps tasks to workspaces. Van Clief compares it to the floor plan on the wall when you walk into a building. You look at it, you know where to go.&lt;/p&gt;
&lt;p&gt;The routing table has three columns: task, where to go, what to read.&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Task&lt;/th&gt;
&lt;th&gt;Go to&lt;/th&gt;
&lt;th&gt;Read&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Spec a feature&lt;/td&gt;
&lt;td&gt;/planning&lt;/td&gt;
&lt;td&gt;CONTEXT.md&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Write code&lt;/td&gt;
&lt;td&gt;/src&lt;/td&gt;
&lt;td&gt;CONTEXT.md&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Write docs&lt;/td&gt;
&lt;td&gt;/docs&lt;/td&gt;
&lt;td&gt;CONTEXT.md&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Deploy or debug&lt;/td&gt;
&lt;td&gt;/ops&lt;/td&gt;
&lt;td&gt;CONTEXT.md&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;Van Clief is emphatic that this file should be short, one screen, 40-50 lines maximum. It&apos;s a router, not a brain dump. Every token in &lt;code class=&quot;inline-code&quot;&gt;CLAUDE.md&lt;/code&gt; is spent on every single turn, so bloat here is the most expensive mistake you can make.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Layer 2: The Rooms (Workspace &lt;code class=&quot;inline-code&quot;&gt;CONTEXT.md&lt;/code&gt; files)&lt;/strong&gt;: Each workspace gets its own context file describing what happens there, what the process looks like, what files live there, and what good work looks like. &lt;code class=&quot;inline-code&quot;&gt;CONTEXT.md&lt;/code&gt; is this method&apos;s naming convention. The router must tell the agent to read it; creating the file does not make Claude Code load it automatically. Reading one workspace&apos;s file also does not remove material already in the conversation. Use separate sessions when work must stay separate, particularly across clients.&lt;/p&gt;
&lt;p&gt;These are plain English, short documents. A few paragraphs. You describe the workspace, the process, the standards. The AI reads the context and immediately knows what it&apos;s working on, what rules apply, and what good output looks like, with almost no prompting.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Layer 3: The Tools (Skills and plug-ins)&lt;/strong&gt;: Reusable capabilities referenced where they&apos;re needed. A testing skill in the &lt;code class=&quot;inline-code&quot;&gt;src/&lt;/code&gt; workspace. A doc-authoring skill in the &lt;code class=&quot;inline-code&quot;&gt;docs/&lt;/code&gt; workspace. The workspace instructions identify which capabilities apply; the coding tool&apos;s skill-loading rules determine when their content enters the session.&lt;/p&gt;
&lt;h3 id=&quot;what-it-replaces&quot;&gt;What It Replaces&lt;a href=&quot;https://caskeycoding.com/blog/spec-driven-development-and-the-folder-architecture-that-makes-it-work#what-it-replaces&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h3&gt;
&lt;p&gt;The elegance is in what you don&apos;t need. Traditional multi-agent frameworks require orchestration code, API calls, and infrastructure to route work between specialized agents. Van Clief&apos;s insight is that for sequential workflows with human review at each step (which is most real work) the filesystem &lt;em&gt;is&lt;/em&gt; the orchestration layer.&lt;/p&gt;
&lt;p&gt;Numbered folders represent stages. Markdown files carry prompts and context. Naming conventions replace database queries. If a spec draft is created, it gets named &lt;code class=&quot;inline-code&quot;&gt;feature-name_spec.md&lt;/code&gt;. If it&apos;s a blog draft, &lt;code class=&quot;inline-code&quot;&gt;topic-name_draft.md&lt;/code&gt;. If it&apos;s a versioned demo script, &lt;code class=&quot;inline-code&quot;&gt;demo_v2.md&lt;/code&gt;. The AI knows where to look, what to pull, and what to do next because the naming tells it everything. No SQL. No vector database. Just conventions.&lt;/p&gt;
&lt;p&gt;The research behind this, published as &lt;em&gt;Interpretable Context Methodology: Folder Structure as Agentic Architecture&lt;/em&gt;, traces the principles back to separation of concerns (1972), Unix philosophy, and modular composition. One stage, one job. Plain text as the universal interface. Layered context loading. Every output is an edit surface. These aren&apos;t new ideas. They&apos;re established software engineering principles applied to AI workflows, and that&apos;s what makes the approach durable rather than trendy.&lt;/p&gt;
&lt;h3 id=&quot;how-the-layers-map-to-a-codebase&quot;&gt;How the Layers Map to a Codebase&lt;a href=&quot;https://caskeycoding.com/blog/spec-driven-development-and-the-folder-architecture-that-makes-it-work#how-the-layers-map-to-a-codebase&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h3&gt;
&lt;p&gt;For developers, the three-layer system maps naturally onto spec-driven development:&lt;/p&gt;
&lt;pre&gt;&lt;code&gt;my-app/
├── CLAUDE.md              # Layer 1: routing table
├── planning/
│   ├── CONTEXT.md         # Layer 2: planning workspace
│   ├── specs/             # spec-*.md files live here
│   ├── architecture/
│   └── decisions/
├── src/
│   ├── CONTEXT.md         # Layer 2: implementation workspace
│   ├── components/
│   ├── services/
│   └── tests/
├── docs/
│   ├── CONTEXT.md         # Layer 2: documentation workspace
│   └── api/
└── ops/
    ├── CONTEXT.md         # Layer 2: operations workspace
    └── deploy/
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The router can say: &quot;Before speccing a feature, read &lt;code class=&quot;inline-code&quot;&gt;planning/CONTEXT.md&lt;/code&gt; and the relevant specs. Before implementation, read &lt;code class=&quot;inline-code&quot;&gt;src/CONTEXT.md&lt;/code&gt; and the approved feature spec.&quot; Open a fresh session and ask it to identify the route and instructions for a sample task, then inspect what it actually read. Claude Code&apos;s &lt;a href=&quot;https://code.claude.com/docs/en/memory&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;memory documentation&lt;/a&gt; describes its native instruction-file loading and imports. A routing instruction helps select context; it does not enforce isolation or compliance.&lt;/p&gt;
&lt;p&gt;But the same three-layer system works for non-developers too: content creators, freelancers, consultants. A freelancer swaps workspaces for Client Intake, Delivery, and Admin. A content creator uses Script Lab, Production, and Distribution. The layers stay the same. The labels change. That accessibility is the point, and it&apos;s what makes Van Clief&apos;s approach useful for cross-functional teams trying to adopt AI workflows beyond engineering.&lt;/p&gt;
&lt;h2 id=&quot;the-five-ways-this-goes-wrong&quot;&gt;The Five Ways This Goes Wrong&lt;a href=&quot;https://caskeycoding.com/blog/spec-driven-development-and-the-folder-architecture-that-makes-it-work#the-five-ways-this-goes-wrong&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Van Clief&apos;s curriculum includes a common mistakes module, and the failure patterns map directly onto what I see in enterprise AI adoption:&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Massive &lt;code class=&quot;inline-code&quot;&gt;CLAUDE.md&lt;/code&gt; files.&lt;/strong&gt; People dump everything into the top-level file: project briefs, style guides, personality instructions, background research. The routing instructions get buried in noise, and every turn burns tokens on information irrelevant to the current task. The fix: the &lt;code class=&quot;inline-code&quot;&gt;CLAUDE.md&lt;/code&gt; is a routing file. Identity, folder structure, routing table, naming conventions. Everything else belongs in a workspace &lt;code class=&quot;inline-code&quot;&gt;CONTEXT.md&lt;/code&gt; where it only loads when relevant.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Skipping the routing table.&lt;/strong&gt; Without one, the AI guesses which files matter. Sometimes it guesses right. &quot;Sometimes&quot; is the problem. The routing table eliminates guessing. One row per type of work.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Too many workspaces.&lt;/strong&gt; Eight workspaces for a project that has two or three modes of work. Now the overhead of maintaining context files exceeds the value of the system. The question to ask: &quot;Do I shift mental modes between these tasks?&quot; Writing and building are different modes. Drafting and editing are the same mode at different stages. Start with two or three workspaces. Add more from real use, not from planning.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Context files that describe the AI instead of the work.&lt;/strong&gt; &quot;Be creative. Be concise. Be professional.&quot; Thirty lines of personality instructions, two lines about the project. The AI responds to context about the work far more than context about itself. Telling it &quot;the audience is mid-market HR directors who&apos;ve tried three other tools and are skeptical of AI claims&quot; changes the output more than &quot;you are a senior copywriter&quot; ever will.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Building the whole system before using it.&lt;/strong&gt; The classic over-engineering trap. Someone reads about the three-layer architecture, spends a weekend building six workspaces with detailed context files and twenty-row routing tables, and hasn&apos;t used the AI once during the process. Then they start working and realize half their decisions don&apos;t match how they actually work. The fix: build the minimum. One &lt;code class=&quot;inline-code&quot;&gt;CLAUDE.md&lt;/code&gt;, one or two workspaces, one &lt;code class=&quot;inline-code&quot;&gt;CONTEXT.md&lt;/code&gt; each. Start working. Grow from use.&lt;/p&gt;
&lt;h2 id=&quot;why-this-matters-for-teams&quot;&gt;Why This Matters for Teams&lt;a href=&quot;https://caskeycoding.com/blog/spec-driven-development-and-the-folder-architecture-that-makes-it-work#why-this-matters-for-teams&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Individual productivity is table stakes. The harder problem is organizational adoption, and this is where specs and folder architecture have a structural advantage over chat-based workflows.&lt;/p&gt;
&lt;p&gt;Specs are reviewable artifacts. A product manager can read &lt;code class=&quot;inline-code&quot;&gt;spec-auth.md&lt;/code&gt; and verify that the requirements match intent. A tech lead can review the design layer before implementation starts. A security engineer can audit the constraints section. The spec becomes a contract, familiar territory for any engineering organization that already does design reviews and RFCs.&lt;/p&gt;
&lt;p&gt;Folder architecture makes AI-assisted work legible. When a new engineer joins a project and sees a &lt;code class=&quot;inline-code&quot;&gt;CLAUDE.md&lt;/code&gt; with a routing table, workspace context files describing each area of the codebase, and spec files decomposing features into tasks, they can orient immediately. The structure itself is documentation. That&apos;s a much easier organizational sell than &quot;trust me, the AI knows what it&apos;s doing.&quot;&lt;/p&gt;
&lt;p&gt;Together, they address the cultural resistance that Kerwin identifies in the &lt;em&gt;Enterprise Vibe Coding Playbook&lt;/em&gt;: skeptics can review the spec. Experts can critique the architecture. Managers can see the task decomposition. The AI&apos;s behavior becomes predictable, auditable, and correctable, which is what organizations need before they&apos;ll trust it at scale.&lt;/p&gt;
&lt;h2 id=&quot;where-to-start&quot;&gt;Where to Start&lt;a href=&quot;https://caskeycoding.com/blog/spec-driven-development-and-the-folder-architecture-that-makes-it-work#where-to-start&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;If you&apos;re new to this, three steps cover 80% of the value:&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;1. Spec before code. Every time.&lt;/strong&gt; Write a one-page spec for your next feature. Requirements, design decisions, task list. Save it as a markdown file in your repo. Point the AI at it. Notice the difference.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;2. Three files, fifteen minutes.&lt;/strong&gt; Create a &lt;code class=&quot;inline-code&quot;&gt;CLAUDE.md&lt;/code&gt; (identity, folder structure, routing table), a &lt;code class=&quot;inline-code&quot;&gt;CONTEXT.md&lt;/code&gt; for your primary workspace (what the work is, what good looks like, what to avoid), and a &lt;code class=&quot;inline-code&quot;&gt;REFERENCES.md&lt;/code&gt; (background material the AI should access but not act on directly). Start working. Grow from use.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;3. One task per session.&lt;/strong&gt; Context degradation isn&apos;t gradual. It&apos;s a cliff. Keep sessions focused on a single task. Clear between tasks. When context degrades, point a fresh session at the spec file and continue from where you left off.&lt;/p&gt;
&lt;p&gt;I teach the basic setup in &lt;a href=&quot;https://caskeycoding.com/blog/lesson-1-the-spec-directory&quot; class=&quot;internal-link&quot;&gt;Lesson 1: Write Feature Specs Before Coding&lt;/a&gt;, with a directory layout, spec template and exercise.&lt;/p&gt;
&lt;p&gt;The spec captures the thinking. The folder structure routes the AI to the right context. Together, they turn &quot;design don&apos;t dive in&quot; from a philosophy into a workflow.&lt;/p&gt;
&lt;h2 id=&quot;further-reading&quot;&gt;Further Reading&lt;a href=&quot;https://caskeycoding.com/blog/spec-driven-development-and-the-folder-architecture-that-makes-it-work#further-reading&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;GitHub&apos;s Spec Kit&lt;/strong&gt;: &lt;a href=&quot;https://github.com/github/spec-kit&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Open-source toolkit&lt;/a&gt; formalizing spec-driven development for Copilot, Claude Code, Cursor, and Gemini. The &lt;a href=&quot;https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;accompanying blog post&lt;/a&gt; from GitHub Engineering is the best starting point.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Ghazi Ahmed&apos;s workflow guide&lt;/strong&gt;: &lt;a href=&quot;https://gahmed.com/blog/spec-driven-development-claude-code/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Spec-Driven Development with Claude Code&lt;/a&gt; is the most detailed practitioner write-up I&apos;ve found. Covers the four-phase workflow, &lt;code class=&quot;inline-code&quot;&gt;CLAUDE.md&lt;/code&gt; structure, context management, subagent delegation, and git worktrees for parallel work.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Clief Notes&lt;/strong&gt;: Jake Van Clief&apos;s &lt;a href=&quot;https://www.skool.com/quantum-quill-lyceum-1116&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;free Foundation course&lt;/a&gt; walks through the three-layer folder architecture from scratch. Module 3 is the meat: a 23-minute video walkthrough, customization examples for content creators, freelancers, and developers, and the common mistakes guide. The system is accessible to non-developers, which makes it useful for cross-functional teams.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;ICM Research Paper&lt;/strong&gt;: &lt;em&gt;Interpretable Context Methodology: Folder Structure as Agentic Architecture&lt;/em&gt; traces the principles from 1972 separation of concerns through to modern AI workflows. Available through the Clief Notes community.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Enterprise Vibe Coding Playbook&lt;/strong&gt;: If you haven&apos;t read my &lt;a href=&quot;https://caskeycoding.com/blog/book-review-enterprise-vibe-coding-playbook-building-real-software-with-ai&quot; class=&quot;internal-link&quot;&gt;review of Kerwin&apos;s book&lt;/a&gt;, it covers the philosophy and cultural case that this methodology operationalizes.&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>Book Review: Enterprise Vibe Coding Playbook, Building Real Software with AI</title>
      <link>https://caskeycoding.com/blog/book-review-enterprise-vibe-coding-playbook-building-real-software-with-ai</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/book-review-enterprise-vibe-coding-playbook-building-real-software-with-ai</guid>
      <pubDate>Wed, 08 Apr 2026 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>AI</category>
      <category>book-review</category>
      <category>software-development</category>
      <category>engineering-culture</category>
      <description>My review of Doug Kerwin&apos;s Enterprise Vibe Coding Playbook: its advice on prompting, design, and review, who I&apos;d recommend it to, and the spec workflow I&apos;d add.</description>
      <content:encoded>&lt;p&gt;Doug Kerwin&apos;s &lt;em&gt;&lt;a href=&quot;https://www.enterprisevibecoding.com/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Enterprise Vibe Coding Playbook&lt;/a&gt;&lt;/em&gt; makes a case for letting AI write most of the code while engineers own the requirements, design, and review. That is the enterprise vibe coding approach I found useful in the book: give the model clear work, inspect what it produces, and course-correct before building on it.&lt;/p&gt;
&lt;p&gt;My verdict: I&apos;d recommend it to engineers and technical leads trying to make AI-assisted development a repeatable team practice. The chapters on prompting, design, and voice gave me concrete ways to approach that work. I&apos;d add &lt;a href=&quot;https://caskeycoding.com/blog/lesson-1-the-spec-directory&quot; class=&quot;internal-link&quot;&gt;persistent specs and a directory an agent can follow&lt;/a&gt;, so the requirements and design decisions have a home after the conversation ends.&lt;/p&gt;
&lt;h2 id=&quot;what-is-enterprise-vibe-coding&quot;&gt;What is enterprise vibe coding?&lt;a href=&quot;https://caskeycoding.com/blog/book-review-enterprise-vibe-coding-playbook-building-real-software-with-ai#what-is-enterprise-vibe-coding&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;As I read it, enterprise vibe coding means letting AI write most of the code while the engineer remains the architect, reviewer, and course-corrector. Requirements, design decisions, and scrutiny of the result remain the engineer&apos;s work.&lt;/p&gt;
&lt;p&gt;What is vibe coding? Kerwin identifies it as the dangerous assumption that AI writes code without human scrutiny. It&apos;s a caricature that has become a convenient shield for skeptics unwilling to adapt. His beef with the term is justified. It misrepresents how AI actually amplifies developer productivity.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;You&apos;re still developing; you&apos;re just not writing line-by-line anymore.&lt;/strong&gt; Think of it as the difference between describing what needs to happen to your copilot and then refining the result, versus typing every character yourself. The hard thinking, the design, the architectural decisions: these remain yours.&lt;/p&gt;
&lt;p&gt;Kerwin crystallizes this with a quote that stayed with me: &lt;em&gt;&quot;The issue isn&apos;t using AI to write all the code. It&apos;s pretending you don&apos;t need to review, guide, and course-correct.&quot;&lt;/em&gt; More pointedly: &lt;em&gt;&quot;The problem isn&apos;t AI writing the code. It&apos;s expecting it to get everything right with one shot prompt and no plan. It&apos;s skipping the hard thinking, the real design, and expecting magic.&quot;&lt;/em&gt;&lt;/p&gt;
&lt;p&gt;It matches what I have found running my own spec-driven agent loops. The setups that win with AI have not abandoned discipline. They spend more of it on requirements, architecture, and review. The tool accelerates, but the thinking stays non-negotiable.&lt;/p&gt;
&lt;h2 id=&quot;why-this-matters-a-historical-parallel&quot;&gt;Why This Matters: A Historical Parallel&lt;a href=&quot;https://caskeycoding.com/blog/book-review-enterprise-vibe-coding-playbook-building-real-software-with-ai#why-this-matters-a-historical-parallel&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;When the industry transitioned from relational databases to DynamoDB and NoSQL architectures, we didn&apos;t resist the shift. We adapted. We learned new patterns, new trade-offs, new ways of thinking about data. The fundamentals of distributed systems didn&apos;t change, but our implementation patterns did.&lt;/p&gt;
&lt;p&gt;AI-assisted development is similar. We&apos;re not abandoning software engineering principles. We&apos;re evolving how we apply them. Context engineering and prompt engineering are emerging disciplines that sit alongside API design and system architecture. AI pipelines and agentic workflows are becoming what data pipelines were to the previous generation: foundational infrastructure.&lt;/p&gt;
&lt;p&gt;The era of purely manual writing, in code, in documentation, in planning, should be assumed to be over. The question isn&apos;t whether to use these tools, but how to use them wisely.&lt;/p&gt;
&lt;h2 id=&quot;the-method-writing-a-book-with-cursor-and-repository-tracking&quot;&gt;The Method: Writing a Book with Cursor and Repository Tracking&lt;a href=&quot;https://caskeycoding.com/blog/book-review-enterprise-vibe-coding-playbook-building-real-software-with-ai#the-method-writing-a-book-with-cursor-and-repository-tracking&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;One of the most interesting aspects of this book is that Kerwin wrote 100% of it with AI assistance, using Cursor as his IDE and a repository to track his ideas and maintain stylistic consistency. This isn&apos;t a book &lt;em&gt;about&lt;/em&gt; AI-assisted development written in a vacuum. It&apos;s a book written &lt;em&gt;with&lt;/em&gt; the methods it describes.&lt;/p&gt;
&lt;p&gt;IDEs, agents, and AI-assisted capabilities are not just for developers anymore. The same tools and patterns apply across the SDLC stack, to product managers, technical program managers, architects, and yes, even to authors writing about software. The infrastructure of thinking has fundamentally changed.&lt;/p&gt;
&lt;h2 id=&quot;the-practical-framework-from-code-generator-to-thinking-partner&quot;&gt;The Practical Framework: From Code Generator to Thinking Partner&lt;a href=&quot;https://caskeycoding.com/blog/book-review-enterprise-vibe-coding-playbook-building-real-software-with-ai#the-practical-framework-from-code-generator-to-thinking-partner&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Chapter 4 compares prompting to writing user stories. Vague prompts leave the model to fill in missing context and requirements. I have worked with Kerwin and heard him push for that same clarity in user stories. The connection fits my spec-driven agent work: the acceptance criteria need to be clear enough to check the result.&lt;/p&gt;
&lt;p&gt;Good prompts require the same discipline as good user stories: clarity, specificity, constraints, and acceptance criteria. The thinking is harder upfront, but the downstream efficiency is dramatic. And if a good prompt is a good user story, the logical next step is a full specification, a persistent document that captures requirements, design decisions, and acceptance criteria in one place. (I explore this further in my companion piece, &lt;a href=&quot;https://caskeycoding.com/blog/spec-driven-development-and-the-folder-architecture-that-makes-it-work&quot; class=&quot;internal-link&quot;&gt;Spec-Driven Development and the Folder Architecture That Makes It Work&lt;/a&gt;.)&lt;/p&gt;
&lt;p&gt;Chapter 7 turns to &lt;strong&gt;how you work on an engineering team that has adopted AI&lt;/strong&gt;. Kerwin identifies two archetypes worth watching for:&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;The Resident Skeptic:&lt;/strong&gt; This person specializes in doubt without building. Kerwin references Amazon&apos;s principle of &quot;disagree and commit,&quot; and he&apos;s right. Once your organization has committed to AI, constant skepticism helps no one: not the team trying to ship, not your career, not your own fluency with the tools. Skepticism earns its place in design reviews and threat-modeling, not in paralysis.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;The Expert&apos;s Paradox:&lt;/strong&gt; Experienced engineers sometimes confine AI to narrow tasks, documentation, simple functions, while refusing to delegate more complex thinking. This self-imposed limitation leaves performance on the table.&lt;/p&gt;
&lt;h2 id=&quot;the-underrated-part-design-and-discipline&quot;&gt;The Underrated Part: Design and Discipline&lt;a href=&quot;https://caskeycoding.com/blog/book-review-enterprise-vibe-coding-playbook-building-real-software-with-ai#the-underrated-part-design-and-discipline&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Chapter 6 is titled &quot;Design Don&apos;t Dive In,&quot; and I couldn&apos;t agree more. The difference between a hastily assembled codebase and a maintainable system is upfront thinking. With AI, this matters more. You can use AI as your thinking partner to reason through the user layer, the UI layer, the data layer, the business rules, the edge cases, the data models. You can ask it to challenge your assumptions. But you can&apos;t skip the thinking.&lt;/p&gt;
&lt;p&gt;Design is the differentiator. AI excels at implementation and iteration, but it cannot replace architectural judgment, domain expertise, or the messy work of understanding constraints.&lt;/p&gt;
&lt;p&gt;Kerwin also acknowledges what often gets overlooked: even with AI assistance, the underlying code is often a mess underneath. Shortcuts, glue code, technical debt: these don&apos;t disappear. They&apos;re just easier to accumulate if you&apos;re not disciplined. This reaffirms that using AI to accelerate development doesn&apos;t mean lowering standards. It means raising the bar on review and refactoring.&lt;/p&gt;
&lt;p&gt;But here&apos;s the question Kerwin leaves open: if the thinking is non-negotiable, where does it live? The thinking needs a home: persistent, reviewable, and structured enough that both humans and AI can follow it. That&apos;s the territory of spec-driven development and structured folder architecture, and it&apos;s where I think the next chapter of this conversation is being written.&lt;/p&gt;
&lt;h2 id=&quot;voice-and-thinking-out-loud&quot;&gt;Voice and Thinking Out Loud&lt;a href=&quot;https://caskeycoding.com/blog/book-review-enterprise-vibe-coding-playbook-building-real-software-with-ai#voice-and-thinking-out-loud&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Chapter 5, &quot;The Power of Voice,&quot; made me smirk at first. Speaking to your computer? It felt embarrassing, inefficient, and gimmicky. But after reading Kerwin&apos;s take, I gave it a serious try.&lt;/p&gt;
&lt;p&gt;I was surprised. Voice-to-transcription technology has improved dramatically, and more importantly, the workflow is different from typing. Speaking allows you to capture your thoughts at a higher level before editing and refining. It&apos;s like a rough draft that forces you to get your ideas out before you polish them. The revision phase comes next: the hard coding, the rewrites, the actual technical work.&lt;/p&gt;
&lt;p&gt;I&apos;m not doing this in the office yet (yes, I still feel self-conscious), but I&apos;ve recommended the approach to others. If more engineers actually tried this, I think adoption would shift quickly. It&apos;s a tool for gathering and aggregating thoughts faster than you can type them.&lt;/p&gt;
&lt;h2 id=&quot;the-missing-piece-cultural-adoption&quot;&gt;The Missing Piece: Cultural Adoption&lt;a href=&quot;https://caskeycoding.com/blog/book-review-enterprise-vibe-coding-playbook-building-real-software-with-ai#the-missing-piece-cultural-adoption&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Here&apos;s what Kerwin does well but what every team will struggle with: moving from individual productivity to organizational capability. You can be the best AI-assisted developer on your team, but if your organization isn&apos;t on board, you&apos;ll hit a ceiling.&lt;/p&gt;
&lt;p&gt;In my own spec-driven agent loops, the repeatable work starts with a written requirement and ends with a check against it. A team adopting the same approach needs to agree on who writes that requirement and who reviews the result.&lt;/p&gt;
&lt;p&gt;But adoption is cultural, not technical. It requires skeptics to engage rather than complain, experts to experiment rather than gatekeep, and organizations to invest in training people how to prompt, how to design for AI assistance, and how to integrate these tools into their workflows. And it requires artifacts that make AI-assisted work legible to the organization: specs that product managers can review, folder structures that new engineers can navigate, routing tables that make the AI&apos;s behavior predictable rather than mysterious.&lt;/p&gt;
&lt;h2 id=&quot;a-complementary-read&quot;&gt;A Complementary Read&lt;a href=&quot;https://caskeycoding.com/blog/book-review-enterprise-vibe-coding-playbook-building-real-software-with-ai#a-complementary-read&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;If you finish &lt;em&gt;&lt;a href=&quot;https://www.enterprisevibecoding.com/&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Enterprise Vibe Coding Playbook&lt;/a&gt;&lt;/em&gt; and want to deepen your understanding of AI&apos;s role in leadership and organizational change, I&apos;d recommend &lt;em&gt;&lt;a href=&quot;https://www.amazon.com/s?k=The+AI-Driven+Leader+Geoff+Woods&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;The AI-Driven Leader&lt;/a&gt;&lt;/em&gt; by Geoff Woods. It builds on the &quot;thinking partner&quot; model that Kerwin introduces and extends it beyond engineering to product, strategy, and organizational design.&lt;/p&gt;
&lt;p&gt;And if you&apos;re ready to move from philosophy to methodology, to see how the &quot;design don&apos;t dive in&quot; mindset translates into persistent specs, structured folder architecture, and context-aware AI workflows, I wrote a companion piece: &lt;a href=&quot;https://caskeycoding.com/blog/spec-driven-development-and-the-folder-architecture-that-makes-it-work&quot; class=&quot;internal-link&quot;&gt;Spec-Driven Development and the Folder Architecture That Makes It Work&lt;/a&gt;.&lt;/p&gt;
&lt;h2 id=&quot;the-verdict&quot;&gt;The Verdict&lt;a href=&quot;https://caskeycoding.com/blog/book-review-enterprise-vibe-coding-playbook-building-real-software-with-ai#the-verdict&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;&lt;em&gt;Enterprise Vibe Coding Playbook&lt;/em&gt; is worth reading for any engineer, tech lead, or manager grappling with AI adoption. It is a practical field guide to how real teams work with AI as a thinking partner and accelerator, specific about the prompt-engineering craft it teaches and clear-eyed about the pitfalls it names.&lt;/p&gt;
&lt;p&gt;The book&apos;s greatest strength is that it doesn&apos;t pretend to have all the answers. Instead, it models the framework: clarify your thinking, use AI to refine it, review rigorously, iterate.&lt;/p&gt;
&lt;p&gt;If you&apos;re on the fence about AI-assisted development, this book will challenge your assumptions. If you&apos;re already using it, it will give you language and frameworks to advocate for broader adoption in your organization. And if your organization is stuck in the vibe coding debates, hand this to the skeptics and the experts alike.&lt;/p&gt;
&lt;p&gt;Let AI write the code, but never let it own the thinking. Keep the requirements, the design, and the review yours, and give them a home more durable than a chat window. Do that and the tool compounds your judgment. Skip it and you are just generating technical debt faster.&lt;/p&gt;</content:encoded>
    </item>
    <item>
      <title>Welcome: Building Platforms for Scale</title>
      <link>https://caskeycoding.com/blog/welcome-building-platforms-for-scale</link>
      <guid isPermaLink="true">https://caskeycoding.com/blog/welcome-building-platforms-for-scale</guid>
      <pubDate>Thu, 12 Jun 2025 00:00:00 GMT</pubDate>
      <dc:creator>Eric Caskey</dc:creator>
      <category>platform</category>
      <category>observability</category>
      <category>monitoring</category>
      <category>introduction</category>
      <description>Where this blog started: owning enterprise monitoring at Prudential and Amazon, an automation mishap that paged a whole support queue for ten minutes, and the throughline that still runs through everything I build, make the safe path the only path and then prove it.</description>
      <content:encoded>&lt;p&gt;The sharpest lesson of my career came during a deployment when a batch of misaimed alerts paged an entire support queue at once: when the automation is large, a small mistake does not stay small. I have spent most of my career on one problem in different shapes, keeping a large system accurate about its own health without a person having to remember to check. Monitoring, and the automation around it.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://caskeycoding.com/blog/welcome-building-platforms-for-scale-blast-radius.svg&quot; alt=&quot;Boxes stepping up from one team with a localized alerting mishap to one company with an organization-wide monitoring standard, then a fleet of my own at the same size as the company box, distinguished in green, where the same lesson is structural.&quot;&gt;&lt;/p&gt;
&lt;h2 id=&quot;one-teams-standard-a-companys-blast-radius&quot;&gt;One team&apos;s standard, a company&apos;s blast radius&lt;a href=&quot;https://caskeycoding.com/blog/welcome-building-platforms-for-scale#one-teams-standard-a-companys-blast-radius&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;At Prudential I owned the enterprise monitoring platform and set the standard for how infrastructure got watched across the company. I chose the hardware it ran on and led the migration off the legacy systems onto that standard. The lesson that stuck was about blast radius. When one team&apos;s decision sets monitoring for a whole company, a good call protects critical services and a bad one exposes them, and you often do not find out which you made until something breaks.&lt;/p&gt;
&lt;h2 id=&quot;coverage-that-every-team-gets-by-default&quot;&gt;Coverage that every team gets by default&lt;a href=&quot;https://caskeycoding.com/blog/welcome-building-platforms-for-scale#coverage-that-every-team-gets-by-default&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;The next version of the problem was the same one an order of magnitude bigger. Infrastructure at Amazon came and went constantly, so the monitoring had to find new hosts and services on its own, attach the right alarms as they appeared, and let go as they disappeared. Writing the shared standards, alert policies, and deployment playbooks turned that from a chore every team repeated into something they got by default. I wrote about that work in more detail in a &lt;a href=&quot;https://caskeycoding.com/case-studies/fleet-monitoring&quot; class=&quot;internal-link&quot;&gt;case study on fleet monitoring&lt;/a&gt;.&lt;/p&gt;
&lt;p&gt;The payoff was that a team could ship a service without first becoming a monitoring expert, and still trust that if the service got sick, someone would know.&lt;/p&gt;
&lt;h2 id=&quot;the-mishap&quot;&gt;The mishap&lt;a href=&quot;https://caskeycoding.com/blog/welcome-building-platforms-for-scale#the-mishap&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;Not every deploy went cleanly. One afternoon we rolled monitors across a large slice of the environment and pointed every one of their alerts at a single support queue. For a short stretch that queue took an alarm from every affected host at once, until we aimed the flood back at ourselves and rolled the change back. It taught me the rule I still work by, in one sentence: when the automation is large, a small mistake does not stay small. It arrives everywhere at the same time.&lt;/p&gt;
&lt;h2 id=&quot;what-i-write-about-here&quot;&gt;What I write about here&lt;a href=&quot;https://caskeycoding.com/blog/welcome-building-platforms-for-scale#what-i-write-about-here&quot; class=&quot;heading-anchor&quot; aria-label=&quot;Link to section&quot;&gt;#&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;That is the throughline, and it still runs through everything on this site. I build systems where the safe behavior is the structural default rather than a rule someone has to remember, and I write about how that goes, including the parts that fail.&lt;/p&gt;
&lt;p&gt;These days the systems are my own. A finance engine that &lt;a href=&quot;https://caskeycoding.com/finance&quot; class=&quot;internal-link&quot;&gt;grades stocks on rules I can inspect&lt;/a&gt;, a &lt;a href=&quot;https://caskeycoding.com/lab&quot; class=&quot;internal-link&quot;&gt;playground of interactive market visualizations&lt;/a&gt;, and a running account of what it is like to &lt;a href=&quot;https://caskeycoding.com/blog&quot; class=&quot;internal-link&quot;&gt;build and ship software this way, with an AI agent doing the typing&lt;/a&gt;. The domain moved from enterprise infrastructure to a small fleet of my own products. The question did not: how do you build a system you can trust, and how do you prove that rather than hope it?&lt;/p&gt;
&lt;p&gt;What is different now is that I can show the receipts: the code, the dated track record, the run where it broke, so you can check that the safe path held instead of taking my word. If you have ever watched a one-line mistake page an entire fleet, we will get along.&lt;/p&gt;
&lt;p&gt;Eric Caskey&lt;/p&gt;</content:encoded>
    </item>
  </channel>
</rss>