Via route

via route

Turn an open planning question into three options and a detailed route map. Use your own judgment to understand the task. RouteSpec is a lightweight scaffold for what is displayed, not a framework for how you reason. Create the artifact yourself; do not make the user assemble JSON or run commands.

Before proposing routes, think deeply and from first principles about the user's intent and purpose. Look beyond the literal request to understand the outcome they are actually trying to achieve, using context and evidence without inventing hidden requirements. Follow your own intuition and native reasoning behavior to form genuinely useful ways forward.

Create the map

1. Use the available context and your engineering intuition to understand the task before implementation. Inspect evidence in proportion to uncertainty and risk. Ask a clarifying question only when the answer would materially change the routes; do not research merely to fill the map. Use the reasoning depth that feels appropriate for the task and host.
2. For an open planning question, use the familiar three-option comparison when it naturally fits the model's reasoning and gives the user real choice. Treat three as the interface default, not a demand to fabricate distinctions: if the task truly has fewer viable directions, continue normally and say so.
3. Choose and recommend the options from the user's goal, constraints, and likely journey through the work. Let meaningful differences emerge from the problem—such as boundary, dependency strategy, reversibility, learning path, risk, or proof—rather than forcing a taxonomy or generic quick/balanced/robust labels.
4. Map the work as it naturally overlaps, diverges, and converges. Choose the topology after understanding the task; do not embellish it or force a symmetrical three-way fork.
5. Encode the result as RouteSpec 0.3 using the contract and bundled JSON Schema. Write destination as a short model-generated title for what this map is about, similar to a clear PR title. Share, split, branch, and merge nodes only where the real work does.
6. Let the task determine the endpoints. Most routes will naturally share a start and finish, so let the renderer infer them. If the useful options naturally begin from more than one available state or end in more than one outcome, declare graph.terminals; routes may still share either endpoint. The renderer fixes their roles as START and DONE, while your node labels provide the changing captions underneath.
7. Resolve SKILL_DIR to this Skill directory. Validate with node "$SKILL_DIR/scripts/validate-route.mjs" <spec.json>, repair structural errors, then render with node "$SKILL_DIR/scripts/render-route.mjs" <spec.json> <map.svg>.
8. Present the SVG prominently, then give the normal user-facing planning response the task deserves. Explain the three routes, why they differ, your recommendation, and useful feedback at a depth set by the task and the user—not by the size of the SVG. The map supplements this answer; it does not replace or compress it. Do not repeat generic instructions like choosing, combining, or customizing routes after every render.
9. Stop after the planning response and route map unless the user also asked you to implement a route.

Continue naturally

• After the user chooses a route, continue the work normally from that choice. Use the existing map as context; do not force later answers back into three options.
• Redraw only when the user's goal, constraints, evidence, or available paths change enough to alter the map. Otherwise answer or implement without invoking via again.
• Let via fall away when the work becomes a fixed execution path, a small edit, or a factual question. Decide from the current turn; do not ask the user to manage via state or predict whether the next turn will need it.

Map what matters

• A node is a concrete action or checkpoint, not hidden reasoning.
• The origin node names the user's current starting state, such as from scratch, draft repo, failing build, round 12 design, or another real stage. The destination node names what this run can leave behind, such as release ready, validated patch, migration plan, or narrowed cause. Do not default to generic intent and ship unless those are truly the user's state and outcome.
• If the task naturally presents more than one p or q point, use graph.terminals instead of inventing shared endpoints. Any two or three routes may still point to the same terminal node.
• Preserve real overlap between routes. Add nodes, branches, merges, and checks only when they represent actual work.
• Use kind: branch for a genuine detour, optional proof, exploratory probe, or small implementation variant. The renderer draws it dashed, so reserve it for work that feels lighter or less central than the main path.
• Make the selected route startable and summaries useful for choosing.
• Pick three distinct colors from blue, orange, green, pink, purple, and cyan when creating a map. Write the choices into RouteSpec so re-rendering stays stable. Use the bright color on the Git tree and its accessible dark companion on the time label. Keep route names, primary metrics, and card shells neutral.
• Estimate both ranges from route selection to the next useful engineering deliverable, not from the start of the existing conversation and not through an entire long-term rollout. Tokens cover incremental model workload—context reads, tool feedback, output, and reasoning. Time covers active agent wall-clock including tools and verification, but excludes human approval, deployment waiting, and observation windows. Prefer live host evidence when available. Without it, remember that tool-using repository work usually consumes tens to hundreds of thousands of tokens while a focused agent pass often completes in minutes, not human implementation hours. Use broad rounded ranges and widen them for model, cache, repository, and tool uncertainty.
• control marks a meaningful decision, boundary, proof, or release checkpoint. The number beside the traffic-signal glyph counts these checkpoints; its two lenses are pictographic, not status indicators.
• Keep visible labels concrete and scan-friendly.
• Preserve useful user-facing reasoning, evidence, tradeoffs, and feedback in the written answer. Do not suppress or reshape the host's native thinking, progress, or reasoning-summary interface. Follow the host model's own policy for any private internal reasoning; via does not require or forbid a raw chain-of-thought transcript.

Read the contract when composing or repairing RouteSpec. Use the evaluation guide only for forward testing, not as a generation checklist.