pin

Pin — Session Decision Board

Persist decisions, questions, constraints, and corrections to a JSON file that survives context compaction. A companion hook injects the board into every tool call so the model never forgets.

Auto-Invoke Rules

After responding to any user message where a decision was made, a question was asked about a proposal, or a constraint was stated, IMMEDIATELY invoke /pin with the appropriate category. Do not ask permission — just pin it.

Examples of auto-invoke triggers:

• User: "yes go with bun" → respond normally, then /pin ✅ use bun
• User: "what about the latency impact?" → respond normally, then /pin ❓ split services — latency impact?
• User: "no skip auth for now" → respond normally, then /pin ❌ auth layer — skip for MVP
• User: "MVP only, max 3 files" → respond normally, then /pin 📌 MVP only, max 3 files
• User: "no I meant artisans not developers" → respond normally, then /pin 🔧 target = artisans, not developers

Do NOT pin:

• Casual conversation, greetings
• Implementation details (code changes, file edits)
• Things already pinned (check board first)

Commands

Command	Action
/pin ✅ <text>	Pin approved item
/pin ❓ <text>	Pin pending question
/pin ❌ <text>	Pin killed/rejected item
/pin 📌 <text>	Pin scope constraint
/pin 🔧 <text>	Pin correction
/pin show or /pin	Display current board
/pin rm <n>	Remove pin by number
/pin clear	Clear all pins
/pin clear triage	Clear ✅/❓ only, keep 📌/❌/🔧

State File

Path: a session-scoped .session-logs/<slug>/pins.json file under a configurable base directory.

Derive slug from CWD:

GIT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
REL_PATH="${PWD#$GIT_ROOT/}"
SLUG=$(echo "$REL_PATH" | tr '/' '-')
PINS_DIR="$PRAXIS_DIR/.session-logs/$SLUG"
PINS_FILE="$PINS_DIR/pins.json"

Schema:

{
  "items": [
    {
      "id": 1,
      "type": "approved",
      "emoji": "✅",
      "content": "use bun everywhere",
      "detail": "",
      "ts": "2026-04-01T14:30:00Z"
    }
  ],
  "next_id": 2
}