wayfinder and triage: plan huge projects and sort incoming issues with an agent

The main flow of Matt Pocock's skills starts from an idea that fits in one session: you sharpen it with grill-with-docs, turn it into a spec and tickets, and build it. But work doesn't always arrive that way. Sometimes it's a project so big and fuzzy you don't know where to start. Other times it comes from outside: bugs and requests piling up on GitHub. wayfinder and triage are the two on-ramps for those cases, and they share something: both work on your issue tracker.

This is part ten of the Matt Pocock skills guide (mattpocock/skills repository, MIT license). Both are user-invoked and need /setup-matt-pocock-skills to have run first.

wayfinder: finding the way through the fog

ask-matt calls it "the most cognitively demanding flow" in the repository. It's for a greenfield project or a huge feature that doesn't fit in one session and is wrapped in fog: you can't see the way from here to the destination.

Plan, don't do

The first rule: wayfinder produces decisions, not deliverables. Each ticket resolves a question, and the map is done when the way is clear and nothing is left to decide. The urge to "just start coding" is the signal you've reached the edge of the map and it's time to hand off.

The map

The map is a single issue labelled wayfinder:map. It's an index, not a store:

## Destination
<what arriving means: the spec, decision or change you're after>

## Notes
<domain, skills every session should consult, preferences>

## Decisions so far
- [Closed ticket title](link): one-line gist

## Not yet specified
<the fog: questions you can sense but can't phrase yet>

## Out of scope
<what was consciously ruled out, and why>

Open tickets aren't listed in the map: they're child issues, and the frontier (open, unblocked, unclaimed tickets) shows up in the tracker itself thanks to native blocking relationships.

Four ticket types

Each ticket is a question sized to a session of about 100,000 tokens, with a type label:

One hard rule: on a human-in-the-loop ticket, the agent never answers for you. An agent that answers its own questions has broken the session.

The fog of war

The map is deliberately incomplete. The test for ticket vs fog isn't whether you can answer it, but whether you can state the question precisely now. If yes, it's a ticket (even if blocked). If not, it goes under "Not yet specified" and graduates into tickets once the frontier reaches it.

The two modes

• Chart the map: grilling to fix the destination, a breadth-first grilling to find the frontier, create the map and tickets, wire the blocking edges in a second pass (issues need ids before they can reference each other), and fire the research tickets in parallel. If no fog appears, the work doesn't need a map and the skill tells you so.
• Work through the map: load the map, take the first frontier ticket, claim it by assigning it before anything else, resolve it by its type, post the answer, close it, add a line to "Decisions so far", and turn any fog that can now be phrased into new tickets.

Never more than one ticket per session, except research tickets.

When the map clears

wayfinder hands off, it doesn't build. Once the way is clear, the work joins the main flow at to-spec, which collapses the linked decisions into a buildable plan. Jumping straight to implement throws all that detail away.

triage: a state machine for what comes in

triage moves issues (and, if you enable it, external PRs) through a small state machine. It's only for work you didn't create: tickets from to-tickets are already agent-ready and don't get triaged.

Roles

Two category roles (bug and enhancement) and five state roles:

Every triaged issue carries exactly one category and one state. The real label strings are configured in /setup-matt-pocock-skills.

How it works

You talk to it in plain language: "show me what needs my attention", "let's look at #42", "move #42 to ready-for-agent". For a specific issue:

1. Gather context: body, comments, labels, earlier triage notes. Two checks against the code: whether it's already implemented (searching by concept, not the issue's wording) and whether it was rejected before (reading .out-of-scope/).
2. Recommend a category and state with its reasoning, and wait.
3. Verify: reproduce the bug from the report's steps, or check that a PR's diff does what it claims.
4. Grill if needed, with grilling and domain-modeling.
5. Apply the outcome: an agent brief when moving to ready-for-agent, triage notes with specific questions for needs-info, or a close with an explanation for wontfix.

Every comment it posts starts with "*This was generated by AI during triage.*".

The agent brief and the rejection memory

The brief is the contract an unattended agent will follow, maybe weeks later. So it describes behaviour and interfaces, not file paths or line numbers, which go stale, and it includes verifiable acceptance criteria and what's out of scope.

Rejected requests are kept in .out-of-scope/, one file per concept (not per issue), written like a short design doc. When a similar request arrives, triage surfaces the earlier rejection instead of re-litigating it.

How they combine

Both feed the same flow from opposite sides:

• wayfinder creates work from inside, when the problem is so big you have to discover what to decide. It ends at to-spec.
• triage filters work from outside, when the problem is separating noise from what's worth doing. It ends at ready-for-agent, which implement picks up.

And they share the base: the issue tracker as shared state, the grilling interview when clarity is missing, and the glossary to name things consistently.

Common mistakes

• Using wayfinder for a well-scoped feature. It's slower and denser; that's what grill-with-docs is for.
• Resolving several map tickets in one session. Decisions lose context.
• Triaging tickets from to-tickets. They're already ready-for-agent.
• Briefs with file paths. They go stale before the agent reaches the issue.

FAQ

Do they work without GitHub? Yes. With the local tracker, the map is .scratch/<effort>/map.md and each ticket a file with Type:, Status: and Blocked by: lines.

Can several sessions work a map at once? Yes: a ticket is claimed by assigning it before starting, and the skill expects other sessions to edit the tracker concurrently.

Does triage cover PRs? Only if you enable the "PRs as a request surface" flag in docs/agents/issue-tracker.md. It's off by default.

Next step

If there's a project you've put off for months because you don't know where to begin, run /wayfinder just to fix the destination. In part 11 of the guide we look at handoff and to-questionnaire, two skills for passing context to another agent or another person.