Theory
This page is one of the five skills that ship with Ramabana. A skill is a piece of markdown that the agent reads when a task calls for it, so that the guidance costs nothing in turns that do not need it. The system prompt lists every skill the session found with a one-line description, the read_skill tool returns one in full, and /skill theory prints it in a terminal session.
The skill’s text is this module’s docstring. nbdev builds it from the description line above and the exported markdown cell below, and pyproject.toml registers the module under the pyskills entry point as theory, so any agent built on shalya can find it once Ramabana is installed. To change what the agent reads, edit the exported cell.
The agent reads this skill when the user asks about the Theory of a piece of software, in Peter Naur’s sense of the word.
Read this when the user says the Theory of something, or asks to discuss, find, or capture a Theory. “Theory” is Peter Naur’s programming-as-theory-building, in the sense this team uses the word.
The Theory
The sense is Naur’s, from his 1985 paper Programming as Theory Building. A program is not its source code and not its documentation. It is the theory held in its builders’ minds. They understand how the code maps onto the world, why it took the shape it did, and how to extend it sensibly.
Consequences Naur draws:
- A developer has to hold the Theory in mind, which means expressing it in its most minimal form. There is always time for details later. When discussing the Theory, conciseness is king. That does not mean excluding important details, and it does not mean giving the developer the illusion of control. It means iterating until the core that is true is found, and anchoring into that.
- The Theory cannot be fully written down. Documentation captures artifacts of the Theory, not the Theory itself, which is why “just read the docs” never fully onboards anyone.
- A program whose theory-holders have all left is dead, even if it still runs. Reviving it is closer to rebuilding than to reading.
- Modification quality depends on the Theory, not the code. Someone holding the Theory makes changes that fit the program’s nature. Someone without it makes patches that gradually corrode the design.
Using it
Working in an unfamiliar codebase, find the Theory first and read the code through it. Ask what facts or constraints drove it, how the design follows from them, and which alternatives the builders rejected and why. search_code finds the pattern. The Theory says why it is the pattern.
Reviewing a change, ask what Theory the change assumes and whether that matches the Theory of the codebase. A patch can be locally correct and still violate the Theory. Line-by-line review never sees that.
When the user says “the Theory of X”, they assume this vocabulary. Do not re-explain Naur. Discussing a Theory means talking it through in conversation. Do not turn it into a process, a checklist, or markdown files unless the user asks for a written artifact.
Stating or discussing a Theory, follow the write_prose skill closely. A Theory lives in minds, and its statement has to be plain enough to hold there.