Build Right Wayfinder
Use this opt-in companion to make a destination progressively taskable without
pretending uncertainty is an implementation plan.
Canonical Artifacts
docs/wayfinding/<slug>/map.mddocs/wayfinding/<slug>/decisions/<id>-<slug>.md
Markdown is canonical. External trackers may mirror links and status but cannot
replace the map or decision records.
Read references/workflow.md before starting or continuing a map. Use
assets/templates/map.md and assets/templates/decision.md for target-repository
artifacts.
Workflow
- Inspect repository instructions, current authority, existing wayfinding
maps, and Git state.
- State the destination and observable completion criterion. If these are not
meaningful yet, route back to
$build-right-preflight.
- Create or resume the canonical map. Keep decisions, the current unblocked
frontier, in-scope fog, and explicit out-of-scope work separate.
- Select one frontier decision and claim it in its decision record before
working. Never silently work an unclaimed decision.
- Resolve at most one non-research decision per run. Research may gather
evidence for several decisions, but must not silently resolve them.
- Record evidence, resolution, residual uncertainty, and map changes.
- When no frontier or fog remains, close the map and hand the resolved
decisions to
$build-right-feature-planning.
Boundaries
- Do not create implementation tasks, OpenSpec changes, or product code.
- Do not turn fog into fake acceptance criteria or dependency edges.
- Do not treat a prototype, unanswered questionnaire, public inference, or
external tracker state as product truth.
- Do not automatically commit, push, merge, publish, deploy, clean up, or alter
production.
- Do not automatically abort or resolve an existing Git operation.
- Ask founders only for decisions; look up repository and public facts directly.
User-Visible Status Badge
End every final response with exactly one status badge block:
✅ [DONE] Status: DONE
Decision: <resolved decision or closed map>
Next action: <next frontier or feature-planning handoff>
Needs user input: <none | one founder decision>
Blocked by: <none | evidence blocker>
Use 🟢 [GREEN] Status: ALL GREEN while a frontier remains actionable,
🟡 [YELLOW] Status: NEEDS INPUT for a founder decision,
🟠 [ORANGE] Status: NEEDS WORK for AI-owned research/prototype work,
🔵 [BLUE] Status: WAITING EXTERNAL for external evidence, and
🔴 [RED] Status: BLOCKED for invalid map state or conflicting authority.
1---2name: build-right-wayfinder3description: Maintain a durable multi-session decision map when the destination is meaningful but the implementation path cannot yet fit in one trustworthy planning session. Use only when the user explicitly invokes this skill for a foggy effort that needs research, prototypes, founder decisions, or technical decisions before feature planning.4---56# Build Right Wayfinder78Use this opt-in companion to make a destination progressively taskable without9pretending uncertainty is an implementation plan.1011## Canonical Artifacts1213- `docs/wayfinding/<slug>/map.md`14- `docs/wayfinding/<slug>/decisions/<id>-<slug>.md`1516Markdown is canonical. External trackers may mirror links and status but cannot17replace the map or decision records.1819Read `references/workflow.md` before starting or continuing a map. Use20`assets/templates/map.md` and `assets/templates/decision.md` for target-repository21artifacts.2223## Workflow24251. Inspect repository instructions, current authority, existing wayfinding26 maps, and Git state.272. State the destination and observable completion criterion. If these are not28 meaningful yet, route back to `$build-right-preflight`.293. Create or resume the canonical map. Keep decisions, the current unblocked30 frontier, in-scope fog, and explicit out-of-scope work separate.314. Select one frontier decision and claim it in its decision record before32 working. Never silently work an unclaimed decision.335. Resolve at most one non-research decision per run. Research may gather34 evidence for several decisions, but must not silently resolve them.356. Record evidence, resolution, residual uncertainty, and map changes.367. When no frontier or fog remains, close the map and hand the resolved37 decisions to `$build-right-feature-planning`.3839## Boundaries4041- Do not create implementation tasks, OpenSpec changes, or product code.42- Do not turn fog into fake acceptance criteria or dependency edges.43- Do not treat a prototype, unanswered questionnaire, public inference, or44 external tracker state as product truth.45- Do not automatically commit, push, merge, publish, deploy, clean up, or alter46 production.47- Do not automatically abort or resolve an existing Git operation.48- Ask founders only for decisions; look up repository and public facts directly.4950## User-Visible Status Badge5152End every final response with exactly one status badge block:5354```text55✅ [DONE] Status: DONE56Decision: <resolved decision or closed map>57Next action: <next frontier or feature-planning handoff>58Needs user input: <none | one founder decision>59Blocked by: <none | evidence blocker>60```6162Use `🟢 [GREEN] Status: ALL GREEN` while a frontier remains actionable,63`🟡 [YELLOW] Status: NEEDS INPUT` for a founder decision,64`🟠 [ORANGE] Status: NEEDS WORK` for AI-owned research/prototype work,65`🔵 [BLUE] Status: WAITING EXTERNAL` for external evidence, and66`🔴 [RED] Status: BLOCKED` for invalid map state or conflicting authority.
pax-k