Wayfinder

Wayfinder — tìm đường, không lao vào đích

Một ý tưởng lớn vừa tới — quá lớn cho một phiên agent, và bọc trong sương: đường từ đây tới đích chưa hiện. Wayfinding là tìm cái đường đó, không phải lao thẳng vào đích. Skill này vẽ đường thành một bản đồ trên ledger issue, rồi làm các ticket quyết định của nó — mỗi ticket là một câu hỏi mà lời giải là một quyết định, không phải một lát cắt build — từng cái một, cho tới khi đường tới đích rõ và không còn gì để quyết.

Đây là bậc trước /propose: propose giả định đã biết hình dạng công việc; wayfinder dành cho lúc chưa biết.

Plan, don't do

Wayfinder mặc định là lập kế hoạch: mỗi ticket giải một quyết định, và bản đồ xong khi đường đã rõ — không còn gì phải quyết trước khi ai đó đi làm. Cái kéo bạn nhảy vào làm thường là tín hiệu đã tới mép bản đồ và tới lúc bàn giao sang /propose. Sinh quyết định, không sinh deliverable.

Gọi tên bằng TÊN, không bằng id

Mỗi bản đồ và ticket là một issue, nên có một tên — tiêu đề của nó. Trong mọi thứ người đọc (tường thuật, Decisions-so-far), gọi bằng tên đó, không bao giờ bằng id trần. Một bức tường #42, #43, #44 không đọc nổi; tên đọc được ngay. Id và link không biến mất — tên bọc lấy link — nhưng chúng đi bên trong tên, không thay tên.

Bản đồ

Bản đồ là một issue trên ledger (nhãn wayfinder:map). Ticket của nó là issue con. Bản đồ là một chỉ mục, không phải một kho: nó liệt kê các quyết định đã làm và trỏ tới ticket giữ chi tiết — một quyết định sống ở đúng một chỗ (ticket của nó), bản đồ không kể lại, chỉ gist và link. Cách bản đồ, ticket con, cạnh chặn, và frontier query sống ở đâu là tuỳ tracker — đọc [[issue-tracker]] § "Wayfinding operations".

Thân bản đồ (nạp một lần mỗi phiên):

## Destination
<đi tới cuối bản đồ này trông như thế nào — spec, quyết định, hay thay đổi mà nỗ lực này tìm đường tới. Một hai dòng; mỗi phiên định hướng vào nó trước khi chọn ticket.>

## Decisions so far
<!-- chỉ mục — một dòng mỗi ticket đã đóng: đủ để phán đoán liên quan, rồi zoom link lấy chi tiết -->
- [<tên ticket đã đóng>](link) — <gist một dòng của lời giải>

## Not yet specified
<!-- fog of war: sương trong-phạm-vi chưa ticket được; tốt nghiệp khi frontier tiến tới -->

## Out of scope
<!-- việc bị loại khỏi ĐÍCH này; đóng, không bao giờ tốt nghiệp -->

Ticket là issue con, thân là câu hỏi, cỡ vừa một phiên:

## Question
<quyết định hay điều tra mà ticket này giải>

Bốn kiểu ticket

Mỗi ticket là HITL (có người sống trả lời) hoặc AFK (agent chạy một mình). Một ticket HITL chỉ giải qua trao đổi sống; agent không bao giờ đứng thay phía người — một agent grilling mà tự trả lời câu hỏi của chính mình là đã phá vỡ điều này.

• research (AFK) — đọc tài liệu/API/kho tri thức để lôi ra một fact mà một quyết định đang chờ. Giải bằng một subagent /research (hoặc /agent-reach). Dùng khi cần tri thức ngoài thư mục hiện tại.
• prototype (HITL) — nâng độ phân giải cuộc bàn bằng một bản thô cụ thể để phản ứng: một outline, một bản nháp, một stub, hoặc UI/logic. Dùng khi "trông thế nào" / "hành xử ra sao" là câu hỏi chính.
• grilling (HITL) — hội thoại từng câu một. Trường hợp mặc định.
• task (HITL hoặc AFK) — việc TAY phải xong trước khi một quyết định làm được: đăng ký một dịch vụ để xét API, cấp quyền, dời dữ liệu để thấy hình dạng. Kiểu duy nhất làm thay vì quyết — và nó đáng chỗ vì mở khoá một quyết định, không phải vì giao deliverable.

Fog of war

Bản đồ cố ý chưa đầy đủ: đừng vẽ cái chưa thấy. Ngoài các ticket sống là sương — cái nhìn mờ về những quyết định biết là sẽ tới nhưng chưa ghim được, vì chúng treo trên các câu hỏi còn mở. Giải một ticket dọn sương phía trước nó, cho tốt nghiệp bất cứ gì giờ đã ghim được thành ticket mới — từng cái một, tới khi đường tới đích rõ.

Sương hay ticket? Test là đặt được câu hỏi cho chính xác BÂY GIỜ chưa — không phải trả lời được chưa.

• Ticket khi câu hỏi đã sắc — kể cả khi nó bị chặn và bạn chưa làm được.
• Not yet specified khi bạn chưa phát biểu sắc được. Đừng cắt sẵn sương thành các mảnh cỡ-ticket: nó thô hơn một ticket, một mảng có thể tốt nghiệp thành vài ticket, hoặc không cái nào, khi frontier chạm tới.

Out of scope

Sương chỉ gom về phía đích. Đích cố định phạm vi, nên việc vượt nó là out of scope — không phải sương, không thuộc Not-yet-specified. Nó có mục riêng: việc bạn ý thức loại khỏi nỗ lực này. Out-of-scope không bao giờ tốt nghiệp. Một ticket đã tồn tại mà hoá ra nằm sau đích → đóng nó và để lại một dòng ở Out-of-scope, không giải nó trên đường.

Invocation

Hai chế độ. Cả hai: không bao giờ giải quá một ticket mỗi phiên — trừ research.

Chart the map (dựng bản đồ)

User gọi với một ý tưởng loose.

1. Đặt tên đích. Chạy /grilling + /domain-modeling (nếu có) ghim đích này tìm đường tới cái gì. Đích cố định phạm vi nên chốt trước. → Xong khi: một câu Destination mà mọi phiên sau định hướng được vào.
2. Vẽ frontier. Grill lại, theo bề rộng: fan ra khắp không gian thay vì sâu một luồng, lôi ra các quyết định mở và bước đầu làm được ngay. Không lôi ra sương nào → đường đã rõ, không cần bản đồ; dừng, hỏi user muốn đi tiếp thế nào.
3. Tạo bản đồ (nhãn wayfinder:map): Destination + Notes điền, Decisions-so-far rỗng, sương phác vào Not-yet-specified.
4. Tạo các ticket ghim được thành issue con — rồi nối cạnh chặn ở lượt hai (issue cần id trước khi trỏ nhau). → Xong khi: mọi ticket ghim-được đã có, phần chưa ghim ở lại sương.
5. Bắn subagent research. Mỗi ticket research → một subagent giải song song, ghi phát hiện, gắn con trỏ ngữ cảnh từ ticket.
6. Dừng — dựng bản đồ là việc của một phiên; nó không tự-giải ticket nào.

Work through the map (làm qua bản đồ)

User gọi với một bản đồ. Ticket là tuỳ chọn — không có thì bạn chọn quyết định kế, không phải user.

1. Nạp bản đồ (view thấp-phân-giải, không phải mọi thân ticket).
2. Chọn ticket. User nêu thì dùng. Không thì lấy ticket frontier đầu tiên (frontier.py --map <id>). Claim nó — ghi ô claim, trước mọi việc.
3. Giải — zoom khi cần: lấy thân đầy đủ của ticket liên quan trên yêu cầu; gọi các skill Notes chỉ tên. Bí thì /grilling + /domain-modeling.
4. Ghi lời giải: post lời giải làm resolution, đóng issue (status: done), append một con trỏ vào Decisions-so-far của bản đồ.
5. Thêm ticket mới lộ ra (tạo-rồi-nối); cho tốt nghiệp sương mà lời giải vừa ghim được, dọn khỏi Not-yet-specified. Lời giải lộ ra một ticket nằm sau đích → loại out of scope. Lời giải phủ định phần khác của bản đồ → cập nhật/xoá ticket đó.

Rules

• Chỉ-gọi-tay (disable-model-invocation: true) — wayfinder là một hành động có chủ ý của user, không phải thứ model tự nhảy vào. Xem [[skill-craft]].
• Plan, don't do — sinh quyết định, không sinh deliverable. Muốn nhảy vào làm = tới mép bản đồ = bàn giao /propose.
• Một ticket một phiên (trừ research), và claim trước khi làm (dùng frontier.py + ô claim của ledger).
• Ledger là nguồn chân lý; tracker remote là mirror. Đọc [[issue-tracker]] cho cách diễn đạt ở repo này.

Origin

• Chưng cất từ mattpocock/skills — skills/engineering/wayfinder/SKILL.md (clone scratchpad/mattpocock-skills/, 2026-07-15).
• Absorb qua /propose → 150726-mattpocock-absorb (T8), task T-260715-01. Đứng trên hạ tầng ledger T6/T7.
• Commit: (verify-before-commit điền)