flashlight

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

A **wayfinder map** charts a large effort as decision tickets on the issue tracker, wrapped in **fog**. Its **frontier** — the open, unblocked, unclaimed tickets — advances in its own order.

A flashlight is the human's beam. They point it at one direction, and this session walks in **now**, out of frontier order, to learn what lies that way.

`/flashlight <map> <request>`. Ask for the map when the invocation omits it. Shine **one beam per session**.

Where the map, its child tickets, blocking edges, claims and the frontier query physically live is tracker-specific. Consult the tracker doc's "Wayfinding operations" section for how this repo expresses each one. Default to the local-markdown tracker when no tracker doc is present.

## Two beams

Read `<request>`, and ask one question: **is the subject the map, or the territory?**

- **Territory** — the work itself. "Can we use SQLite for the queue?" → [Shine into the territory](#shine-into-the-territory).
- **Map** — the chart you already drew: what to focus on, what to defer, what no longer belongs. "We have too many open tickets — what should we focus on?" → [Redraw the map](#redraw-the-map).

Ask the human to choose when the request reads both ways.

## Shine into the territory

The beam becomes one ad-hoc ticket, and leaves the same trail as any ticket the map was charted with.

### 1. Aim the beam

Load the map — Destination, Notes, Decisions so far — and the open tickets bearing on the direction. Where an open ticket already asks this question, work that one instead: claim it, and continue from step 4.

Infer the **type** from the request:

| Type | Use it for | Resolve with |
| --- | --- | --- |
| **Grilling** (HITL) | a decision to settle by conversation — the default | `/grilling` and `/domain-modeling` |
| **Research** (AFK) | a fact from outside this working directory | a `/research` subagent |
| **Prototype** (HITL) | "how should it look, how should it behave", answered by a cheap concrete artifact | `/prototype`; `/grill-design` for an unsettled frontend look |
| **Task** (HITL or AFK) | manual work that unblocks a decision | the agent alone where it can; otherwise a precise checklist for the human |

On a **HITL** type the human answers their own questions — this session asks and records. An **AFK** type runs alone.

**Done when** the type is chosen and the map's Destination is in hand.

### 2. Zoom out

Brief the human: the **type** in bold, what this session is about to do, and where the direction sits on the map.

**Done when** the human has seen the type before any ticket exists.

### 3. Create and claim the ticket

Create a child issue of the map titled `Flashlight: <direction>`, carrying the verbatim `<request>` as its question and the `wayfinder:<type>` label. It takes no blocking edges — it is born and closed inside this session.

**Claim it** — assign it to the dev driving the map — before the work starts.

**Done when** the ticket exists, carries its type, and shows an assignee.

### 4. Work the ticket

Resolve it as a ticket of its type. Invoke the skills the map's `## Notes` names, plus the type's own. Zoom into any related or closed ticket on demand.

**Done when** the question has an answer its type can support.

### 5. Record and adjust the map

- Post the answer as a **resolution comment**, then **close** the ticket.
- Append one line to **Decisions so far**: the ticket name, its link, and a one-line gist of the answer.
- Create the tickets the answer made specifiable, and clear each graduated patch from **Not yet specified**.
- Rule out of scope whatever the answer put past the destination: close it, and leave one line in **Out of scope**.

**Done when** the ticket is closed and every section the answer touched carries its line.

## Redraw the map

The beam falls on the chart itself. This mode creates no ticket — the comments it leaves on the tickets it touches are the record.

### 1. Read the whole chart

Load the map and **every** open ticket: question, type, blockers, assignee.

**Done when** each open ticket is accounted for, the claimed ones included.

### 2. Propose

Show the human one change list, and wait for their approval. Name every edit, and why it earns its place.

**Done when** the human has approved the list.

### 3. Apply

| Verb | What it does |
| --- | --- |
| **Create** | a new ticket — then wire its edges in a second pass, because issues need ids before they can reference each other |
| **Update** | a ticket's question |
| **Re-order** | map order decides frontier order, so this is how you prioritise |
| **Re-wire** | a ticket blocked by an open ticket leaves the frontier and returns when that blocker closes, so this is how you defer |
| **Rule out of scope** | close it, and leave one line in **Out of scope**: the gist, and why it sits past the destination |
| **Cancel** | for a duplicate or a mistake. Close it, and leave one line in **Decisions so far** marked **cancelled**, carrying the reason |

Comment on every ticket you touch, saying what happened and why.

A ticket with an assignee is **claimed**: a live session is working it right now. Leave its state as it is, and comment on it, so that session learns what changed.

**Done when** every approved edit is applied, and every touched ticket carries its comment.

From will-ness-ai/skills, MIT.

More from will-ness-ai/skills