wayfinder

Files (1)

• SKILL.md

SKILL.md (first lines)

# Wayfinder

All work enters through wayfinder regardless of size, but not all work
earns a map. Grill first; if the way to the destination is already clear,
take the no-fog early exit (Mode 1, step 3) and proceed without one. A
trivial task's map might have 1 grilling ticket and 1 task ticket; a large
migration might have 20+. The process is consistent; only the map size
varies.

## The map

A single document (on the configured tracker) containing:

- **Destination** — one sentence: where are we trying to get.
- **Decisions so far** — one line per resolved ticket: enough to judge
  relevance, plus a link to the ticket holding the detail.
- **Open tickets** — the sharp questions, with blocking relationships.
- **Not yet specified** — in-scope fog: questions you can tell are coming
  but cannot yet phrase sharply. Graduates into tickets as the frontier
  advances.
- **Out of scope** — work ruled beyond the destination. Closed, and it
  never graduates.

### The map is an index, not a store

A decision lives in exactly one place — its ticket. The map **gists and
links**; it does not restate. Load the map at low resolution to orient,
then zoom into individual tickets on demand.

Keep it this way for a concrete reason: a decision written in two places
starts drifting between them the moment one is edited, and a map that
restates every decision grows until it no longer fits the context window it
exists to save.

When fog graduates into a ticket, **clear the graduated patch** from *Not
yet specified* so it lives only as its new ticket.

### Fog or ticket?

The test is whether you can **state the question precisely now** — not
whether you can answer it now.

- **Ticket** when the question is already sharp, even if it is blocked and
  cannot be acted on yet.
- **Not yet specified** when you cannot phrase it that sharply. Leave the
  patch coarse: one patch may graduate into several tickets, or none, once
  the frontier reaches it.

*Not yet specified* is for work inside the destination. Fog gathers only
*toward* the destination — work beyond it belongs under *Out of scope*,
where it does not read as takeable frontier.

## Ticket types

| Type | Mode | Purpose |
|------|------|---------|
| **Grilling** | HITL | Resolve a decision the user must make. One question at a time. |
| **Research** | AFK | Investigate primary sources, write findings. Delegates to `research` skill. |
| **Prototype** | HITL | Throwaway artifact to answer "how should it look/behave?" |
| **Task** | AFK/HITL | Config, provisioning, data migration — doesn't need a decision. |
| **Bug** | AFK/HITL | Diagnose and fix a defect. Delegates to `skills/diagnosing-bugs/SKILL.md`. |

HITL = human in the loop. AFK = agent works unattended.

## Grilling discipline

Grilling happens inside tickets typed as "grilling". The full grilling
methodology lives in `skills/grilling/SKILL.md`. Key points:

1. **One question at a time.** Never batch multiple questions.
2. **Propose before asking.** State a recommended answer; user
   confirms or corrects. Faster than open-ended questions.
3. **Facts vs decisions.** If it can be found by reading the codebase,
   look it up. Only ask about decisions the user must make.
4. **Challenge every answer.** After each response, explore what it
   implies, what it breaks, and what happens at the edge. Do not move
   on until the downstream effects are mapped.
5. **Spot and reject vagueness.** Push abstract answers ("flexible",
   "whatever makes sense") to concrete specifics.
6. **No question cap.** Could be 3 or 50 — driven by ambiguity. The
   session ends when you cannot generate another question whose answer
   would change what gets built.
7. **Domain modeling inline.** Terms captured to CONTEXT.md as they
   surface. ADRs written when non-obvious decisions are made.
8. **Confirmation gate.** Do not proceed from grilling tickets until
   user confirms shared understanding is reached.

## Mode 1: Chart the map

1. Name the destination in one sentence. It fixes the scope and shapes
   every ticket, so settle it first.
2. **Map the frontier** — grill breadth-first, fanning out across the whole
   space rather than deep on any one thread, to surface the open questions
   and what is takeable now.
3. **No-fog early exit.** If that breadth-first pass surfaces no fog — the
   way to the destination is already clear and the whole journey fits one
   session — **stop and ask the user how they would like to proceed.** Do
   not build a map nobody needs. This fires *before* any map exists, and is
   cheaper than the post-map fork in "Completion".
4. Otherwise create the map: destination filled in, decisions empty, and
   the fog sketched into **Not yet specified**.
5. Create the tickets you can specify now, then mark blocking
   relationships. Everything you cannot yet phrase sharply stays as fog.

## Refer to tickets by name

In everything the user reads — narration, the map's *Decisions so far* — a
ticket goes by its **name**, not a bare id. `#42, #43, #44` is illegible;
names read at a glance. Keep the id or link, but carry it inside the name
rather than in place of it.

## Mode 2: Work through the map

1. Load the map at low resolution — the index, not every ticket body.
   Orient to the destination before choosing.
2. Find the next unblocked ticket. Zoom into related or closed tickets on
   demand as the work needs them.
3. Resolve it (grilling → ask user; research → delegate to research
   skill; prototype → delegate to `skills/prototype/SKILL.md`;

From lynchypin/project-onboard, MIT.

More from lynchypin/project-onboard