Windsurf rules

1---
2name: find-way
3model: sonnet
4description: "Plan a large effort as a shared map of decision tickets on an issue tracker, resolving them one at a time until the way is clear. Use when an idea is too big for one session, needs structured exploration before implementation, or requires mapping decisions before building."
5---
6 
7# Find Way
8 
9## Concept
10 
11A large effort arrives — too big for one session, wrapped in fog. **Find-way** charts the way as a **shared map** on the repo's issue tracker, then works **decision tickets** — questions whose resolution is a decision, not build slices — one at a time until the route is clear.
12 
13**Plan, don't do.** Each ticket resolves a decision. The map is done when the way is clear — nothing left to decide before someone executes.
14 
15**Refer by name.** Every map and ticket is an issue with a title. Always use the name, never bare ids or numbers.
16 
17## The Map
18 
19A single issue labelled `wayfinder:map` — the canonical artifact. Child issues are its tickets.
20 
21```markdown
22## Destination
23<what reaching the end looks like — one or two lines>
24 
25## Notes
26<domain, skills to consult, standing preferences>
27 
28## Decisions so far
29- [closed ticket title](link) — one-line gist
30 
31## Not yet specified
32<in-scope fog you can't ticket yet>
33 
34## Out of scope
35<work ruled beyond the destination>
36```
37 
38## Ticket Types
39 
40| Type | Label | Mode | Purpose |
41|------|-------|------|---------|
42| Research | `wayfinder:research` | AFK | Surface facts from docs/APIs |
43| Prototype | `wayfinder:prototype` | HITL | Cheap artifact to react to |
44| Grilling | `wayfinder:grilling` | HITL | One-question-at-a-time dialogue |
45| Task | `wayfinder:task` | Either | Manual work unblocking a decision |
46 
47**HITL** = human in the loop. **AFK** = agent alone.
48 
49## Two Modes
50 
51### Chart the Map
52 
53User invokes with a loose idea.
54 
551. **Name the destination** — grill to pin down what this map finds its way to
562. **Map the frontier** — breadth-first: surface open decisions and first steps. If no fog emerges, the effort fits one session — skip the map
573. **Create the map** issue (label `wayfinder:map`)
584. **Create tickets** as child issues, then wire blocking edges in a second pass
595. **Fire research subagents** for each `research` ticket in parallel
606. Stop — charting resolves nothing
61 
62### Work Through the Map
63 
64User invokes with a map (URL/number). Ticket optional — without one, pick the next frontier ticket.
65 
661. Load the map (low-res view)
672. **Choose & claim** — assign ticket before any work
683. **Resolve** — zoom into related/closed tickets as needed
694. **Record** — post resolution comment, close issue, append to Decisions-so-far
705. **Graduate fog** — create new tickets from newly-specifiable fog, clear from Not-yet-specified
716. **Rule out of scope** if resolution reveals something past the destination
72 
73**Never resolve more than one ticket per session** (except research).
74 
75## Fog of War
76 
77Beyond live tickets lies the **fog** — decisions you can tell are coming but can't pin down yet. The **Not yet specified** section holds this dim view.
78 
79**Fog or ticket?** Test: can you state the question precisely now?
80 
81- **Ticket** when the question is sharp (even if blocked)
82- **Not yet specified** when you can't phrase it sharply yet
83 
84## Out of Scope
85 
86Work beyond the destination. Ruling something out is a scoping act, not a route step. Never graduates — returns only if destination is redrawn.
87 
88If an existing ticket sits past the destination, close it and note in Out of scope.
89 
90## Blocking & Frontier
91 
92- **Blocking**: tracker's native dependency relationship
93- **Unblocked**: every blocker is closed
94- **Frontier**: open, unblocked, unclaimed children — the edge of the known
95 
96## Detailed Reference
97 
98See [REFERENCE.md](REFERENCE.md) for ticket anatomy, resolution protocol, and examples.
99 
100---
101 
102# Find-Way Reference
103 
104## Ticket Anatomy
105 
106Each ticket holds one question, sized to one 100K token agent session:
107 
108```markdown
109## Question
110 
111<the decision or investigation this ticket resolves>
112```
113 
114**Labels:** `wayfinder:research`, `wayfinder:prototype`, `wayfinder:grilling`, or `wayfinder:task`
115 
116**Claim:** Assign to yourself before any work — claim blocks concurrent sessions.
117 
118**Blocking:** Use tracker's native dependency relationship so the frontier renders visually.
119 
120**Resolution:** Post answer as a comment, close the issue, append to map's Decisions-so-far.
121 
122## Resolution Protocol
123 
1241. **Load the map** — read low-res view, not every ticket body
1252. **Choose & claim** — assign ticket to yourself (or take first frontier ticket if not named)
1263. **Resolve** — zoom into related/closed tickets as needed; invoke skills the Notes block names
1274. **Record** — post resolution comment with the answer, close the issue
1285. **Update map** — append to Decisions-so-far with one-line gist + link
1296. **Graduate fog** — create new tickets from newly-specifiable fog; clear from Not-yet-specified
1307. **Rule out of scope** if resolution reveals something past the destination
131 
132## Ticket Types in Detail
133 
134### Research (AFK)
135Surfacing facts from docs, APIs, or knowledge bases that a decision waits on.
136- Resolved by a `/research` subagent
137- Use when knowledge outside the working directory is required
138- **Label:** `wayfinder:research`
139 
140### Prototype (HITL)
141Raise fidelity by building cheap, rough, concrete artifact to react to — outline, stub, UI/logic code.
142- Use the `/prototype` skill
143- Links the prototype as an asset
144- Use when "how should it look" or "how should it behave" is key
145- **Label:** `wayfinder:prototype`
146 
147### Grilling (HITL)
148Conversation via `/grilling` and `/domain-modeling` skills, one question at a time.
149- The default case for clarifying decisions
150- **Label:** `wayfinder:grilling`
151 
152### Task (HITL or AFK)
153Manual work unblocking a decision — signing up for service, provisioning access, moving data.
154- This is the **only** type that does rather than decides
155- Earns its place by unblocking a decision, not by delivering the destination
156- Agent drives AFK tasks alone; HITL tasks get precise checklist
157- **Label:** `wayfinder:task`
158 
159## Fog-to-Ticket Graduation
160 
161When resolving a ticket clears fog, graduate the newly-specifiable bits into fresh tickets:
162 
1631. **Identify the fog** in Not-yet-specified that the resolution illuminates
1642. **Create new tickets** with crisp question statements
1653. **Wire blocking edges** if the new tickets depend on each other or existing ones
1664. **Clear from fog** — remove the graduated patch from Not-yet-specified so it lives only as its ticket
167 
168## Out-of-Scope Close Protocol
169 
170If a ticket turns out to sit past the destination:
171 
1721. **Close the ticket** — mark it resolved or won't-fix
1732. **Add one line to Out of scope** — gist + why it's out of scope, linking the closed ticket
1743. **Never append to Decisions so far** — scope boundaries aren't steps on the route
175 
176## Map State Transitions
177 
178| State | Meaning | Action |
179|-------|---------|--------|
180| **Open, unblocked, unclaimed** | Frontier — ready to take | Claim and resolve |
181| **Open, blocked** | Waiting on something | Wait for blockers to close |
182| **Open, claimed** | Concurrent session working | Skip for now |
183| **Closed** | Decided — lives in Decisions so far | Reference, don't re-open |
184 
185## Concurrency
186 
187Users may run unblocked tickets in parallel, so expect the tracker to be edited concurrently. Always:
188 
189- Refresh the map before picking a ticket
190- Claim immediately before starting work
191- Never assume state hasn't changed since last read
192