logoalt Hacker News

anupamchughtoday at 12:14 PM2 repliesview on HN

Documentation debt happens when docs and code are decoupled. One fix is to make specs stateful artifacts with change detection. In Shadowbook (disclosure: I built it), specs are files with hashes; when a spec changes, linked issues get flagged and can’t be closed until someone acknowledges the drift. That creates a feedback loop between docs and implementation without “vibe documenting.” It doesn’t solve everything, but it makes contradictions visible and forces a review gate when context shifts.


Replies

gf000today at 3:51 PM

I have been thinking of something similar for quite some time. Though my idea was more like making comments "first class citizens", and in certain formats they can link to each other/external documents, tracking inconsistent changes.

This might also extend to runtime checks (e.g. some business invariant in the form of an assert that has such a "dependency-tracked" comment)

4b11b4today at 1:45 PM

Shadowbook is a fork of beads?