survey

# 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. Skim `${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 If args named specific task ids, `list --ids <those ids>` (validate they exist and are `planned`). 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. ...