wayfinder

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

A loose idea has arrived, too big for one agent session, and wrapped in fog: the way from here to the **destination** isn't visible yet. This skill carries that effort as a **mission**: one issue on the repo's tracker that names a working outcome, and whose child tickets are the decisions and the build that get there. It is done when the outcome is seen working. A complete specification is never the finish line, because specifications are never quite right until something is built against them.

Building teaches what grilling can't, and the code around the mission keeps moving. The mission therefore plans a few steps ahead, in detail that fades with distance, builds the nearest step, and replans from what the building revealed and from what changed around it. Planning is never final; replanning is the normal way a mission moves.

## Refer by name

Every mission and ticket is an issue, so it has a **name**: its title. In everything the human reads (narration, the mission's sections), refer to it by that name, never by a bare id, number, or slug. A wall of `#42, #43, #44` is illegible; names read at a glance. The id and URL ride _inside_ the name, as its link.

## The Mission

The mission is a single issue on this repo's issue tracker, labelled `wayfinder:map`. It is the canonical artifact, and every ticket that serves it, decision or build, is its child issue. Child membership is what lets the repo's dispatcher rank and cap the mission's work together (see the tracker doc).

The mission is an **index**, not a store. It gists each decision and each landing, and links to the ticket or change that holds the detail. Each fact lives in exactly one place.

**Where the mission, its child tickets, blocking, priority and frontier queries physically live is tracker-specific.** The issue tracker should have been provided to you. If not, tell the user to run `/setup-matt-pocock-skills`. Consult the tracker doc's "Wayfinding operations" section for how _this_ repo expresses them, and its "Wayfinding execution" section for how build tickets are dispatched. If no tracker has been provided, default to the local-markdown tracker.

### The mission body

The whole mission at low resolution, loaded once per session. Open tickets are **not** listed: they are open child issues, found by query.

```markdown
## Destination

<the working outcome, in one or two lines, and how anyone can see that it works: the observation, demo or check that closes this mission.>

## Notes

<domain; skills every session should consult; standing preferences for this effort>

## Priority

<the mission's rank against other missions, expressed the way the tracker doc says (for example Value, Class of service, Crew limit), with one line of reason. "Parked: <reason>" when the mission is not being advanced.>

## Decisions so far

<!-- one line per closed decision ticket: enough to judge relevance; zoom the link for detail -->

- [<decision ticket title>](link): <one-line gist of the answer>

## Landed and learned

<!-- one line per landed piece of building, and per outside change that moved the plan -->

- [<build ticket or change title>](link): <what works now>. Learned: <what turned out differently, or "as expected">
- Elsewhere: [<outside change>](link): <what it changed for this mission>

## Not yet specified

<!-- see "Fog of war": known-to-be-coming work and questions whose prerequisites don't exist yet -->

## Out of scope

<!-- see "Out of scope": work ruled beyond the destination; closed, never graduates -->
```

### Tickets

Each ticket is a **child issue** of the mission; the tracker's issue id is its identity. It carries a `wayfinder:<type>` label (see [Ticket Types](#ticket-types)).

- A **decision** ticket's body is the question, sized to one agent session:

  ```markdown
  ## Question

  <the decision or investigation this ticket resolves, and the build step that waits on it>
  ```

- A **build** ticket's body is the contract the repo's dispatch expects: what the next piece of building delivers, how it is checked, and what is out of scope. A **ready** build ticket is written from the decisions it rests on and the code as it stands now. A **planned** build ticket is an outline written further ahead; it is refreshed against the code and marked ready before anyone starts it (see [Planning horizon](#planning-horizon)).

A session **claims** a ticket by assigning it to the dev driving the mission, **first**, before any work, so concurrent sessions skip it. That assignee _is_ the claim: an open, unassigned ticket is unclaimed.

Blocking uses the tracker's **native** dependency relationship, so the tracker's own UI shows what's takeable without opening the mission. Only a tracker that lacks native blocking falls back to a body convention. A ticket is **unblocked** when every ticket blocking it is closed; the **frontier** is the open, unblocked, unclaimed children.

Answers and outcomes are recorded on resolution (see [Advance the mission](#advance-the-mission)). Assets created while resolving a ticket are linked from the issue, not pasted in.

## Ticket Types

Every ticket is either **HITL** (human in the loop, worked _with_ a human who speaks for themselves) or **AFK**, driven by agents alone. A HITL ticket only resolves through that live exchange; the agent asks, and the human answers.

- **Build** (AFK): A slice of the outcome itself, delivered the way the repo builds things (for example a dispatched crew and a change request). It resolves when the slice has landed, and its landing is followed by a learn pass.
- **Research** (AFK): Reading documentation, third-party APIs, or local resources to surface a fact a decision waits on. Resolved by a subagent that calls the Skill tool with "research". Use when knowledge outside the current working directory is required.
- **Prototype** (HITL): A cheap, rough, concrete artifact to react to (an outline, a stub, UI or logic code), made by calling the Skill tool with "prototype". Use when "how should it look" or "how should it behave" is the key question. A spike that settles a question by trying it beats a decision argued from priors.
- **Grilling** (HITL): Conversation. Call the Skill tool twice, for "grilling" and "domain-modeling".
- **Task** (HITL or AFK): Manual work a decision or a build step waits on (provisioning access, signing up for a service, moving data so its shape can be seen). The agent drives it alone where it can; otherwise it hands the human a precise checklist. The answer records what was done and the facts later tickets depend on.

## Planning horizon

Plan the way a controller steers: look a few steps ahead, act on the nearest one, then measure where you are and plan again. Detail fades with distance.

- **Ready**: the next build step or two. Their decisions are settled, and each build ticket is a contract written against the code as it stands now. Building can start.
- **Planned**: the few steps after that. Write them as tickets when seeing them makes the near steps safer or clearer: the order of work, the seams the near steps must leave room for, the decisions worth settling early. A planned ticket is an outline and a working assumption. Mark it planned the way the tracker doc says, and refresh it into a ready ticket when it reaches the front.
- **Fog**: everything further out stays loose in **Not yet specified**. Planning it in detail now is wasted, because it may be irrelevant by the time building gets there.

Plan ahead as far as it reduces risk, and no further. When a grill starts settling the detail of work several steps past the planned horizon, record the thought in **Not yet specified** and return to the near steps.

Decisions and plans are working assumptions. Revisit them whenever the picture changes:

- **After a landing**: what the building revealed.
- **When the surroundings change**: other work landing in the codebase, a dependency or tool in the stack changing, another mission's decision, a fact the team learns elsewhere.

When one is wrong, reopen or supersede the decision, rewrite or close the planned tickets it fed, and say why in **Landed and learned**.

## Fog of war

The mission is _deliberately_ incomplete. Beyond the planned horizon lies the **fog of war**: work and questions you can tell are coming, written down loosely in **Not yet specified**. Write as loosely or as fully as the view allows; it signposts where the effort is headed for collaborators.

A patch of fog **graduates** into tickets when the planning horizon reaches it: when a landing brings it a few steps closer, or when a near step turns out to depend on it. One patch may graduate into several tickets, or none.

**Not yet specified** excludes what's already decided (Decisions so far), what's landed (Landed and learned), what's already a live ticket, and what's out of scope.

## Out of scope

The destination fixes the scope, so work beyond it is **out of scope**: it isn't fog, and it doesn't belong in **Not yet specified**. It gets its own **Out of scope** section: work consciously ruled out of _this_ mission. Out-of-scope work returns only if the destination is redrawn, and then as a fresh mission.

When an existing ticket turns out to sit past the destination, **close it** and leave one line in **Out of scope**: the gist, why, and the link.

## Invocation

Two modes. Resolve at most one HITL ticket per session; AFK tickets (research, build) may run in parallel.

From flotilla-org/mattpocock-skills, MIT.

More from flotilla-org/mattpocock-skills