---
name: pin
description: Put a pin in a good idea that isn't ready to be a plan, so it survives until it is.
---

# Pin

You keep pins for me. A pin is an idea with enough shape to survive past this conversation, but not enough structure to execute. It waits until the time is right, then gets promoted: tested with a probe, or built with a plan.

## What a pin is

- A premise with enough shape to survive a context window.
- Not a todo. A todo is "do X." A pin is "X might be worth doing, here's why, here's what we'd need to know first."
- Not active work. Something being worked now or next belongs in my working notes. A pin can sit for weeks. It's ripe when it's ripe.
- Not a plan. No items, no acceptance criteria, no dependencies, no owners. That's plan territory.
- A piece of writing. Some pins are a paragraph. Some are pages. The format follows the thought.

## Where pins live

```
<pins-dir>/{YYYY-MM-DD}/{nn}-{slug}.md
```

- **Date folder:** the date the pin was dropped. Create it if it doesn't exist.
- **Numbering:** sequential within the date folder (`01-`, `02-`, `03-`...).
- **Slug:** lowercase, hyphenated, descriptive (`pricing-model`, `supplier-switch`).

If I haven't told you where `<pins-dir>` is, ask once, then use it every time.

Working notes and to-do lists don't hold pins. They can *point* to a pin while it's being worked, but the pin itself always lives in the pins folder.

## Pin format

Pins aren't rigid templates. They follow the shape of the thought. But every pin has these elements:

```markdown
# Pin: {Name}

*{Date} — {who raised it}, {where it came up}*
*Status: {pinned | workshopped | promoted | dropped}*

---

{The premise. Why this matters. What was observed. What the question is.
This can be a paragraph or pages. Include quotes, diagrams, open questions,
study directions — whatever the thought needs to survive.}

---

// PROVENANCE
// Originator: {who had the idea} — "{key quote if available}"
// Conduit: {who structured or expanded it, if different}
// Session: {date, where}
```

**Required:**
- Title with `Pin:` prefix
- Date and origin line
- Status line
- The premise (any length, any structure)
- Provenance block

**Optional:**
- Open questions
- Study direction
- Trigger: what would make this ripe
- Related pins or documents
- Which existing documents would change if this went ahead
- Workshopping history (dated update lines)

## Commands

- `/pin {description}` — Drop a pin. Capture the premise from the current conversation and write a new file to the pins folder.
- `/pin` or `/pin list` — List all current pins across all date folders.
- `/pin review` — Review all pins against their triggers and status. Flag any that are ripe.
- `/pin promote {name}` — Promote a ripe pin to a probe or a plan. The pin's premise becomes the probe's question or the plan's source. Set the pin's status to `promoted`.
- `/pin drop {name}` — Set a pin to dropped and note why. Don't delete the file; set status to `dropped` with a reason.

## Lifecycle

```
pin → probe → plan → propagate
seed   test    build   record
```

```
idea surfaces in conversation
    → pin dropped (file written)
    → pin sits (reviewed at the start of sessions and at regular check-ins)
    → trigger condition met, or the premise ripens
    → probe (bounded research: does the premise hold?)
    → probe returns signal → new plan (pin promotes)
    → plan completes → propagate (the record catches up)
    → pin status set to "promoted"
```

Not every pin needs a probe. Some premises are self-evident and go straight to a plan. Use the steps you need.

## Rules

1. **Pins are cheap.** Drop them freely. Losing a premise costs more than keeping a stale pin.
2. **Pins are not commitments.** A pin doesn't mean we're doing the work. It means the idea has enough shape to remember.
3. **Review at the start of a session.** When checking pins, scan for ripeness.
4. **One pin, one premise.** If a pin has two ideas, it's two pins.
5. **Promote, don't expand.** When a pin is ready, promote it to a probe or a plan. Don't grow the pin into a plan in place; that defeats the separation.
6. **Kill stale pins.** If a pin has sat 30+ days without its trigger moving, check whether it still matters. Drop it or rewrite it.
7. **Never delete pin files.** Set status to `dropped` with a reason. The pins folder keeps everything.
8. **Anyone on the work can drop a pin.** The pins folder is shared. Every person or agent on the project can read and write to it.