The Pin

Geoffrey Huntley recently did a livestream on Ralph Wiggum from first principles. One concept stood out: the pin.

Previously, I covered Ralph as a plugin. Then, the methodology. This covers the implementation detail that makes specs discoverable.

The Problem: Invention

When an autonomous loop can’t find relevant code, it invents. “Invention” means hallucination about your codebase - the agent confidently writes authentication logic that duplicates what already exists in src/auth/, just slightly different.

This happens because the search tool missed. The agent searched for “login”, but your spec uses “authentication”. No hits. So it invents.

Compaction makes it worse. Context windows compress over long sessions, losing the frame of reference that told the agent “we already have auth middleware in this exact location.” The agent loses its bearings.

The more it’s able to find and look up that context, the less it’s going to invent.

— Geoffrey Huntley

The pin is your defense against this.

The Pin Concept

A pin is a lookup table that links to your specs with search hints. It’s an index file - typically specs/readme.md - containing “generative words” for each spec.

These words are synonyms, related terms, and keywords that improve hit rate when the agent searches. The more descriptors you add, the higher the probability the search tool finds your spec instead of returning nothing.

The pin becomes your frame of reference. It’s the thing that survives compaction and keeps the agent oriented toward existing code rather than invention.

Implementation

A pin file lists each spec with keywords and location hints:

# Specs Index

## User Authentication
Keywords: auth, login, logout, session, JWT, token, credentials,
  signin, signup, password, verification, 2FA, MFA, middleware
Spec: specs/authentication.md

## Feature Flags
Keywords: flags, toggles, experiments, rollout, AB testing,
  feature management, launch darkly, gradual release, canary
Spec: specs/feature-flags.md

## Analytics Events
Keywords: tracking, events, metrics, telemetry, posthog, mixpanel,
  user behavior, pageviews, conversions, funnels
Spec: specs/analytics.md

The keywords give the search tool multiple entry points. Search for “JWT” or “session” or “2FA” - all hit authentication. The agent then reads the full spec for implementation details.

Why It Works

Search tools use keyword matching. Your codebase uses inconsistent terminology. “Auth” in one file, “authentication” in another, “session handling” in a third.

The pin bridges this gap. By listing many synonyms per spec, you increase the probability that whatever term the agent searches will match something in your pin. One hit is enough to pull in the full spec.

Wiring It Up

Reference the pin in your CLAUDE.md so the agent knows to check it first:

## Specs
Read specs/readme.md first to understand existing functionality.
Use the search hints to find relevant code before implementing.

To bootstrap the pin itself, prompt your agent:

Study all files in specs/ and create specs/readme.md as an index.
For each spec, list 10-20 keywords (synonyms, related terms).

The agent will read your specs, extract the key concepts, and generate the lookup table. Review it, add any missing synonyms, and commit.

Practical Takeaway

Create specs/readme.md as your pin file. List every spec with:

• Keywords: 10-20 terms covering synonyms and related concepts
• Spec path: Direct link to the full spec file

Update the pin when you add new specs. Watch your loop’s behavior - if it’s inventing code that already exists, the search tool is missing. Add more keywords to the pin.

The pin is small overhead for significant improvement in loop convergence. Your specs become discoverable. The agent stays oriented. Invention drops.