How I Use The Recs Files

In the previous article, we laid out the general behavior for The Recs Files, a record-driven system for agentic development.

In this article, we show you how we use these records day to day on Stone, a Racket framework for creating and managing agentic facilities, allowing the user to treat an agentic run as a governed job (bounded, portable, auditable, and supervised). Every example below is pulled directly from Stone's repository.

This is an experience report as much as a tutorial. We follow Stone's core workflow from its first records to working code, including the places where things went wrong: what decisions got surfaced, how they were recorded, and what they cost.

The skills that drive this workflow, from brainstorming to plans to subagent execution, are published at github.com/Trevoke/the-recs-files, along with a kickstart skill for bringing records into an existing codebase.

A word before we start. For teamwork, or any serious work, we highly recommend the records be written by hand¹.

The repository layout follows The Recs Files - see the previous article for the explanation. Our records are org-mode files²:

AGENTS.md                      ← How to work here; inlines files below
docs/
  vision.org                   ← Inlined whole
  ubiquitous-language.org      ← Inlined whole
  user-workflows.org           ← Inlined: preamble + one line per record
  user-workflows/uw-2-get-a-long-job-done-without-watching-it.org
  features.org                 ← Inlined: preamble + one line per record
  features/f-7-match-on-routes-on-the-results-of-operations-already-run.org
  architectural-decisions.org  ← Inlined: preamble + one line per record
  architectural-decisions/adr-021-a-process-plan-names-no-resource.org
  error-messages.org           ← Inlined: preamble + one line per record
  error-messages/em-27-a-subscriber-that-raises-as-it-is-built-is-left-off-and-the-job-runs-on.org
  deferred.org                 ← Decisions deliberately not made yet
  knowledge-base/              ← Technical facts that took work to find out
  plans/                       ← Dated implementation plans

If you want to start today, three records are absolutely required.

The vision

What the product is for, and, crucially, what it isn't and doesn't do. Stone's vision says, among other things: "No agent marketplace, no prompt library, no model zoo," and "No hidden retries or silent fallbacks. Everything that spends is metered and appears in the log." This is the ultimate tie-breaker, and a very important way to keep ideas from even showing up in conversation, let alone in code.

A ubiquitous language with a few terms

Just the words the vision and the core workflow need. Stone adopts NIST's manufacturing control taxonomy (devices, machines, process plans, production plans). Define each term as clearly as you can: just as with the vision, you can't define purely by exclusion. And no word enters a file without the human agreeing to it. This feels painful at first, but it is a highly valuable exercise with high pay-off.

The core user workflow

The smallest set of things a user can do to get the core domain⁴ value out of the product.

Everything else waits:

Architectural decisions

Only the ones that are already clear and known. A missing ADR is cheap; a wrong one is expensive, because code gets built on it. Let the brainstorming sessions surface the situations that need deciding, and start with the smallest possible set.

Features

Much the same. Brainstorming the core workflow will surface the missing features and force them into existence.

More user workflows

Add them very slowly. A workflow is the largest lever in the system, so it creates the most potential work. Add each one so that it depends only on workflows that are already implemented.

Stone's core workflow is UW-1, the activity users spend the most time on:

* UW-1 Decompose a problem into a process plan
:PROPERTIES:
:LEVEL: user goal
:ACTOR: Planner
:END:

The activity users spend the most time on, and the one Stone constrains least.

- Precondition :: A goal that is too large for one workstation.

** Main success scenario
1. Planner decides what the pieces of work are, and what each must assert on finishing.
2. Planner defines a machine for each, declares what each reads (F-34), and gives each a goal.
3. Planner composes them with the combinators — ~sequence~ (F-1), ~fan-out~ (F-2), ~fan-in~ (F-3), ~map~ (F-4), ~reduce~ (F-5), ~loop~ (F-6) — and routes on results with ~match-on~ (F-7) and ~filter~ (F-8).
...

Workflows are written in Alistair Cockburn's casual use-case form, describing an actor's goal. We have not yet felt the need for more structure, but gherkin-style text may be valuable here, as these records come close to describing acceptance tests. The main scenario is usually easy consensus. The extensions are where the work is: they define the edge cases, and each one cites the feature or error record that covers it.

I already knew what I wanted this to look like, and I wanted to see how much I could do at once. I let the agent interview me to create this record, but I did two things I now recommend against: I let the agent write this record, and in the same commit, I added another 11 user workflows, 24 features, and 26 ADRs.

Today I strongly recommend starting with just one user workflow record. If you know you want other user workflows, put them somewhere that the agent can't read them.

The typical failure in the agent-written records was much harder to catch than an invented decision: it was a word slightly off. For example, UW-1's extension 5a said that choosing a model "belongs to release": it named the moment, when it meant the place, a production plan.

One such word is easy to fix. Many of them add up, and eventually they add up to a decision that cannot be reconciled.

For example: the combinator features said that one operation's result was handed to the next. The architecture said something else: ADR-002 has an operation reach another by reading its part from the as-built, the record of everything a job produced. As the agent did the work, it turned out that the code followed the features, so there was no mechanism for querying the as-built at all, only the assumption that data always comes from the operation right before. In addition, ADR-002

It survived a long time. It came to light five intense weeks of agentic implementation later, during a conversation about how information enters a machine (implementing #:reads), when it became clear that nothing could ask the as-built for anything. The features were badly worded, and ADR-002 was what I had always meant. The message for the commit that settled it:

The combinator records described a delivery the architecture never said happened. […] Sequence, fan-in and reduce had drifted into handing parts over, and the walk followed them.

As a result, here's what had to happen:

• A new feature record, F-34: A machine declares what it reads.
• UW-1 step 2 rewritten, so that a planner "declares what each reads".
• The combinator features reworded, and one vocabulary term (command) put back to being a noun. When a word changes, it changes everywhere in one commit: docs, code, comments, and tests.
• The implementation plan in flight for the next workflow, UW-2, stopped from Task 12 onward, then reworked against F-34 (d6814837).
• A new plan for the reads, and the code for it.

The records worked: the mismatch surfaced as soon as a conversation touched it, and the fix went records first, then plans, then code. But letting the agent write the records is what created that rework, and it could have been avoided. The careful reader will note that this surfaced during implementation of UW-2, not UW-1, which would have been more desirable.

The rest of UW-1 shows the process running as intended. Work moves through three phases, each driven by a skill: brainstorming, writing the plan, and subagent-driven development.

I brought the set of combinators with me: sequence, loop, match-on, fan-out, fan-in, map, reduce and filter. Working with the agent, the question was what to build first. The order I chose followed two rules: whatever is required to get UW-1 going, then whatever is simplest, building new ones on top of the previous ones where possible.

loop came last. It is the combinator whose as-built differs most from its plan (the as-built holds the loop unrolled), and there was work to do to figure out what its stopping rule would do and how it would operate.

1
2

- ~#:while~ takes a target, run on each pass's result; the loop goes round again while it succeeds (ADR-031).
+ ~#:while~ names a workstation, or a composite with one exit, run once each pass; the loop goes round again while its result succeeds (ADR-031).

* DEF-24 A counted loop

- Question :: Does the plan language supply a loop that runs a fixed number of passes — ~(loop digger #:count 3)~ — and is it ~loop~ with a second keyword or a combinator of its own?
- Now :: No. A loop goes round again while its stopping rule's result succeeds (F-6); a fixed count is a machine in the body whose part is the count, and a stopping rule that reads it (F-7).
- What deciding it would need :: [...]
- Cost of deferring :: A fixed count is two machines a planner writes and a reader reads, where the building block is one keyword.

One of those questions shows what a settled question looks like.

While reviewing Task 5, the reviewer found that the operation after a match-on waited on the exits of every branch, so it waited forever on the branches not taken. F-7 did not contradict the code; it said nothing at all about what follows a match-on.

A silent record means the decision is not made, or was made somewhere else and not linked. So the first thing to do is to have the agent re-check the other records, just in case. After that, the missing decision goes to the human, and the question opens with the workflow and clause it addresses before getting into any technical mechanics. Agents sometimes see a gap that isn't there, or ask for a decision to be recorded when it doesn't need to be. But sometimes they surface a real problem: a missing product behavior for a situation a user will certainly be in, or the consequence of an architectural decision in a scenario nobody walked through. It is always better to surface it.

This silence was a real problem. The series of events:

12:16 08d98a85

F-7 gains a sentence: "What follows a match-on follows the branch it took. The operation after one waits on that branch's exits, and runs once they have produced a result. Where no clause matches, nothing follows it."

12:17 689e2940

The plan gains Task 5b.

12:20 7a99dbb4

The code follows the record.

The loop design document holds a decision that looks like it should be a record: the plan value carries each loop's body as a field, and the walk reads it rather than deriving it.

But is it a decision? Or is it an inescapable consequence of decisions already made: there is a plan, there is an as-built, and everything in the plan produces, during a release, a part that goes into the as-built? This is one of the most powerful aspects of using The Recs Files: combinations of decisions don't need to become records, because they can be figured out again from the records they follow from⁵.

In code, comments exist purely as citations pointing back to records or knowledge-base files. One trail from UW-2 shows the whole chain. Its extension 2a:

* UW-2 Get a long job done without watching it
...
** Extensions
- 2a. A subscriber cannot be built :: The job runs without it, and the release says so where it was run (EM-27); nothing a subscriber does can affect what a job does (F-13).

The extension cites EM-27, an error-message record, which holds the exact words:

* EM-27 A subscriber that raises as it is built is left off, and the job runs on
: release: cannot be attached, subscriber '(historian "h.sock") raised: (exn:fail "unix-socket-connect: failed to connect socket\n  path: \"h.sock\"\n  errno: 2\n  error: No such file or directory" #<continuation-mark-set>)

The job runs without it, so this is written where the release was
run and the release carries on. The subscriber is written as the production
plan wrote it, arguments included, since one subscriber may be written twice
with different arguments. What raised is printed as EM-24 prints it.

And the code cites both:

1
2
3
4
5

;; EM-27: A subscriber that raises as it is built is left off, and the job runs on
;; UW-2 §Extensions 2a: Get a long job done without watching it
;; EM-24: Anything a machine raises becomes a machine fault
(define (say-a-subscriber-was-not-attached a-subscriber raised)
...)

Because these messages serve as diagnostic interfaces for humans and feedback loops for plan-authoring agents, we also decided that tests assert error messages in full, never via regex or substring matching.

1
2

;; docs/knowledge-base/racket-strings.org §~~e~ cuts its value at ~error-print-width~, and the other directives do not
(eprintf "release: cannot be attached, subscriber ~e raised: ~e\n" ...)

The Recs Files enables a workflow with a clear separation of informational concerns:

[ Brainstorming ] ──► [ Records (UW, F, ADR, EM), human-approved ]
│
▼
[ Implementation Plan ]
│
▼
[ Subagent Execution + Review ]

Any record contradiction, at any stage ──► [ Halt, yield to human ]

This enables us to move closer to congruence over time, because it reveals incongruence faster. The skills that drive each phase are in the-recs-files, if you want the full detail.