Decision Ledger

Decision Ledger is a set of three powerful agent skills for Claude Code that enhances the decision-making process during software development. These skills—/ledger, /ledger-audit, and /ledger-report—act as a structured framework to document and defend structural decisions made throughout a project's lifecycle.

Overview

In software development, the ability to explain and justify decisions is essential. Decision Ledger addresses this by encouraging developers to document their reasoning at the moment a structural decision is made. With the understanding that two developers may ship the same feature, yet only one can explain their choices weeks later, Decision Ledger provides insights that help you build a robust justification for every choice.

"Status: early. This is an experiment, not a product. There is no usage data yet."

Key Skills

1. /ledger: Activated during structural decisions, this skill prompts the user for a reason, records it, and continues to write code without interruption while documenting the thought process.
2. /ledger-audit: Utilized once per project on an existing codebase to perform a comprehensive review. It gathers questions pertinent to the historical decisions and documents them systematically.
3. /ledger-report: Triggered during a commit or pull request, it summarizes the tracked decisions providing a clear overview of defended and undefended choices.

Practical Example & Utility

Imagine adding authentication to a Next.js application. Before any code is written, users are prompted to make a strategic decision:

Session in an httpOnly cookie or a token held client-side? And why that one?

After deciding on the cookie option, the skill continues and writes the code, while documenting that the reasoning was only partially covered. After a few weeks, at a pull request, a mastery map is generated:

Mastery map: 24 decisions tracked, 21 days

auth/          ██████░░░░░  2 of 5 defended
data-model/    █████████░  4 of 5, 1 decayed
ui/            ██████████  7 of 7
jobs/          ████░░░░░░  2 of 5, 1 unknown
Transfers observed: 2 (session-storage, cache-invalidation)

Documentation & User Experience

Decision Ledger is designed to integrate seamlessly into a developer's workflow. It operates without blocking the user's productivity, ensures decision-making context, and records answers—even when a developer is unsure. The skills are installed in the standard Claude Code method, making it easy to get started without heavy configurations.

Addressing Comprehension Debt

The tool confronts the issue of comprehension debt—the scenario where code is functional, yet the rationale behind its structure is absent. By recording decisions and reflecting on their justification, Decision Ledger creates a tangible link between choices made and the underlying thought processes, providing clarity and direction in future development efforts.

Reinforcing Understanding Through Feedback

As developments progress and decisions are revisited, the Decision Ledger allows real-time assessment of understanding, revealing areas where knowledge has decayed over time. By revisiting these decisions, developers can ensure that the rationale behind their choices evolves accordingly and contributes to a well-documented project.

Conclusion

Decision Ledger acts as a crucial ally for developers, transforming the often overlooked rationale behind decisions into valuable data that supports project growth and team accountability. By ensuring that every choice is documented effectively, teams can work with greater confidence and clarity.