Question the Source: A Questionable Code History

States in history are tagged with a version number on public release. Semantic Versioning is a convention to give extra meaning to the numbers by conforming to a format MAJOR.MINOR.PATCH.

A software repository generally has a primary history (often named “main”) which can be imagined as a simple sequence of states, while underneath is modeled as a branching structure.

It's always gonna be costly. Making the below assumptions, we still say it's worth it.

Accepting ambiguity and assuming the process [of maintaining a decision journal] is more important than the end – then it seems favorable to at least always try, no matter how poor your documentation (also ignoring the amount of cost of such maintenance and that this maintenance does occur such that decisions are up to date).

Within the Tandem History are participants and narratives. A narrative is defined by participants’ interactions recorded in the journal. The narrative is where source history and decision history are joined. There may be many narratives for a codebase, however, in general, there is one commonly accepted narrative. An example of differing narratives is: a detailed versus condensed narrative.

A narrative is organized in books, chapters and paragraphs. A book contains a sequence of chapters. A chapter contains a sequence of paragraphs. Paragraphs contain a set of participant interactions. Paragraphs also validate coverage of lines of code in source history (discussed in “Responsibility Links”).

A paragraph brings together source history and decision history via “binding”. A paragraph binds to a sequence of states in source history and a set of interactions in decision history.

While paragraphs serve as a “loose” binding site for joining source history with decision history, the methodology additionally enforces a tighter relationship between code and accepted decisions’ answers.

Every line of code in each source state must be mapped to an accepted answer. In other words: from accepted answers, a responsibility “edge” must link to every line of code added in a source state.

Questions are the nodes in the graph and contain possible answers and the accepted decisions.

Answers live within a question node and serve as a source for edges to connect to other questions.

Answers are broken into two abstractions: slices and stances. The purpose is to allow the exact answer (stance) to be revised, while still belonging to the same general direction (slice).

A slice is the “general direction” of an answer. A slice serves as a container for answer revisions.

A stance is the exact position of an answer. To revise an answer, a new stance is created within the slice.

Edges within the decision space are directed. The source is always an answer (stance) and the destination is another question.

There are two types of edges: "leads to" and "constrains".

For a question, decision points are explicitly created. At a decision point, participants may individually accept an answer (a stance).

A new decision point must be created, to accept a revised or different stance.

Interactions have two kinds: commands or queries. Queries are “reads” and commands are “writes”. Query interactions only return a value to be read. Command interactions may emit zero or more events.

The methodology utilizes an event-based approach. An event represents a successful mutation to a narrative. For example: an event may describe the creation of a question, an accepted answer, a responsibility link, etc. The graph representation is then built from the sequence of recorded events.

A CLI exposes commands for initializing a new history, running tutorials, as well as performing individual participant interactions. The CLI may also be driven conversationally by an agent.

A visual representation of the methodology is extremely helpful in understanding the method itself but as you are authoring history. A web based viewer is provided. The web viewer can replay history on an individual interaction basis or narrative organizational basis (book, chapter, paragraph).

Ask questions first, consider options, accept answers, then author the code. After making commits, bind commits to the paragraph, and lastly, assign responsibility from accepted answers to lines of code.

Write the code first, then backfill questions and answers to assign responsibility coverage to lines of code.

Switch between the decision and source space as new questions naturally arise or answers are revised.

An example scenario of designing a library which can double a number to give a minimal demonstration.

The methodology was used during the development of this project’s own source code. From this experience, I must say that the process of formulating the question graph does indeed introduce quite a bit of friction. Coming up with questions, proposing possible answers… then linking accepted answers to cover every line of merely the README took a lot of time and effort (that being said, the readme contained quite a few concepts). I might compare it to the effort of deciding on appropriate member names, doing research, documenting a process, etc.

Before line responsibility coverage, binding commits to paragraphs forces one to reconsider the order in which behavior is introduced. Grouping by paragraph does enable flexibility of commit size, however by design demands that nearby commits are related, which in practice is often not the case. Even though I was conscious of this as I was authoring the code, I very often found myself re-writing [git] history. Re-writing history is acceptable for unpublished code, but generally forbidden otherwise.

I curated a set of starting questions and minimal source boilerplate as an open-source repository to be forked. The purpose of the example repository is: 1. demonstrate the methodology, 2. promote an accessible starting point, 3. identify common sets of questions.

This methodology has been trialed in a three person team for development of a financial auditing software. During the initial information gathering phase of an audit, the software helps coordinate documentation requests between a firm and the client being audited.

To evaluate onboarding an existing repository, a general set of instructions have been developed to serially process repository commit history and directly linked context (issues, Pull Requests (PRs), etc). The goal is to infer a condensed educational history which introduces the code expressed as a series of questions.

The constrains edge is currently ceremony. I would be curious to try a System One model which "decides" if a proposed answer is valid or invalid with respect to the constraints from previously accepted answers.

Currently, responsibility assignment is manual through the GUI or CLI. I have also evaluated it when driven via a Large Language Model (LLM) agent. I would be curious to feed a line or hunk into a decision model where it returns a noul for each accepted answer.