procedure

Documentation

Overview

Package procedure answers the question before_you_try's dead-end half leaves unanswered: not just what was ruled out, but what is known to work, including the trap in doing it the obvious way.

It is the mirror of internal/deadend on purpose. A dead end stops an agent from repeating a mistake; a procedure stops it from repeating the discovery that the mistake was avoidable in the first place — "run the chaos tier before calling a durability fix done, or go test ./... passes with the bug still there" is exactly as valuable as a recorded failure, and exactly as likely to be known only to whoever last hit it.

A procedure earns storage only if it carries a trap: something not derivable from reading the repository, that cost someone time. Without that bar this package would duplicate CONTRIBUTING.md one remembered line at a time, which is the failure BRAINPROMPT.md already warns against — "don't call remember for what the repository already says."

Index

• func Render(hits []Hit) string
• func Validate(r Record) error
• type Evidence
• type Hit
  • func Check(corpus []memory.Memory, p *provider.Provider, ...) ([]Hit, error)
• type Record
  • func ParseRecord(raw string) Record
  • func (r Record) Typed() bool

Functions

func Render

func Render(hits []Hit) string

Render writes the "known to work" half of before_you_try.

Unlike deadend.Render, silence here is not a finding worth stating — "nothing recorded" needs no caveat the way "nothing rules this out" does on the dead-end side, because absence of a procedure was never going to read as approval or disapproval of anything. So an empty result renders nothing at all, and the caller omits the section entirely rather than showing it empty.

Every payload field goes through untrusted.Inline before it lands here — a route or a trap is vault content a prior agent wrote, and this output reaches a model exactly like a dead-end ruling does.

func Validate

func Validate(r Record) error

Validate reports whether a record earns storage as a procedure at all.

The trap requirement is the package's whole editorial policy, made mechanical rather than a matter of taste: if a route cannot be written down with something that goes wrong without it, it is documentation, and documentation belongs in CONTRIBUTING.md, not in a memory a model might mistake for something worth repeating uncritically. This is also the one guard against the failure the memory-architecture survey calls reflective-memory pollution — a single bad write contaminating every before_you_try answer downstream — since a required, specific trap is much harder to fabricate convincingly than a plausible-sounding tip.

Types

type Evidence

type Evidence string

Evidence says how hard the claim that this works has been checked. Distinct from deadend.Degree, which grades certainty that something failed — this grades certainty that something succeeds, which is a different question with a different failure mode: a procedure someone assumes works but never ran is the one most likely to waste a reader's time.

const (
	EvidenceVerified Evidence = "verified" // the author ran Verify and watched it work
	EvidenceOnce     Evidence = "once"     // worked one time; not yet repeated
	EvidenceReported Evidence = "reported" // someone said so; the author did not check
)

type Hit

type Hit struct {
	Text    string
	Project string
	Agent   string
	When    int64
	Score   float64
	// Elsewhere is true when this was recorded on a different project than
	// the one being asked about — worth surfacing and worth flagging, the
	// same distinction deadend.Ruling draws for the same reason.
	Elsewhere bool
	Record    Record
	// Stale mirrors deadend.Ruling.Stale: a version-bound procedure old enough
	// that the dependency it names may have moved. Surfaced as a caveat,
	// never dropped — a stale procedure is still the best lead available.
	Stale bool
}

A Hit is one recorded procedure bearing on a proposed approach.

func Check

func Check(corpus []memory.Memory, p *provider.Provider, embedModel, approach, project string, k int) ([]Hit, error)

Check returns the recorded procedures bearing on a proposed approach, best match first, out of the given corpus. The corpus is every memory.Kind = Procedure row in the vault — gathering it is the caller's job (see memory.RecallProcedures), so this package can be tested against a handful of hand-built candidates without a store behind it.

Ranking mirrors deadend.Check exactly: lexical containment for a proposal restating a route in the same vocabulary, embedding cosine for the same idea in different words, same-project rulings first, then score. Degrades to lexical-only with no embedder rather than disappearing.

type Record

type Record struct {
	Route    string
	Trap     string
	Verify   string
	Layer    deadend.Layer // shares deadend's vocabulary: same question, "does this transfer?"
	Scope    deadend.Scope
	Evidence Evidence
	Raw      string
	// Truncated is set when the source entry ran past recordCap and was cut
	// to fit. The cut is visible here rather than silent, per the invariant
	// that a lossy operation says so.
	Truncated bool
}

Record is one procedure, typed. Route and Trap are both required for a record to count as typed — see Validate — because a route with no trap is a convention rather than a procedure. Layer, Scope, Verify and Evidence are each optional and simply absent from Render when unset.

Raw is always populated — the on-disk form, exactly as recorded — so a hand-edited or partially-typed entry stays readable rather than silently losing whatever did not parse.

func ParseRecord

func ParseRecord(raw string) Record

ParseRecord turns one stored procedure line into a typed Record.

The wire format mirrors deadend.ParseRecord exactly: a line of `key: value` segments joined by " | ", anchored on a `route:` key. Anything else — including a line that fails Validate and should never have been stored — comes back as free prose with Layer: unclassified, so a caller never has to branch on which kind of entry it got.

func (Record) Typed

func (r Record) Typed() bool

Typed reports whether this parsed as the structured shape at all, rather than falling back to free prose.