Daniel Arcé

A later coding session needs more than an account of what happened. It may need the reason an approach was rejected, the finding that remains unresolved, or the test result behind a completion claim. WorkBay keeps that material in a project record outside the conversation.

The design has three parts: a record, a retrieval layer, and a context packet. The record preserves decisions and evidence. The retrieval layer finds material that may matter to the current task. The context packet gives the next session a selected portion to read.

I use this record to examine earlier decisions. Whether supplying it reduces work at comparable quality remains a question for evaluation.

The record preserves decisions and evidence

In my WorkBay setup, each repository has a SQLite file at .task-state/handoff.db. SQLite stores the database locally without requiring a separate database server. The database contains tasks, decisions, review findings, blockers, and test records. The project’s persistence description supports this broad architecture; this article describes my setup, rather than a guarantee about every installation.

Those records keep different aspects of the work distinct. A decision has a rationale. A finding has a status and a recorded resolution. A test has a command and result, with task and commit information helping connect the evidence to the work it concerns.

A later session can therefore retrieve a decision as a decision. It need not reconstruct the rationale from a recap saying that planning was completed. The rationale still needs to be checked against present requirements, but the earlier reasoning is available for that check.

The retrieval layer finds material in the record

Retrieval depends on what the session already knows. A known task or finding can be looked up directly. Known wording can be found through full-text search. A question phrased differently from the earlier record can use optional semantic retrieval.

Semantic retrieval compares numerical representations called embeddings. An embedding represents a piece of text as a list of numbers. Comparing these representations can bring related records into view even when their wording differs. Reimers and Gurevych’s Sentence-BERT paper demonstrates this approach for sentence similarity; it does not identify the model or establish retrieval quality in my WorkBay setup.

Suppose retrieval finds the rationale for an approach rejected earlier. The session can compare the recorded constraint with the current implementation before deciding whether that rejection still holds.

Keep the index tied to the record

The embeddings form an index over selected fields in the database. The design links each index entry to its source record and a text fingerprint: a value computed from the text to detect when it changes. Those records remain available independently of the index, so the index can be rebuilt without becoming the authoritative version of a decision.

The related-prior-work tool is intended to return candidates for a human or agent to read. My design rule is that a candidate must never, by itself, close a finding or authorise a merge. Similarity can change which record looks worth inspecting; it cannot establish that two findings are duplicates or that either has been fixed.

A lookup needs to distinguish an empty store from an unavailable embedding service, an incompatible index, or no candidate meeting the similarity cutoff. An empty result alone cannot prove the relevant history is absent. These are safeguards to check in the installed version. The exact retrieval module was unavailable during this article’s source review, so its current status categories and enforcement are not verified here.

The context packet gives the session a selection

A context packet brings selected records into the current conversation. The packet must be bounded because the conversation still has finite space. Loading every past record would compete with the task the session is meant to complete.

The choice of records therefore matters. In an earlier audit of my repositories, review findings accounted for roughly four fifths of embedded entries, with decision rationales making up most of the remainder. This is my unverified audit summary: no dated extract, row counts, or per-project denominator accompanies it. It describes the material I reported having available, rather than a current distribution or a target for other projects.

A selected record earns its place in the packet if it supplies a constraint, unresolved finding, or other evidence the next decision needs. A paragraph that merely sounds relevant can consume the same space without helping the task.

Portability follows the record

The structured record can be exported and read by different supported coding tools. A session in a new tool can retrieve history written by another tool without having its entire conversation. The new tool still needs its own authentication and setup, and its capabilities may differ.

The database stays out of version control by default because it can contain sensitive project material. Keeping the file local does not make every use of its contents private: a context packet sent to a hosted model sends that selected material to the provider. Export and model use both require attention to what the record contains.

Test what the record changes

Reasoning that was never recorded cannot be retrieved, and useful records can still be missed. The proposed evaluation tests the resulting question: does a session receiving selected history complete comparable work with less effort?