deadend

Documentation

Overview

Package deadend answers one question: has this been tried before?

Every other retrieval path here is pull — an agent asks, and the store answers. This one is push. The agent is about to propose something, and the useful move is to interrupt: *you tried that in March, here is why it did not work, here is who found out.*

The distinction matters more than it looks. `resume` gives an arriving agent the last checkpoint, which covers the approach ruled out yesterday on the project it is already working on. It does nothing for the approach ruled out in March, on a project nobody mentioned, by an agent that no longer exists. That knowledge is in the vault — it just has no way of reaching the moment it would have been useful, because nobody thinks to search for the thing they are about to suggest.

So the corpus is every dead end recorded anywhere in the vault, and the query is the proposal itself. This is also the part of the system that cannot be copied: the mechanism is a morning's work, and the two years of accumulated "we tried that" is not.

What counts as a dead end

Checkpoints carry a Failed list, which is the curated corpus — someone chose to write those down as ruled out. Working notes are messier and matter anyway: an agent killed before it could check in leaves its findings only there, and "the audio team vetoed dropping the second mic" is exactly the kind of thing that dies with the session. Those are admitted when they read as a failure, by an explicit marker rather than by sentiment, because a note wrongly filed as a dead end will stop work that should have happened.

Index

• func Render(proposed string, hits []Ruling) string
• type Ruling
  • func Check(vaultDir string, db *sql.DB, p *provider.Provider, ...) ([]Ruling, error)
  • func Collect(vaultDir string, db *sql.DB, project string) ([]Ruling, error)
• type Source

Functions

func Render

func Render(proposed string, hits []Ruling) string

Render writes the interruption.

The wording is doing real work here, and it is not decoration. This output lands in front of a model that is about to propose something, and there are two ways to get it wrong. Too soft — "you may wish to consider" — and it gets skimmed past. Too hard — "this will not work" — and it stops an agent from retrying something that deserves a second look, which is worse, because a dead end recorded a year ago under different constraints is evidence, not a verdict.

So the shape is: state plainly that it was tried, say by whom and when, and hand the decision back. The agent is told to say out loud that it knows, because the visible version of this — "we tried that in March, the drop test failed at 1.2m" — is the difference between a memory that stores and a memory that helps.

Types

type Ruling

type Ruling struct {
	Text    string  `json:"text"`
	Project string  `json:"project"`
	Agent   string  `json:"agent"`
	When    int64   `json:"when"`
	Slug    string  `json:"slug,omitempty"`
	Source  Source  `json:"source"`
	Score   float64 `json:"score"`
	// Elsewhere is true when this was ruled out on a different project than the
	// one being asked about. Still worth saying, and worth flagging: what failed
	// on other hardware may not fail here, and presenting it as settled would be
	// the same overreach this package exists to prevent.
	Elsewhere bool `json:"elsewhere"`
}

A Ruling is something already tried that did not work.

func Check

func Check(vaultDir string, db *sql.DB, p *provider.Provider, embedModel, proposed, project string, k int) ([]Ruling, error)

Check returns the recorded dead ends bearing on a proposed approach, best match first.

Two ways to match, either sufficient. Lexical containment catches a proposal restating the original almost word for word, which is the common case when an agent has read the project note and is working from the same vocabulary. Embedding similarity catches the opposite case — the same idea in different words — and is what makes this useful across projects, where the vocabulary has no reason to line up. With no embedder available the lexical arm still works, so this degrades rather than disappearing.

func Collect

func Collect(vaultDir string, db *sql.DB, project string) ([]Ruling, error)

Collect gathers every recorded dead end. An empty project means the whole vault, which is the interesting case: the approach that failed on one project is often the same approach about to be proposed on another.

type Source

type Source string

Source says where a ruling came from, which is also how much to trust it.

const (
	// FromCheckpoint is a Failed entry someone deliberately recorded.
	FromCheckpoint Source = "checkpoint"
	// FromNote is a working note that reads as a failure. Never committed, so
	// it may be a first impression rather than a conclusion.
	FromNote Source = "working note"
)