Beyond the Commit: Why We Keep a Working Journal

A useful project should come with more than a functioning screen. It should come with enough context for someone to understand why it works this way, what was checked, and where to pick up tomorrow.

That matters when you return after a weekend. It matters even more when a different developer — or a different AI assistant — takes over. A promising idea is easy to lose between conversations. A failed approach is surprisingly easy to repeat.

At Solution Adventurists, we keep a working journal alongside the source code. We record progress as we go, give significant design decisions a home, and document obstacles while the evidence is still fresh. The aim is practical: fewer mysteries, clearer handovers, and more time spent building the next useful thing.

Git remembers the changes. Our journal remembers the investigation.

Git remains essential. It records versions, shows differences between files and lets us return to earlier work. A thoughtful commit message can explain a great deal.

But an investigation often produces useful information before it produces a commit. We may test three explanations, discover an environmental constraint, and abandon two approaches. The final code usually contains the solution. It does not necessarily contain the journey that made that solution sensible.

Our journal preserves that context. It complements Git; it does not replace version control, tests or review.

Think of a ship's log beside its charts. The chart shows the route. The log explains the weather, the repair and the reason the captain chose a different harbour. Tomorrow's crew benefits from both.

Three kinds of notes, three different jobs

We keep the records in plain Markdown inside the project repository, so they can be reviewed and versioned with the work.

The folders are deliberately ordinary: docs/daily-progress, docs/architecture and docs/obstacles-and-workarounds. Their value comes from useful entries, not elaborate tooling.

An architecture record is warranted when a decision has lasting consequences. Changing a sentence does not need a design essay. A workaround deserves a record when it would otherwise surprise the next person.

A small example from this very website

The first article containing tables exposed a rendering problem. The source had the right line endings, but the published page displayed pipes and dashes instead of a table.

It would have been easy to keep rearranging the text. Inspection showed that the article renderer used basic Markdown parsing without pipe-table support. We added a regression test using both Windows and Unix line endings. Both cases failed before the fix. After enabling the table extension, the component tests passed.

The journal records that distinction: what the symptom suggested, what the test established, and what actually changed. It also distinguishes a passing local test from a deployed production fix. Those are separate claims with separate evidence.

During release rehearsal, another check failed because it searched for an old log message. The application emitted a newer structured success event. We corrected the check to require the actual success event and reran the rehearsal. We did not turn a failing check into a passing one by quietly removing it.

These are small details. They are also exactly the details someone needs when a similar problem appears six weeks later.

Specify, plan, build, verify

Our shared workflow follows four steps:

1. Specify the requirements. Describe the problem, the scope and what would count as a successful result.
2. Plan the work. Identify the affected parts, likely risks and useful checks.
3. Build the change. Make a focused implementation that respects the project's architecture.
4. Verify the result. Run the relevant checks, inspect their results and record any remaining uncertainty.

For a small bug, a few clear paragraphs in the progress record may be enough. A substantial feature gets a separate specification and implementation plan. The documentation should fit the decision, rather than become a ceremony that delays it.

We apply this local workflow across our AI-assisted development tools. It was informed by the open-source Superpowers project, with a focused adaptation for our own engineering rules and working environment. Shared instructions help maintain continuity; they do not make every assistant response automatically correct.

Useful notes include the things that did not work

A record that says “fixed the issue” is reassuring for about three seconds. Then the next question arrives: which issue, why, and how do we know?

A stronger entry gives the next person a starting point:

Goal: Render article tables correctly.
Finding: The CMS renderer did not enable pipe tables.
Evidence: Tests failed with both CRLF and LF input.
Change: Enable table parsing and add readable table styles.
Verification: Component tests passed; production checks recorded separately.
Next step: Inspect the live article after deployment.

We also record unsuccessful attempts when they teach us something. That can prevent the next session from spending an hour rediscovering a constraint already encountered yesterday.

An unresolved note should say unresolved. A local workaround should say local. A test that could not run should remain visible as a missing check. Honest limitations are more useful than a polished account that implies everything went smoothly.

Continuity when people and tools change

Conversation history can help, but it is an awkward place to hide a project's operating knowledge. Important decisions can be scattered across long chats, screenshots and half-remembered experiments.

A maintained record gives the next work session a concise entry point: the goal, current state, evidence and next action. A developer can inspect it. An AI assistant can read it. The owner can ask informed questions without reconstructing the whole conversation.

This is particularly useful for a small business, where the same person may be shaping the product, talking to customers and returning to technical work between other responsibilities. The project should not depend entirely on one person's memory—or on one particular model remembering a previous chat.

Studying and improving how we work

We also keep these records because our way of working is itself something we want to improve. Looking back across projects lets us ask which approaches helped, which created unnecessary work, and which obstacles keep returning. A journal gives us evidence to revisit, rather than relying on our impressions of a particularly good or frustrating day.

Over time, we can make that accumulated knowledge easier to study with AI. One possibility is to index suitable, sanitised notes in a vector database: a searchable collection that can find related ideas even when the wording differs. That could help us connect similar investigations, identify recurring patterns and suggest improvements to our workflow.

Those suggestions would still need checking against the original records and actual outcomes. The purpose is a continuing learning loop: record the work, study what happened, try a better approach, and check whether it helped. We want the journal to improve tomorrow's decisions as well as explain yesterday's.

Documentation also needs boundaries

We write repository notes as though they may eventually be public. Passwords, access tokens, customer information and private configuration do not belong in a progress journal. A useful technical explanation can normally use placeholders and sanitised evidence.

The notes are a working record, not an immutable audit system or an independent compliance certificate. They can be mistaken or become outdated. We review them against the code and actual results, and update or supersede decisions when circumstances change.

We also distinguish three kinds of evidence: what we intended, what a check demonstrated, and what we observed in the running system. Keeping those separate makes the record easier to trust.

The benefit belongs to the business

The point of this discipline is not to accumulate documents. It is to make the work easier to understand, continue and maintain.

A business owner should be able to ask why a choice was made and receive a grounded answer. A maintainer should be able to find a previous obstacle without repeating it. A new feature should start from what the project already knows.

That is the standard we are working towards: useful software, supported by a readable account of the decisions and checks behind it.

If you are planning an automation project, ask what will remain after the demo: the code, the configuration guidance, the verification evidence and the handover notes. Those are part of what makes a working idea sustainable. Tell us what you are building, and we can discuss a scope that includes both the functionality and the knowledge needed to look after it.