/survey

name: survey
description: Advanced surface, normally reached through the `foreman` entrance's Reconcile and pick mode, which hands it a near-term set of ids to scope the pass to. Ground-truths the roadmap's near-term candidates against the actual codebase — an Explore agent checks whether each candidate's planned_touches/depends_on still match reality, then proposes a concrete repair for every finding (hidden dependency, already-done, stale description or planned files), applies only the ones you approve, and persists them back into ROADMAP.jsonl so future sessions pick them up automatically. Also retires any recorded lesson the same evidence contradicts, so a wrong claim stops being quoted into later handoffs. It costs materially more than a plain pick, which is why it is explicit.
when_to_use: Reached through the `foreman` entrance for Reconcile and pick; trigger directly when a power user explicitly asks to reconcile, audit, double-check, or verify the roadmap's ordering — "survey the roadmap", "audit the next tasks", "double-check what's next", "is the roadmap still accurate", or invokes /foreman:survey. Never trigger automatically from foreman:roadmap's pick-next-task flow, a commit, or any other implicit signal.
argument-hint: "<optional — a task id or two to focus on, otherwise surveys the top unblocked candidates>"
allowed-tools: AskUserQuestion, Read, Bash, PowerShell, Agent

foreman:survey — ground-truth the roadmap's near-term candidates

This is the one Foreman flow that deliberately investigates the codebase against the roadmap. `foreman:roadmap`'s pick-next-task branch explicitly does **not** do this — see the 0.4.4-alpha changelog entry, where doing exactly this at pick time burned ~100k tokens on every invocation. Keeping it a separate, explicitly-triggered skill is what makes both halves cheap: the fast path stays mechanical, and ground-truthing only runs when someone actually asks for it.

All reads/writes to `ROADMAP.jsonl` go through `${CLAUDE_PLUGIN_ROOT}/scripts/roadmap.js` — never `Read`/`Edit` the file directly — run it with `--help` for the command shapes. Read the **Fields** section of `${CLAUDE_PLUGIN_ROOT}/roadmap-schema.md` for field semantics.

**Pre-check**: if `ROADMAP.jsonl` doesn't exist at the project root, tell the user to run `/foreman:init` first and stop here.

---

1. Pick the scope

<!-- [Foreman: 141] --> If a caller handed over a set of ids, that set **is** the scope — args naming specific tasks, or **Reconcile and pick**'s near-term set (`foreman:roadmap`'s pick branch derives it from one `next-candidates --menu` result: the candidate rows plus the `in_progress` and `awaiting_acceptance` rows). Run `list --ids <those ids>`, drop any that don't exist or are terminal (`done`/`dropped`/`rejected` — history its commits already describe) and say which you dropped, and skip the `next-candidates` call below. Scoping decides which entries get investigated and nothing else: steps 2–4 run exactly as written, on whatever the scope holds. Otherwise:

`node ${CLAUDE_PLUGIN_ROOT}/scripts/roadmap.js next-candidates` (default `--limit 3`) — candidates already include each one's own `depends_on`, no separate call needed just to get that.

Survey the top candidates only — same 3 by default as `foreman:roadmap` shows. This is deliberately not the whole backlog: a hidden dependency or stale claim matters most for what's about to be picked, and checking every `planned` entry every time would make this as expensive as the thing it's trying to avoid. If `total_unblocked` is larger than what you surveyed, say so when reporting back — don't imply full coverage silently.

Collect the exact set of dependency ids referenced across all candidates' `depends_on` (dedup). If non-empty, resolve just those — `node ${CLAUDE_PLUGIN_ROOT}/scripts/roadmap.js list --ids <comma-joined ids>` — never the unfiltered `list`, which loads the whole file just to answer a question about a handful of ids.

**Mechanical pre-check, not an agent's job:** that `list --ids` call already answered whether each entry's commits exist — every finished entry it returns carries `commit_evidence` (`commit_count`/`resolved_count`/`unresolved`/`has_trailer_match`). Read it; do not re-derive it with `git cat-file` (which only ever asks the project repo, so a commit living in a submodule comes back "missing" when it is right there) and do not spend agents on it. `unresolved` lists the shas git could not find; `has_trailer_match: true` means a commit message names the entry, which is the whole evidence a staged close leaves — an entry with `commit_count: 0` and a trailer match is recorded, not empty.

Same reasoning applies to `planned_touches`: collect every path named across the candidates being surveyed (dedup), and check existence directly — `test -e <path>` (Bash) / `Test-Path <path>` (PowerShell), relative to the project root, one call per unique path (or a short loop in one call). Build a `path_exists: true/false` map from this too — no agent needs a `Read`/`Glob` round trip just to learn a file isn't there. A missing path is a **question, not a verdict**: `planned_touches` is a forward-looking best guess written at `add`/`init` time and routinely names files the task will create, so absence alone is expected on a healthy backlog and proves nothing by itself. Survey only ever ranges over that predicted half — `observed_touches` is derived from commits that already landed, so there is nothing there to ground-truth and nothing `correct` could repair.

One more mechanical fact, gathered once regardless of which path above set the scope: a **not-done digest** — `id`, `title`, `planned_touches` for every entry currently `planned`, `in_progress`, `awaiting_acceptance`, or `deferred` (the whole not-done backlog, not just the candidates being surveyed) — `node ${CLAUDE_PLUGIN_ROOT}/scripts/roadmap.js list --status planned,in_progress,awaiting_acceptance,deferred --summary` (`--summary` rows already