diff --git a/.claude/skills/walkthrough/SKILL.md b/.claude/skills/walkthrough/SKILL.md new file mode 100644 index 0000000..eaad8a6 --- /dev/null +++ b/.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: +--- + +# 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: +commit: +# For diff mode, add ONE of (priority: baseCommit > baseBranch > pr): +baseCommit: +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/.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/.md +``` + +**Naming conventions:** +- PR review: `pr-.md` +- Codebase tour: `architecture.md` +- Subsystem tour: `.md` +- Incident trace: `incident-.md` +- Implementation guide: `.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." diff --git a/.claude/skills/walkthrough/metadata.toml b/.claude/skills/walkthrough/metadata.toml new file mode 100644 index 0000000..33b5d49 --- /dev/null +++ b/.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" diff --git a/.claude/skills/walkthrough/modes/codebase-tour.md b/.claude/skills/walkthrough/modes/codebase-tour.md new file mode 100644 index 0000000..089076e --- /dev/null +++ b/.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 diff --git a/.claude/skills/walkthrough/modes/implementation-guide.md b/.claude/skills/walkthrough/modes/implementation-guide.md new file mode 100644 index 0000000..de23d45 --- /dev/null +++ b/.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 diff --git a/.claude/skills/walkthrough/modes/incident-trace.md b/.claude/skills/walkthrough/modes/incident-trace.md new file mode 100644 index 0000000..714c37e --- /dev/null +++ b/.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: ` 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" diff --git a/.claude/skills/walkthrough/modes/pr-review.md b/.claude/skills/walkthrough/modes/pr-review.md new file mode 100644 index 0000000..7aad8eb --- /dev/null +++ b/.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 .. + ``` + 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 #: ` diff --git a/.claude/skills/walkthrough/modes/subsystem-tour.md b/.claude/skills/walkthrough/modes/subsystem-tour.md new file mode 100644 index 0000000..32f6fcc --- /dev/null +++ b/.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