Create Walkthrough Artifact

Generate .agent/{branch-name}/walkthrough.md — the final summary for PR delivery.

Prerequisites

Before invoking this skill:

1. All tests must be passing
2. Documentation must be updated
3. plan.md must exist and have an up-to-date Progress Log
4. You must be inside the worktree

Procedure

Step 1: Determine file location and gather information

Run this command to get the artifact path and gather git information — do NOT guess the branch name:

BRANCH=$(git branch --show-current) && mkdir -p ".agent/${BRANCH}" && echo "Artifact path: .agent/${BRANCH}/walkthrough.md" && echo "---" && git diff --stat main...HEAD && echo "---" && git log --oneline main...HEAD

From plan.md (read the file — must run in the same shell session as above, or re-assign BRANCH):

BRANCH=$(git branch --show-current) && cat ".agent/${BRANCH}/plan.md"

Extract: Summary, Decisions, Requirements, File Changes table.

From test results:

Recall or re-run the test suite to confirm current status.

Step 2: Write walkthrough.md

Create the file at the path from Step 1 using the template below. Do NOT hardcode or guess the branch name.

Step 3: Present to user

After writing the file, output the walkthrough content directly in the conversation so the user sees it immediately.

Template

All timestamps MUST use full ISO 8601 with time: YYYY-MM-DDTHH:MM:SSZ

---
created: { TIMESTAMP }
branch: { BRANCH }
task: { TASK_DESCRIPTION }
pr: { PR_NUMBER }
---

# Walkthrough: {TASK_DESCRIPTION}

## Quick Reference

- **Branch**: `{BRANCH}`
- **PR**: #{PR_NUMBER}
- **Worktree**: `{WORKTREE_PATH}`

## Summary

<!-- 2-3 sentences: what was implemented and the key outcome -->

## Changes

| File | Change | Purpose |
| ---- | ------ | ------- |

<!-- List ALL modified/created/deleted files from git diff -->

## Key Decisions

<!-- Numbered list of important decisions made during implementation.
     Pull from plan.md Decisions table — include only the most significant ones. -->

1. {decision and brief rationale}

## Testing Results

<!-- Test outcomes with pass/fail indicators -->

- [x] {test category}: {result summary}
- [x] {test category}: {result summary}

## How to Verify

<!-- Step-by-step instructions for a reviewer to verify the changes work -->

1. {step}
2. {step}
3. {step}

## Next Steps

1. Review draft PR
2. Mark as ready for review
3. After merge: `gw remove {BRANCH}`

Validation Checklist

After writing walkthrough.md, verify:

• File location: Path from git branch --show-current — inside the worktree
• Frontmatter: created, branch, task, pr — all filled
• Timestamps: ISO 8601 with time
• Summary: Concise, describes what was done and the outcome
• Changes table: Matches actual git diff --stat output (no missing files)
• Key Decisions: Pulled from plan.md, covers the important choices
• Testing Results: Reflects actual test run outcomes
• How to Verify: Actionable steps a reviewer can follow
• Presented to user: Walkthrough content shown in conversation (not just written to file)

Delivery

The walkthrough is delivered in two ways:

1. File — saved to .agent/{branch-name}/walkthrough.md for reference and handoff
2. Inline — presented in the conversation with PR link so the user sees the summary immediately

Both are mandatory. Do not announce completion without showing the walkthrough.