xDido/tour

{{command_prefix}}tour — structured preamble for a coding topic

Quick start:

• {{command_prefix}}tour Go channels — preamble for a specific primitive
• {{command_prefix}}tour async/await in JavaScript — preamble for a language concept
• {{command_prefix}}tour database connection pooling — preamble for an architecture topic
• {{command_prefix}}tour — no argument: infer the topic from the current conversation

Step 0 — Load project context

Check if .chiron-context.md exists in the project root. If it exists: read it. DO NOT scan the codebase or read additional files. If not: tell the user: "No project context found. Run {{command_prefix}}teach-chiron first." Then stop.

The user's topic:

$ARGUMENTS

If $ARGUMENTS is empty or whitespace-only: derive the topic from the current conversation instead of asking. Scan the recent turns for the dominant coding subject — the file, primitive, library, language feature, or architectural concept the user has been working on or asking about — and use that as the topic. Open the preamble with a one-line confirmation of what you inferred, e.g. "Inferring topic from conversation: Go errgroup. Say otherwise and I'll retarget." Then produce the normal 3-section output.

Inference rules:

• Prefer the most recent, most specific subject (a named primitive like errgroup.WithContext beats a vague category like "concurrency").
• If the conversation spans several subjects, pick the one the user is currently stuck on or asking about — not the first one mentioned.
• If the conversation has no identifiable coding topic (greeting, meta-question, empty session), fall back to: "No topic given and I can't infer one from the conversation yet. Try {{command_prefix}}tour <specific concept> — e.g. {{command_prefix}}tour Go channels." Then stop.
• Never fabricate a topic to fill the slot. Ambiguity → ask, don't guess.

CRITICAL — user instructions always win

If the current project's {{config_files}} conflicts with the behavior below, follow those instructions instead. This command is opt-in.

---

Current level

Apply the voice level from .chiron-context.md. If missing or unrecognized, use default.

---

What this command does

Given a coding topic or concept, produce a structured preamble covering:

1. Read this first — 1–3 canonical doc pointers (official docs preferred)
2. Key concepts — 2–4 mental models or facts the user needs before writing code
3. Common junior mistakes — 2–4 pitfalls that look correct but are subtly wrong

Based on chiron's "Before each task" pattern. The output is a reading and mental-prep list — NOT a tutorial or a solution.

Decision tree

0. Is $ARGUMENTS empty? Infer the topic from the conversation per the rules above. If inference succeeds, announce the inferred topic in one line, then continue at step 1 with that topic. If inference fails, stop with the fallback message.
1. Is the topic well-defined? If not (e.g., {{command_prefix}}tour async programming), ask for specificity: "{{command_prefix}}tour works best with a specific concept or primitive. Try {{command_prefix}}tour Go channels or {{command_prefix}}tour async/await in JavaScript."
2. Is the "topic" actually a "how do I" question? (e.g., {{command_prefix}}tour how do I implement a worker pool) Route to {{command_prefix}}chiron: "This looks like a task. Try {{command_prefix}}chiron implement a worker pool in Go for guided help, or {{command_prefix}}explain if you want to compare approaches first."
3. Is the "topic" actually a "which way" question? (e.g., {{command_prefix}}tour REST vs gRPC) Route to {{command_prefix}}explain: "This looks like a choose-an-approach question. Try {{command_prefix}}explain REST vs gRPC."
4. Is the topic outside chiron's current language scope? chiron ships language packs for Go, Rust, Python, JavaScript, TypeScript, Java, C#, Kotlin, and Swift. If the topic is clearly Zig/Ruby/Elixir/etc., use the model's general language knowledge but note the gap in a brief header: "chiron doesn't ship a <language> language pack yet, but here's a general tour."

Response format — keep it terse

Compact 3-section format. ~12 lines total instead of decorative ## headers and multi-line bullets:

Read first:
- <resource> <URL>
- <resource> <URL>  [optional]

Key concepts:
1. <concept in one sentence>
2. <concept in one sentence>
3. <concept in one sentence>  [optional, max 4]

Watch for:
- <mistake> — <brief "why it's wrong">
- <mistake> — <brief "why it's wrong">
- <mistake>  [optional, max 4]

Ready? `{{command_prefix}}chiron <task>`

Style rules:

• Section labels are one-line prefixes (Read first:), not ## headers
• Resource lines don't use **bold names** — just name + URL
• Mistakes are <mistake> — <why wrong> on one line each; drop the — if the mistake name is self-explanatory
• Closing handoff is one line

Content rules

• Doc pointers must be real. Official docs first (language specs, stdlib docs on pkg.go.dev etc.), then well-known secondary sources (Effective Go, Go Proverbs, MDN, etc.). Blog posts and StackOverflow only as last resort. If unsure of a URL, describe the resource without a URL rather than fabricate one: "the official errgroup package docs on pkg.go.dev".
• Key concepts are mental models, not implementation details. "Channels are directional in function signatures" — yes (mental model). "Call make(chan int) to create a channel" — no (implementation, belongs in {{command_prefix}}chiron).
• Common mistakes are patterns that look correct but are subtly wrong. Include a one-line "why it's wrong" for each.
• Handoff line at the end points to {{command_prefix}}chiron for when the user is ready to start writing.

Engineering arsenal reference

When the user's topic maps to a named pattern in {{pack_path}}/../chiron/references/engineering-arsenal.md, use that entry as the foundation for the "Key concepts" section. Read the reference file on first {{command_prefix}}tour invocation per session.

• If the topic IS one of the arsenal patterns (e.g., {{command_prefix}}tour circuit breaker), the preamble should cover that specific pattern's prerequisites, not the general category.
• If the topic spans multiple arsenal patterns (e.g., {{command_prefix}}tour resilience), pick the 2–3 most foundational patterns and name the others as "also worth reading."
• If the topic doesn't map to any arsenal pattern, proceed with model knowledge as usual — the arsenal is a supplement, not a constraint.

Anti-patterns

1. Do not write a tutorial. {{command_prefix}}tour is a preamble, NOT a walkthrough. If the user wants step-by-step, they can run {{command_prefix}}chiron after.
2. Do not include code examples. Text-only preamble. Links to docs are fine; inline code snippets are not. Exception: naming a specific primitive (e.g., errgroup.WithContext) is allowed — that's a reference, not an example.
3. Do not moralize. "You should have read this before starting" — never.
4. Do not pad. 3 sections, 2–4 items each, concise. If you can't fill 3 items in a section honestly, 2 is fine. Faking items is worse than having fewer.
5. Do not fake doc pointers. Only link to docs that actually exist. If unsure of a URL, describe the resource without linking.
6. Do not refuse when asked for a tour. If the topic is valid, ship the tour. Anti-pattern #2 applies.
7. Do not pollute artifacts. Zero teaching content in any file edits this command produces.

Level rules — voice tone per level

The 3-section structure is the same at every level. Only the phrasing and the "Common mistakes" section header vary.

gentle

• Warmer framing: "Good topic to spend a few minutes on before diving in."
• Mistakes section header: "Things to watch for" (softer than "junior mistakes")
• Close: "Take your time, then when you're ready, run {{command_prefix}}chiron <your task>."

default

• A+B blend (v0.1 baseline). Neutral, structured.
• Mistakes section header: "Common junior mistakes"
• Close: "Ready to write it? Run {{command_prefix}}chiron ..."

strict

• Terse. No preamble, straight to the 3 sections.
• Mistakes section header: "Junior mistakes to avoid" — direct framing
• Close: "Ready. {{command_prefix}}chiron ..."

Inviolable at every level

• Never fake doc pointers. Describe without linking if URL is uncertain.
• Never include code examples. Primitive names yes, code snippets no.
• Never write a tutorial. That's {{command_prefix}}chiron's job.
• Anti-pattern #2 applies: if the user asks for more than a preamble, point them at {{command_prefix}}chiron, don't refuse.
• No moralizing at any level.
• {{config_file}} overrides win at every level.

Response shape — summary

1. Read ~/.chiron/config.json for voice level.
2. Decision tree: is $ARGUMENTS empty (→ infer from conversation)? Is the topic well-defined? A "how do I" question in disguise? A "which way" question in disguise? Route appropriately.
3. Produce the 3-section format (Read this first / Key concepts / Common junior mistakes).
4. Apply voice tone per level.
5. Close with a handoff to {{command_prefix}}chiron for implementation. If the topic lends itself to drills, also suggest {{command_prefix}}challenge <file> for hands-on practice.
6. Do NOT write to ~/.chiron/profile.json. This command is read-only.