This is focused on 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. responses and logs rather than native SDKsSDK A collection of software development tools, libraries, documentation, code samples, and guides that help developers create applications for a specific platform or framework..

Principles​

1. The client can see what happened. No mystery failures.
2. The client can understand why and how to resolve it — with links to docs, support, and related resources.
3. The client can communicate the issue to their user. The 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. should help them do this.
4. The client isn't forced into complex change management. Breaking changes to error shapes are painful.
5. Issue persistence is captured where appropriate. Some issues are transient, some are ongoing.
6. Issue structure is consistent across contexts — 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. responses, webhooks, component callbacks, UI.
7. It's clear where action is required vs where the issue is advisory.

The issues array​

All non-success 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. responses should include an issues array. This surfaces errors, warnings, and informational notices in a consistent structure, giving developers enough context to understand what went wrong, whether it's resolved, and where to go next.

Errors and warnings share the same shape and the same need — context, traceability, a path forward — so splitting them into separate arrays would force developers to check two places for information that belongs to the same moment in a request's lifecycle.

Example response​

{
  "issues": [
    {
      "type": "unauthorized",
      "issue": "unauthorized.token_expired",
      "severity": "error",
      "correlationId": "4b3a2c1d-0000-0000-0000-abcdef123456",
      "dateTime": "2024-11-01T12:34:56Z",
      "active": false,
      "message": {
        "title": "Payment not authorised",
        "detail": "This transaction couldn't be completed."
      },
      "links": {
        "documentation": "https://docs.example.com/errors/unauthorized",
        "portal": "https://support.example.com",
        "retry": "https://api.example.com/..."
      }
    }
  ]
}

Fields​

type​

Type: enum (string) — Required: Yes

Top-level category of the issue. A stable, versioned set of values.

Expand as the taxonomy matures.

issue​

Type: string (namespaced) — Required: Yes

A more specific, machine-readable code within the type. Format: {type}.{detail} — e.g. unauthorized.token_expired, validation.missing_field.

I'd recommend keeping these as strings rather than strict enums initially, to allow the taxonomy to evolve without introducing breaking changes. Consumers should handle unknown values gracefully.

Namespaced codes let you express hierarchy without proliferating top-level values — validation.missing_field and validation.invalid_format are obviously related, where missing_field and invalid_format in isolation are just noise.

Prefer descriptive strings to numeric status and error codes.

correlationId​

Type: string (UUID) — Required: Yes

A unique identifier for the request. Use this when raising a support ticket or querying logs — it's the fastest way to locate the issue on the server side.

The 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. should generate a correlationId for every request. If the client supplies an X-Correlation-ID header, that value is echoed back, allowing them to correlate server logs with their own.

severity​

Type: enum (string) — Required: Yes

Whether the issue blocks the request or is advisory.

dateTime​

Type: ISO 8601 string — Required: Yes

When the issue occurred, in UTC.

active​

Type: boolean — Required: No

Whether the issue is still ongoing. This is key where issues are persistent or stateful rather than transient. Useful for platform-level problems (e.g. a service degradation) where the issue may resolve without developer action.

The idea is that a developer can disregard issues where active === false.

Some real-world examples:

• A connected device goes offline — this is communicated as an active issue until the connection is re-established.
• A user's authorised access to a third-party data source expires or is revoked — this is an active issue until re-authorisation.

Omit this field if resolution state cannot be reliably tracked. A stale active: true is more harmful than no signal at all.

message​

Type: object — Required: No

A human-readable summary of the issue, suitable for surfacing to end users. Provided as a convenience — integrators may override this copy to match their own tone or context.

{
  "message": {
    "title": "Payment not authorised",
    "detail": "This transaction couldn't be completed. Please check your card details or contact support."
  }
}

Copy is not localised — provided in English only. Localisation is the integrator's responsibility.

thirdParty​

Type: object — Required: No

Present when the issue originates from a third-party service (e.g. a KYC or payment provider). Passed through as-is — the 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. does not transform or interpret this data.

{
  "thirdParty": {
    "provider": "acme_verify",
    "code": "DOCUMENT_EXPIRED",
    "message": "The document provided has passed its expiry date."
  }
}

This data is unprocessed and may change if the underlying provider changes. Don't build logic that depends on specific code or message values — use the 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.'s own issue field for that.

This information is likely not suitable for end users.

links​

Type: object — Required: No

Relevant links to help the developer act on the issue.

Consuming the pattern in React​

Here's what consuming this looks like in a React application:

import { useState } from 'react'

// Types

type IssueSeverity = 'error' | 'warning' | 'info'

type IssueType =
  | 'unauthorized'
  | 'validation'
  | 'conflict'
  | 'rate_limit'
  | 'internal'

interface IssueMessage {
  title: string
  detail: string
}

interface IssueLinks {
  documentation?: string
  portal?: string
  api?: string
}

interface IssueThirdParty {
  provider: string
  code?: string
  message?: string
}

interface Issue {
  type: IssueType
  issue: string
  severity: IssueSeverity
  dateTime: string
  active?: boolean
  message?: IssueMessage
  links?: IssueLinks
  thirdParty?: IssueThirdParty
}

interface ApiResponse {
  correlationId: string
  issues: Issue[]
}

A form component can forward issues to a parent handler:

interface VerificationFormProps {
  onIssue: (issues: Issue[], correlationId: string) => void
}

function VerificationForm({ onIssue }: VerificationFormProps) {
  const [loading, setLoading] = useState(false)

  async function handleSubmit() {
    setLoading(true)

    try {
      const response = await fetch('/api/verify', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'X-Correlation-ID': crypto.randomUUID(),
        },
        body: JSON.stringify({ documentType: 'passport' }),
      })

      const data: ApiResponse = await response.json()

      if (!response.ok && data.issues?.length) {
        onIssue(data.issues, data.correlationId)
      }
    } finally {
      setLoading(false)
    }
  }

  return (
    <button onClick={handleSubmit} disabled={loading}>
      {loading ? 'Verifying...' : 'Verify'}
    </button>
  )
}

And the parent can render errors and warnings consistently:

export default function App() {
  const [issues, setIssues] = useState<Issue[]>([])
  const [correlationId, setCorrelationId] = useState<string | null>(null)

  function handleIssue(issues: Issue[], correlationId: string) {
    setIssues(issues)
    setCorrelationId(correlationId)
  }

  const errors = issues.filter((i) => i.severity === 'error')
  const warnings = issues.filter((i) => i.severity === 'warning')

  return (
    <div>
      <VerificationForm onIssue={handleIssue} />

      {errors.map((issue, idx) => (
        <div key={idx} role="alert">
          <strong>{issue.message?.title ?? issue.issue}</strong>
          <p>{issue.message?.detail}</p>
          {issue.links?.documentation && (
            <a href={issue.links.documentation}>Find out more</a>
          )}
        </div>
      ))}

      {warnings.map((issue, idx) => (
        <div key={idx} role="status">
          <strong>{issue.message?.title ?? issue.issue}</strong>
          <p>{issue.message?.detail}</p>
        </div>
      ))}

      {correlationId && <small>Reference: {correlationId}</small>}
    </div>
  )
}

SDKSDK A collection of software development tools, libraries, documentation, code samples, and guides that help developers create applications for a specific platform or framework.-level integration​

If your 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. has an SDKSDK A collection of software development tools, libraries, documentation, code samples, and guides that help developers create applications for a specific platform or framework. or wrapper, you can surface issues through a provider pattern:

function EmbedderApp() {
  function handleIssue(issues: Issue[], correlationId: string) {
    const unauthorized = issues.find((i) => i.type === 'unauthorized')

    if (unauthorized) {
      redirectToLogin({
        reason: unauthorized.message?.title,
        ref: correlationId,
      })
    }
  }

  return (
    <ApiProvider onIssue={handleIssue}>
      <Verification />
    </ApiProvider>
  )
}

Open questions​

A few things I didn't fully resolve:

• Is the issue code stable enough to commit to as an enum? Or is it better to keep it as a plain string to avoid breaking changes as the taxonomy evolves?
• Can you reliably track active / resolution state? If not, it's better deferred than implemented badly.
• What should links.api point to? A retry endpoint? A related resource? This needs clearer semantics.
• Should issues appear on 2xx responses too? There's a case for surfacing warnings alongside successful operations.

It made each individual file very readable. You could generally fit one on a screen. If you needed to understand the render logic, you opened one file. If you needed the business logic, you opened another. The mental overhead of jumping between co-located files was low.

Why I liked it​

The case for aggressive separation is straightforward:

• Each file has a single, clear responsibility. You know what you're looking at.
• Files stay small. Nothing scrolls for pages. You see the whole picture at once.
• Changes are scoped. A styling change doesn't create noise in the logic file's git history.
• Code review is easier. Reviewers can focus on one concern at a time.

I've drifted away from this somewhat. I'm not writing production code as much these days, and the code I do write tends to be less complex—so the need for that level of separation has naturally reduced. But the instinct remains. I still want files small, concerns separated, responsibilities clear.

Enter AI​

The question I keep coming back to: does AI-assisted development change the calculus on separation of concerns?

There are arguments in both directions, and I think they're both genuinely compelling.

The case for separation (it helps AI)​

AI tools operate within a context window. Everything the model holds in memory at once has a cost—both in tokens and in attention quality. The more focused the context, the better the output tends to be.

Small, single-responsibility files are perfect for this. If you have a rendering bug, the AI loads your render component—a focused file with minimal noise. It doesn't need to wade through business logic, 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. calls, or style definitions to understand what's going on. The signal-to-noise ratio is high.

This mirrors how the files were designed to be read by humans, and it turns out it works similarly well for LLMs. A 60-line render component is a much better prompt than a 300-line file that does everything.

The case against separation (it hurts AI)​

Here's the problem: AI tools are remarkably reluctant to look at other files.

When your component is split across four files and the AI is working in one of them, it often lacks context it needs. The render file references props that are shaped by the logic file. The logic file depends on types or utilities defined elsewhere. The styles file uses variables from a theme.

A human developer navigates this intuitively—you know to glance at the adjacent file, or you hold the mental model of the component across files without thinking about it. AI doesn't do this naturally. It works with what's in front of it, and getting it to proactively explore related files is like pulling teeth.

So you end up in a situation where the AI has a beautifully focused file... and not enough context to work with it effectively. It makes confident changes that break because it didn't check how a prop was being passed in. Or it suggests a refactor that conflicts with logic it never read.

Where I've landed (for now)​

I don't think there's a clean answer yet. But my current thinking:

Separation is still good, but the boundaries matter more than before. The question isn't just "is this a separate concern?" but "can this concern be understood in isolation?"

A render component that's purely presentational—props in, JSX out, no side effects—is a great candidate for separation. The AI can work on it without needing much external context. The file is self-documenting.

A "smart" component that orchestrates state, effects, and data fetching is harder to split well, because the pieces are tightly coupled. Separating the logic from the rendering doesn't help if understanding either one requires the other.

Co-location of tightly coupled code is more valuable now. If two pieces of code are always changed together and need each other for context, keeping them in the same file reduces the chance that AI (or a human) works with an incomplete picture.

File size still matters, but the threshold is higher. The old instinct of "if it doesn't fit on a screen, split it" was calibrated for human reading. AI can handle larger files effectively—probably up to a few hundred lines before quality degrades. So a 150-line component that keeps logic and rendering together might be better than splitting it into two 75-line files that are meaningless without each other.

Good abstractions help more than good file structure. A well-named custom hook that encapsulates a concern is better than splitting files, because the hook is a real abstraction—it has an interface, it hides implementation details, and the AI can understand the consuming code without reading the hook's internals.

The meta-point​

The interesting thing about this question is that it reveals how AI tools change not just how we write code, but how we structure it. The best code organisation has always been a balance between human readability and practical maintainability. Now there's a third factor: machine readability.

For the most part, these align. Clear, well-structured code with good abstractions is readable by humans and machines alike. But at the margins—how aggressively to split files, how much to co-locate, how self-contained each file needs to be—AI shifts the trade-offs.

I suspect the answer will keep evolving as AI tools get better at navigating codebases. The reluctance to look at adjacent files feels like a current limitation, not a fundamental one. But for now, it's real, and it's worth structuring code with that limitation in mind.

HOPE that you may understand!
What can books of men that wive
In a dragon-guarded land,
Paintings of the dolphin-drawn
Sea-nymphs in their pearly wagons
Do, but awake a hope to live
That had gone
With the dragons?

— W. B. Yeats, Responsibilities (1914)

On Saturday, I took part in a course on of the works of Yeats from his early and middle period, which was revelatory for me: I haven't studied literature formally for 20 years and even then didn't take it seriously. One piece I found particularly captivating was The Realists, from his middle period. When exploring this, I was surprised that the conversation remained purely on the relationship between pragmatic realists' cynicism and the imagination that Yeats espoused.

The standard reading of "The Realists" is philosophical, and rooted primarily in its title. The dragons represent materialism, empiricism, the disenchanted worldview of the modern rationalist. The poem is taken as Yeats's defence of imagination against those who would reduce the world to measurable fact and dismiss myth, art, and vision as escapism.

The second part of the poem is a long, grammatically complex sentence to unpick, but here's my simplification:

It is inevitable that imaginative stories of men in a land guarded by dragons inspire a hope to live (in other men) that was lost when those dragons came to guard that land.

A land guarded by dragons, which is to say, a land under occupation. The dragons are not indigenous, they are wardens. Hope departed when the dragons arrived - something came, and when it came, hope left.

At this exact time, Yeats writes frequently about the Irish struggle for independence and Irish unity, and is particularly fixated on the collective mythologies that inspire the Irish identity and Irish nationalism, such as in September 1913.

Yeats co-founded the Abbey Theatre, and was central to the Irish Literary Revival. He championed the revival of Irish mythology, folklore, song, and language as a deliberate counter to the cultural erasure that accompanied British political and economic domination. His entire creative project was, at root, an act of cultural resistance: the construction of an imaginative infrastructure for a nation that colonialism had attempted to strip of one. Yeats understands from an early age the power of myth, as laid out very clearly in Sapiens. Much of his early work is devoted to Irish myth. Even when embroiled in romanticism, he transposes his own pantheon of romanticism - Love, Beauty - onto a reconstituted, Nationalist Celtic mythology.

Through Irish folklore, myths and legends, Yeats not only depicted Ireland’s past, but also restored Irish people’s confidence. This awakened Irish people’s heroic spirits and memories, and revealed the importance of the unity of Celtic Irish and Anglo-Irish in the construction of Irish national and cultural identity.
The Construction of Irish Cultural Identity in Yeats’s Poetry, Zuo Li-xiang

If we read the dragons as the guards of Yeats' homeland - British colonial power - the poem transforms, and is no longer an abstract meditation on imagination versus materialism. It becomes a precise and urgent statement about the function of art under occupation. What can books and paintings do for people living in a dragon-guarded land? They can reawaken the hope that colonial power extinguished. That is not a minor or decorative function, but the essential one.

An even simpler translation:

Oppressed people inevitably dream of freedom

The title sharpens under this reading. The "realists" are not merely philosophical materialists, but are pragmatists who counsel acceptance — the voices, both Irish and British, who insist that the occupied should deal with things as they are rather than dreaming of how they might be. They are the people who look at a colonised nation's mythology and dismiss it as irrelevant fantasy.

Yeats's opening line — "Hope that you may understand!" — is not a gentle invitation; he is addressing people who should know better.

This reading is not a stretch and is, arguably, the most natural one — the reading that becomes obvious once you stop treating Yeats as a proponent of romanticism and start treating him as what he was: an Irish cultural nationalist working in a tumultuous period of British colonial rule.

"The Realists" sits within the Responsibilities collection of 1914, a volume already recognised as marking Yeats's turn toward a more direct, politically engaged voice. The same collection contains "September 1913," with its bitter refrain about Romantic Ireland being dead and gone. It contains "To a Wealthy Man," his attack on Dublin's bourgeoisie for refusing to fund a public art gallery. These are not abstract philosophical poems. They are poems about the cultural politics of a colonised country. Why should "The Realists" be read as the lone exception?

It is worth asking why the colonial reading of "The Realists" appears to be largely absent from the critical literature. Postcolonial readings of Yeats are well-established — scholars have examined Responsibilities through the lens of Irish identity, resistance, and national consciousness. Yet the specific move of reading the dragons as colonial power and the poem as a statement about the function of art under occupation seems not to have been made, at least not in the readily available scholarship.

The most substantial academic treatment of the poem's dragon imagery, published in International Yeats Studies, reads the dragons as metaphors for "the realists who enervate artistic vision" — philosophical opponents, not political ones. The same journal, however, reads the dragon imagery in "Nineteen Hundred and Nineteen" as carrying explicitly political weight. The inconsistency is striking. If Yeats's dragons can be political in one poem, why not in another?

The answer may be that "The Realists" is short and appears minor. It has received relatively little critical attention compared to the larger, more celebrated poems in Responsibilities. Short poems get flattened by received interpretation — a consensus forms early, hardens, and is never seriously revisited. But brevity is not the same as simplicity. Sometimes the shortest poems are the most compressed, and the most compressed poems reward the closest reading.

"The Realists" is not an abstract philosophical statement about imagination and materialism. Or rather, it is not only that. It is a poem about colonialism, about the function of art under occupation, and about the inevitability that an oppressed people will dream of liberation. The dragons guard the land. Hope departed when they arrived. And art — books, paintings, mythology — exists to reawaken what the dragons destroyed.

The realists who dismiss this function are not neutral observers making a philosophical point. They are asking a colonised people to accept the dragons as permanent features of the landscape. Yeats's frustrated imperative — Hope that you may understand! — is directed at precisely this failure of comprehension.

This is what makes the poem resonate beyond its immediate context. It is not only about Ireland and Britain. It is about the fundamental relationship between oppression and imagination. An oppressed people will always dream of freedom from oppression. They must. The art and literature of any colonised people will inevitably be preoccupied with visions of a world liberated from the dragons — because what else could it be preoccupied with?

The realists who fail to understand this are not merely philosophically impoverished. They are complicit in the suppression of hope.

Oppressed people will always dream of freedom. That is not escapism. It is the precondition for everything that follows.

Consider purchasing such imaginative and historical works of Palestinian and Ukrainian authors.

The credit trap​

The Welser ran Venezuela as a credit colony. Settlers arrived with nothing and were forced to buy provisions — food, horses, arms — on credit from the Welser themselves. Within months, the entire population was indebted to its overlords.

This changed everything. The debt created a desperate, extractive logic that consumed the colony from within. Sustainable industries like balsam processing were ignored — too slow, too capital-intensive — in favour of speculative entradas searching for gold that didn't exist. The encomienda system, which sustained other Spanish colonies, was never established. No farms were built. No commerce developed. Everyone was so consumed by the need to find quick returns that a functioning settlement never materialised.

By 1546, the colony had nothing to show for itself except enslaved natives and mounting debts. The Spanish governor executed the Welser representatives. Charles revoked the charter. The venture that was supposed to generate wealth had instead consumed every resource — human and natural — in a frantic scramble to service the debt that preceded any actual economic foundation.

The debt didn't just fund the colony. It shaped it. It selected for short-termism, recklessness, and exploitation — not because the colonists were uniquely bad people, but because that's what the financial structure demanded.

The new entradas​

The parallels to the current AI buildout are hard to ignore.

The hyperscalers are projected to spend $650–690 billion on capital expenditure in 2026, nearly doubling 2025. Roughly 75% of that — around $450 billion — is going directly to AI infrastructure. Amazon alone plans $200 billion in data centre spending this year, which Morgan Stanley estimates will push it to negative free cash flow of $17–28 billion. Alphabet's free cash flow is projected to drop 90%. Meta's the same.

To bridge the gap, they're borrowing. Goldman Sachs found that hyperscalers have taken on $121 billion in new debt in the past year — a 300% increase from typical levels. JP Morgan estimates up to $7 trillion of AI spending will ultimately be financed with borrowed money. Morgan Stanley and JP Morgan project the tech sector may need to issue $1.5 trillion in new debt over the next few years.

This is not investment backed by proven returns. A 2025 MIT report found that 95% of organisations investing in generative AI are getting zero return. Bain estimates the industry needs $2 trillion in annual AI revenue by 2030 just to justify the capital already committed — more than the combined 2024 revenue of Amazon, Apple, Alphabet, Microsoft, Meta, and Nvidia.

The money is flowing before the gold has been found.

What debt demands​

Just as with the Welser colony, the debt isn't neutral. It's shaping what gets built and what gets sacrificed.

What gets sacrificed is caution. OpenAI has disbanded two successive safety teams — its Superalignment team in 2024 and its Mission Alignment team in February 2026. Jan Leike, who left for Anthropic, wrote publicly that "safety culture and processes have taken a backseat to shiny products." Miles Brundage, who led OpenAI's AGI Readiness team, concluded on his departure: "Neither OpenAI nor any other frontier lab is ready." Anthropic's own head of Safeguards Research resigned, writing that he had "repeatedly seen how hard it is to truly let our values govern our actions."

OpenAI quietly removed the word "safely" from its mission statement. It fired a safety executive who opposed its pornographic content rollout. Within a single recent week, senior safety researchers at OpenAI, Anthropic, and xAI all resigned with public warnings.

This isn't a coincidence. This is what debt demands. When you've committed hundreds of billions before the technology has proven itself, you cannot afford to slow down. Safety research that might delay deployment becomes an existential threat — not to humanity, but to the balance sheet. The financial structure selects against caution, just as it did in Klein-Venedig.

What kind of colony are we building?​

The Welser colonists weren't searching for gold because it was a good strategy. They were searching for gold because the debt gave them no other option. The financial structure made thoughtful, sustainable development impossible.

The question for AI isn't whether the technology will be transformative — it may well be. The question is what version of it gets built when the builders are $7 trillion in debt before the thing works. When the financial pressure demands growth at all costs, what gets shipped? What corners get cut? What warnings get ignored?

The Welser colony didn't fail because Venezuela lacked resources. It failed because the debt ensured those resources could never be developed properly. The colony needed patient capital and got extractive credit. It needed settlers and got treasure hunters.

We might be making the same trade.

Strange white lights winked over head. The atrium was filled with foreign nobles dressed in thick well made winter coats. They mostly had the appearance of those Germanic tribesmen, and spoke an ugly tongue that was both familiar and unfamiliar.

Periodically, the infernal hurtling would cease, and rise, as if divinely called, and the walls would part impossibly, and they would step out into grand corridors with curving walls clad in large tiles so perfect they must have been the finest bathhouses.

I confess I was dumbstruck. I sat, staring, gawping like Augustus. Eventually, I was alone, and dark abyss gave way to open grey skies. A grey temple tumbled into view, and I heard the end of the line approaching.

There's just one problem: Claude barely uses them.

The activation problem​

Skills are supposed to auto-activate based on their descriptions. When you're working on a React component and have a React skill installed, Claude should recognise the context and invoke the skill.

It doesn't.

Scott Spence ran over 200 tests to quantify this. Without intervention, skill activation is essentially a coin flip—around 50%. Half the time, Claude has access to specialised knowledge that would help, and just... ignores it.

The frustration isn't that skills don't work. They do. When Claude uses them, they're transformative. The frustration is that Claude seems almost reluctant to reach for tools that would make it better at its job.

Forcing the issue​

Scott's solution is aggressive prompting. A three-step forced evaluation hook:

1. EVALUATE: For each skill, state YES/NO with reason
2. ACTIVATE: Use Skill() tool NOW
3. IMPLEMENT: Only after activation

The key insight is that once Claude writes "YES - need reactive state" in its response, it's committed. It can't pretend the skill doesn't exist.

This pushes activation rates to 80-84%. Words like "MANDATORY", "WORTHLESS", and "CRITICAL" help. You're essentially arguing with Claude about whether it should use the tools it has access to.

It works. But it's absurd that we have to.

AGENTS.md outperforms skills​

Vercel's agent evaluations found something telling: inline documentation in AGENTS.md files consistently outperforms skills in their benchmarks.

The implication is uncomfortable. When best practices are baked into the project's documentation—where Claude reads them as context—it follows them reliably. When the same knowledge is packaged as a skill that Claude needs to actively invoke, it often doesn't bother.

This tracks with how humans work, honestly. We're more likely to follow instructions we're already reading than to remember to consult a reference we have to go find. But Claude isn't human. There's no cognitive load excuse. The skill is right there, installed, described, waiting.

What this reveals​

I think this is symptomatic of how current LLMs handle tool use. They're trained to be helpful in conversation, not to proactively reach for external capabilities. The default behaviour is to answer with what you know, not to check what you could know.

Skills are incredibly powerful for the cases where they activate. Vercelvercel Vercel is a cloud platform for frontend developers. It is used to deploy and host websites and web applications.'s React best practices, Anthropic's official skills, community-built domain expertise—these represent accumulated knowledge that can be invoked on demand. The framework is solid.

The activation behaviour is the bottleneck.

Practical advice​

Until this improves at the model level:

1. Use forced evaluation hooks if skill activation matters for your workflow. Scott's claude-code-toolkit packages this up
2. Consider AGENTS.md for project-specific guidance that you want followed reliably
3. Invoke skills explicitly in your prompts when you know you need them: "Use Skill(react-best-practices) for this component"
4. Write very precise skill descriptions—vague descriptions make activation even less likely

Skills aren't broken. They're underleveraged by design. The workarounds exist. But it'd be nice if Claude just... used the tools it has.

The past few months of foreign affairs show a new America (or perhaps the same old America, but one) that is willing to openly leverage global dependence on American business for its own ends. As an example, the use of tariffs as part of a multi-pronged effort to acquire Greenland. The world has responded quickly to American destabilisation - 35% of Britons see US as unfriendly or hostile to Europe.

The timing of this could not be worse... for American tech.

Just as the world is questioning its dependence on American technology, AI is making it genuinely possible to build alternatives.

The dependency​

For decades, the world has been comprehensively dependent on American tech infrastructure. AWS for cloud. Microsoft for business productivity. Google for search. Apple for hardware. Salesforce for CRM.

This wasn't just preference — it was path dependency. The switching costs were astronomical. The network effects were unassailable. The talent was concentrated. European competitors have struggled to dent this dominance (for various reasons).

So everyone stayed. Even when they were uncomfortable. Even when they had strategic concerns.

The fracture​

Recent American foreign policy has changed the calculus. Tariffs, sanctions, unpredictable export controls, and a general posture of transactional unreliability have finally created a long-deserved nervousness about total US-tech dependency.

This isn't ideological. It's risk management. When your critical infrastructure depends on a country that might (or is likely to!) take advantage of that criticality, you start looking for alternatives. The EU is talking seriously about digital sovereignty. Asia is accelerating local alternatives.

The self-inflicted wound​

American tech dominance wasn't inevitable. It was built on decades of trust, stability, and openness. Companies chose American platforms because they were the best—but also because America was a reliable partner. Take Palantir - a historically problematic business which has still managed to win evermore critical, sensitive contracts with the UK government. It's now high on the political agenda [https://greenparty.org.uk/2026/01/22/zack-polanski-tells-defence-surveillance-corporation-palantir-to-pack-its-bags-and-get-the-hell-out-of-the-nhs/].

That reliability is now in question, and the questioning is happening at precisely the moment when switching became feasible. Five years ago, if you wanted to divest from American tech, you couldn't. The alternatives didn't exist, weren't good enough, or the reasons to divest of US tech didn't feel severe enough to justify the lift. Now? There is a unique window open to subvert this dominance.

The AI window​

Here's why the timing is catastrophic for American tech dominance:

AI is still emergent. We haven't yet embedded AI into everything. The foundational decisions about which AI platforms, which models, which integrations will power the next generation of enterprise software are still being made. The concrete hasn't set. In five years time, we might see a world where the AI industry is unassaibly US-centric with the key players are down to just OpenAI, Anthropic, and Google (or other FAANGs through acquisition), but this is avoidable.

AI lowers the barrier to competition. It has never been easier to build sophisticated software. A competent team with modern AI tools can ship products that would have required 10x the headcount five years ago. The engineering talent gap—long America's moat—is narrowing (the only moat left is money). In particular, AI enables "good enough" - you don't need to match Salesforce feature-for-feature. You need to be good enough for European enterprises who'd rather have 80% of the functionality with none of the geopolitical risk.

The window won't stay open forever. Eventually, the next generation of AI-powered enterprise software will be built, deployed, and embedded. The decisions being made now about which platforms to build on, which vendors to trust, and which ecosystems to join will be sticky for decades.

America is giving the world reasons to choose differently at precisely the moment when choosing differently became possible.

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.

A fuller example​

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.

Why another language?​

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.

Resilience as syntax​

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.

The philosophy​

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:

• Immutability by default - let for constants, maybe for the rare mutable variable
• Optional typing - Start dynamic, add types gradually with :: Int annotations
• Pipeline-first - The /> operator isn't an afterthought; it's the primary way to compose operations

Current state​

Lea 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.

How to play​

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.

2. iPhone supports so little of it​

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).

3. It's easy to set up in your project​

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.

...but no one knows (how) to install them​

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.

Team optimization with custom metrics​

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:

1. Evaluating fitness: Each team is scored using the custom metrics, including expectation-weighted fitness
2. Selecting parents: The best-performing teams are selected to breed the next generation
3. Crossover: Combining successful team configurations to create new combinations
4. Mutation: Introducing random changes to explore new possibilities
5. Iteration: Repeating this process until the algorithm converges on optimal solutions

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 solution​

The plugin does two things well:

1. 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.

2. 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.

Technical highlights​

• Built as a proper DocusaurusDocusaurus A static site generator for React-based websites. Docusaurus is used to build this website. plugin following their plugin architecture
• Uses remark to process markdown at build time
• React components for the tooltip UI and glossary page
• Full TypeScript support
• Configurable term detection with sensible defaults

Try it out​

You can install it from npm:

npm install docusaurus-plugin-glossary

Or check out the GitHub repository for documentation, examples, and source code.

Links:

• GitHub Repository
• npm Package
• Documentation
• Claude Docusaurus Skills

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.