walkthrough

name	walkthrough
description	Generate a narrative summary and visual storyboard (browser screenshots) of completed changes and sync it to the Linear issue. Use after implementation to produce a human-readable walkthrough and visual proof of what was built for reviewers and stakeholders.

You are running the walkthrough skill. Your goal is to provide a "Visual Storyboard" and a concise narrative summary of the work just completed.

1. Context Gathering

• Ask for the Linear issue key if not known.
• Fetch the issue description via Linear MCP.
• Identify Worktree:
  • Check if the current directory is a git worktree root (e.g., git rev-parse --is-inside-work-tree).
  • Search the issue description for a "Worktrees" note or section that specifies where the work was performed.
  • If a worktree path is found (e.g., worktrees/feature/LIN-123) and you are not already there, cd into it.
  • Verify that the current branch in the worktree matches the expected issue key.
• Review the implemented changes using the git history:

  !{git diff origin/development..HEAD --stat}
  

2. Narrative Summary

Write a 2-3 paragraph "Walkthrough" summary that explains:

• The Problem: Briefly restate the goal.
• The Solution: How the implementation addresses the goal.
• Key Changes: Highlight the most important logic or UI updates. This summary should be high-level and suitable for a reviewer or stakeholder.

3. Visual Storyboard (Browser Automation)

If the changes involve UI elements (React, HTML, CSS), you MUST create a visual storyboard:

1. Setup: Identify the local development URL (default to http://localhost:3000).
2. Targeting Changes:
   • Extract keywords from the git diff (e.g., new button labels, component names, updated text).
   • Use browser:new_page to open the app.
   • Use browser:take_snapshot to get the unique IDs (uids) of elements on the page.
   • Match your keywords against the snapshot to find the uids of the elements you changed.
3. Scroll & Capture:
   • For each relevant element found:
     • Use browser:evaluate_script with the element's uid to scroll it into the center of the viewport: (el) => el.scrollIntoView({ behavior: 'smooth', block: 'center' }).
     • Wait a moment for any animations to finish.
     • Use browser:take_screenshot (without fullPage=true) to capture the specific context of that change.
4. Action Loop:
   • Use browser:click or browser:hover to demonstrate interactivity if applicable, scrolling to the next target as needed.

4. Sync to Linear

• Update the Linear issue description.

• Insert a ## Walkthrough section at the end of the description.

• Include the narrative summary.

• Storyboard Gallery: Embed the screenshots in a numbered list or gallery format: "### 🎬 Visual Storyboard

  1. Landing: [Brief description of the screenshot]
  2. Interaction: [Brief description of what happened]"

• Upload Attachments:we do not upload the screenshot to linear (the attachment tool is currently not working).

5. Local Walkthrough Artifact

• Create a walkthrough.md file in the root of the current worktree (or project root if not using worktrees).
• This file should contain:
  • The narrative summary.
  • The visual storyboard with local relative paths to the screenshots.
• Ensure the screenshot files are saved in a stable location (e.g., ./walkthrough/ within the worktree) and referenced correctly in the markdown.

6. GIF Creation (Optional)

If multiple screenshots were taken and ffmpeg is available on the system:

• Suggest creating a walkthrough.gif to the user and ask for confirmation.
• If confirmed, run the shell command to generate and attach it to both the Linear issue and the local walkthrough.md.

Confirm once the walkthrough is synced, the local artifact is created, and the Linear issue is updated.