A useful decision ledger records what was decided, why the choice was made, what evidence supported it, who can revise it, and which nearby questions remain open.
Recover decisions from primary project records
Start with committed architecture records, pull requests, issue discussions, release notes, deployment configuration, and signed specifications. Chat summaries can point toward a decision but should not outrank the artifact that implemented it. Each ledger entry should cite the commit, issue, document, or meeting record that supports the statement and should say when the evidence is incomplete.
The entry needs the decision in one sentence, the problem it addressed, alternatives considered, the deciding constraint, affected modules or processes, the person or role with authority, and the condition that would justify revisiting it. This gives the next builder enough context to distinguish a deliberate tradeoff from accidental code shape.
Keep open questions separate from decisions
A repository transfer creates pressure to make every gap look resolved. That pressure produces false history. If the record does not establish why a vendor was chosen or whether an endpoint is still supported, the ledger should state the question, cite what is known, and name the owner who can decide. A clear unknown gives the new builder a safe stopping point.
The open-work tree should link to the relevant decision without rewriting it into a task. A decision such as 'all writes pass through the service layer' may constrain several tasks, while a task to migrate one write path has its own status, acceptance check, and next command. Keeping those records separate prevents a status update from changing architecture by accident.
Put the ledger where work can update it
The ledger should live in version control or sync through a documented repository workflow. A new decision receives a normal review, and code changes that invalidate an entry update it in the same branch. GitHub's guidance places contributor expectations and project context inside recognized repository files, which makes the repository itself a durable handoff surface.
Cold Start Ledger prepares the first verified ledger through Reality Contact, LLC. The customer confirms historical decisions and remains the only authority that can ratify a disputed or newly proposed decision.
Where the service stops
Reality Contact, LLC prepares and verifies the handoff, but does not maintain or operate production, retain credentials, decide undocumented intent, or present guesses as historical decisions. The buyer reviews the pack, confirms the recorded decisions and access boundary, gives it to a fresh agent or developer, and authorizes that person to complete one bounded task from the verified state. This is technical documentation and verification support; it does not replace legal, security, employment, intellectual-property, or production-operations review. We do not promise that a repository is defect-free, that every historical decision can be recovered, or that a new builder can work without questions.
Sources: GitHub guidance for README and project context; GitHub guidance for repository contribution instructions.