Analyze

Analyze — Tour Spec Authoring

Read input artifact(s) and write a tour-spec.json that the renderer consumes. Hand off to learning-guide:render at the end.

Trigger phrases

• "create a learning guide for X"
• "make an interactive tour"
• "generate onboarding doc"
• "build a learning module from this session"

Inputs to collect from the user

1. Source artifact path(s) — required. One or more files/folders.
2. Output directory — default <input-parent>/learning/.
3. Archetype hint — optional; auto-detect with these rules:
   • Filename ends .observations.md OR YAML frontmatter contains session_date: → planning-session.
   • Input is a directory of source files with no obvious doc layer → codebase.
   • Input contains "Phase 1", "Phase 2", "rollout", "blockers" structure → refactor-plan.
   • Otherwise → generic.
4. Language — auto-detect from input text dominance; require >80% single-locale tokens to commit, otherwise default en. Always state the detected language and offer an override before drafting.

Flow

1. Resolve inputs. Confirm path(s) and output dir before reading anything large. Reject non-existent paths.
2. Pick archetype. Auto-detect, state the choice, ask the user to confirm or override.
3. Load archetype reference. Read references/archetype-<name>.md.
4. Survey the input.
   • Codebase: structured exploration — entry points, module map, control flow.
   • Doc: top-to-bottom read.
   • Session: lift decisions, blockers, files-touched.
5. Discover embedded sources. Look for user-authored markdown referenced from the input (links, frontmatter artifacts: lists, sibling .md files). If none found AND archetype is codebase or generic, plan to synthesize tour-companion.md per references/synthesis-contract.md.
6. Discover external link tokens. Scan input for ticket/issue patterns. Ask the user for URL templates (e.g., TICKET- → https://tracker.example.com/browse/TICKET-{id}). Templates must start with http://, https://, or mailto: and contain {id} — the renderer rejects other schemes.
7. Discover cross-ref patterns. Per references/cross-ref-design.md. Propose only token-shaped patterns; bare words are forbidden. Show the user the proposed list, get confirmation.
8. Draft the tour spec. Follow the archetype's section outline. Each section gets a markdown body, optional inline quiz. Synthesize tour-companion.md if planned in step 5. Use references/spec-authoring.md for body_md style.
9. Quality gates. Before handoff, verify:
   • Every section has non-empty body_md.
   • Every section with level >= 2 has a parent (the renderer rejects a spec that violates this — the JSON Schema only hints it for editors).
   • Every cross-ref pattern uses a non-bare-word token shape, names an existing source, AND its anchor_format resolves to a heading in that source. Heading anchors are bare slugs with no section- prefix (see references/cross-ref-design.md).
   • Every external_links template starts with an allowed scheme (http(s):// / mailto:) and contains {id}.
   • Every quiz answer_index is in [0, options.length-1].
   • Mermaid blocks parse as valid (best-effort regex on the first non-blank line).
10. Hand off to render. Invoke learning-guide:render with the spec path. No "shall I render?" gate — render is cheap and idempotent.

Re-invocation behavior

If tour-spec.json already exists at the target path, ask:

"Existing spec found. Update it (preserve your edits), regenerate from scratch, or just re-render?"

• Update mode — preserve sections[].body_md, sections[].quiz, final_quiz, glossary verbatim. Refresh embedded_sources, external_links, cross_ref_patterns only when input artifacts have changed since the spec's mtime. All other top-level fields refresh. Conflicts are surfaced as a numbered list before write.
• Regenerate — delete the existing spec, re-run from step 1.
• Re-render only — invoke learning-guide:render; skip analyze entirely.

References

• references/archetype-codebase.md, references/archetype-planning-session.md, references/archetype-refactor-plan.md, references/archetype-generic.md
• references/spec-authoring.md — body_md style and field rules.
• references/cross-ref-design.md — pattern shapes and slug algorithm.
• references/synthesis-contract.md — tour-companion.md skeleton.