Files
plan2code/skills/plan2code-0-pathfinder/references/trail.md
T

195 lines
13 KiB
Markdown
Raw Normal View History

# Trail Footer
> Loaded at the top of the skill. Read once; it applies to EVERY response in both modes. Defines the map visual and the pathed resume command that close each turn.
>
> **Backend note.** The glyphs, the two forms, and the discipline are identical either way. On `**Backend:** github` the inputs come from the sub-issue query rather than the checklist, and Form A's command is the map issue URL — see `github-issues.md`.
The trail is how a human with no memory of the last session sees, at a glance, how far the map has come and what is left — and copies the exact command to resume without hunting for a path that lives in gitignored `specs/`. It closes every response once a map exists.
It is **presentation only**. Rebuild it fresh from `map.md` each response; never write it to disk, and never let it emit a loop token (`TASK_COMPLETE`, `PHASE_COMPLETE`, and the rest). It is an index of an index — the question files remain ground truth.
---
## When it renders
| Situation | Footer? |
|---|---|
| `map.md` exists and the turn **ends the session** — Session End, a cleared map, a fully blocked frontier | **Yes**, both parts: the trail, then the resume command (Form A) |
| `map.md` exists and the turn **asks the human something** — a probe batch, a sketch put up for reaction, a `legwork · HITL` checklist | **Yes**, but with the waiting form of Part 2 (Form B). Never a resume command — see below |
| `map.md` exists and the turn **offers the menu after a recorded decision** — the continue-or-stop fork of the Work cadence | **Yes**, the fork form of Part 2 (Form C): the takeable questions AND the resume command as the stop branch |
| Intent Gate (Step 0), the no-fog off-ramp, or any route-and-stop before Step 5 | **No** — no map on disk yet, and no path to resume. There is nothing to draw. |
One idea per session, so there is only ever one trail. Draw the trail for the active idea and no other.
---
## The two parts
Always in this order, after everything else in the response:
1. **The trail** — the horizontal path plus its legend and confidence line. Identical on every turn.
2. **The next line** — either the pathed resume command or the waiting notice, chosen by turn type.
### Part 1 — the trail
```
🧭 audit-log-export · Working · 2/7 cleared
START ●━●━◉··○··○··⊘··⊝ ····⚑
● done · ◉ here · ○ open · ⊘ blocked · ⊝ out of scope · ⚑ destination · ~4 fog
1 Codebase context ✔ · 2 Export format ✔ · 3 Row-count ceiling ◀ here
4 Export authorization · 5 Testing posture · 6 Delivery channel (blocked:3) · 7 SIEM push (out of scope)
Confidence: solid, but Risk is borderline.
```
How each line is built, top to bottom:
- **Heading** — `🧭 <idea> · <Status> · <resolved>/<total> cleared`. `<Status>` is the map's `**Status:**` verbatim (`Charting` / `Working` / `Cleared`). `<resolved>` counts `[x]` rows; `<total>` counts every question row **except** out-of-scope `[-]` rows (a ruled-out question is off the route, not an unfinished stop).
- **The path** — one glyph per question row in `NN` order, left to right, from `START` to the `⚑` destination. Connectors carry meaning: solid `━` joins stops already walked (everything up to and including `◉ here`); dashed `··` joins stops still ahead. After the last question glyph, a fog stretch `····` then `⚑` — drop both if there is no fog and join straight to `⚑` with `━`.
- **The legend** — only the glyphs actually on this path, so a map with no blocked question does not advertise `⊘`. Append `~N fog` when `## Not yet specified` holds N bullets.
- **The named legend** — the same `NN` order, `<NN> <Name>` each, `·`-separated, wrapping across lines as needed. Tag each: `✔` resolved, `◀ here` the claimed one, `(blocked:NN)` with its blocker, `(out of scope)`. Names come straight from the checklist rows.
- **Confidence** — the map's four internal scores (Requirements / Feasibility / Integration / Risk, each out of 25) exist for the Clearing Gate, not the human. Never print the raw numbers or the `R·F·I·K` letters. Instead, reduce them to one plain-English line:
| Scores | Line |
|---|---|
| All four ≥ 20 | `Confidence: solid.` |
| All four ≥ 18, one or more sitting at 18-19 | `Confidence: solid, but <Dimension> is borderline.` (name every dimension in that range, comma-separated) |
| Any dimension < 18 | `Confidence: not yet — <Dimension(s)> still need work.` |
Omit the whole line if the map has no `**Confidence:**` line yet.
### Glyph reference
| Glyph | Map marker | Meaning |
|---|---|---|
| `●` | `[x]` | resolved — a stop already walked |
| `◉` | `[/]` | the claimed question — you are here |
| `○` | `[ ]` | open, on the frontier |
| `⊘` | `[!]` | open but blocked |
| `⊝` | `[-]` | ruled out of scope |
| `⚑` | — | the destination |
| `····` | — | the fog still between the last question and the destination |
### Part 2 — the next line
Part 2 answers exactly one question for the human: **is this turn over, or is it my move?** It has three forms, and the **turn type** picks between them — not the map's status.
#### Form A — the turn ends the session
```
NEXT STEP · start a new conversation and run:
`/plan2code-0-pathfinder specs/audit-log-export/pathfinder`
```
The path is always relative and always ends `/pathfinder` — that is exactly the argument this skill's Auto-Discovery resolves an idea from, so the human pastes it back with zero edits. Fill `<idea>` from the active map's directory; never leave the `<spec-folder>` placeholder in a rendered footer.
The command target follows the map's status, but the sentence is always the same shape — `start a new conversation and run:` followed by the command on its own line:
| Status | Command |
|---|---|
| `Charting` / `Working` | `/plan2code-0-pathfinder specs/<idea>/pathfinder` |
| `Cleared` | `/plan2code-1-plan` — point at the PLAN-DRAFT the Clearing Gate wrote |
| `Cleared`, but `## Ground rules` records `AGENTS.md` **absent** | `/plan2code-init` FIRST (offer `questions/00-codebase-context.md`), then `/plan2code-1-plan` |
#### Form B — the turn asks the human something
Any turn whose next move is theirs and happens **in this same conversation**: a batch of grill probes, a sketch put up for reaction, a `legwork · HITL` checklist, the Chart Step 2 destination grill, the Chart Step 4 frontier grill.
```
WAITING ON YOU · answer here, in this conversation:
Q1 Duration model · Q2 Contract while held · Q3 Placement & restore
```
Name every outstanding item at its stable number so a partial reply is cheap to give and a dropped probe is visible to both of you. `·`-separated on one line; one per line if the names run long. Never more items than the three-probe cap allows.
**Emit no resume command on a Form B turn.** There is nothing to resume — the session is alive and holding a claim. A resume command here reads as *we're done*, and the human either walks away mid-decision or burns the next turn asking what you meant. This is the single most common way the footer misfires, and it costs the batch the round trips batching was introduced to save.
One exception: `grilling.md`'s unreachable-human procedure. Parking a mid-grill question and stopping IS a session end — use Form A, and say in the body that the question is parked mid-grill with its batch outstanding.
#### Form C — the menu after a recorded decision
Used ONLY on the Work cadence's fork-menu turn (resolve.md §Cadence), immediately after an `## Answer` landed and the map row flipped `[x]`. It is the one legitimate hybrid: an *explicit* continue-or-stop fork where the resume command IS the stop branch, not a farewell.
First print the stop branch, clearly labeled:
```
OR START FRESH · new conversation, paste:
`/plan2code-0-pathfinder specs/audit-log-export/pathfinder`
```
Then invoke the structured question tool (header `Next step`) asking: "Continue here, or start fresh? Everything is saved." Options: up to three takeable question names, then `Start fresh`. Put each question's gist / newly-unblocked note in its description. The automatic `Other` path lets the human name another frontier question not shown. Mark one option's description `RECOMMENDED` — early in the session that is a question; at the checkpoint it is `Start fresh`.
Rules for Form C:
- **The command label is mandatory and exact:** `OR START FRESH · new conversation, paste:`. It makes the command the stop branch, not a farewell. Never render a bare command on a menu turn.
- **The choice itself always uses the structured tool.** Never print `NEXT UP` as a prose menu when the tool exists.
- Options come from the map's checklist rows (names + gists), takeable questions only. Flag anything the decision just recorded unblocked. The fourth slot is `Start fresh`; `Other` covers a frontier question omitted from the top three.
- **The recommendation carries the checkpoint** (resolve.md §Cadence): early in a session recommend a question; after ~3 resolved this session — or after a heavy, contested, or `Locked: yes` decision — recommend `Start fresh`, with the reason said in the question text ("to keep me sharp").
- **Form C never replaces Form B.** A turn that asks probes, shows a sketch, or hands over a checklist is Form B, no command. Form C fires only between decisions, when nothing is claimed.
- If the human walks away mid-menu, nothing is stranded: no claim is open, and the command to come back is already on screen.
---
## State-by-state examples
**Charting, mid-grill, no question claimed yet** (`◉` is omitted; the frontier head is the first `○`). The Chart Step 4 frontier grill is a Form B turn — the batch is above, so the footer says stay:
```
🧭 audit-log-export · Charting · 1/5 cleared
START ●··○··○··○··○ ····⚑
● done · ○ open · ⚑ destination · ~6 fog
1 Codebase context ✔ · 2 Export format · 3 Export authorization · 4 Testing posture · 5 Row-count ceiling
Confidence: not yet — Requirements, Feasibility, Integration, Risk still need work.
WAITING ON YOU · answer here, in this conversation:
Q1 Data · Q2 Surface · Q3 Permissions
```
**Working, a claimed question mid-grill** — probes are out, the claim is held, nothing is resolved yet. Same trail, Form B again. Note that Q2 is a re-ask carried over at its original number from a batch that came back partial:
```
🧭 audit-log-export · Working · 2/7 cleared
START ●━●━◉··○··○··⊘··⊝ ····⚑
● done · ◉ here · ○ open · ⊘ blocked · ⊝ out of scope · ⚑ destination · ~4 fog
1 Codebase context ✔ · 2 Export format ✔ · 3 Row-count ceiling ◀ here
4 Export authorization · 5 Testing posture · 6 Delivery channel (blocked:3) · 7 SIEM push (out of scope)
Confidence: not yet — Feasibility, Integration, Risk still need work.
WAITING ON YOU · answer here, in this conversation:
Q2 Ceiling behaviour past the cap (re-ask) · Q3 Who sees the truncation warning
```
**Frontier fully blocked** — report the chain in the body; the trail shows why nothing is takeable. Work Step 4 stops the session here, so Form A:
```
🧭 audit-log-export · Working · 5/7 cleared
START ●━●━●━●━●━⊘··⊘ ⚑
● done · ⊘ blocked · ⚑ destination
6 Delivery channel (blocked:2) · 7 Notification (blocked:6)
Confidence: not yet — Feasibility, Risk still need work.
NEXT STEP · start a new conversation and run:
`/plan2code-0-pathfinder specs/audit-log-export/pathfinder`
```
**Cleared** — every stop walked, fog empty, command hands off:
```
🧭 audit-log-export · Cleared · 8/8 cleared
START ●━●━●━●━●━●━●━●━⚑ arrived
Confidence: solid.
NEXT STEP · start a new conversation and run:
`/plan2code-1-plan`
```
At `Cleared` the named legend is optional — the destination is reached and the PLAN-DRAFT is the thing to point at. Keep the confidence line; the Clearing Gate leaned on it.
---
## Discipline
- **Never print a bare resume command on a turn that asks a question.** The footer must not tell the human to leave a conversation you are still waiting in. Before you write Part 2, ask whether the response above it ends with something for them to answer: mid-question (probes, sketch, checklist) → Form B, no command, no exceptions but the parked-grill one; between decisions at the fork-menu → Form C, where the command appears ONLY under its `OR START FRESH` label as the explicit stop branch.
- **Alignment is not the point.** Glyphs sit in `NN` order and the legend names them in the same order; do not burn effort column-aligning numbers under waypoints across variable-width glyphs. Legibility over pixels.
- **Rebuild, never cache.** The markers come from the current `map.md`, which Work Step 2 has already reconciled against the question files this session. A footer that disagrees with the checklist above it means you drew from memory.
- **One trail.** Never render two ideas' trails, and never invent a stop the map does not list.