Wayfinder

---
name: wayfinder
description: Plan a huge chunk of work (more than one agent session can hold) as a shared map of decision tickets on your issue tracker, and resolve them one at a time until the way to the destination is clear.
---

Read [ZeNorm integration](../zenorm-integration.md) for the supplied records, actual human answers and bounded assignments.

Wayfinder charts a **shared map** of **decision tickets** for an effort too large or uncertain for one session. Its **destination** fixes the scope. Planning is the default: the map clears when the way is known, before delivering the destination. An explicit Notes agreement may include execution; otherwise hand off when decisions are settled.

## Map and frontier

The map is an **index**, not a store. Keep decision detail in its ticket and reference it by a named link with a one-line gist. Use names in human-facing narration, not bare identifiers.

Write for a busy reader: the shortest wording that keeps the important detail, each thing said where it applies rather than through chains of cross-references, and no code identifiers in questions unless the human needs one to decide. Name another map's spec by its title, never by its spec number or criterion ids. In the map's summary and destination, link that title to the spec's page. Write to the reader as "you", and for the product's own users use the word the project itself uses (in its code, docs or the map), not one of yours.

The map contains:

- **Destination**: the outcome, in one or two lines.
- **Notes**: relevant domain and standing preferences.
- **Decisions so far**: named links and one-line answers to resolved in-scope tickets.
- **Not yet specified**: in-scope **fog of war**, questions not yet sharp enough to ticket.
- **Out of scope**: excluded work and why. It does not graduate as fog clears; changing the destination starts a fresh effort for it.

Open tickets are queried, not copied into the map body. A ticket is a bounded question with a canonical type, claim, sources and blocking relationships. The **frontier** is open, unclaimed tickets whose blockers are resolved, in the environment's stable order (filename order in the local tracker). Claim before working; on conflict refresh instead of duplicating work.

**Fog or ticket?** Ticket when the question is precise, even if blocked. Keep it as fog when prerequisites still prevent phrasing the question. Graduate fog one question at a time; remove graduated text so the question lives only in its ticket. Neither settled decisions nor existing tickets belong in fog. Fog holds only uncertainty that could need the human or change scope or observable behaviour; implementation mechanics never go into fog, nor does how the change is tested or proven, which the agent decides from the repository's conventions. Fog that is mechanics after all is decided by the agent: it becomes a ticket resolved with the agent's decision, which the human can reopen, never dropped. Fog a resolution already settles is cleared by that resolution, stating the decision, with no duplicate ticket.

## Existing records

A change lands on data that already exists: rows, files and deployed state that were written before it and may not match what it expects. Whenever the destination adds, changes or constrains persisted data, find out what that data actually looks like before settling its fate. Those records exist the day the change ships; don't treat them as a deferrable edge case.

- **When the destination changes ZeNorm itself**, inspect the **application records**: this instance's own persisted records, read-only and current. Start from the tables the decision touches, look for records in states the change does not expect, and check that whatever those records point at outside the database (paths, external identifiers, other records) still resolves.
- **For any other project**, its live data (production databases, user files, deployed configuration) is outside ZeNorm's view, and the application records say nothing about it. Read what the repository reveals (schema, migrations, fixtures), and ask the human about what only they can see: how much data exists and which unusual states it holds.

**What happens to existing records when this ships?** is a standing question. Whenever the destination adds, changes or constrains persisted data, the map must hold a Grilling ticket that asks the human, citing what exists (the records you inspected, or what the human told you): backfill them, migrate them, leave them as they are, or reject them. Block it on the ticket that settles the data's shape. Ask it as its own question, not bundled with rare edge cases such as a record a user later renames or deletes: dismissing those would silently dismiss the case that happens to every record at ship. [To Spec](../to-spec/SKILL.md) cannot save a contract that changes persisted data without citing that answer.

## Ticket types

- **Research** (AFK): a primary-source fact that an actual decision depends on and that documentation, source code or the repository can answer. A fact only running something can settle (a live experiment or spike) is not a Research ticket: fold it into the decision as an assumption and a risk that delivery verifies. Use [Research](../research/SKILL.md); supply the bounded question, relevant sources and report destination to its background investigator. A report with an unresolved factual gap does not answer the question.
- **Prototype** (HITL): a cheap concrete artifact to settle a named uncertainty about appearance or behavior. Use [Prototype](../prototype/SKILL.md). Preserve the artifact, exercised scenarios and actual scoped human verdict; automatic preparation supplies no verdict.
- **Grilling** (HITL): the decision conversation, for a decision that passes the salience gate (see Chart the map). Use [Grilling](../grilling/SKILL.md) and [Domain Modeling](../domain-modeling/SKILL.md) when terminology needs sharpening. The human speaks for themselves; pending answers remain pending.
- **Task** (HITL or AFK): mechanical work required before a decision, such as provisioning access. It earns its place by unblocking that decision, not by delivering the destination. Record actual work and resulting facts, or the precise human action still needed. Ask the human only for what only they have (access, credentials, accounts, facts about their environment or data the plan depends on, a preference), never their instance configuration values (binary paths, sign-in method, chosen model or effort), which they supply at setup; never hand them engineering work such as an experiment to run. A fact that can't be verified read-only but that delivery will verify (its tests, a live test) is recorded as an assumption and a risk for the spec, not asked.

## Chart the map

1. Establish the destination through a question round and actual answer, and short follow-ups only when an answer moves the scope (at most 3 rounds). First decide whether the idea is one map or several: when it names separate outcomes that could each be planned, specified and shipped on their own, and together are too big for one map, keep the core one in this map and offer each other part as a map of its own, with a title, an idea and the Out of scope line this map leaves to it. The human creates or dismisses each offer before answering the round; a dismissed one stays in this map. Never split one coherent piece of work. Read the idea in the project's own vocabulary and structure (its glossary, such as CONTEXT.md, and how the code groups the thing named), and recommend the reading a user of this project most plausibly means: neither wider nor narrower than the unit the project itself treats as that thing. When a word in the idea maps to a group in the project (a family of sessions, a pipeline stage, a module), the recommended option covers the whole group; narrower and wider readings are offered as alternatives, never recommended. The recommended option complies with the rules the project's instruction files state (AGENTS.md, CLAUDE.md and the like); an option that breaks one is offered only naming the rule it breaks, and is never recommended. The round's intro states the destination in the idea's terms and the project's. Before creating any Grilling tickets, check whether a map is needed at all: if there is no fog and the work fits one session (a single small function or script, for example), create no tickets, explain that a map is unnecessary and ask how the user wants to proceed. Word the no-map choice as staying in ZeNorm's flow, for example "Skip the map and go straight to the spec"; never "build it directly" or "in one session", which suggests leaving ZeNorm. Choosing it does not skip the questions [To Spec](../to-spec/SKILL.md) will need answered (see Before clearing). A map without tickets is charted by its Notes: on this path, once those questions are answered, save Notes recording the agreement to skip the map and the submitted answers the specification rests on. Otherwise explore the decision frontier breadth-first.
2. Chart no ticket, and ask no question, whose answer the confirmed destination or the destination rounds' answers already state: check each ticket against them. Check proportionality before adding work. Group closely related choices into one bounded Grilling ticket. Create Research only for a named unknown fact that could change a decision, and Prototype only for an interaction uncertainty that discussion cannot settle. Ordinary implementation choices and verification checks belong after planning. A possible future feature is not automatically fog.
3. Distinguish a requirement from an assumption. Ask about an assumption only if it changes scope or creates a prerequisite; otherwise leave implementation flexibility in the answer. Terms such as local, browser-based or simple do not by themselves select a deployment mechanism or storage API.

   **The salience gate.** A Grilling ticket, and any question to the human, exists only when its answer changes scope, behaviour the human can observe, cost, or risk and irreversibility (a rewrite, a major migration, data loss, a breaking change to configuration or stored data). Implementation mechanics are the agent's to decide from the repository and research, never the human's: where a configuration key lives, internal API and record shapes, error-code mapping, parser details, command-line flags, test seams. Decide them and record each as an assumption the human can reopen. Most maps need a handful of Grilling tickets at most. A decision that removes or weakens an existing safety guarantee, permission boundary or enforced guardrail, or accepts a new security risk, always passes the gate: ask, stating what is lost; never decide it alone. Nor does the agent decide alone anything that refuses or blocks the capability the destination asks for: that always passes the gate. Values that belong to one person's machine or instance configuration (a binary's path, an account or sign-in method, the model or effort values they choose) are configuration the person supplies at setup, not planning decisions: never ask for them while planning, and never write them into the repository's artifacts; refer to them as configuration keys, with placeholders in any example. The same holds for the machine's setup state (whether a tool is installed, whether the person is signed in, local accounts): never ask about it while planning; the plan assumes the person sets it up, and the spec states the startup check and coded error when it is missing. A decision that adds required setup, configuration or steps for users who don't use the new capability is a cost to everyone and passes the gate: choose the option that adds no burden to them when the project's rules allow it, otherwise ask.

   **Project rules.** Before deciding anything, read the project's agent instruction and convention files if present (AGENTS.md, CLAUDE.md, CONTEXT.md and the files they reference). Everything decided alone conforms to the rules they state (a rule against silent defaults rules out an implicit default); when the destination truly requires breaking one, ask, naming the rule.
4. Give each ticket a scope that doesn't overlap its neighbours. Assign an event or case that touches several tickets (a deleted account, for example) to one of them, and name that boundary in the others. Every unblocked Grilling ticket is asked at the same time, side by side. Overlapping scopes therefore reach the user as the same question asked twice, sometimes with different framings.
5. Block a ticket on every ticket whose answer would change its options, including the Research that settles whether its options are feasible. Asking too early costs the user an answer they may have to give again. Typical dependencies:
   - How the behaviour is verified depends on the behaviour.
   - How something is presented depends on what it does.
   - Edge-case handling depends on the rule that creates the edge case.

   Blocking costs only latency: the dependent ticket is asked once its blockers resolve.
6. Save Destination/Notes and only the visible fog. Create precise tickets with their blockers: obtain prerequisite identities before publishing dependents, because eligible work starts automatically. In local Markdown, create and link files before claiming work.
7. Leave eligible Research and Prototype preparation to their assigned workers. In the local tracker, claim and delegate independent Research with its question, sources and report destination. Stop after charting; this assignment resolves no child tickets.

## Before clearing

A map clears only when [To Spec](../to-spec/SKILL.md) can draft without new human input. This applies to every path, including the no-map path where the user chooses to build directly. Before clearing, ask, through an actual question round, every decision the specification will need a submitted human answer for. When the destination adds, changes or constrains persisted data, include what happens to existing records when it ships (see Existing records). Include the observable guarantees the tests will verify only when they pass the salience gate (they change what the human gets or the risk they accept) and no retained testing agreement or recorded delegation covers them. When the repository has a clear testing convention, decide the proof from it yourself; To Spec carries it as plain-language criteria. How the change is tested or proven follows the repository's conventions and is never asked, in the destination round or as an either/or between test methods. The testing seam and environment are yours to propose, not the human's to choose: ask in plain language what must hold, such as "Should an invoice without a customer be impossible, or just flagged?", never "at which seam?". Ask each of these as soon as the behaviour it depends on is settled. Combine it with other pending questions when possible, but don't ask it before its blockers resolve: a guarantee settled before the behaviour is known misses the cases that behaviour creates. Don't ask what a submitted answer already settles. Pending answers keep the map uncleared.

## Consistency pass

Tickets are resolved one at a time, so two resolutions can each be sound and still contradict each other. Once every ticket is resolved or excluded and no fog remains, a map with two or more resolved tickets clears only after a **consistency pass** has compared exactly those resolutions. ZeNorm runs the pass as its own fresh assignment, never as the resolving agent's self-check. Any change to a resolved ticket afterwards needs a new pass.

The pass reads every resolved ticket's full resolution and compares each with every other. It reports only conflicts the human would care about, ones that change scope, observable behaviour, cost or risk, of three kinds:

- **Conflicting surfaces**: two resolutions that cannot both hold, such as one that shows export history on the settings page and another that removes the settings page from scope.
- **Terms used but never defined**: a resolution relies on a term, record or surface that no resolution defines, such as an "archived" state that no resolution introduces.
- **A decision that assumes a deferred case**: one resolution depends on a case that another ticket deferred, excluded or left to later work.

Bookkeeping is never a finding: a reference to a ticket that doesn't exist or names the wrong one, different wording for one thing, a missing Out of scope line, a term whose meaning is plain from context, or a difference in implementation mechanics the spec and tickets can settle. When in doubt, report nothing. Report a finding only when settling it needs the human: a resolution it involves was answered or directed by the human, it conflicts with the destination, or settling it changes scope, observable behaviour, cost or risk. A conflict between resolutions the agent decided alone, over details the human wouldn't notice, is not a finding: the spec reconciles it. At most three findings per pass.

Quote the wording each finding rests on and name every ticket involved. A later resolution that explicitly reconciles two earlier ones settles their conflict, as does a resolved ticket an earlier pass opened. The pass decides nothing itself: it doesn't recommend a fix, redesign the destination or re-ask what a resolution already answers.

Record the pass once, listing every resolved ticket it compared. Each finding becomes a new Grilling ticket that cites the resolutions it compares, so the map stays uncleared until it's resolved. Its run asks the human only when the answer passes the salience gate; otherwise it settles the finding itself and says so in the resolution. Resolving those tickets changes the resolutions, and a new pass compares them again. A pass with no findings is recorded, and the map clears. In the local tracker, write the pass as a note on the map listing the tickets compared, and chart each finding as a Grilling ticket.

## Work through the map

1. Read the low-resolution map. Use the supplied eligible ticket/claim, or claim the first frontier ticket. A user may name an eligible ticket.
2. Work only that question using its type's skill. Zoom into full related resolutions and exact sources as needed, reusing supplied records. Independent Research may continue concurrently; only its dependents wait.
3. Submit the answer with evidence and applicable actual human-response references. Verify the saved resolution and map index update. In local Markdown, append the answer, mark the ticket resolved and add its named link to Decisions so far.
4. Chart newly precise questions that pass the salience gate (ordinary implementation choices are not tickets: decide them in your own work), clear graduated fog and refresh the frontier. If a ticket falls outside the destination, exclude it and link the reason from Out of scope, not Decisions so far. Preserve earlier answers when revisiting dependent decisions.

When no in-scope decisions or fog remain and the consistency pass has recorded no open findings, the map is cleared. For an implementation destination, hand off through [Scope Specs](../scope-specs/SKILL.md), [To Spec](../to-spec/SKILL.md) and [To Tickets](../to-tickets/SKILL.md). A selected prototype first reaches its [High-fidelity demo](../high-fidelity-demo/SKILL.md) checkpoint. The application dispatches these as separate assignments.