loopmap

Documentation

Overview

Package loopmap is the loop-stage -> tool map: the in-loop affordance that answers "what tool do I reach for RIGHT NOW?" at each stage of the agentic-coding loop (orient -> plan -> act -> verify -> ship -> learn, the six stages owned by internal/loopindex). It is the #1153 lever of the 10x dev-experience epic (#1148): the loop-index scorecard measures whether the loop is getting faster; this makes the RIGHT verb cheap to FIND at the right moment so every other lever gets used by DEFAULT instead of by luck.

The map is DATA, not prose — a queryable table the impure shell (cmd/fak/loopmap.go, the `fak loop-map` verb) prints, filters by stage, or matches against a free-text "what now?" situation. Each fak-kind entry names a REAL `fak` verb; the no-drift witness (loopmap_test.go) re-derives fak's verb registry from cmd/fak/main.go and fails if the map points at a verb the binary does not have — so the map cannot rot away from the tool surface it describes.

Index

• func FakVerbs() []string
• func Stages() []string
• func VerifyNudge() string
• type Entry
  • func Ask(situation string) (Entry, bool)
  • func ForStage(stage string) []Entry
  • func Map() []Entry
• type Kind

Functions

func FakVerbs

func FakVerbs() []string

FakVerbs returns the set of bare `fak` subcommand names the map references (the first token after "fak " of every KindFak verb). The no-drift witness checks each against the real registry parsed from cmd/fak/main.go.

func Stages

func Stages() []string

Stages returns the six canonical loop stages, in loop order — bound to the loopindex spine so a renamed stage there fails to compile here.

func VerifyNudge

func VerifyNudge() string

VerifyNudge is the "did you verify?" reminder surfaced at the verify/ship boundary — the one-line prompt that turns a silent self-report into a checked claim.

Types

type Entry

type Entry struct {
	Stage     string   `json:"stage"`
	Situation string   `json:"situation"`
	Verb      string   `json:"verb"`
	Kind      Kind     `json:"kind"`
	Why       string   `json:"why"`
	Keywords  []string `json:"keywords"`
}

Entry is one row of the map: at loop Stage, when you are in Situation, reach for Verb (which lives on surface Kind), because Why. Keywords drive the free-text Ask match; they are the words a mid-tier agent would actually type at that moment.

func Ask

func Ask(situation string) (Entry, bool)

Ask matches a free-text "what tool do I reach for right now?" situation to the best map entry by keyword overlap (the thin lexical lookup the issue asks for — a 6-way stage classifier, not a new oracle). It returns the highest-scoring entry and true, or a zero Entry and false when nothing matches. Ties resolve to loop order, so the earliest stage wins a draw.

func ForStage

func ForStage(stage string) []Entry

ForStage returns every entry at the given loop stage, in map order. An unknown stage returns nil.

func Map

func Map() []Entry

Map returns the whole loop-stage -> tool map in loop order (a copy; callers must not mutate the package data).

type Kind

type Kind string

Kind tags where a verb lives so a reader knows which surface to reach for.

const (
	// KindFak is a `fak` subcommand (always present in this binary; drift-checked).
	KindFak Kind = "fak"
	// KindDos is a `dos` kernel verb (the domain-free trust substrate / MCP tools).
	KindDos Kind = "dos"
	// KindSkill is a paged Claude skill (#1103 loads these on demand).
	KindSkill Kind = "skill"
)