Add pathfinder BRIEF mode, resolved-date tracking, and decide-menu-checkpoint cadence (v2.3.0)

AI Assisted

skills/plan2code-0-pathfinder/SKILL.md

@@ -10,47 +10,49 @@ Start all PATHFINDER MODE responses with '🧭 [PATHFINDER: Chart - Step X: Name
 
 ## Role
 
-Pathfinder, not architect. An idea has arrived too big or unclear to plan. Chart the way as a map of decision **questions**, then clear them ONE PER SESSION until nothing is left to decide. Hand off to `/plan2code-1-plan`.
+Pathfinder, not architect. An idea has arrived too big or unclear to plan. Chart the way as a map of decision **questions**, then clear them one at a time until nothing is left to decide. Hand off to `/plan2code-1-plan`.
 
 Read references/grilling.md
 
-> Fallback: ≤3 independent probes/turn, each with a recommendation, re-ask any skipped; structured tool first, prose only on a detail-test trip; plain English, no jargon; facts you look up, decisions are the human's.
+> Fallback: ≤3 independent probes/turn, each with a recommendation, re-ask any skipped; AskUserQuestion for every question, prose only if unavailable; plain English; facts you look up, decisions are the human's.
 
 ## Backend
 
 The map lives in ONE of two places — the human's pick at Chart Step 1, never yours:
 
 - **local** (default) — files under `specs/<idea>/pathfinder/`. Private, gitignored, solo.
-- **github** — a `pathfinder:map` issue whose questions are sub-issues, driven by `gh`. Shared, visible in the tracker UI, parallel.
+- **github** — a `pathfinder:map` issue whose questions are sub-issues, driven by `gh`. Shared, visible in the tracker, parallel.
 
-Read references/github-issues.md — REQUIRED on `github`, skip it on `local`.
+Read references/github-issues.md — REQUIRED on `github`, skip on `local`.
 
-> Fallback: map = issue labelled `pathfinder:map` titled `Map: <idea>`; questions = its sub-issues, labelled `pathfinder:<type>-<mode>`; blocking = native issue dependencies; claim = assign `@me`; resolve = `## Answer` comment, then close.
+> Fallback: map = a `pathfinder:map` issue titled `Map: <idea>`; questions = its sub-issues, labelled `pathfinder:<type>-<mode>`; blocking = native dependencies; claim = assign `@me`; resolve = `## Answer` comment, then close.
 
-Recorded as the first `## Ground rules` bullet (`**Backend:** local|github`), never re-asked, never switched. Either way the PLAN-DRAFT lands in local `specs/<idea>/` — downstream steps read files, not issues.
+Recorded as the first `## Ground rules` bullet (`**Backend:** local|github`), never re-asked or switched. Either way the PLAN-DRAFT lands in local `specs/<idea>/` — downstream steps read files, not issues.
 
 ## Project Context
 
-Load `./AGENTS.md` if it exists — its conventions govern; never re-ask what it answers. If missing, do NOT ask here; fold it into the Step 0 gate batch: *"No `AGENTS.md`. Pathfinder can chart without it. Continue, or run `plan2code-init` first?"* Record it in `## Ground rules` so no later session re-asks.
+Load `./AGENTS.md` if it exists — its conventions govern; never re-ask what it answers. If missing, fold it into the Step 0 gate batch: *"No `AGENTS.md`. Pathfinder can chart without it. Continue, or run `plan2code-init` first?"* Record it in `## Ground rules`.
 
 ## Rules
 
 - **Plan, don't do.** Every question resolves a DECISION. The pull to just build it is the edge of the map — hand off.
 - **Confirm before creating anything.** No files, no issues, until the Intent Gate (Step 0) and backend pick (Step 1) return.
-- **One question per session** (`research` excepted — parallel subagents).
+- **One question at a time** (`research` excepted — parallel); fork-menu between decisions, fresh session after ~3.
 - **Refer by name.** "[Export format](<link>)", never "02" or "#42" in prose. Bare ids belong on `Blocked by:` lines and in commands.
-- **HITL questions are never self-answered.** Ask and wait. An agent that answers its own grill has broken the skill.
+- **HITL questions are never self-answered.** Ask and wait; an agent that answers its own grill has broken the skill.
 - **Questions are ground truth; the map is a rebuildable index.** A filled `## Answer` beats any state marker; detail lives in one place.
-- **Never write implementation code** into the project. Sketches are throwaway, living only under `specs/<idea>/pathfinder/sketch-NN/`.
+- **Never write implementation code** into the project. Sketches are throwaway, living only under `pathfinder/sketch-NN/`.
 - **Reserved names — never create inside `pathfinder/`:** `overview.md`, `phase-<N>.md`, `PLAN-DRAFT-*.md`, `PLAN-CONVERSATION-*.md`.
 - **Never emit the loop's completion tokens under `specs/`** — `TASK_COMPLETE`, `PHASE_COMPLETE`, `ALL_TASKS_COMPLETE`, `IMPLEMENTATION_COMPLETE`, `SPEC_COMPLETE`, `WORK_COMPLETE`. It scans for them.
-- **No `- [ ]` checkboxes inside question files**, and no `METRICS_JSON` anywhere. Pathfinder is not a metered step.
+- **No `- [ ]` checkboxes inside question files**, and no `METRICS_JSON` anywhere.
 
 ## Auto-Discovery and Mode Selection
 
-⚠️ `specs/` is gitignored — NEVER use Glob (silently fails). Shell only: `ls specs/` (Bash) or `Get-ChildItem specs/` (PS).
+⚠️ `specs/` is gitignored — NEVER use Glob. Shell only: `ls specs/` (Bash) or `Get-ChildItem specs/` (PS).
 
-**Identify the target idea FIRST** (from the argument, or ask), then evaluate for THAT idea — first match wins. An issue URL or number as the argument means `github`; else look for a local map, then `gh issue list --label pathfinder:map` for `Map: <idea>`.
+**Brief/recap/minutes asked?** → read references/brief.md: reconcile, write plain-English `briefs/brief-<YYYYMMDD>.md` (decisions in range, still open, next step), STOP. Never resolves.
+
+**Identify the idea FIRST** (from the argument, or ask), then evaluate for THAT idea — first match wins. An issue URL or number means `github`; else look for a local map, then `gh issue list --label pathfinder:map` for `Map: <idea>`.
 
 | Condition | Route |
 |---|---|
@@ -61,13 +63,13 @@ Load `./AGENTS.md` if it exists — its conventions govern; never re-ask what it
 | Map `**Status:** Cleared` | Point at the PLAN-DRAFT and `/plan2code-1-plan`. STOP |
 | Map exists, `**Status:**` unreadable | MODE B — Step 2 rebuilds and sets it |
 
-Each idea has its own map. Never chart two in one session.
+One idea per session, each with its own map.
 
 ## Questions
 
-Read references/questions.md — the `local` format. On `github` the backend playbook's equivalence table replaces it, and there is no checklist: the frontier is a live query.
+Read references/questions.md — the `local` format. On `github` the backend playbook's equivalence table replaces it: no checklist, the frontier is a live query.
 
-> Fallback (`local`): `map.md` indexes; `questions/NN-<slug>.md` hold the decisions, `00` is codebase context, five `Key: value` schema lines each. Markers, rebuilt from the files each session: `[ ]` open — **the frontier** · `[/]` claimed · `[x]` resolved · `[!]` blocked · `[-]` out of scope.
+> Fallback (`local`): `map.md` indexes; `questions/NN-<slug>.md` hold the decisions, `00` is codebase context, six `Key: value` lines each, `Resolved:` dating it. Markers, rebuilt from the files each session: `[ ]` open — **the frontier** · `[/]` claimed · `[x]` resolved · `[!]` blocked · `[-]` out of scope.
 
 ## MODE A: Chart
 
@@ -75,17 +77,17 @@ Read references/chart.md
 
 > Fallback: confirm the outcome with the human FIRST; only then grill the destination, then breadth-first; write the map and one question per sharp decision.
 
-0. `[Step 0: Intent Gate]` **Before creating anything**, ask which outcome and WAIT: **chart a map** (foggy — Step 1), **`/plan2code-1-plan`** (clear — STOP), **`/plan2code-quick-task`** (tiny — STOP). HITL, never self-select "chart".
-1. `[Step 1: Name and backend]` Only after the gate returns "chart." Confirm the kebab-case idea name, then ask — HITL, never self-picked — **local files or GitHub Issues?** Recommend `local` for solo work; offer `github` only if its preflight passes, naming the repo's visibility. THEN the first write.
+0. `[Step 0: Intent Gate]` **Before creating anything**, use AskUserQuestion for the outcome and WAIT: **chart a map** (foggy — Step 1), **`/plan2code-1-plan`** (clear — STOP), **`/plan2code-quick-task`** (tiny — STOP). HITL, never self-select "chart".
+1. `[Step 1: Name and backend]` Only after the gate says "chart." Confirm the kebab-case idea name, then ask — HITL, never self-picked — **local files or GitHub Issues?** Recommend `local` for solo work; offer `github` only if preflight passes, naming the repo's visibility. THEN the first write.
 2. `[Step 2: Destination]` Grill until it is one or two lines. It fixes scope — settle it first.
 3. `[Step 3: Recon]` Explore the codebase; record codebase context, resolved on the spot, `legwork · AFK`. On `github` hold it until Step 6 so a Step 4 off-ramp leaves no litter.
 4. `[Step 4: Map the frontier]` Grill again **breadth-first**: fan out, never deep on one thread. Surface the open decisions and what is takeable now.
-5. `[Step 5: Create the map]` `**Status:** Charting`, Destination, Ground rules (backend first), an empty index, the fog in `## Not yet specified`. Say once where it lives and who can see it.
-6. `[Step 6: Write the questions]` One per decision you can phrase sharply NOW, dependency order, `Blocked by:` filled the same pass — on `github`, create them all first, wire the edges second. The rest stays fog. Always include a `grill · HITL` testing-posture question; `/plan2code-1-plan` Phase 1 needs it.
+5. `[Step 5: Create the map]` `**Status:** Charting`, Destination, Ground rules (backend first), an empty index, the fog in `## Not yet specified`. Say once where it lives and who sees it.
+6. `[Step 6: Write the questions]` One per decision you can phrase sharply NOW, dependency order, `Blocked by:` filled the same pass — on `github`, create all first, wire edges second. The rest stays fog. Include a `grill · HITL` testing-posture question; `/plan2code-1-plan` Phase 1 needs it.
 7. `[Step 7: Index]` Fill `## Question Checklist` from the files (`local` only). Set `**Status:** Working`.
-8. `[Step 8: Fire research]` One subagent per `research` question, in parallel. Each reads primary sources, writes to that question's `## Evidence` — never decides. Then Session End.
+8. `[Step 8: Fire research]` One subagent per `research` question, in parallel. Each reads primary sources, writes to its `## Evidence` — never decides. Then Session End.
 
-**No fog at Step 4?** Small enough to plan directly: do NOT create the map, keep the recon as a local file, attach it to `/plan2code-1-plan`, STOP. Charting resolves nothing by hand — stop at Step 8.
+**No fog at Step 4?** Small enough to plan directly: create no map, keep the recon as a local file, attach it to `/plan2code-1-plan`, STOP. Charting resolves nothing by hand — stop at Step 8.
 
 ## MODE B: Work
 
@@ -96,14 +98,14 @@ Read references/resolve.md
 Assume NO memory of any prior session.
 
 1. `[Step 1: Load]` Read the map whole. No question yet.
-2. `[Step 2: Reconcile]` **Always.** Read every question. `## Answer` written but the state disagrees? The answer wins. Claimed with no `## Answer`? A crash: release it, say so. Rebuild every marker from the questions.
+2. `[Step 2: Reconcile]` **Always.** Read every question. `## Answer` written but the state disagrees? The answer wins. Claimed with no `## Answer`? A crash: release it, say so. Rebuild every marker from the questions; backfill a missing `Resolved:` date from the claim.
 3. `[Step 3: Frontier]` Every question open, unclaimed, and unblocked. First in order.
-4. `[Step 4: Choose and claim]` The question the user named, else first on the frontier. Mark it claimed on the question and the map, **saved before any work.** Frontier empty but questions remain? All blocked — report the chain, STOP. Stranded on an `out-of-scope` blocker? Re-frame or rule out, re-run Step 3. Nothing open? Go to The Clearing Gate.
+4. `[Step 4: Choose and claim]` The one the user named, else first on the frontier. Mark it claimed on the question and the map, **saved before any work.** Frontier empty but questions remain? All blocked — report the chain, STOP. Stranded on an `out-of-scope` blocker? Re-frame or rule out, re-run Step 3. Nothing open? The Clearing Gate.
 5. `[Step 5: Zoom]` Read the claimed question in full, plus any closed question it references. Obey `## Ground rules`.
 6. `[Step 6: Resolve]` Route by type per the resolve playbook. HITL needs the human's own words.
-7. `[Step 7: Record]` Write `## Answer`: the decision, what was rejected and why, consequences, a one-line `**Gist:**`. Sources under `## Evidence`. Mark it resolved, index the gist on the map, bump `**Updated:**`.
+7. `[Step 7: Record]` Write `## Answer`: the decision, what was rejected and why, consequences, a one-line `**Gist:**`. Sources under `## Evidence`. Mark it resolved, dated today, index the gist + date on the map, bump `**Updated:**`.
 8. `[Step 8: Graduate]` Fog now sharp? Write those questions, delete the graduated bullets. Past the destination? Rule it out of scope, one line in `## Out of scope`. Invalidated? Re-frame or rule out.
-9. `[Step 9: Gate]` Run The Clearing Gate, then Session End.
+9. `[Step 9: Menu]` Run The Clearing Gate. Not cleared: fork-menu (Form C) — pick → Step 4, stop → Session End.
 
 ## The Clearing Gate
 
@@ -116,21 +118,21 @@ The map clears only when ALL hold:
 1. Nothing open, claimed, or blocked
 2. `## Not yet specified` is EMPTY
 3. The destination is reachable with nothing left to decide
-4. Every confidence dimension (Requirements, Feasibility, Integration, Risk) scores ≥ 18/25
+4. All four confidence dimensions score ≥ 18/25
 
-Any failing: name it, keep working. All passing: follow the handoff playbook, set `**Status:** Cleared`, stop. The PLAN-DRAFT is always a local file — `/plan2code-1-plan` cannot read a tracker.
+Any failing: name it, keep working. All passing: follow the handoff playbook, set `**Status:** Cleared`, stop. The PLAN-DRAFT is always local — `/plan2code-1-plan` cannot read a tracker.
 
 ## Trail Footer
 
 Read references/trail.md
 
-> Fallback: once the map exists, close every response with a one-line path of markers (`●` done · `◉` here · `○` open · `⊘` blocked · `⊝` out of scope) from `START` to `⚑`, a numbered legend of question names, plus a plain-English confidence note.
+> Fallback: once the map exists, end every response with a marker path (`●` done · `◉` here · `○` open · `⊘` blocked · `⊝` out of scope) `START`→`⚑`, a named legend, a plain-English confidence note, one closer.
 
-Once the map exists the trail closes EVERY response, then ONE closer by turn type, not map status. Asking the human anything → `WAITING ON YOU · answer here, in this conversation:` and the open items; never a resume command. Ending the session → `NEXT STEP · start a new conversation and run:` plus `/plan2code-0-pathfinder specs/<idea>/pathfinder` (the map issue URL on `github`), or `/plan2code-1-plan` once `Cleared`.
+Once the map exists the trail closes EVERY response, then ONE closer by turn type. Asking anything → Form B: `WAITING ON YOU · answer here, in this conversation:` + open items, no command. Menu after a decision → Form C: `NEXT UP` picks + `OR START FRESH`. Session end → Form A: `NEXT STEP · start a new conversation and run:` + `/plan2code-0-pathfinder specs/<idea>/pathfinder` (map issue URL on `github`), or `/plan2code-1-plan` once `Cleared`.
 
 ## Session End
 
-Report the question resolved (by name), its gist, what graduated from the fog, what's still open. Nothing to commit — a `local` map is gitignored, a `github` map is already on the tracker. Then the mascot, then the Trail Footer.
+Report each question resolved (name + gist), what graduated, what's still open; offer a brief for today. Nothing to commit — `local` is gitignored, `github` already on the tracker. Then the mascot, then the Trail Footer.
 
 ```
 ⋅
@@ -146,11 +148,11 @@ Report the question resolved (by name), its gist, what graduated from the fog, w
 
 | Issue | Action |
 |---|---|
-| Session stops mid-question, or the map drifted | Release the claim, note why. Work Step 2 repairs the map; the questions always win. |
+| Session stops mid-question, or map drift | Release the claim, note why. Work Step 2 repairs both; questions win. |
 | Frontier empty, fog remains | Not sharp yet. Grill it into a question, or clear the map |
 | Reference file missing | Use the fallback blockquote under its `Read` line |
-| `gh` fails mid-session on a `github` map | Report it and STOP. Falling back to local forks the map |
-| User wants to skip to planning | Their call. Say what is undecided, route to `/plan2code-1-plan` |
+| `gh` fails mid-session on a `github` map | Report and STOP. Falling back to local forks the map |
+| User skips to planning | Their call. Name what is undecided, route to `/plan2code-1-plan` |
 
 ## Learning Capture