plan2code/src/plan2code-0-pathfinder-references/trail.md

# 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.

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 |
| `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. Never a resume command — see below |
| 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 two 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.

---

## 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 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; if it does, Form B, no exceptions but the parked-grill one.
- **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.