Article 9 of 12 · ARTHA Craft
Said it hundreds of times across 25 years. The fix was not discipline.
"I'll remember that."
The most expensive lie in software development
I have said those words hundreds of times across 25 years of building software. About a bug I spotted while working on something else. About an enhancement idea that arrived mid-session. About a shortcut I took because the deadline was real and the proper solution was not.
And I remembered. Sometimes. For a while. Until the next session opened and the next problem arrived and the thing I was definitely going to remember quietly disappeared.
In the vibe coding era this got worse. More agents. More context switches. More things that never got picked up.
Not a ticket system. Not a Jira board with seventeen custom fields. A register is a structured markdown file, a flat list with a consistent format. Lightweight enough that logging an entry takes thirty seconds. Structured enough that every entry has an ID, a severity, a status, and enough context to act on it later.
Three registers. Three jobs. Nothing duplicated.
Register 1: Bugs
BUGS.MD
Every bug found in testing goes into BUGS.MD before it gets fixed. No exceptions. Not because bureaucracy is valuable, because fixing a bug before it is registered means fixing it without triage. Without knowing if there are three other bugs in the same module that should be fixed together. Without a traceable record that this problem existed, was fixed, and was verified.
The register entry takes thirty seconds. The triage it enables saves hours. Even VERIFIED bugs stay in the file. Knowing a bug existed, was fixed, and stayed fixed is information worth keeping.
Register 2: Enhancements
ENHANCEMENTS.MD
Every improvement idea, UX observation, and "we should do this properly one day" goes into ENHANCEMENTS.MD before it gets built. Good ideas arrive at the wrong moment: mid-session, while building something else, when the scope boundary says stay in your lane.
Without a register the idea gets acted on immediately, breaking scope. Or it gets ignored and the moment of clarity is lost. The register is the third option: capture it now, schedule it properly later. At the start of every sprint, the list is reviewed and items that are ready get promoted to step files.
Register 3: Tech Debt
08-Tech-Debt.MD
Every shortcut taken deliberately. Every stub left intentionally. Every test skipped because the deadline was real. The tech debt register exists because debt that isn't recorded becomes invisible, and invisible debt compounds. You refactor a module without knowing it had a known gap. You build on top of a stub that was never meant to be permanent.
A truth table for every module: WORKING, PARTIAL, or STUBBED. Reviewed at every major planning session. Every stub has a comment in code pointing back to the register entry. Nothing is silently promoted. A step file is required to resolve any debt item.
The Rule That Closes Every Gap
Every coding agent has one obligation beyond its scope boundary: if it finds something, it logs it.
Most teams treat registers as something humans go to after they notice a problem. That is half the system. The other half, the half that makes it airtight, is built into every task file as a standing instruction.
The agent's job does not end at "build this." [2] It ends at "build this and report everything you found along the way."
Agent logs to BUGS.MD: ID, severity, description, what it was doing when it found it. Then continues with its assigned scope. Does not fix it. Does not ignore it. Logs it and stays in its lane.
Agent logs to ENHANCEMENTS.MD. The moment of clarity is preserved. Sprint planning decides whether and when to act on it. The agent does not implement it. That would break scope boundary.
Agent logs to Tech-Debt.MD before the session closes. Comment in code points back to the entry ID. Nothing is silently incomplete. Everything deliberate is recorded and traceable.
This means the registers are not updated when humans remember to update them. They are updated as a contractual part of every execution session.
Complete Health Picture
Not just what was built: what was found, what was deferred, what was deliberately left incomplete. Every agent, every session, every sprint planning conversation starts from this picture.
Triage Before Fix
Nothing fixed in isolation. Everything reviewed in context. Related bugs grouped. Debt items sequenced. Enhancements prioritised. No more random firefighting.
Agent as Reporter
The agent doesn't just build. It discovers and logs. Every session ends with not just code but a record of what was found along the way. The system gets smarter with every execution.
Permanent History
IDs never reused. Entries never deleted. A bug that was fixed three months ago is still in the file, because knowing it existed and was resolved is information worth keeping forever.