Decisions → Specs

human-only. Start this only when a human asks for it by name. If you arrived here from another skill, stop and get explicit confirmation before running any step.

/wayfinder charts decisions as GitHub issues — the conversation, captured at that moment. Those issues are the record; they are not where a decision lives. This skill takes a wayfinder map and settles its resolved decisions into durable spec files in the repo, so the next step — /specs-to-tickets — has something concrete to slice.

Read GitHub for the decisions; write the repo for the specs. The two surfaces stay split on purpose (see Split surfaces). This skill is the bridge, and only the bridge — it never creates issues, never moves specs onto the tracker.

Write the repo from a worktree of its own. Other sessions share the primary checkout, and this skill edits specs all across the tree. Working in the shared checkout drops half-written specs into someone else's build, or swaps the branch out from under them. Every repo write below happens in a worktree this skill creates, on a branch of its own — see step 4. Steps 1–3 read GitHub and the tree, and are safe anywhere.

Settling a decision supersedes its ticket. The issue is a snapshot of one conversation; from there the decision lives in the spec — and only the spec moves as later decisions, review, and implementation refine it. A decision ticket read months later is therefore likely stale, so step 8 stamps each one with a superseded banner pointing at its spec. The issues stay closed as the rationale trail; the specs are what /specs-to-tickets slices into implementation tickets.

Approvals go on the tracker, not into the specs. Where the human settles something while this skill runs — a gated name, a spec's home, a decision to drop one — follow the approval-policy skill for where that gets written. The spec carries the rule it produced; who approved it, when, and what it beat belong on the decision ticket or the map. An ADR's considered-alternatives section is the one place in the tree that holds the alternative, and it holds it as a decision record, never as an account of the conversation.

Process

1. Load the map and its decisions

Resolve the map from the argument (issue URL or number). If none was given, find the open issue labelled wayfinder:map. Read its body — Destination and Decisions so far. For every decision listed, fetch its child ticket and read the answer /wayfinder recorded on close — its resolution comment.