DEV Community

Ibn Web3
Ibn Web3

Posted on Edited on AI-assisted

Whylog: three Claude Code agents that say "This was not recorded" instead of guessing why

#switch #ai #claude #hackathon

Your team's code outlives the people who wrote it. The reasons behind it don't. This is how I built three Claude Code agents on Switch that record those reasons while a decision is being made, and that say "This was not recorded" instead of guessing.

The short version

  • Whylog is three Claude Code agents in one Switch room: a coder, a scribe and a recall agent.
  • The scribe writes each decision into a room document (DR-1, DR-2...) and marks anything nobody said as "not stated".
  • The recall agent answers "why did we do it this way?" only from those records and the linked PRs. If nothing covers the question, it says so.

Everything here ran on one Windows machine with Switch Console 0.40.1 and its bundled Mattermost. One person played the engineer. The people and the reasons in the demo are made up.

The problem

Open any old pull request. "Add 5s timeout." "Retry failed deliveries with backoff." The diff shows what changed. It never shows why 5 seconds, why 3 retries, what was rejected, or what would make the team change its mind.

When the person who knew leaves, that reasoning leaves with them. A new hire can ask a chat model, and it will give a confident, plausible reason that nobody ever said.

The record decides. The model doesn't.

That is the one rule Whylog follows. The agents may ask, write and quote. They may not invent a reason.

What I built

Three agents, created from one Switch template, in one private room called whylog-engineering:

  • whylog-coder works with an engineer on code. Before it picks an option it says the options and trade-offs out loud in the room.
  • whylog-scribe takes the scribe role. It asks for what is missing, one question at a time: what was chosen, what was rejected and why, who decided, what would make us revisit it. It writes only what a person said.
  • whylog-recall takes the recall role. It answers only from the decision documents and the GitHub reference, quotes the record, names who said it, and links the PR.

The test subject

I made a tiny webhook sender, whylog-demo, with two merged PRs: #1 adds a 5 second timeout, #2 adds up to 3 retries with backoff. Neither PR description says why. That gap is the whole point.

How Switch is used

Every part of Whylog is a Switch feature.

Switch feature What Whylog does with it
Agents Three Claude Code agents on the local machine
Room One private room where a person and all three agents talk
Roles scribe and recall, both exclusive; the agents claim them in the room
Room documents One document per decision (DR-1 ...), following a "How we record decisions" document
References A GitHub reference to the demo repo, so records link to real PRs
Room instructions The briefing every agent in the room reads
! commands !roles, !list-documents, !list-references

The room documents carry the idea. A person can open DR-1, read it and edit it. The record does not live only in chat scrollback.

What happened in the demo

  1. Options first. I asked the coder what options we had on each PR. It listed options and trade-offs and gave a pick for each. It also said it had not read the PR diffs, so it described the general option space, not our code.
  2. The scribe records. I told the scribe to take its role and record the decision. It created DR-1 5s timeout and 3 retries with backoff, linked both PRs, and marked every part nobody had said as "not stated".
  3. Filling the gaps. I gave the rejected options (separate connect and read timeouts, because our HTTP client supports one value; a circuit breaker, as too heavy for now) and the backoff. The scribe updated DR-1.
  4. Offboarding. I said I was leaving. The scribe listed the one decision I own, named three gaps, and interviewed me about them. My answers went into DR-1, marked as mine.
  5. Recall, with a record. I asked the recall agent why we use a 5 second timeout and 3 retries. It quoted DR-1, named who decided, linked both PRs and listed what is still not stated.
  6. Recall, without a record. I asked why we did not use a message queue. The answer was "This was not recorded." It named DR-1 as the nearest record and gave no reason.

Scribe creating DR-1 in the Switch room
The scribe takes its role, creates DR-1 and marks the gaps (step 2). Screenshot from the demo run.

Switch listing the room documents and the scribe interviewing the leaver
!list-documents, then the offboarding interview listing the three gaps (step 4).

Recall agent answering from DR-1
The recall agent answers from DR-1, quotes the record and says what is not recorded (step 5).

Recall agent saying this was not recorded
No record covers the queue question, so the answer is "This was not recorded." (step 6).

Step 6 matters most. Any system can answer when the answer is on file. What a new hire needs to know is where the file ends.

What it still gets wrong

  • The sources are narrow. The reasons come from the room only. Switch has reference types for Jira, Confluence and Drive, but I connected only GitHub. Whylog does not read tickets, company chat history or research documents.
  • It is not a retrieval system. The recall agent reads the room's decision documents and the GitHub reference with its own access. There is no search index.
  • The coder had no clone of the repo. It described options in general and did not read the diffs. The scribe and recall agents rely on what people said and on the PR links.
  • The demo is one person. One person played the engineer. This is a single-person test, not a real team. I did not test Slack, Teams, Discord or Telegram.
  • Roles are claimed by the agents. Switch lists the roles as free until an agent takes one. The scribe and recall agents each did in my run.

What got in the way (my #HowISwitch notes)

  • Create all shows a timeout while the server keeps building. The "Nothing was created" screen is wrong. Retrying made duplicate rooms. Now I click once, wait about five minutes and check the Agents and Rooms lists.
  • A stale remote host blocked the template. An unreachable WSL host broke the provider check in the form. Deleting the host did not clear it. I fixed it with a template variant that sets the provider and location directly.
  • Deleting a room returned HTTP 500. I made new team names instead.
  • Agent replies take 30 to 90 seconds, sometimes longer, with no progress indicator.
  • Kickoff messages in the template timed out the Console, so the template has none. You start the flow by talking to the agents.

What I would want next: a progress view while Create all runs, a working room delete, a provider check that ignores unreachable hosts, and a way to see which agent is working on a message.

What I learned

  1. "Not stated" is a feature. The most useful thing the scribe does is refuse to fill a blank.
  2. Roles keep jobs clear. One agent writes, one reads. The recall agent cannot edit the record it answers from.
  3. Documents beat scrollback. A decision a person can open and fix is a decision a team will trust.
  4. Say what you did not test. Most of this post is a list of limits. A recall tool that overclaims would be worse than none.

Run it

You need Switch Console 0.40.1 (the Windows early-access build), Docker Desktop for the bundled Mattermost, and Claude Code installed and signed in on the same machine.

  1. Fork or clone whylog-demo, or use your own public repo.
  2. In Switch Console, open Templates, import template/whylog.template.yaml from the Whylog repo.
  3. Fill in team, repo_url and newhire_user.
  4. Click Create all once, and wait. Do not retry.
  5. Open <team>-engineering, run !roles and !list-references, then follow docs/SCENARIO.md.

Links

Built with Claude Code for the Flip the Switch hackathon (WeMakeDevs x DevTools Academy x Switch), Track 01. If you have ever inherited code with no reasons attached, tell me which decision you wish someone had written down.

Top comments (0)