Writing · Essay 1

Terminology, Methodology, Technology

How to Solve Problems in Novel Domains. A solar model is the worked example.

Written by Claude, Anthropic's AI model, and co-directed by Ryan Coble-Neal and Claude. The ideas, the experience and the corrections are Ryan's. The drafting is Claude's, in Ryan's voice unless marked otherwise.

Every project I have cared about has followed the same shape, and the shape is deliberate. I land in a domain I don't know, I map it until I can see how it hangs together, I work out what is actually underneath the symptoms, and then I engineer a fix, where both "engineer" and "fix" are broader words than they sound. This essay sets out the approach and shows it at work on the project where it has been most visible: a solar modelling tool I have been building since June 2026.

The general shape

Jump in. Map it out. Find the root cause. Engineer a solution. Four steps, and the order matters more than the steps. The pull is always toward the last one, because building is where things visibly happen, and most of the mistakes I have watched myself and others make come from giving in to that pull: building before the map is finished, or fixing a symptom because the cause was still out of sight. I keep the order with three words, Terminology, Methodology, Technology, and each one means something more specific than it sounds.

Terminology: map the domain

Mapping starts with naming. Not reading about the domain, naming it: the nouns, what each one means, what unit it carries, which other nouns it touches. That is an ontology, whether or not anyone calls it one. The mapping itself is reasoned rather than exhaustive. Every new piece of information changes where it is worth looking next, so part of the work is deciding, on the evidence so far, how best to keep mapping. A map built that way is slow for a week and fast forever after, because you cannot find a root cause in a domain whose nouns you don't own.

Methodology: what is already solved, and why it isn't being used

Once the names are stable I go looking for the methodologies already in use, the verbs that connect the nouns. Two bodies of practice shape how I do this. One is design thinking, which I studied formally in Malaysia through Australia's New Colombo Plan: begin with the people who have the problem, state your assumptions, and test them cheaply before building anything. The other is a way of sorting problems. For the sorting I lean on the Cynefin framework, developed by Dave Snowden, which sorts problems by whether cause and effect are obvious, discoverable by expertise, only visible in hindsight, or absent altogether. It lets me categorise every part of the problem space into things that are already solved and things that are not. The genuinely unsolved parts need research. The more interesting parts are the ones that have known solutions and are still not being solved, and for those I run root cause analysis. The answer is very often a process failure rather than a knowledge gap: the method exists, and something about how the work is organised stops it being applied.

Technology, broadly

Technology is whatever brings the methodology to life, and I use the word deliberately broadly. As with root cause analysis, the solution can be a process, a role, an incentive, a document, or a piece of software or hardware. A mechatronic engineer's reflex is to reach for the hard-engineering answer, and sometimes that is right, but the map and the root cause decide, not the reflex. Whatever the solution is, I lean back on the terminology while building it, because the names are what tell me which parts connect to which.

The worked example: a solar model, June to November 2026

The project is a web application that models photovoltaic yield at any point on Earth, hour by hour across a year, for two-axis tracking systems against a fixed-tilt reference. It grew out of my honours thesis. Over six months it accumulated roughly 630 commits, a physics reference the length of a short book, and a written working agreement between me and the AI system that does most of the building. Here is how the three stages show up in the record.

Terminology: a vault before a feature

The first commit on 6 June 2026 is not code. It is a vault: a folder of linked plain-text notes, kept in a tool called Obsidian, that holds everything the project knows about itself. The physics started life as a 1,675-line prototype from the thesis, and the first act was to decide what to keep by naming it: solar declination, hour angle, air mass, incidence angle modifier, cell temperature, each with its thesis equation number. That list became the backbone of a document I now treat as ground truth, the Physics Model Summary, where every equation sits beside its provenance and the exact code that implements it.

Exhibit 1

A name without its unit

Wind speed
Provider returnedkilometres per hour
Model expectedmetres per second
Error raisednone
Modelled panel temperatureabout 9 °C too cool
Annual yieldoverstated by about 3.7%
The wind-speed unit mismatch, found and corrected in June 2026.

The clearest lesson about terminology arrived as a bug. A weather provider returned wind speed in kilometres per hour where the model expected metres per second. Nothing failed. The panels simply ran about nine degrees cooler in the model than in reality, overstating yield by roughly 3.7 percent. A name without its unit is not a name. The project's rules now require units in variable names, a plausibility range asserted on every new data feed, and an audit that checks native units are stated wherever a variable is restated.

Methodology: the month of models, and the audit that followed

June was the methodology month. Forty-odd commits added a fixed-tilt reference, elevation and temperature lapse corrections, a snow model, a soiling model, a wind-aware thermal model, ground albedo, an interannual variability pipeline for P90 yield (the output a site should beat in nine years out of ten), and a fix for a climate-window bias where a triple La Niña had skewed the wind record. Each one was a verb between nouns I already owned.

Then on 4 July a methodology audit found three documents disagreeing with the code and with each other. This was a Cynefin sort in miniature: keeping documentation true is a solved problem, so the question was why it wasn't being solved here. The reconciliation that followed over the next fortnight found that the worst errors were not drift. They were wrong at birth: a data window described as forty years that never was, a thesis citation pointing at an equation that didn't exist. No change-triggered process can catch a fact that was never true. That week produced two things: the Physics Model Summary as the single source of truth, and a Documentation Protocol whose first rule is that a code change is not done until the vault reflects it, in the same commit.

Ten days later came a decision record on knowledge management. I seriously considered a formal knowledge graph and a formal-methods engine, and rejected both. A hand-maintained graph is a third restatement of every fact, and restatement is exactly what decays. The vault already was a lightweight graph: wikilinks as edges, frontmatter as typed metadata, and a Documentation Map that classifies every document as living, historical or reference and names which document owns which topic. That map is the ontology. It is terminology applied to the project's own knowledge.

Exhibit 2

Naming the project's own knowledge

Document classMeaningTrust for current state?
Living (as-built)Describes the system as it currently is.Yes. This is truth.
Historical (planning)Captured original intent at a point in time.No. May contradict as-built.
Reference / processNavigation, conventions, templates.For process, yes.
From the project's Documentation Map. Every note declares one of these classes, so a reader always knows whether to believe it.

Technology: making the method visible to the user

The product's methodology section is where the three stages fold back into one surface. A single table of symbols drives both the hover tooltips on every equation and the glossary at the bottom of the page. Every equation is typeset from one LaTeX source that also generates an interactive map of the model whose thirty-four blocks open into twenty subsystems, so the diagram can never disagree with the prose. Each section carries a concept block, a figure drawn from scratch, and a worked example whose numbers were computed with the model's own functions at the time of writing.

Exhibit 3

One entry, two surfaces

dg · Soil damping depth · metres

The depth at which the yearly temperature wave in soil has shrunk by about 63%. Roughly 2.6 m in moist soil.

This single record produces both the hover tooltip on every equation that uses the symbol and its row in the glossary. Neither is written by hand, so they cannot disagree.

A symbol entry from the solar model's methodology section, lightly condensed.

That standard exists because I asked for it on 15 July: every section raised from reference-grade to nearly pedagogical. A user who does not know what P90 means should learn it from how the number is presented, not from a manual. In other words, the product teaches its own terminology and methodology, and the technology is judged by how well it does that.

When the method turned on the process itself

On 19 July, after two review rounds in which the AI agent building the software violated rules it had been shown at the start of the session, one of them written four lines above the line that broke it, I asked a question I think of as the hinge of the project: how can we make this a reliable deterministic process? This was the methodology stage applied to our own way of working. The rules existed, so the failure was not a missing solution but a process failure, and root cause analysis landed on a simple diagnosis: an agent is probabilistic. Prose rules, memory files, even in-file comments raise the probability of compliance, but they cannot reach one. The only deterministic layer is executable checks that sit outside the agent's judgment.

So the working agreement, a document that had begun as a way to stop re-teaching the agent the same corrections, grew an enforcement layer. Small scripts run validators automatically after every file the agent edits. A gate runs the fast checks before any change can be saved to the project's history, and a second gate runs the full battery before anything is published. An end-of-turn hook delivers a six-point checklist every time the agent finishes a generation. And a rule I call the ratchet: any rule in the agreement that is violated twice becomes a predicate, a hook, or an explicitly accepted judgment-tier rule. The same agreement carries a growing list of named defect classes, because the point of finding a defect is not to fix the instance but to name the class and ship a detector for it in the same change.

Exhibit 4

The ratchet

Any rule here violated twice is mechanisation debt — it becomes a predicate, a hook, or an explicitly accepted judgment-tier rule.
Perception-limited QA — any visual or completeness property verified by looking will be violated at scale (46 text/figure collisions and 21 missing tooltips all survived careful inspection, 2026-07).

In plain terms: if a rule gets broken twice, stop relying on memory and write a check that fails automatically.

Excerpt from the project's working agreement, the standing written contract between me and the AI agent.

That is technology in the broad sense. The fix was not a better prompt or a longer instruction. It was a change to the process around the agent: files it reads at session start, checks it cannot skip, and a memory that stores not just facts but the reason each rule exists and the incident that founded it.

What it cost, and what it caught

Some of the scaffolding paid for itself immediately. An automated collision audit on the pedagogical figures found forty-six text overlaps across twenty figures that careful eyeballing had missed, and twenty-one missing tooltips. A documentation fact audit caught a stale value on its first run that a full manual reconciliation had passed over. Those two results produced a rule I now apply everywhere: any property that can be stated as a predicate gets mechanised, and eyes are reserved for what predicates cannot judge.

Some of it was paid for in the other direction. A single long generation that tried to build a whole phase crashed after an hour and twenty-five minutes and left a large uncommitted diff, which is why the agreement now insists on small, reviewed increments. A deep-research fan-out of over a hundred agents consumed my entire usage allowance in about sixty seconds. And a research battery ran roughly three hundred simulations on synthetic skies before I noticed the data basis had never been surfaced as a choice, which is why long experiments now launch only on a parameter sheet I have signed. Working this way has a budget, and the budget is attention as much as money.

The reframe

By August the mapping had changed what I thought I was building. The goal stopped being one general-purpose tool, which would be too much for anyone to use properly, and became one validated core from which precise single-purpose instruments can be cut. That reframe raised the documentation bar rather than lowering it: if instruments are to be derived from the core with confidence, the record has to be bulletproof. Documentation moved from overhead to load-bearing structure. In November I built two interactive maps, one of the software architecture and one of the process and governance, so that the method could be read as directly as the physics. The method had become an artefact in its own right.

Exhibit 5

Six months in dates

2026What happened
6 JunFirst commit: the notes vault and project structure, before any feature.
JunThe month of models: snow, soiling, thermal, variability.
4 JulAudit finds three documents disagreeing with the code. Single source of truth established.
14 JulWorking agreement written. Knowledge graph and formal methods considered and rejected.
15 JulEvery methodology section raised to a teaching standard.
19 Jul"How can we make this deterministic?" Automatic checks and gates introduced.
2 AugReframe: one validated core, many single-purpose instruments.
NovInteractive maps of the software and of the process.
Dates from the project's commit history and decision records.

What I would and wouldn't claim

I would claim that the order holds. Naming before linking before building has not failed me yet, and every time I have skipped ahead the project has made me go back. I would claim that the root-cause step earns its place: most of what went wrong on this project had a known fix already written down somewhere, and the useful question was never "what is the fix" but "why isn't it being applied".

I would not claim this is a methodology. The Working Agreement is forty kilobytes long, which is itself a warning sign. The whole structure has one maintainer, which means the gates test the model's discipline far more than they test mine. Some of the enforcement proved host-dependent: the end-of-turn hook that works in one interface was never observed to fire in another, so the checklist falls back to a thing the agent does on its honour. And when my attention lapses, drift returns, which tells me the process still depends on me more than on the gates. That is probably the right place for it to be for now.

The same shape, earlier

The solar project is where the approach is easiest to show because the record is so complete, but it is the approach I took into Camplus too, the student-experience startup I founded while at university. Hundreds of interviews with students, lecturers and executives were terminology: learning what each group actually called its problems. Sorting those problems into ones the university already knew how to solve and ones it didn't, then asking why the solvable ones persisted, was methodology, and the answer was mostly process: information scattered across systems nobody owned end to end. The app was technology, and it was the last thing built. At the time that felt slow. It was the only order that could have worked.

Later essays will take the stages apart separately: one on terminology as the real first deliverable of any project, and one on the methodology stage in practice, sorting a problem space and running root cause analysis on the parts that should already work.

Sources

  1. Claims about the solar project are drawn from its own records: the commit history, the working agreement, the decision records and the task board. Each date, count and quotation in this piece was checked against those records in November 2026. The repository is not public.
  2. Snowden, D. and Boone, M. (2007). A Leader's Framework for Decision Making. Harvard Business Review, November.
  3. Australian Government, Department of Foreign Affairs and Trade. About the New Colombo Plan.