with one click
select-pin
// Use when context is needed and pins might already index it — triggers include 조회, 컨텍스트 필요, lookup pin, 어디에 권위가, 누가 알아, 어디 있더라, 찾아봐, 알고 있어, pin 확인, pin 있어. Do NOT use to write or emit new pins (that is write-pin's job).
// Use when context is needed and pins might already index it — triggers include 조회, 컨텍스트 필요, lookup pin, 어디에 권위가, 누가 알아, 어디 있더라, 찾아봐, 알고 있어, pin 확인, pin 있어. Do NOT use to write or emit new pins (that is write-pin's job).
[HINT] Download the complete skill directory including SKILL.md and all related files
| name | select-pin |
| description | Use when context is needed and pins might already index it — triggers include 조회, 컨텍스트 필요, lookup pin, 어디에 권위가, 누가 알아, 어디 있더라, 찾아봐, 알고 있어, pin 확인, pin 있어. Do NOT use to write or emit new pins (that is write-pin's job). |
select-pin is the read-only lookup half of the pins system. When a session needs context that a pin might already index, invoke this skill to walk the pin graph and surface the relevant SSOT pointer — without emitting a new <pin> or modifying any file.
Core principle: Pins are pointers, not wikis. select-pin dereferences those pointers — finding the slug, reading the frontmatter, walking cross-links — then hands the AI the SSOT location so it can act from ground truth.
Context needed?
│
├─ Check the SessionStart <pins> index output
│ ├─ Relevant slug visible? → invoke select-pin (Steps 1–5)
│ └─ No relevant slug but pins:N > 0? → invoke select-pin (a scan may surface it)
│
├─ User asks "where is it?", "who knows?", "is there a pin?"
│ └─ Invoke select-pin first, before any web search or asking the user
│
└─ About to ask the user for context or search externally?
└─ Check pins first (Steps 1–5). Only on miss: proceed to alternative sources.
6 trigger scenarios (see Use cases):
ls $OMT_DIR/pins/
Enumerate all {slug}.md files in the flat directory. The SessionStart hook surfaces a compact index (pins:N | recent:slug1,slug2,slug3) — use it as a pre-filter when available. If $OMT_DIR is unset, log a WARN and skip pin lookup (fail-open: proceed without pins context).
Note the slug prefix pattern: kind-topic-descriptor (with optional -HHMMSS suffix auto-applied by the Stop hook on collision). The kind component is one of {jira / linear / slack / github / notion / code / person / decision / finding / gotcha / unknown} — use it as a first rough filter before reading frontmatter.
For each candidate slug from Step 1, read its frontmatter fields:
| Field | Purpose |
|---|---|
slug | Canonical identifier — matches the filename |
source_url | SSOT location: URL or person:name free-form identifier |
authority | Who or what is ground truth for this topic |
tier | Pin quality tier (1 = high confidence, 3 = placeholder) |
tags | Comma-separated topic labels |
sensitivity | private (default v1) — governs visibility |
created_at | ISO8601 creation timestamp |
related | Optional: comma-separated related slugs (cross-link graph) |
supersedes | Optional: slug this pin replaces |
discovery_context | Optional: one-line Memex trail of the discovery moment |
Read frontmatter only at this step — do not load the full body yet. The goal is to narrow the candidate list to the 1–3 most relevant slugs.
Apply relevance filters:
decision-* for architectural decisions, person-* for human authority, code-* for codebase location)tags fields intersect with the current topic keywords?authority field name a system, person, or URL relevant to the current question?supersedes field, the superseded slug is stale — prefer the newer pin.Rank survivors by relevance. Carry the top 1–3 slugs forward to Step 4. If zero candidates survive, move directly to the Use cases miss scenarios (C, D, E, or F). Distinguish E (authority unknown) from F (authority clear, external SSOT location absent — needs registration).
For each ranked candidate from Step 3, read the full pin body. A well-formed pin body has 4 sections (validator-coupled Korean tokens):
한 줄 요지 (≤80 chars) — the single claim this pin capturesSSOT 위치 + 도달 경로 — where the source of truth lives and how to reach it전후 컨텍스트 — what task or conversation surfaced this knowledge관련 cross-link — links to sibling pins or external SSOT URLsUse section 2 (SSOT 위치) to find the actual information source. The pin body is a pointer — dereference it to the real SSOT when needed. Do not treat the pin body itself as the authoritative content (SSOT principle: ssot-no-copy).
related fieldAfter reading a matched pin's body, check its related field. If present, walk the linked slugs to depth 1 (minimum) for context completeness. Configurable to depth 2 when the topic is complex.
Walk procedure:
related: [slug1, slug2, ...] from the matched pin's frontmatter.hooks/pin-up/validator.ts (AC-19) ensures related slugs point to existing files before a pin is persisted. If a related slug is nonetheless missing at read time (e.g., pin deleted after write), log a WARN and continue — do not abort the lookup.Synthesis: After completing the walk, produce a concise summary that states:
source_url / authority)This synthesis is the output of the select-pin invocation. Use it to answer the question or inform the next action.
A named, callable sub-procedure used in Step 5 and reusable independently when starting from a known slug.
Input: a starting slug (string)
Procedure:
walk_related(slug, depth=1, visited={}):
if slug in visited: return # cycle guard
visited.add(slug)
pin = read $OMT_DIR/pins/{slug}.md
if not exists:
log WARN "related slug missing: {slug}"
return
collect: slug, source_url, authority, tags, body summary
related_slugs = parse pin.frontmatter.related # [] if absent
if depth > 0:
for each rs in related_slugs:
walk_related(rs, depth - 1, visited)
Default depth: 1 (walk immediate neighbors). Use depth 2 when the topic spans multiple subsystems and the initial pin's related list contains decision-* or person-* pins likely to carry further cross-links.
Cycle guard: the visited set prevents infinite loops if two pins reference each other.
Output: a flat list of {slug, source_url, authority, one-line summary} tuples, ordered by walk order (matched pin first, then its neighbors).
SSOT dereference note: when source_url is a URL, it points to a living document (code, PR, Notion, Slack). When it is person:name, the SSOT is a person's knowledge — note this explicitly in the synthesis and, if the context is needed urgently, escalate to asking that person directly.
<pin> XML — that is write-pin's responsibility. select-pin is strictly read-only.$OMT_DIR/pins/, no cursor updates, no escape-log entries.write-pin separately.pin-up hook concerns.The SSOT principle applies here too: select-pin reads pins (which are indexing-not-wiki pointers), then dereferences them to the actual SSOT (URL, person:name, PR, Slack thread) when needed. The pin is never the truth — it points to the truth.
Context is needed. SessionStart output shows recent:auth-jwt-verifier. Slug is immediately visible.
Lookup behavior:
auth-jwt-verifier.md frontmatter → source_url: https://github.com/.../auth/jwt.ts#L142, authority: jwt.ts:verifyToken.code, tags match the auth topic → confirmed relevant.verifyToken at line 142. One-line summary: "JWT verification entry point is jwt.ts:142 verifyToken."related: [decision-auth-strategy] → walk neighbor → context on why this design was chosen.jwt.ts:142, authority confirmed. No new <pin> emit — use the existing pin as-is.A pin exists but the AI or user suspects it no longer reflects reality (e.g., tier: 3 placeholder, or discovery_context references an old task).
Lookup behavior:
write-pin with supersedes: <stale-slug> to update. select-pin does NOT emit the supersedes pin — that is write-pin's job.No pin matches the query. The AI can locate the SSOT directly through code search, documentation, or web fetch.
Lookup behavior:
write-pin to capture the new pin. select-pin's job ends at the miss report — it does not write.No pin, and the SSOT is held by a specific person ("ask A about it").
Lookup behavior:
person-* slugs that might index this person's domain. If a person:name pin exists for a related domain, surface it as a warm lead.write-pin with source_url: person:name. select-pin does NOT write.No pin, no accessible SSOT, nobody knows. A placeholder is warranted.
Lookup behavior:
write-pin with tier: 3 (placeholder) so the gap is indexed for future resolution. select-pin does NOT write the placeholder.No pin matches the query. The information is rich (user-authored content, interview notes, ephemeral chat) but no formal record exists in a stable external system (Notion / Wiki / PR / code repo). file:/// paths are non-dereferenceable for others and volatile.
Lookup behavior:
write-pin Scenario F (3-step collaborative registration → emit). select-pin does NOT register and does NOT write. After the user agrees and the external system entry is created, write-pin emits the pin pointing at the registered URL.