wayfinder

Files (1)

• SKILL.md

SKILL.md (first lines)

# Wayfinder

Before reading relative links, run `cd '<loaded-skill-directory>' && pwd -P`
with this loaded file's directory to obtain the physical base, then resolve
links against that printed directory. Resolve the source symlink before applying
`..`. Read linked files even when their skills are absent from the discovery
list. In Notes, provide a verified file pointer for each required skill, with an
explicit base when stored outside the filesystem; a name alone is insufficient
for a fresh session.

Use a **shared map** to determine the route from a loose idea to a named
**destination**. The destination may be a spec, a decision required before
planning, or an in-place change such as a data-structure migration. The map may
cover engineering, course content, or another domain.

## Plan by default

Investigations determine the route to the destination rather than implementing
it. A request to work through a map authorizes selecting and resolving one
in-scope investigation per session; continue established steps without asking
for reconfirmation. The map is complete when no decision remains before
execution. When the next step would implement the destination, pass it through
the adaptive Delivery mode gate. One selected Ticket stays with the current
responsible conversation whether the maintainer stays or authorizes work while
away; absence alone adds no readiness, Prompt Audit, or dispatcher. Multiple
selected implementation Tickets use Mission dispatch. Preserve gates explicitly
required by the task or repository; map Notes do not add execution authority.

## Refer to issues by title

In narration and the map's **Decisions so far**, refer to every map and ticket
by its linked title. Do not use a bare id, number, or slug as its human-readable
name; retain the id or URL in the title's link.

## Map structure

The map is the authoritative issue for the effort in the configured tracker,
labelled `wayfinder:map`. Its tickets are child issues.

The map indexes decisions; each decision's detail exists only in its ticket.
**Decisions so far** contains a one-line gist and link.

Tracker storage, child relationships, blocking, and frontier queries are
tracker-specific. Read the configured issue tracker's "Wayfinding operations"
section. If configuration is missing, follow
[setup-omskills](../setup-omskills/SKILL.md) and its scoped authorization gate
before continuing, including in headless runs; use local markdown when that is
the resolved configuration. Respect read-only roles and return unresolved
prerequisites to the responsible caller.

### Map body

Load this low-resolution view once per session. Find open tickets by querying
child issues; include a child index in the map body only when the configured
tracker requires it as the relationship fallback.

```markdown
## Destination

<the spec, decision, or change that marks the end of this map; one or two lines>

## Notes

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

## Decisions so far

<!-- one line per closed decision ticket: linked title plus enough detail to judge relevance -->

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

## Not yet specified

<!-- in-scope questions that cannot yet be stated precisely enough for a ticket -->

## Out of scope

<!-- work beyond the destination; it does not graduate into tickets -->
```

### Tickets, claims, and dependencies

Each ticket:

- is a child issue of the map and uses the tracker's issue id as its identity;
- contains a single tracked resolution target sized for one fresh agent session;
- has exactly one `wayfinder:<type>` label: `research`, `prototype`, `grilling`,
  or `task`;
- records its answer in a resolution comment rather than the body; and
- links assets created during resolution instead of pasting them into the body.

```markdown
## Question

<the decision or investigation this ticket resolves>
```

The `## Question` field states the tracked Ticket's resolution target; it is not
a conversational **Question**. A `wayfinder:grilling` Ticket may need several
Question rounds to resolve that single target.

An open, unassigned ticket is unclaimed; assigning it to the developer driving
the map claims it. Concurrent sessions skip claimed tickets.

Use the tracker's native dependency relationship for blocking. Use a body
convention only when the tracker has no native blocking relation. A ticket is
**unblocked** when every ticket blocking it is closed. The **frontier** is the
set of open, unblocked, unclaimed child tickets.

## Ticket types

Every ticket is either **HITL** (requires live input from a human speaking for
themselves) or **AFK** (the agent can resolve it without live human input). An
agent must not supply the human side of a HITL exchange.

- **Research** (AFK): use when resolving the question requires knowledge outside
  the current working directory, such as external documentation, third-party
  APIs, or a local knowledge base. Produce and link a Markdown summary.

From luizomf/omskills, MIT.

More from luizomf/omskills