code-tour-writer

name	code-tour-writer
description	Create verified CodeTour `.tour` walkthrough artifacts with real repository file, directory, line, selection, pattern, or URI anchors. Use for onboarding tours, architecture tours, PR walkthroughs, RCA paths, security-review paths, or reusable explain-how-this-works artifacts.

Code Tour Writer

Use this skill to create a reusable guided walkthrough artifact, not a one-off chat explanation.

Output

Write CodeTour JSON under:

.tours/<audience>-<focus>.tour

Do not modify source code while creating a tour unless the user separately asks for code changes.

Workflow

1. Read the project entry points, docs, relevant modules, and changed files.
2. Choose the audience:
   • new-joiner
   • architect
   • pr-reviewer
   • rca-investigator
   • security-reviewer
   • feature-explainer
   • bug-fixer
3. Pick a focused path. A tour should explain one system, feature, change, or failure path.
4. Verify every anchor:
   • file exists;
   • directory exists;
   • line number is in range;
   • selection range is valid;
   • pattern exists when using pattern anchors.
5. Write the tour JSON.
6. Validate the JSON parses and every local anchor still exists.

Step Guidelines

Use 5-8 steps for a quick tour, 7-11 for PR/RCA/security paths, and 9-15 for onboarding or architecture.

Each step description should state:

• what the reader is looking at;
• how it connects to the previous step;
• why it matters;
• one concrete gotcha when useful.

Prefer file and selection anchors over vague content-only steps. The first step should anchor to a real repository location.

JSON Shape

Use the standard CodeTour style:

{
  "$schema": "https://aka.ms/codetour-schema",
  "title": "Short Tour Title",
  "description": "What this tour helps the reader understand.",
  "steps": [
    {
      "file": "src/example.ts",
      "line": 1,
      "title": "Entry Point",
      "description": "This is where the path starts."
    }
  ]
}

Supported anchors:

• directory
• file plus line
• file plus selection
• file plus pattern
• uri
• content-only closing step

Validation Checklist

• .tour file parses as JSON.
• Every local path is relative to the repository root.
• Every line and selection is valid.
• Pattern anchors match at least one line.
• The tour has a narrative arc rather than a flat file list.
• The final step gives the next useful move.

Avoid

• Guessing line numbers.
• Creating huge tours that try to document the whole repo.
• Using content-only steps as the main body.
• Duplicating README content.
• Hiding uncertainty about volatile anchors.