Architecture decisions
SigMap makes choices most tools in its space do not: it ranks with BM25 instead of embeddings, ships no parser, calls no model, and keeps shared state in a local text file. Each is a trade, and each has a cost this project pays on purpose.
An architecture decision record (ADR) is the short answer to "why is it built this way, and what would change your mind?" These pages write down decisions that were already made — in private planning notes and across years of issues and release notes — so the reasoning is in one public place and checkable. The Why sections are reconstructed from the source, the changelog, issues and those notes; where a reason is not in the record, the page says so.
How to read a record
Every record has the same parts, so a skeptic can go straight to the one they doubt.
| Part | What it answers |
|---|---|
| Context | What problem forced a choice, and what the options were |
| Decision | What SigMap does, stated so it can be tested |
| Why | The reasons, in order of weight |
| Consequences | What the decision costs, including the cases it gets wrong |
| Evidence | The file, test, benchmark or issue behind each factual claim. Where a reason is the author's reconstruction, or nothing is recorded, the page says so |
| Revisit when | The evidence that would reopen it. A decision with no such condition is a belief |
A record can be Accepted, Accepted with exceptions (the decision stands and the page lists where it does not), Deprecated (the thing it describes is on its way out) or Superseded by a later record. A record is never rewritten to hide that it changed; a later one points back at it.
The records
| # | Decision | Status |
|---|---|---|
| 0001 | Rank files with identifier-aware BM25, not embeddings | Accepted |
| 0002 | Hand-written extractors; SigMap ships no parser or grammar | Accepted with exceptions |
| 0003 | No LLM call on the path that produces SigMap's output, and no network beyond two opt-in paths | Accepted |
| 0004 | Blast radius is a closed-form score, min(100, 4 × direct + 1 × transitive) | Accepted |
| 0005 | The centrality ranking prior shipped behind a flag, was measured, and is deprecated | Deprecated |
| 0006 | Cross-session state is local, append-only NDJSON — no daemon, socket or hosted store | Accepted |
Adding one
Copy the template. Number it next in sequence, keep it to one decision, and cite evidence that lives in the repository — a file, a test, a benchmark report or an issue. If the decision reverses an earlier record, mark the earlier one Superseded and link both ways; do not delete or reword it.
Two rules keep the records honest: state the cost of the decision as plainly as its benefit, and where a claim has no recorded basis, say so rather than supply one.