HN Explorer

Show HN: Gnosis, a knowledge base for what the code can't tell you (github.com)

6 points by stavros ↗ HN
For the past few years, I've been frustrated at how we document our products. The code can tell you what you ended up doing, maybe why you ended up doing it (if your team is disciplined about comments/documents), but it can't tell you why you didn't do what you didn't do.

Time and time again, I've seen teams try to change something to a better way, only to realize why it was done the "worse" way in the first place. Documenting decisions not taken is just really hard, ADRs help but doing it for everything is just too noisy and time-consuming. What's more, most of the decisions just detail what was decided, which is the easy part.

I've been wanting to change this for a long time, and with LLMs, we now can. LLMs are diligent about documenting, and all you need is an instruction in AGENTS.md. That's why I built gnosis.

Simply tell your agent to run it after planning and when done, and gnosis provides the agent with all direction necessary.

Gnosis tells the agent to document only information it got from the human, not anything it can find by itself, and especially to document why alternatives were rejected. It uses a JSONL append-only log and a SQLite index (for retrieval), making it simple, fast, and convenient.

I'd appreciate it if you tried it out and gave me feedback!

3 comments

[ 3.0 ms ] story [ 34.5 ms ] thread
sebakubisz
Rejections are usually conditional on the world at the time: a constraint, a dependency, a workaround that exists today. When those conditions change the rejection is stale but the log still reads "we tried this and it failed." How do you think about surfacing stale entries for revisit? Is it on the agent to spot them on its own or is there a manual deprecation step?
michelhabib
Im currently using mintlify, with a section for design decisions, and why i picked evey one. usually i start by discussing the design, comparing options, picking a suitable one with a certain criteria, document it all in an md, and add it to that section. what is the workflow in your case?