I've been experimenting with a simple idea: add a YAML frontmatter block to the top of each file.
/**
* ---
* purpose: Fetches player data from FPL API
* related:
* - ./search/route.ts - paginated version
* ---
*/
The theory is that the AI reads just the first 15-20 lines of each file, builds a rough map of the codebase, and only loads full files when needed.
On paper, the numbers look good. A 300-line file's frontmatter might use ~50 tokens versus ~1500 for the full file. But whether that translates to meaningful gains in practice—fewer wasted reads, better file selection—is less clear. It depends on how well the AI actually uses the information, and whether the overhead of maintaining frontmatter is worth it.
There's a secondary benefit: it doubles as documentation. Unlike comments buried in the code, frontmatter sits at the entrance.
I'm not convinced yet. It's extra friction on every file, and the actual efficiency gains are hard to measure. A benchmarking test I conducted seemed to show the context window consumption reduced to 40% of it's previous size, much smaller than the theoretical. But it's an interesting direction—treating code like a searchable index rather than a pile of files to grep through.
Here's what this might look like across a real project—a serverless data pipeline that mirrors the Fantasy Premier League APIAPI A set of rules and protocols that allows different software applications to communicate with each other. APIs define the methods and data formats that applications can use to request and exchange information. into Postgres:
// app/api/cron/route.ts
/**
* ---
* purpose: Cron endpoint triggered by GitHub Actions hourly
* inputs:
* - Authorization header (cron secret)
* outputs:
* - Triggers data collection job
* related:
* - ./lib/collector.ts - actual collection logic
* - ./lib/db/jobs.ts - job tracking
* ---
*/
// lib/collector.ts
/**
* ---
* purpose: Fetches fresh data from FPL API and writes snapshots
* inputs:
* - None (fetches from external API)
* outputs:
* - Immutable snapshots in player_snapshots table
* - Updated master tables (players, teams)
* related:
* - ./db/snapshots.ts - snapshot storage
* - ./db/players.ts - player master table
* - ./fpl-client.ts - API client
* domain: FPL data is time-sensitive; snapshots preserve history
* ---
*/
The pattern particularly starts to pay off when files reference each other. An AI looking for "how team optimization works" can read the headers, see that genetic.ts depends on fitness.ts for scoring, and load only the relevant files. Without frontmatter, it would likely load the entire lib/ directory to understand the relationships.
Obviously this requires some maintenance to keep the frontmatter fresh/accurate, but Claude Code helps do that.
]]>Most programming languages force you to read inside-out. Consider filtering and transforming a list in JavaScript:
console.log(reduce(map(filter(numbers, x => x > 2), x => x * x), 0, (a, b) => a + b))
Your eyes jump to the innermost function, then work outward. It's backwards from how we naturally describe the process: "take the numbers, filter them, square them, sum them up."
Lea fixes this with pipes:
let numbers = [1, 2, 3, 4, 5]
numbers
/> filter((x) -> x > 2)
/> map((x) -> x * x)
/> reduce(0, (acc, x) -> acc + x)
/> print -- 50
Data flows left-to-right through transformations. You read it exactly as you'd explain it.
The other thing that always frustrated me: handling retries, timeouts, and caching in production code requires so much boilerplate. In Lea, these are first-class language features through decorators:
let fetchUser = (id) -> http.get("/users/" ++ id)
#retry(3)
#timeout(1000)
#memo
No wrapper functions. No importing retry libraries. The resilience behaviour is declared right where the function is defined.
Lea occupies a specific niche: functional scripting with built-in resilience. It's designed for the kind of code that glues systems together—data pipelines, APIAPI A set of rules and protocols that allows different software applications to communicate with each other. APIs define the methods and data formats that applications can use to request and exchange information. orchestration, backend automation.
The goal isn't to replace JavaScript or Python everywhere. It's to make certain kinds of code dramatically more readable and robust.
Some design choices:
let for constants, maybe for the rare mutable variable:: Int annotations/> operator isn't an afterthought; it's the primary way to compose operationsLea is still experimental. It has a tree-walk interpreter written in TypeScript, a VS Code extension for syntax highlighting, and a REPL for playing around. It's perfect for learning about language design or prototyping data transformation logic.
Is it production-ready? No. But that's not really the point. Sometimes you build things to explore ideas, to see what programming could feel like if we made different choices.
If you're curious, check out the GitHub repo or use the playground. Run the REPL. Try writing some pipelines. Let me know what you think.
git clone https://github.com/mcclowes/lea.git
cd lea
npm install
npm run repl
I've been working on a new game called Prefix.
You have to guess the word of the day (usually a 5-12 letter word). You start with the first letter revealed. By guessing words that fit given the letters revealed so far, you gradually arrive at the right answer.
You can play it here.
It looks a bit like Wordle, but it's actually an attempt to make a 1-player version of the fantastic word game Contact.
WIP
I haven't really touched the tech since 2017, and my main memory of them ws encountering issues with them caching code and breaking sites (which is still a risk but was also probably mainly inexperience). Looking into them 8 years later, I was surprised to see...
### 1. It's so fully featured
And the features are pretty easy to set up.
You can see everything a PWAPWA A Progressive Web App (PWA) is a type of web application that is built with progressive enhancement, rather than traditional web development techniques. PWAs are designed to be fast, reliable, and installable on a user's device. can do here: https://whatpwacando.today/
I've found implementing notifications the PWAPWA A Progressive Web App (PWA) is a type of web application that is built with progressive enhancement, rather than traditional web development techniques. PWAs are designed to be fast, reliable, and installable on a user's device. way pretty nice and the storage features are great. For instance, having offline-access to my full FPL database is great, when the official FPL doesn't work offline.
If you go through each of those features on your mobile device, you'll probably see that most of them, especialy the cool most native feeling things, aren't supported.
Given Steve Jobs was such a PWA-believer, it's disappointing that Apple is so behind the state-of-the-art in PWAPWA A Progressive Web App (PWA) is a type of web application that is built with progressive enhancement, rather than traditional web development techniques. PWAs are designed to be fast, reliable, and installable on a user's device. support (though obviously Apple has plenty of reasons to fear exposing near-native app experiences without the need to go through app certification).
If you've already done the hard part of implementing an app, the pretty boilerplated work of retrofitting your web app into a PWAPWA A Progressive Web App (PWA) is a type of web application that is built with progressive enhancement, rather than traditional web development techniques. PWAs are designed to be fast, reliable, and installable on a user's device. is trivial for Claude/Cursor.
Ultimately though, very few people ever 'Add to home screen' on iPhone (or know it's an option), and even less see the 'Install app' icon in the Chrome URL bar. It's so hidden away in these UIs.
It was a nice reminder to me to see what apps I use regularly already have PWAPWA A Progressive Web App (PWA) is a type of web application that is built with progressive enhancement, rather than traditional web development techniques. PWAs are designed to be fast, reliable, and installable on a user's device. functionality - Vercelvercel Vercel is a cloud platform for frontend developers. It is used to deploy and host websites and web applications., youTube, and more. It can be really nice to have a dedicated window, dock presence, etc. for your go-to web sites, and remove the clutter of the browser.
]]>The project is a serverless data pipeline that mirrors the Fantasy Premier League public APIAPI A set of rules and protocols that allows different software applications to communicate with each other. APIs define the methods and data formats that applications can use to request and exchange information. into a Supabase Postgres database. It's built with Next.js App Router and runs on Vercelvercel Vercel is a cloud platform for frontend developers. It is used to deploy and host websites and web applications., where scheduled GitHub Actions workflows invoke the collection routines through APIAPI A set of rules and protocols that allows different software applications to communicate with each other. APIs define the methods and data formats that applications can use to request and exchange information. routes. The collected data is stored as immutable snapshots, so I can analyze historical trends and make better decisions about my team.
The architecture is straightforward: GitHub Actions hits a cron endpoint every hour, which triggers the data collector. The collector fetches fresh data from the FPL APIAPI A set of rules and protocols that allows different software applications to communicate with each other. APIs define the methods and data formats that applications can use to request and exchange information., writes snapshots, and updates master tables. Everything is tracked in Supabase with job history, so I can see what's happening and when.
The dashboard gives me a clean view of players, teams, and gameweek data. I can filter by position, team, status, and see historical trends through the snapshot system. But the real power of the tool comes from its team optimization features.
What the FPL!? helps you optimize your team using my own custom metrics, including expectation-weighted fitness. This metric goes beyond simple point totals by weighting player performance against their expected output based on their position and upcoming fixture difficulty. It gives you a clearer picture of which players are truly outperforming their cost and situation.
The optimization engine uses a genetic algorithm to find a (probably) optimal team composition within your budget constraints. It starts with a population of random team configurations, then evolves them over multiple generations by:
This approach lets you explore thousands of team combinations automatically, finding lineups you might never have considered manually. You can specify constraints like budget, required players, and formation preferences, and the algorithm will find the best team that meets those requirements.
The whole thing is open source and available on GitHub, with a full RESTREST An architectural style for designing networked applications. REST uses HTTP methods (GET, POST, PUT, DELETE) to perform operations on resources identified by URLs. APIAPI A set of rules and protocols that allows different software applications to communicate with each other. APIs define the methods and data formats that applications can use to request and exchange information. for querying current and historical data. It's been a fun project to rebuild with modern tooling, and it's already helping me make better picks this season.
If you're curious about the original 2019 version, you can read about it here.
]]>Fetching repository details…
I've always been frustrated by how technical documentation often assumes readers know all the jargonjargon Technical jargon is a type of language that is used to describe technical concepts in a precise and concise manner. It is often used in scientific, engineering, and technical fields.. Whenever I build a site with DocusaurusDocusaurus A static site generator for React-based websites. Docusaurus is used to build this website., I wanted a way to automatically link and explain key terms, so readers can hover to see definitions without breaking their flow.
There used to be plugins for this, but these open source projects all went stale.
That's why I built docusaurus-plugin-glossary - a plugin that automatically detects glossary terms in your markdown content and turns them into interactive tooltips.
The plugin does two things well:
Interactive tooltips: Hover over any linked term (like this - DocusaurusDocusaurus A static site generator for React-based websites. Docusaurus is used to build this website.) and see its definition instantly. Click to navigate to the full glossary page for related terms.
Automatic term detection: It scans your markdown files and automatically links glossary terms with a subtle dotted underline. No manual markup required.
The magic happens through a remark plugin that processes your markdown before it hits the browser. It respects word boundaries (so "APIAPI A set of rules and protocols that allows different software applications to communicate with each other. APIs define the methods and data formats that applications can use to request and exchange information." doesn't match "application"), and it smartly skips terms inside code blocks, links, or existing components.
You can install it from npm:
npm install docusaurus-plugin-glossary
Fetching package details…
Or check out the GitHub repository for documentation, examples, and source code.
Links:
]]>
How cool is Good Press?!
]]>
I've been working on an MRP-based election modal and poll aggregation web app.
Let me know if you want access!
]]>Loved Paper Crown. Great, fun, relatable poetry.
]]>With ubiquitous deck trackers and shared analytics, card game communities quickly converge on optimal lists and lines. Like an optimisation problem, the search space collapses to a few dominant solutions. Experimentation becomes a tax: novelty is punished because you already know it underperforms. You can hear streamers say they “can’t do anything fun” without tanking their win rate, even when entertainment is the goal.
Streaming dashboards reveal what “works,” and modern tools make it trivial to replicate those sounds. Intros get shorter, hooks arrive earlier, and timbres cluster around proven palettes. When everyone optimises for the same metrics, we rush toward homogeneity.
If ignorance is the fuel of play, then a little fog of war is a design feature, not a bug. Keep some hidden information, time‑delayed feedback, or friction in the loop, and the space for creativity reopens.
]]>Below is a small grid of cards using images I generated with ChatGPT. Move your mouse (or touch) to tilt and reveal the foil. Use the toggle to switch between different mask modes. For each, I've created an non-holo overlay manually, making some elements sit apart from the holographic card elements.
The winner was Ana Reisens with her poem "The Translated Instruction Manual for Loving", which used funny excerpts from badly translated instruction manuals to create a poetic guide for love. The other runners up were Larry Needham with "Marriage Bed of the Roses" and Jim Burns with "Tourist Trap".
All four poems will appear in their upcoming Autumn issue, Machinery.
]]>I've been working on an interesting project that combines AI, automation, and generative art. It's called ai-art, and it's a self-evolving digital canvas that improves itself over time.
The project creates a digital artwork that evolves automatically through several mechanisms:
The artwork state is stored as structured data in src/artwork-state.ts, and a React Canvas component renders it. The improvement scripts analyze the current state for visual balance, color harmony, and element distribution before making changes.
The project uses GitHub Actions to run three different improvement systems in parallel:
improve-artwork.jsimprove-codebase.jsThe system doesn't just make random changes. It applies intelligent heuristics:
Here's a carousel showing how the artwork has evolved over time:
This project explores several interesting concepts:
The artwork is currently at generation 176 and continues to evolve. You can see the live version at ai-art-sigma.vercel.app, and the full source code is available on GitHub.
What's fascinating is watching how the combination of random mutations and intelligent improvements creates something that feels both organic and purposeful. The AI doesn't just make random changes - it analyzes the current state and applies principles of good design, color theory, and composition.
It's a reminder that automation doesn't have to be mindless. With the right constraints and intelligence, automated systems can create genuinely interesting and evolving work.
]]>
Consider Shakespeare. Nearly every one of his plots hinges on someone not knowing something: Viola disguising herself as a man, Iago's manipulation of Othello through misperception, letters lost or forged, twins mistaken for each other. The comedy and tragedy alike arise from gaps—of knowledge, of identity, of intention. To a God-like observer, nothing surprising happens in Twelfth Night. But to its players, the unknown is everything.
This tension between what is known and what cannot be known isn't just theatrical, it's fun! In Sam Sorensen's game Cataphracts, a wargame simulating Byzantine campaigns, you can see how the real drama lies not in combat mechanics but in the fog of war—supply chains faltering, orders misunderstood, messengers ambushed. The challenge isn't what to do, but whether your intention will survive the distance between thought and action.
Dataism tends to frame complete information as some oerfect state, and income knowledge as a bug to be fixed. But these examples indicate it might be a little dull knowing everything.
]]>In hindsight, these definitions reveal a persistent tension: is intelligence located in the mechanism itself, or in the results it produces? Should we evaluate a system by its inner workings, or by how it makes us feel?
At their core, large language models like GPT are conceptually straightforward: they predict the next token in a sequence, guided by statistical patterns. If you trace a response step by step, you won’t find “thought” as we experience it, and certainly not self-awareness.
Critics seize on this mechanistic truth to dismiss these systems as mere stochastic parrots — mathematical engines that remix human-authored text without genuine understanding. This is true.
Yet these same models write working code, pass professional exams, offer effective therapy, plan complex trips, interpret poetry, draft legislation, and even play chess tutor or romantic confidant. People build relationships with these LLMs that, to them, are very real.
They are reshaping law, journalism, design, education, and medicine—often in profound ways. The mechanisms may be simple, but their outputs can surprise, unsettle, amuse, and even move us. For most users, intelligence isn’t a property hidden under the hood—it’s an experience at the interface.
We’re surrounded by systems we only half understand. You can’t describe exactly how your pancreas regulates insulin, how your car’s fuel injection works, or how a judge arrives at sentencing. You model what you don’t see—simulating beliefs, desires, and likely actions in people, institutions, and now, machines.
The Turing Test wasn’t about proving consciousness; it was about demonstrating competence. Its power lies in shifting the question of intelligence away from internal processes and toward external behavior. By that measure—intelligence as perceived—modern language models already qualify.
Every time AI masters a new benchmark, we redefine “intelligence” to exclude it:
This intellectual retreat obscures what is already happening and lulls us into complacency. If we keep shifting the bar, we risk ignoring systems capable of influence, persuasion, or even manipulation—simply because they don’t think “our” way.
In everyday life, we judge people by their words and deeds, not by their brain chemistry. We call someone intelligent if they communicate clearly, solve problems deftly, or adapt to new challenges—without demanding a tour of their neural pathways. We infer intelligence from interaction and outcome.
The same standard applies to machines. When an LLM untangles a confusing question, tutors a student, or composes a lullaby, it feels intelligent. Focusing solely on “predictive text” is like calling a violin “just vibrating strings” or a novel “just ink on paper.” Mechanism matters—but meaning emerges in context.
Navigating this AI era, you must hold two truths simultaneously:
Ignoring either leads to mistakes: techno-mysticism on one side (or worse), dismissive complacency on the other. Instead, we need a Turing-style perspective that recognises intelligence as a property that emerges in the space between system and user.
That doesn’t mean abandoning rigor or skepticism. It means focusing on outcomes as well as architecture, and acknowledging what’s already changing—even if we don’t yet fully grasp how.
Because intelligence—like meaning, trust, or beauty—isn’t hidden in the mechanism. It lives in the moments when something surprises us, helps us, or moves us. And those moments are already here.
]]>
In this post, I'll walk you through my process of creating Fakemon (fan-made Pokémon) using a combination of traditional sketching and modern AI tools. The journey takes us from initial concept sketches through ChatGPT refinement, and finally to Sora for animation.
The process began with traditional pencil and paper sketches. This phase is crucial for getting the basic concept down and exploring different design possibilities. I usually start with a type combo, and try and come up with I focused on creating unique and interesting silhouettes while maintaining the distinctive Pokémon style. After the initial rough sketch, I refined the design with more detailed linework.
With ChatGPT's new o3 model & image generation, and some specific prompts I've crafted, I've found I can get pretty great fake Pokemon designs. I just upload a photograph of the above in the prompt, and ask for a more refined version of the design, with specific reference to the creatures type, colours, etc.
Then I creatged an image for card art, in this case a holographic design variant:
The final step was using Sora to generate an animated version of Ghowlish. This brought the creature to life, allowing us to see its movements and expressions in action:
I find this incredibly hit and miss, and it's still absolutely awful most of the time, but in this case I actually got a good result.
You can also turn to ChatGPT to help refine the design and develop the Pokémon's characteristics. I've used prompts to design its abilities and moves, and more.
]]>