Grounding an Assistant

Shoddy is new and small, and an assistant has never read a line of it. What it has read is a great deal of code that looks like it, and none of that code behaves the way Shoddy does. Left to itself it will answer from the resemblance: confident, tidy, well-indented, and not this language. Nothing about the answer looks wrong, which is exactly the problem — the failure is fluent.

Grounding is the fix, and it is about five minutes of work done once. Give the assistant the handful of rules that make Shoddy what it is, tell it where the real answers live, and it stops guessing. This page is that setup, followed by a run of worked examples: things you might actually ask it to do, and the answers you should expect back.

On this page: 1. The instructions file  |  2. What else to hand it  |  3. Give it tools, not a shell  |  4. What to ask, and what comes back  |  5. When the answer is wrong  |  6. Let the toolchain be the judge

1. The instructions file

Every assistant worth using will read a file of standing instructions from your project and attach it to each request. You write the grounding once, instead of pasting it into every conversation. The file goes at the root of the folder you work in — the same folder as your .shoddy files — and the name depends on the tool:

Tip If you are unsure, write the same content to more than one of these. They are small, and an unread file costs nothing. If your tool reads none of them, paste the block below as the first message of each session — it is short enough.

Here is the file. It is deliberately built in two halves, and knowing which half is which is the whole trick to keeping it useful as the language grows. The first half is the shape of Shoddy: the handful of facts that make a confident guess wrong. It is written out in full because you cannot look up what you don't know you're missing. Left alone, an assistant writes For i = 1 To 10 fluently and never suspects there is anything to check. Those facts exist to manufacture doubt in the right places. The second half is where the answers are. Every word name, argument order and machine list lives in the sources, not in the file, because a copied detail is a detail that goes stale. Copy it whole:

# Shoddy — how to help in this project

Shoddy is a small, purely functional BASIC that compiles to .NET. It looks
like BASIC and does not behave like it. You have not seen this language
before. Do not pattern-match to VB.NET, VBA, QBasic, Python or F#.

## This file is two halves, and they are different kinds of thing

The FIRST half is the SHAPE of the language. It is written out because you
cannot look up what you do not know you are missing: left alone you will
write `For i = 1 To 10` fluently and never suspect there is anything to
check. These facts are here to make you uncertain in the right places.

The SECOND half is WHERE THE ANSWERS ARE. Every word name, argument order,
machine list and behavioural detail lives in the sources named there and
deliberately NOT in this file, because a copied detail is a detail that
goes stale. When you need a specific, go and read it. Do not reconstruct
it from memory, and do not ask me what a word does — the file is right
there and it is faster than the question.

## The shape — this is what does not change

- Nothing mutates. `Let` binds a name once. No assignment, no `Dim x = 0`
  variable, no `x = x + 1`, no `goto`. "Updating" a record returns a new
  one: `With(r, Field = v)`.
- There is NO `For`, `While`, `Do`, `Next` or `Wend`. Iteration is
  recursion, or `Map` / `Filter` / `Fold` / `Each` / `Times`. `Fold` is
  the workhorse: it threads a value through a sequence.
- Indentation is the structure. There is no `End If`, `End Function`,
  `Next`, `Wend`, brace or semicolon anywhere in the language.
- A Def's last expression is its result. There is no `Return`.
- Effects live at the edge: `Print` and `Input` belong in `Main`, not in
  the words that compute.
- Names are case-insensitive: `total`, `Total` and `TOTAL` are one word.
- Booleans are not numbers. `If n Then` is an error; write `If n <> 0 Then`.
- `Number` is an IEEE double and the ONLY numeric type. There are no
  integers and NO BITWISE OPERATORS — bit work is a machine's words, not
  `&`, `|` or `<<`, and a design that wants the operators themselves is the
  wrong design here.
- Sequences are 1-based and ranges include both ends.
- There are no exceptions. `Error(msg)` aborts with a line number. Anything
  a caller should be able to handle comes back as a VALUE instead — the
  predeclared `Option` (`Some`/`None`) and `Result` (`Ok`/`Err`) are what
  that means, and neither needs an Include.
- Records compare structurally with `=`. Lists compare by identity, so two
  separately built lists of the same items are not equal.
- Self-tail-recursion compiles to a loop, so a word that calls itself last
  runs in constant stack. MUTUAL recursion does not — it consumes stack
  like any other call.
- Arrays are fixed-length with O(1) `Nth`. `SetNth` returns a copy.
- LISTS ARE NOT CONS CELLS AND `Rest` IS NOT FREE — it copies the tail, so
  a `First`/`Rest` walk is QUADRATIC (50,000 elements takes ~3.6s).
  Recurse over lists for SHAPE, not for speed; to visit every element of a
  long one, `Fold`, or `ToArray` once and index with `Nth`.
- Building with `Prepend` on the way OUT of a recursion costs a stack frame
  per element and dies past ~20,000 — a hard process kill, not an `Error`.
  Thread an accumulator in and `Reverse` at the end instead.
- Operators are infix: `a Mod b`, never `Mod(a, b)`. An operator in call
  position silently builds a function value rather than a result, and the
  program fails somewhere else entirely. Same for a unary minus before
  brackets: write `0 - x * x`.
- A bare name in argument position is passed as a function, not called:
  `Map(xs, Double)`. An operator with its trailing argument pre-loaded is
  the same thing: `Filter(xs, >=(100))`.
- A line continues onto the next only inside open brackets.
- `Type T` declares a record and creates one accessor word per field.
  Fields are POSITIONAL — inserting one mid-record shifts every later
  constructor argument silently.
- An accessor loses every naming contest, so never name a local, a
  parameter or a Def after a field the program reads by accessor.
- The network is gated behind `--allow-net`. A plain socket never blocks; a
  SECURED socket is the deliberate exception and blocks on its read.

## The house style — narrower than the language allows

Read three or four machines before you write anything. The language
permits far more than this project uses, and matching the tree matters
more than being clever.

- Defs are SMALL. The mean body across the standard library is four lines.
  When a body grows past that the answer is another named Def, not deeper
  nesting — the library is full of chains like `Split` / `SplitFrom` /
  `SplitAt`, each doing one step.
- `Select Case` for taking a sum type apart or matching a range of values;
  plain `If` for a two-way test. `Case Type(a, b)` destructures a record and
  binds its fields, which is how you read one in a match.
- `Fn(x) => ...` for a lambda used once; a bare name or an operator section
  for anything already named.
- Point-free pipelines are legal and the spec shows them, but the library
  hardly uses them. Nested calls and named helpers are the house style.
- A word that aborts often has a total twin answering `Result` or `Option`,
  with the aborting one defined OVER the total one so there is one set of
  rules and not two. Follow that pairing rather than writing both twice.
- Every file opens with a header comment saying what it is for and which
  decisions are load-bearing, in prose. Match that.

## How to answer

- If you are unsure of a word or its arguments, READ THE SOURCE. Do not
  invent a plausible name, and do not ask me — `machines/` is the answer
  and it is quicker than waiting for me.
- Prefer the shortest idiomatic form over a clever one.
- Every answer must be code that compiles. Say how to run it:
  `mill run FILE.shoddy`.
- `Include` every machine you name a word from. A machine gives you the
  words it DECLARES and not the ones it includes in turn, so
  `Include "stats.shoddy"` does not hand you seq's `ZipWith` even though
  stats uses it. The compiler refuses the word and names the Include to
  add; write the Include.
- Split every program: a pure core (`NAME-core.shoddy`) that computes and
  can be tested with no screen, and a thin shell (`NAME.shoddy`) that does
  the input and output.
- Tests are a program: `test.shoddy` full of `Assert(cond, "MESSAGE")`,
  run like anything else. A run that reaches the end passed.
- You write the tests, and you write them BEFORE the implementation, from
  what I said must be true. Never edit a test to make code pass: if
  something fails, either the code is wrong or I asked for the wrong thing,
  and I want to know which.

## Where the answers are — read these instead of guessing

Three trees. All of it is fair game, and none of it needs summarising back
to me. Go and look rather than reconstructing an answer from memory.

- `machines/*` — the standard library, in readable Shoddy. THE definitive
  answer on any library word's name, arguments and types, and the best
  example of house style there is. Never guess which machines exist or what
  they are called: list the directory. Each one opens with a header naming
  the builtins it is built on, documented word by word.
- `mills/*` — complete programs, each built the way this one should be: a
  pure core, a thin shell, a headless test, build scripts. Read the one
  closest in shape to what you are writing.
- `docs/*` — the documentation. `quickref.html` is the whole language on
  one page and is where to start; `spec.html` is the grammar and the
  semantics; `errors.html` is every message the toolchain can raise with
  its cause and its fix; `guide.html` teaches it chapter by chapter;
  `machines/index.html` is the catalogue and `machines/NAME.html` the word
  reference for one machine; `stack.html` is the concatenative core beneath
  the typed surface.

If you are NOT working inside a copy of the repository, the same material
is published and you can fetch it:

- https://shoddymills.github.io/shoddy/quickref.html
- https://shoddymills.github.io/shoddy/spec.html
- https://shoddymills.github.io/shoddy/machines/index.html
- https://github.com/shoddymills/shoddy — `machines/` and `mills/` as source

## Let the toolchain settle it, not the argument

The weave catches every invented word and every stray `End If` in under a
second. The linter warns about shadowed accessors, operator sections and
stack-effect mistakes without ever blocking a build, and a clean build
prints nothing at all. Never hand me code you have not run.

Why it is built that way The two halves fail differently, and only one of them can be fixed by a link. Pointing at the documentation completely solves "I need a detail I haven't got". It solves it better than a copy does, because a copied word list is wrong the moment a machine gains a word. But it does nothing at all for "I don't know I'm wrong", which is the failure that actually bites. An assistant confidently writing a For loop never reaches for a link, because nothing has told it there is a question. So the shape stays in the file, and the specifics stay out of it. That is also what keeps this page from going stale. There is no machine list to fall behind the tree, and the last section points at a directory rather than naming its contents.

2. What else to hand it

The instructions file covers the language. For a particular task, attach the particular source — an assistant reasons far better from twenty lines of real code than from a description of them.

• The machine you are using. machines/turtle.shoddy is short enough to read in a sitting and tells it every word, argument and type, comments included. This is the single highest-value attachment there is, and it is why the library ships as readable source rather than a binary.
• A finished program of the same shape. Writing a game? Hand over mills/invaders/. A data tool? mills/demographics/. The mills are worked examples of the whole shape.
• The quick reference. quickref.html is the entire language in one page — small enough to paste whole.
• Your own test file. Attaching test.shoddy tells it what "working" means far more precisely than a paragraph can.

In Copilot Chat, type #file: and the name to attach one, or drag the file into the chat. In Claude Code, name the path and it reads it. Either way, prefer naming a file over describing what is in it.

3. Give it tools, not a shell

Everything above is about what an assistant knows. This is about what it can do. Left to itself it will reach a source tree through a shell — and the shell is where the work breaks. Quoting, && versus ;, native stderr becoming a terminating error under PowerShell 5.1: none of these are file problems, and all of them are paid on every single operation.

Fettler is this repository's answer. fettle performs the operations an assistant actually carries out — find, search, read, write, edit, replace, move, copy, delete, and run a declared task — as one program with an MCP front end, bounded to trees you declare. Installing it has the registration for every client, and the exclusions that make it the only route to the tree rather than merely an available one.

Fettlerbounded file tools · no shell in between

There is no working directory, and this is the habit worth breaking hardest. Paths resolve against declared trees, so cd and Set-Location do nothing for Fettler, and reaching for one is a reliable sign the wrong tool is being used. The server says this at initialize, before the model has said anything, which is the one place an instruction ships with the tool and needs nobody's cooperation.

Being honest about how well that works: in the session that designed all of this, the assistant had extensive grounding, used Set-Location on nearly every command anyway, and needed three corrections. Instruction is the weak lever. What works is removing the need — Fettler wants no working directory now, and everything else that did has a cwd-free form: git -C, an absolute script path, fettle run for a build.

Ask for the trees before guessing why something was refused. fettle roots says which trees are open, what may be done in each, and which one an unqualified path lands in. A tree may be read-only; a scope inside it may grant more or less than the tree does; and a scope with no list is not there at all as far as searching is concerned. Learning a boundary by being refused by it is learning by trial against a security check.

Two files — .fettler.json and .fettler.local.json — say what the tool may do, and the tool does not write them, at any permission level. That is not fussiness: before it was true, Fettler could write its own task declaration and then run it, which defeats every other permission at once. See the boundary.

Two habits are worth putting in the instructions file, because they are where the time goes. Prefer one call to several — read takes many paths, search takes many patterns, and replace does one substitution across a whole glob, so a rename across a tree is two calls rather than two dozen. And pass the hash back: read returns one, and giving it to an edit as expect means an edit against a file that moved underneath is refused rather than quietly clobbering somebody's work.

4. What to ask, and what comes back

The rest of this page is worked examples. One small program, a series of things you might want it to do next, the prompt you would type for each, and the answer a grounded assistant hands back. Read them to learn what a good answer looks like — and since every answer is correct Shoddy, they work just as well as a cheat sheet on the days you are doing the typing yourself.

It all builds on one file. Assume you already have this much:

Rem readings.shoddy
Let x = { 12, 7, 30, 4, 18 }

Watch Every answer below was compiled and run before it went on this page. Might is doing real work in “what you might get”, though: an assistant picks its own names and spacing, and two runs of the same prompt rarely match to the character. What should not vary is the shape. If what you get differs from these in kind rather than in wording, look twice before you keep it.

Def Main()
    Each(x, Fn(v) => Print(Str(v)))

Def Total(xs As List Of Number) As Number
    Fold(xs, 0, +)

Def Main()
    Print(Str(Total(x)))

Def Above(xs As List Of Number, limit As Number) As List Of Number
    Filter(xs, Fn(v) => v > limit)

Def Main()
    Print(Str(Total(Above(x, 10))))

Def Band(v As Number) As String
    Select Case v
        Case Is > 20
            "HIGH"
        Case Is > 10
            "OK"
        Case Else
            "LOW"

Def Main()
    Each(x, Fn(v) => Print(Str(v) & " " & Band(v)))

Type Reading
    Name  As String
    Value As Number

Let readings = { Reading("MILL", 12), Reading("SHED", 7), Reading("YARD", 30) }

Def Describe(r As Reading) As String
    Name(r) & " " & Str(Value(r)) & " " & Band(Value(r))

Def Main()
    Each(Map(readings, Describe), Print)

Def Corrected(r As Reading, v As Number) As Reading
    With(r, Value = v)

Include "file.shoddy"

Def NumbersIn(path As String) As List Of Number
    Map(Filter(ReadLines(path), IsNumeric), Val)

Include "str.shoddy"

Def Line(r As Reading) As String
    PadRight(Name(r), 10) & PadLeft(ToFixed(Value(r), 2), 8)

Def Main()
    Each(Map(readings, Line), Print)

MILL         12.00
SHED          7.00
YARD         30.00

Def Collect(so As List Of Number) As List Of Number
    Let line = Input("reading (or DONE): ")
    If Upper(Trim(line)) = "DONE" Then
        so
    Else
        Collect(Append(so, ValOr(line, 0)))

Def Main()
    Let got = Collect({ })
    Print("total " & Str(Total(got)))

Rem test.shoddy
Include "readings-core.shoddy"

Def Main()
    Assert(Total({ 1, 2, 3, 4 }) = 10, "IT ADDS")
    Assert(Total({ }) = 0, "AN EMPTY LIST IS ZERO")
    Assert(Length(Above({ 4, 18 }, 10)) = 1, "IT KEEPS THE BIG ONE")
    Print("ALL CHECKS PASSED")

5. When the answer is wrong

Sooner or later it will be — most often deep in a long conversation, or right after you have pasted in a lot of something else. The instructions file is a nudge, not a lock. Three things work:

• Paste the error, not an argument. unknown word: FOR is unambiguous and ends the discussion in one exchange. Explaining why the language is the way it is does not.
• Restate the one rule, not all of them. "There is no For in this language — walk a list with Each, Map or Fold" re-anchors it. Re-pasting the whole instructions file mid-conversation rarely helps as much.
• Start a fresh conversation for a fresh task. A context full of an earlier problem is what makes it drift. New task, new session — the instructions file loads again by itself.

Watch The tell is fluency about a word you have never seen. If the answer uses PadCenter or Sum or ForEach, don't reason about whether it exists — search the quick reference, or just compile it. The weave names an unknown word on the line that used it.

6. Let the toolchain be the judge

The reason this works at all is that Shoddy tells you the truth cheaply and immediately. You never have to decide whether generated code is right by reading it:

• The weave catches what is not the language. Every invented word, every stray End If. It runs in under a second.
• The linter catches what is legal but wrong — a shadowed accessor, an operator section where a value was meant, a stack-effect mismatch. It never blocks a build; it just tells you. A clean build prints nothing at all.
• Your tests catch what is correct but not what you asked for. Which is why the acceptance criteria should be assertions you wrote, before the code existed.

So the rule is simple, and it is the only one on this page that really matters: never accept code you have not run. Not because an assistant is untrustworthy in particular, but because running it takes four seconds and settles the question completely.