Walkthrough skill

.claude/skills/walkthrough/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: walkthrough
+description: Generate interactive code walkthroughs in Virgil markdown format
+disable-model-invocation: true
+argument-hint: <pr-number|tour|keyword|incident|guide>
+---
+
+# Walkthrough Generator
+
+Generate interactive code walkthroughs in Virgil markdown format for the Virgil VS Code extension.
+
+## Mode Routing
+
+Determine the walkthrough mode from `$ARGUMENTS`:
+
+| Pattern | Mode | Description |
+|---------|------|-------------|
+| Number (e.g. `123`) | PR review (diff) | Walk through PR changes with diff mode |
+| `tour` | Codebase tour | High-level architecture walkthrough |
+| Keyword (e.g. `auth`) | Focused subsystem tour | Deep dive into a specific subsystem |
+| `incident` or `debug` | Incident trace | Investigation/debugging narrative |
+| `guide` or `setup` | Implementation guide | Step-by-step setup or implementation |
+
+If `$ARGUMENTS` is ambiguous, ask with AskUserQuestion: "What type of walkthrough?" with options matching the modes above.
+
+## Virgil Markdown Format
+
+### Frontmatter
+
+YAML between `---` delimiters at the start of the file:
+
+```yaml
+---
+remote: <git remote URL>
+commit: <full HEAD commit SHA>
+# For diff mode, add ONE of (priority: baseCommit > baseBranch > pr):
+baseCommit: <base commit SHA>
+baseBranch: main
+pr: 123
+# Any additional key-value pairs become metadata
+---
+```
+
+Always include `remote` and `commit`. The extension uses `remote` to filter walkthroughs to the matching workspace. A warning is shown if multiple base references are specified.
+
+### Document Structure
+
+- **Title**: The first `# heading` becomes the walkthrough title
+- **Description**: Text between frontmatter and first `##` heading (optional)
+- **Steps**: Each `##` through `######` heading creates a step
+
+### Steps
+
+Header level determines hierarchy:
+
+| Header | Relationship |
+|--------|-------------|
+| `##` | Top-level step |
+| `###` | Child of nearest `##` |
+| `####` | Child of nearest `###` |
+| `#####` | Child of nearest `####` |
+| `######` | Child of nearest `#####` |
+
+Navigation traverses all steps in depth-first order.
+
+### Location Links
+
+Place location links in the step body (typically right after the heading or explanation).
+
+**View code** (head/current file): `[View code (startLine-endLine)](/path/from/repo/root)`
+**Base** (diff mode, base file): `[Base (startLine-endLine)](/path/from/repo/root)`
+
+Rules:
+- Line numbers are **1-based** and **inclusive**
+- Path **must** start with `/` (repo root-relative)
+- Multiple ranges: `[View code (10-20,33-45)](/src/file.ts)`
+- Single line: `[View code (10)](/src/file.ts)`
+
+### Step Display Modes
+
+| `View code` | `Base` | Mode | Display |
+|-------------|--------|------|---------|
+| Yes | No | Point-in-time | Standard code highlight |
+| No | Yes | Base-only | Base file highlight |
+| Yes | Yes | Diff | 3-way toggle: diff view / head / base |
+| No | No | Informational | No code view (overview/summary steps) |
+
+### Body Content
+
+Full markdown is supported in step bodies: headers, bold/italic, code blocks (with language identifier), inline code, lists, links, blockquotes.
+
+### Step Links
+
+Link to other steps using anchor syntax: `[link text](#step-title-as-anchor)`
+
+Anchor rules (GitHub/CommonMark): lowercase, spaces to hyphens, strip special chars.
+Example: `## JWT Validation` → `[see validation](#jwt-validation)`
+
+## Shared Workflow
+
+These steps apply to **all** walkthrough modes:
+
+1. **Gather repository info**
+   ```bash
+   git remote get-url origin 2>/dev/null || echo "no-remote"
+   git rev-parse HEAD
+   ```
+
+2. **Explore the codebase** — Use Glob for structure, Grep for patterns, Read for content. Map out the relevant execution flow or architecture.
+
+3. **Design walkthrough structure** — Plan 5-15 steps. Determine hierarchy (## for major areas, ### for details). Map each step to a file path and line range.
+
+4. **Write the walkthrough** — Use the **Write tool** to create `walkthroughs/<name>.md`. Do NOT use `cat` heredoc or Bash for output.
+
+5. **Verify accuracy** — Read each referenced file and confirm:
+   - File paths exist
+   - Line numbers point to the correct code
+   - Narrative flows logically from step to step
+
+## Mode-Specific Instructions
+
+After determining the mode from [Mode Routing](#mode-routing), **Read** the corresponding mode file for detailed instructions:
+
+| Mode | File to Read |
+|------|-------------|
+| PR review (diff) | `modes/pr-review.md` |
+| Codebase tour | `modes/codebase-tour.md` |
+| Focused subsystem tour | `modes/subsystem-tour.md` |
+| Incident/debugging trace | `modes/incident-trace.md` |
+| Setup/implementation guide | `modes/implementation-guide.md` |
+
+Read the file path relative to this skill's directory. Only read the one mode file that applies — do not read all of them.
+
+## Quality Guidelines
+
+1. Always **read files** to get correct line numbers — never guess
+2. One concept per step; meaningful titles (what the code does, not file names)
+3. Focused line ranges (10-50 lines); break up larger sections
+4. Body explains "why", not just "what" — use markdown formatting
+5. Always include `remote` and `commit` in frontmatter
+6. Use step links (`#anchor`) to cross-reference related steps
+7. Informational steps (no location links) for overview/summary/transitions
+8. Narrative flow: start with context, build understanding progressively
+
+## Output
+
+Use the **Write tool** to create the walkthrough file at:
+
+```
+walkthroughs/<name>.md
+```
+
+**Naming conventions:**
+- PR review: `pr-<number>.md`
+- Codebase tour: `architecture.md`
+- Subsystem tour: `<keyword>.md`
+- Incident trace: `incident-<id>.md`
+- Implementation guide: `<guide-name>.md`
+
+Create the `walkthroughs/` directory if it doesn't exist.
+
+After writing, tell the user: "Walkthrough generated! Open in VS Code/Cursor with the Virgil extension, then use **Convert Markdown to Walkthrough** to view it."

.claude/skills/walkthrough/metadata.toml

@@ -0,0 +1,9 @@
+name = "walkthrough"
+version = "1.0.0"
+type = "skill"
+
+[skill]
+prompt-file = "SKILL.md"
+
+[custom]
+author = "ealt"

.claude/skills/walkthrough/modes/codebase-tour.md

@@ -0,0 +1,29 @@
+# Codebase Tour
+
+## Analysis
+
+Before writing, explore:
+- Directory structure and organization patterns
+- Entry points (main files, command registration, route definitions)
+- Key abstractions and interfaces
+- Dependencies and how components connect
+
+## Frontmatter
+
+Point-in-time mode only — do **not** include base references (`baseBranch`, `baseCommit`, `pr`) in frontmatter.
+
+## Structure
+
+1. **Welcome/overview** (informational) — What the project does, who it's for, what you'll learn
+2. **Project structure** (informational) — Directory layout with brief descriptions
+3. **Entry point** — Where execution starts, bootstrap/initialization flow
+4. **Core concepts** — Major abstractions, one `##` per concept with `###` sub-steps for details
+5. **Common patterns** — Recurring patterns new readers should recognize (error handling, data flow, etc.)
+6. **Summary** (informational) — Recap and pointers to deeper walkthroughs or docs
+
+## Tips
+
+- Use `##` for major areas, `###` for specifics within each area
+- Start broad and zoom in — readers should understand the big picture before details
+- Include a directory tree in the project structure step's body (as a code block)
+- Link between steps when concepts reference each other

.claude/skills/walkthrough/modes/implementation-guide.md

@@ -0,0 +1,23 @@
+# Setup/Implementation Guide
+
+## Approach
+
+Structure the walkthrough chronologically — the reader follows steps in order to achieve a goal (setting up a dev environment, implementing a feature, configuring a system).
+
+## Frontmatter
+
+Point-in-time mode only. Do **not** include base references unless the guide specifically compares before/after states.
+
+## Structure
+
+1. **Prerequisites** (informational) — What the reader needs before starting: tools, access, background knowledge
+2. **Configuration** — Config files, environment variables, or settings to create/modify. Include the actual config content in code blocks within the step body.
+3. **Step-by-step implementation** — Use `##` for major phases, `###` for individual steps within each phase. Each step points to the relevant code location.
+4. **Verification/testing** — How to confirm the implementation works. Point to test files or show commands to run.
+
+## Tips
+
+- Use hierarchy for multi-phase setups: `##` per phase, `###` per step within
+- Include shell commands or config snippets in step bodies (as fenced code blocks) for anything the reader needs to run or create
+- Each step should be independently verifiable where possible — "after this step, you should see X"
+- Link to prerequisite steps when later steps depend on earlier ones

.claude/skills/walkthrough/modes/incident-trace.md

@@ -0,0 +1,24 @@
+# Incident/Debugging Trace
+
+## Approach
+
+Structure the walkthrough as an investigation narrative — the reader should follow the same reasoning path that leads to the root cause.
+
+## Frontmatter
+
+Include `incident: <id>` in frontmatter metadata if an incident ID is known. This becomes a metadata field in the converted walkthrough.
+
+## Structure
+
+1. **Symptom** (informational or with location) — What was observed? Error messages, unexpected behavior, metrics anomaly
+2. **Where to look** — Starting point for investigation based on the symptom. Show the code that's most likely involved.
+3. **Evidence chain** — Each step shows code that was examined and what was learned. Use `###` sub-steps to group hypothesis → supporting evidence.
+4. **Root cause** — The specific code (with location) that caused the issue, with explanation of *why* it fails
+5. **Fix/mitigation** — The fix or workaround, with location pointing to the corrected code (or suggested fix location)
+
+## Tips
+
+- Each step should advance the reader's understanding — don't include dead ends unless they teach something
+- Use hierarchy to group related investigation threads (e.g., `## Network layer investigation` with `### Connection pooling` and `### Timeout handling` underneath)
+- Include relevant log output, error messages, or metrics in code blocks within step bodies
+- If the incident is ongoing, the last step can be "Current status" rather than "Fix"

.claude/skills/walkthrough/modes/pr-review.md

@@ -0,0 +1,46 @@
+# PR Review (diff mode)
+
+## Data Gathering
+
+1. **Fetch PR data:**
+   ```bash
+   gh pr view $ARGUMENTS --json number,title,body,url,files
+   gh pr diff $ARGUMENTS
+   gh pr view $ARGUMENTS --json baseRefName
+   ```
+
+2. **Get changed files:**
+   ```bash
+   git diff --name-status <base>..<head>
+   ```
+   Categorize each file by its git status (A/D/M/R) — this determines which link types are required.
+
+## Frontmatter
+
+Include `baseBranch` (from the PR's base ref) or `pr` number in the YAML frontmatter to enable diff mode.
+
+## Coverage Rules
+
+**100% of changed files must be covered.** Every file in the diff must appear in at least one step with the correct link type:
+
+| Git status | Required links |
+|------------|---------------|
+| **A** (Added) | `[View code ...]` |
+| **D** (Deleted) | `[Base ...]` |
+| **M** (Modified) | Both `[View code ...]` AND `[Base ...]` |
+| **R** (Renamed) | `[Base ...]` for old path, `[View code ...]` for new path |
+
+Verify coverage before finalizing — every changed file path must appear in a location link somewhere in the walkthrough.
+
+## Structure
+
+1. **Overview** (informational) — PR purpose, scope, and key decisions
+2. **Grouped changes** — Organize by category (e.g., "API Changes", "Database Migrations", "UI Updates"). Use `##` for categories, `###` for individual file/change walkthroughs within each category.
+3. **Impact summary** (informational) — User-facing impact, developer impact, testing notes, and recommendation (approve/request changes/comment)
+
+## Tips
+
+- Read the PR description and comments for context on *why* changes were made
+- For modified files, explain what changed and why — not just what the code does now
+- Group related files together even if they're in different directories
+- Use the PR title as part of the walkthrough title: `# PR #<number>: <title>`

.claude/skills/walkthrough/modes/subsystem-tour.md

@@ -0,0 +1,26 @@
+# Focused Subsystem Tour
+
+## Scoping
+
+1. **Find relevant files:** Grep for the keyword (`$ARGUMENTS`) across the codebase
+2. **Filter:** Only include files directly relevant to the subsystem — resist the urge to explain the whole codebase
+3. **Trace:** Follow the subsystem's execution flow or data flow from entry to exit
+
+## Frontmatter
+
+Point-in-time mode only unless the user specifies a comparison. Do **not** include base references by default.
+
+## Structure
+
+1. **What it does** (informational) — Brief explanation of the subsystem's purpose and role in the larger system
+2. **Entry point** — Where this subsystem is invoked or where data enters
+3. **Core logic** — Main implementation, using `###` sub-steps for distinct phases or components
+4. **Integration points** — Where this subsystem connects to others (calls out, is called by, shared state)
+5. **Summary** (informational) — Key takeaways and pointers to related subsystems
+
+## Tips
+
+- Narrow scope: 5-10 files maximum for a focused tour
+- Follow the data — trace how input flows through the subsystem to output
+- Name steps after what the code *does*, not file names (e.g., "Validate JWT claims" not "jwt.ts")
+- If the subsystem spans many files, group by responsibility using hierarchy