feat(planning): add /wayfind decision-map planning skill by kyle-sexton · Pull Request #150 · melodic-software/claude-code-plugins

kyle-sexton · 2026-07-13T06:47:57Z

Adds /planning:wayfind — charts a too-big-AND-foggy effort as a shared decision map on the work-item tracker, then works its frontier one decision at a time, routing each resolved decision to the right skill until the map graduates to a Brief/PRD/PLAN. Upstream of the whole planning pipeline.

What's here

plugins/planning/skills/wayfind/SKILL.md + context/tracker-mechanics.md + context/map-anatomy.md — chart + work modes, fog test, type-routing table, map anatomy, graduation/closure.
Escalation pull-back lines in /planning:interview, /planning:architect, /implementation:implement (guide the user to /wayfind when a task is too-big-AND-foggy, never auto-switch). Wording reviewed with the maintainer.
Registration: planning 0.5.0→0.6.0, implementation 0.3.0→0.3.1, marketplace tags.

Design notes

Plain gh idiom, matching the shipped /work-items sibling — one claim model across both tracker skills (status:claimed + @me assignee + comment-ID collision check). The Pocock-v11 seam (tools/work-item-tracker/) is not consumed by the published plugins, so its verb/lease mechanics are superseded; skill substance (fog test, modes, routing, escalation, map anatomy) is idiom-independent.
Native gh ≥2.94 primitives: sub-issues (--parent), dependency edges (--add-blocked-by). Frontier = open ∧ zero OPEN blockers ∧ unassigned.

Verification

Full lifecycle run live against melodic-software/tracker-sandbox: chart → typed items + edge → frontier → claim → resolve → re-frontier → close map. The live run caught and fixed two real bugs in the mechanics doc (blockedBy/subIssues are {nodes,totalCount} objects not arrays; a closed blocker stays in totalCount so frontier must count only OPEN blockers). scripts/validate-plugins.sh + scripts/run-plugin-tests.sh both green.

Refs melodic-software/medley#1338

Note

Low Risk
Changes are plugin skill markdown and manifest metadata only; no application runtime or auth paths. Residual risk is operational (gh issue/label writes in consumer repos) when users run the skill.

Overview
Introduces /planning:wayfind upstream of the planning pipeline: for efforts that are too big and still too foggy to ticket, it charts a decision map on GitHub Issues (work-map parent + typed wayfind:* sub-issues), applies a fog test (sharp question → item; unphrasable uncertainty → prose), and runs chart (interactive only) or work (frontier claim → route → graduate).

New skill docs cover map anatomy (five body sections, invariants, closure handoff to Brief/PRD/PLAN) and tracker mechanics (label bootstrap, sub-issues, blocked-by, frontier jq counting OPEN blockers only, claim protocol aligned with /work-items).

Escalation pull-backs (recommend only, never auto-switch) are added to /planning:interview, /planning:architect, and /implementation:implement when work is too-big-and-foggy for that stage.

Registration: planning 0.6.0, implementation 0.3.1, README/marketplace keywords (wayfind, decision-map).

^{Reviewed by Cursor Bugbot for commit 1e8e2d6. Bugbot is set up for automated code reviews on this repo. Configure here.}

@me

Charts a too-big-AND-foggy effort as a shared decision map on the work-item tracker, then works its frontier one decision at a time — routing each resolved decision to the right skill (research/interview/design/prototype/task) until the map graduates to a Brief/PRD/PLAN. Upstream of the whole planning pipeline. - SKILL.md (chart + work modes, fog test, type-routing, escalation) + context files (tracker-mechanics gh commands, map anatomy) in the planning plugin - plain gh idiom matching the shipped /work-items sibling (one claim model: status:claimed + @me assignee + comment-ID locking); native sub-issue/ blocked-by primitives, frontier = open and zero OPEN blockers and unassigned - escalation pull-back lines in /planning:interview, /planning:architect, /implementation:implement (guide the user to /wayfind, never auto-switch) - registration: planning 0.5.0 to 0.6.0, implementation 0.3.0 to 0.3.1, marketplace tags Full lifecycle verified live against tracker-sandbox. Co-Authored-By: Claude <noreply@anthropic.com>

cursor · 2026-07-13T06:48:06Z

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_b22ff205-adea-4d62-9e56-a184453cafbf)

cursor

Stale comment

Risk: low. Not approving: Cursor Bugbot completed as skipped (usage limit reached), so the automated review signal is incomplete. Human review is needed before merge; no reviewers were assigned because the PR author is the sole human repository contributor.

_{Sent by Cursor Approval Agent: Pull Request Router and Approver}

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: cc24a1cc64

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@me

Address two bot-review findings on /wayfind tracker-mechanics: - create-if-missing the wayfind taxonomy (work-map, wayfind:*, needs-human) at chart-mode entry — a fresh consumer repo lacks these plugin-specific labels, so an unknown --label would fail the first map create - claim collision check uses claim-comment ORDER (earliest wins), not assignee comparison — two same-identity sessions both assign @me and resolve to one login, so the comment timeline is the only reliable discriminator (matches the /work-items sibling's optimistic-locking-via-comment mechanism)

cursor · 2026-07-13T06:57:01Z

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_b6653fff-a639-4772-bf65-b9f65062de73)

cursor

Risk: low. Not approving: Cursor Bugbot completed as skipped (usage limit reached), so the automated review signal is incomplete. Human review is needed before merge; no reviewers were assigned because the sole human repository contributor is the PR author.

_{Sent by Cursor Approval Agent: Pull Request Router and Approver}

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1e8e2d6fee

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-07-13T07:02:23Z

+
+# 3. Collision check via claim-comment ORDER (not assignees). The EARLIEST claim comment wins.
+gh issue view <item#> --json comments \
+  --jq '[.comments[] | select(.body | startswith("🔒 claim:"))] | sort_by(.createdAt) | .[0].body' | tr -d '\r'


Ignore stale claim comments when arbitrating claims

When a session crashes or releases its own stale hold, the reclaim step below only clears the label/assignee and records a release comment; it does not remove or invalidate the previous 🔒 claim: comment. Since this jq always selects the oldest claim comment ever posted, a later session with a fresh marker will compare against the stale marker and back off even though the item is back on the unassigned frontier, leaving reclaimed items permanently unclaimable. Please either delete/mark obsolete claim comments during reclaim/release or filter this check to the current active lease.

Useful? React with 👍 / 👎.

cursor Bot reviewed Jul 13, 2026

View reviewed changes

chatgpt-codex-connector Bot reviewed Jul 13, 2026

View reviewed changes

Comment thread plugins/planning/skills/wayfind/context/tracker-mechanics.md

Comment thread plugins/planning/skills/wayfind/context/tracker-mechanics.md

cursor Bot reviewed Jul 13, 2026

View reviewed changes

kyle-sexton merged commit 792a6fd into main Jul 13, 2026
20 of 22 checks passed

kyle-sexton deleted the feat/wayfind-decision-map-skill branch July 13, 2026 06:59

chatgpt-codex-connector Bot reviewed Jul 13, 2026

View reviewed changes

claude Bot mentioned this pull request Jul 17, 2026

fix(planning): align wayfind label taxonomy with colon-space axis grammar #235

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(planning): add /wayfind decision-map planning skill - #150

feat(planning): add /wayfind decision-map planning skill#150
kyle-sexton merged 2 commits into
mainfrom
feat/wayfind-decision-map-skill

kyle-sexton commented Jul 13, 2026 •

edited by cursor Bot

Loading

Uh oh!

cursor Bot commented Jul 13, 2026

Uh oh!

cursor Bot left a comment •

edited

Loading

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

Uh oh!

Uh oh!

cursor Bot commented Jul 13, 2026

Uh oh!

cursor Bot left a comment

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Jul 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

kyle-sexton commented Jul 13, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What's here

Design notes

Verification

Uh oh!

cursor Bot commented Jul 13, 2026

Bugbot couldn't run - usage limit reached

Uh oh!

cursor Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

cursor Bot commented Jul 13, 2026

Bugbot couldn't run - usage limit reached

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Jul 13, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

kyle-sexton commented Jul 13, 2026 •

edited by cursor Bot

Loading

cursor Bot left a comment •

edited

Loading