walkthrough

name	walkthrough
description	Generate step-by-step walkthrough guides for testing features or bug fixes. Auto-detects code changes from git diff or PR. Use when the user asks to create testing instructions, QA documentation, or says "write a walkthrough" after implementing a feature.
allowed-tools	Bash, Read, Grep, Glob, Write, AskUserQuestion
model	claude-sonnet-4-6
context	fork

Feature Walkthrough Generator

You are generating a comprehensive, step-by-step walkthrough guide for manually testing a feature or bug fix.

Workflow

1. Detect Code Changes

First, check if there are staged changes:

• Run git status to see if there are staged files or changes
• If there are staged changes, read those files using the Read tool to understand what was changed
• If there are no staged changes, the code has been pushed:
  • Try to auto-detect the PR using gh pr view --json title,body,files for the current branch
  • Use git rev-parse --abbrev-ref HEAD to get the current branch name
  • If the gh command fails or returns no PR, ask the user for the PR number
  • Once you have the PR, use gh pr view <pr-number> --json title,body,files to get the PR details

2. Understand the Feature

Analyze the code changes to understand what was added/changed:

• Read the changed files to understand the implementation
• Look at route definitions, controllers, models, migrations, etc.
• Understand the complete scope of the feature

If you cannot clearly determine what was added/changed from the code alone:

• Ask the user BOTH of the following:
  1. "What does this feature do?" (description of functionality)
  2. "What's a short name for this feature?" (e.g., "User Authentication", "PDF Export")
• Use their answers combined with the code to fully understand the feature

3. Ask for Output Format

Present the user with a question asking how they want the walkthrough:

• Option A: Display the walkthrough in the current context (shown right here)
• Option B: Create a docs/walkthrough.md file (the docs directory will be created if it doesn't exist)

4. Generate the Comprehensive Walkthrough

Create a detailed, easy-to-follow testing guide that includes:

Setup Steps (if applicable):

• Any database migrations that need to be run
• Any seeding or data initialization required
• Any environment configuration needed
• Any build/compilation steps needed

Testing Instructions:

• Start from the application's home page or login page
• Provide numbered, sequential steps
• Include exactly what to click, what links to follow, what buttons to press
• Specify form fields to fill out and what values to enter
• Only include routes and pages related to testing this specific feature
• Include what the user should expect to see after each action

Data Setup:

• Include any test data creation that's needed to properly test the feature
• Explain how to create test records if needed (via forms, migrations, or commands)

Verification:

• At the end, include steps to verify the feature is working correctly
• Include expected outcomes

Format:

• Use numbered steps (1., 2., 3., etc.)
• Use clear, concise language
• Use bullet points for sub-steps or details
• Text-only format (minimal markdown formatting)
• Make it easy to follow without external documentation

5. Output the Walkthrough

If the user chose context display:

• Show the complete walkthrough in the conversation with clear formatting

If the user chose to create a file:

• Create the docs/ directory if it doesn't exist
• Create docs/walkthrough.md with the walkthrough content
• Include a header indicating what feature the walkthrough covers
• Confirm the file was created and show its location

Important Guidelines

• Explore the codebase before writing anything - Never assume how the application works, what routes exist, or how the UI is structured. Always read the relevant source files (routes, views, controllers, components, configs) to build an accurate picture of the current state of the project before generating any instructions. Outdated assumptions lead to misleading walkthroughs.
• Focus only on the new feature - Don't include unrelated features or general app navigation beyond what's needed
• Assume starting point is home page or appropriate entry point - Don't require knowledge of hidden pages
• Be thorough but concise - Include all necessary details but avoid redundancy
• Test-focused - Make the guide practical for someone testing, not documenting the code
• Include setup - Don't assume migrations are already run or test data exists
• Real world scenarios - Use realistic test data and workflows