Workthrough

This skill automatically generates detailed workthrough documentation for all development work, capturing the context, changes made, and verification results in a clear, structured format.

When to Use This Skill

Use this skill automatically after:

• Implementing new features or functionality
• Fixing bugs or errors
• Refactoring code
• Making configuration changes
• Updating dependencies
• Resolving build/compilation issues
• Any significant code modifications

Documentation Structure

The workthrough documentation follows this structure:

1. Title: Clear, descriptive title of the work completed 2. Overview: Brief summary of what was accomplished and why 3. Changes Made: Detailed breakdown of all modifications 4. Code Examples: Key code snippets showing important changes 5. Verification Results: Build/test results confirming success

Implementation Guidelines

When generating workthrough documentation:

1. Capture Complete Context

• What problem was being solved?
• What errors or issues existed before?
• What approach was taken?
• Why were specific decisions made?

2. Document All Changes Systematically

• List each file modified with full paths
• Describe what changed in each file
• Include before/after code snippets for significant changes
• Note any dependencies added or removed
• Document configuration updates

3. Show Code Examples

Use clear, well-formatted code blocks:

// file: src/path/to/file.tsx
<div className="example">
  {/* Show relevant code changes */}
</div>

4. Include Verification

• Build output showing success
• Test results
• Error messages (if any remain)
• Exit codes
• Screenshots (if relevant)

5. Use Clear Formatting

• Use markdown headers (##, ###)
• Use bullet points and numbered lists
• Use code blocks with syntax highlighting
• Use blockquotes for output/logs
• Keep paragraphs concise

Document Organization

Save workthrough documents with this naming convention:

workthrough/YYYY-MM-DD-brief-description.md

Or organize by feature/project:

workthrough/feature-name/implementation.md
workthrough/bugfix/issue-123.md

Example Workthrough Structure

# [Clear Descriptive Title]

## Overview
Brief 2-3 sentence summary of what was accomplished.

## Context
- Why was this work needed?
- What was the initial problem/requirement?
- Any relevant background information

## Changes Made

### 1. [First Major Change]
- Specific modification 1
- Specific modification 2
- File: `path/to/file.tsx`

### 2. [Second Major Change]
- Specific modification 1
- File: `path/to/another-file.ts`

### 3. [Additional Changes]
- Dependencies added: `package-name@version`
- Configuration updates: `config-file.json`

## Code Examples

### [Feature/Fix Name]

// src/path/to/file.tsx const example = () => { // Show the key code changes }

## Verification Results

### Build Verification

build command output

✓ Compiled successfully Exit code: 0

### Test Results

test command output

All tests passed

## Next Steps
- Any follow-up tasks needed
- Known limitations or future improvements

Automation Instructions

After completing ANY development work:

1. Gather Information

• Review all files modified during the session
• Collect build/test output
• Identify the main objective that was accomplished

2. Create Document

• Generate workthrough document in workthrough/ directory
• Use timestamp or descriptive filename
• Follow the structure guidelines above

3. Be Comprehensive

• Include all relevant details
• Don't assume future readers have context
• Document decisions and reasoning
• Show concrete examples

4. Verify Completeness

• Confirm all changes are documented
• Include verification results
• Add any relevant warnings or notes

Quality Standards

Good workthrough documentation should:

• Be readable by other developers
• Provide enough detail to understand changes
• Include verification that changes work
• Serve as a reference for similar future work
• Capture important decisions and context

Avoid:

• Overly verbose descriptions
• Unnecessary technical jargon
• Missing verification steps
• Vague or unclear explanations
• Incomplete code examples

Output Location

Unless specified otherwise, save workthrough documents to:

workthrough/YYYY-MM-DD-brief-description.md

Create the workthrough/ directory if it doesn't exist.

Integration with Workflow

This skill should be triggered automatically at the end of development sessions. The documentation serves as:

• A development log/journal
• Knowledge base for the project
• Onboarding material for new developers
• Reference for debugging similar issues
• Record of architectural decisions

Remember: Good documentation is a gift to your future self and your team.

Workthrough Documentation Examples

This file contains examples of well-structured workthrough documentation for various types of development work.

Example 1: Bug Fix

# Fixed Build Errors and Layout Issues in Classroom App

## Overview
Resolved JSX syntax errors and missing component dependencies that prevented the build from succeeding. Also restructured the classroom layout to properly display chat sidebar alongside video area.

## Context
- **Problem**: Build failed with multiple errors including JSX syntax issues and missing Radix UI components
- **Initial State**: Cannot run production build, chat layout overlapping video area
- **Approach**: Fix syntax errors first, add missing dependencies, then refactor layout structure

## Changes Made

### 1. Fixed JSX Syntax Error
- **File**: `src/app/(classroom)/classroom/[id]/page.tsx`
- **Issue**: Extra closing `</div>` tag causing parse error
- **Fix**: Removed redundant closing tag at line 127

### 2. Added Missing UI Components
- **Description**: RadioGroup and ScrollArea components were imported but not defined
- **Packages Added**:
  - `@radix-ui/react-radio-group@^1.1.3`
  - `@radix-ui/react-scroll-area@^1.0.5`
- **Files Created**:
  - `src/components/ui/radio-group.tsx` - RadioGroup primitive wrapper
  - `src/components/ui/scroll-area.tsx` - ScrollArea primitive wrapper

### 3. Restructured Classroom Layout
- **File**: `src/app/(classroom)/classroom/[id]/page.tsx`
- **Change**: Wrapped video area in flex container to enforce side-by-side layout
- **Result**: Chat sidebar now properly positioned to the right of video

## Code Examples

### Layout Restructure

// src/app/(classroom)/classroom/[id]/page.tsx (lines 45-60) <div className="flex-1 flex overflow-hidden relative"> {/ New wrapper for video area /} <div className="flex-1 relative"> <VideoPlaceholder /> <UserPIP /> <ClassroomControls /> </div>

{/ Chat sidebar as sibling /} <ChatSidebar /> </div>

## Verification Results

### Build Verification

pnpm build

▲ Next.js 16.0.3 (Turbopack)

• Environments: .env.local

Creating an optimized production build ... ✓ Compiled successfully ✓ Linting and checking validity of types ✓ Collecting page data ✓ Generating static pages (12/12) ✓ Finalizing page optimization

Exit code: 0

### Manual Testing
- [x] Chat sidebar displays correctly on right side
- [x] Video area maintains proper aspect ratio
- [x] No layout shift during interaction
- [x] Responsive behavior works as expected

## Next Steps
- Consider adding tests for layout components
- Document the layout pattern for future pages

Example 2: Feature Implementation

# Implemented User Authentication with NextAuth.js

## Overview
Added complete authentication system using NextAuth.js with Google OAuth provider, protected routes, and session management across the application.

## Context
- **Requirement**: Users need to sign in to access classroom features
- **Initial State**: No authentication, all routes publicly accessible
- **Approach**: Integrate NextAuth.js with App Router, use Google OAuth for simplicity

## Changes Made

### 1. NextAuth.js Setup
- **Packages Added**:
  - `next-auth@^5.0.0-beta.4` - Authentication for Next.js 14+
  - `@auth/prisma-adapter@^1.0.0` - Database adapter
- **Files Created**:
  - `src/app/api/auth/[...nextauth]/route.ts` - Auth API routes
  - `src/lib/auth.ts` - Auth configuration
  - `src/middleware.ts` - Route protection

### 2. Database Schema Updates
- **File**: `prisma/schema.prisma`
- **Changes**:
  - Added User, Account, Session, VerificationToken models
  - Configured relations for OAuth accounts
  - Set up session handling

### 3. Protected Routes Configuration
- **File**: `src/middleware.ts`
- **Protected Paths**:
  - `/classroom/*` - Requires authentication
  - `/dashboard/*` - Requires authentication
- **Public Paths**:
  - `/` - Landing page
  - `/api/auth/*` - Auth endpoints

### 4. UI Components
- **Files Created**:
  - `src/components/auth/SignInButton.tsx` - Google sign-in button
  - `src/components/auth/SignOutButton.tsx` - Sign out button
  - `src/components/auth/UserAvatar.tsx` - User profile display

## Code Examples

### Auth Configuration

// src/lib/auth.ts import { PrismaAdapter } from "@auth/prisma-adapter" import { AuthOptions } from "next-auth" import GoogleProvider from "next-auth/providers/google" import { prisma } from "./prisma"

export const authOptions: AuthOptions = { adapter: PrismaAdapter(prisma), providers: [ GoogleProvider({ clientId: process.env.GOOGLE_CLIENT_ID!, clientSecret: process.env.GOOGLE_CLIENT_SECRET!, }), ], callbacks: { session: async ({ session, user }) => { if (session?.user) { session.user.id = user.id } return session }, }, }

### Middleware for Route Protection

// src/middleware.ts import { withAuth } from "next-auth/middleware"

export default withAuth({ callbacks: { authorized: ({ token }) => !!token, }, })

export const config = { matcher: ["/classroom/:path", "/dashboard/:path"], }

## Verification Results

### Build Verification

pnpm build

✓ Compiled successfully ✓ Linting and checking validity of types ✓ Collecting page data ✓ Generating static pages (15/15)

Exit code: 0

### Database Migration

pnpm prisma migrate dev --name add_auth

Environment variables loaded from .env Prisma schema loaded from prisma/schema.prisma

✓ Generated Prisma Client ✓ Applied 1 migration

### Manual Testing
- [x] Google OAuth flow works correctly
- [x] User session persists across page refreshes
- [x] Protected routes redirect to sign-in
- [x] Sign out clears session properly
- [x] User avatar displays correct profile image

## Environment Variables Added

GOOGLE_CLIENT_ID="your-client-id" GOOGLE_CLIENT_SECRET="your-client-secret" NEXTAUTH_URL="http://localhost:3000" NEXTAUTH_SECRET="generated-secret"

## Next Steps
- [ ] Add email/password provider option
- [ ] Implement role-based access control
- [ ] Add user profile edit functionality
- [ ] Set up email verification flow

## References
- [NextAuth.js Documentation](https://next-auth.js.org/)
- [Prisma Adapter Guide](https://authjs.dev/reference/adapter/prisma)

Example 3: Refactoring

# Refactored State Management to Zustand

## Overview
Migrated global state management from React Context to Zustand for better performance and simpler code. Eliminated prop drilling and reduced unnecessary re-renders.

## Context
- **Problem**: Context causing excessive re-renders, prop drilling 4-5 levels deep
- **Initial State**: Multiple React Contexts, performance issues with large lists
- **Approach**: Migrate to Zustand with atomic state updates and selectors

## Changes Made

### 1. Installed Zustand
- **Package Added**: `zustand@^4.4.7`
- **Dev Dependency**: `@types/zustand@^3.5.0`

### 2. Created Store Modules
- **Files Created**:
  - `src/store/useUserStore.ts` - User/auth state
  - `src/store/useClassroomStore.ts` - Classroom data
  - `src/store/useChatStore.ts` - Chat messages
  - `src/store/useUIStore.ts` - UI state (modals, sidebar)

### 3. Removed Legacy Context
- **Files Deleted**:
  - `src/context/UserContext.tsx`
  - `src/context/ClassroomContext.tsx`
  - `src/context/ChatContext.tsx`
- **Provider Removed**: Removed nested providers from `src/app/layout.tsx`

### 4. Updated Components
- **Files Modified** (15 files):
  - Replaced `useContext` hooks with Zustand selectors
  - Removed unnecessary wrapper components
  - Simplified component props by removing state drilling

## Code Examples

### Zustand Store Implementation

// src/store/useClassroomStore.ts import { create } from 'zustand' import { devtools, persist } from 'zustand/middleware'

interface ClassroomState { currentRoom: string | null participants: User[] setCurrentRoom: (id: string) => void addParticipant: (user: User) => void removeParticipant: (userId: string) => void }

export const useClassroomStore = create<ClassroomState>()( devtools( persist( (set) => ({ currentRoom: null, participants: [], setCurrentRoom: (id) => set({ currentRoom: id }), addParticipant: (user) => set((state) => ({ participants: [...state.participants, user] })), removeParticipant: (userId) => set((state) => ({ participants: state.participants.filter(p => p.id !== userId) })), }), { name: 'classroom-storage' } ) ) )

### Component Before (Context)

// Before: src/components/ParticipantList.tsx import { useClassroom } from '@/context/ClassroomContext'

export function ParticipantList() { const { participants, removeParticipant } = useClassroom() // Component implementation }

### Component After (Zustand)

// After: src/components/ParticipantList.tsx import { useClassroomStore } from '@/store/useClassroomStore'

export function ParticipantList() { // Only subscribe to needed state const participants = useClassroomStore((state) => state.participants) const removeParticipant = useClassroomStore((state) => state.removeParticipant) // Component implementation }

## Performance Comparison

### Before (React Context)
- Re-renders: 47 per interaction
- Memory: ~8.2MB for state tree
- Update latency: ~120ms average

### After (Zustand)
- Re-renders: 3 per interaction (85% reduction)
- Memory: ~2.1MB for state tree (74% reduction)
- Update latency: ~15ms average (87% improvement)

## Verification Results

### Build Verification

pnpm build

✓ Compiled successfully ✓ Linting and checking validity of types

Exit code: 0

### Test Results

pnpm test

PASS src/store/useClassroomStore.test.ts PASS src/components/ParticipantList.test.tsx PASS src/components/ChatWindow.test.tsx

Test Suites: 12 passed, 12 total Tests: 89 passed, 89 total

### Browser Performance
- React DevTools Profiler shows significant render reduction
- Chrome Performance tab shows smoother frame rates
- No memory leaks detected in 10-minute stress test

## Migration Notes
- Zustand DevTools enabled in development for debugging
- State persisted to localStorage for user/UI stores
- Maintained same API surface where possible for easier migration
- All component tests updated and passing

## Next Steps
- [x] Update team documentation on state management patterns
- [ ] Consider adding Immer middleware for complex nested updates
- [ ] Explore time-travel debugging capabilities

## References
- [Zustand Documentation](https://github.com/pmndrs/zustand)
- [React Re-render Optimization Guide](https://react.dev/learn/render-and-commit)

Best Practices Demonstrated

✅ Good Documentation Includes:

1. Clear Context: Why the work was needed 2. Detailed Changes: What specifically changed 3. Code Examples: Show actual implementation 4. Verification: Prove it works with output 5. Metrics: When relevant (performance, before/after) 6. Next Steps: What remains to be done

❌ Avoid:

1. Vague descriptions: "Fixed some bugs" 2. Missing verification: No build/test output 3. No context: Jumping straight to code without explanation 4. Incomplete examples: Code snippets without file paths 5. No follow-up: Not mentioning remaining work

Using These Examples

When creating workthrough documentation: 1. Choose the example that matches your work type 2. Adapt the structure to your specific changes 3. Maintain the level of detail shown 4. Include concrete verification results 5. Be honest about what's done and what remains

Workthrough Skill - Quick Start Guide

What is This?

The workthrough skill automatically documents all your development work in a structured, professional format. Think of it as an AI-powered development journal.

How It Works

After you complete any coding task, Claude will automatically: 1. ✅ Analyze what changed 2. ✅ Create structured documentation 3. ✅ Include code examples 4. ✅ Add verification results 5. ✅ Save to workthrough/ directory

When Does It Activate?

The skill triggers automatically after:

• ✨ Implementing new features
• 🐛 Fixing bugs or errors
• ♻️ Refactoring code
• ⚙️ Changing configurations
• 📦 Updating dependencies
• 🔧 Resolving build issues

Example Usage

You say:

"Fix the build errors in the classroom app and make the chat sidebar display properly"

Claude does the work, then automatically creates:

workthrough/2025-11-19-classroom-build-fixes.md

The document includes:

• Overview of what was fixed
• All files that were changed
• Code examples showing the fixes
• Build verification output
• Any remaining tasks

Output Location

Documents are saved as:

workthrough/YYYY-MM-DD-brief-description.md

Benefits

For You

• 📝 No manual documentation needed
• 🧠 Never forget why you made changes
• 🔍 Easy to search past solutions
• ⚡ Quick reference for similar issues

For Your Team

• 👥 Better knowledge sharing
• 🎯 Clear development history
• 🚀 Easier onboarding for new members
• 📊 Visible progress tracking

What Gets Documented?

Context

• Why the work was needed
• What the problem was
• What approach was taken

Changes

• Every file modified
• Dependencies added/removed
• Configuration updates
• Code refactoring details

Verification

• Build output showing success
• Test results
• Error messages (if any)
• Manual testing checklist

Examples

• Before/after code snippets
• Key implementations
• File paths and line numbers

Customization

You can customize the output by:

1. Specifying location:

"Save the workthrough doc in docs/development/"

2. Requesting specific format:

"Make the workthrough more concise" or "Include more technical details"

3. Adding sections:

"Include a section on performance impact"

Files in This Skill

• SKILL.md - Main skill instructions for Claude
• README.md - Detailed overview and benefits
• TEMPLATE.md - Blank template for documentation
• EXAMPLES.md - Real-world examples
• QUICKSTART.md - This file!
• LICENSE.txt - MIT license

Tips for Best Results

✅ Do:

• Let Claude work naturally and document automatically
• Review generated docs occasionally for quality
• Use workthrough docs during code reviews
• Reference them when debugging similar issues

❌ Don't:

• Try to manually create workthrough docs (Claude does this)
• Delete workthroughs too quickly (they're your project history)
• Worry about format - Claude handles it consistently

Sample Workthrough

Check out test.md for a real example of what gets generated.

Getting Started

You're already set up! Just start coding, and Claude will automatically document your work in the workthrough/ directory.

No configuration needed. No manual steps. Just build, and the documentation happens automatically.

---

Questions or Issues?

• See EXAMPLES.md for detailed examples
• Check README.md for comprehensive documentation
• Review TEMPLATE.md to understand the structure

Workthrough Documentation Skill

Automatically generate comprehensive documentation for all development work in a structured "workthrough" format.

Purpose

This skill helps maintain a detailed record of all development activities by automatically creating structured documentation after completing coding tasks. Think of it as an automated development journal that captures context, changes, and verification results.

What Gets Documented

• Feature implementations
• Bug fixes and error resolutions
• Code refactoring
• Configuration changes
• Dependency updates
• Build/compilation issue fixes
• Architecture changes

Key Benefits

1. Knowledge Retention: Capture important decisions and context while fresh 2. Team Communication: Share detailed progress with team members 3. Debugging Reference: Quickly recall how similar issues were solved 4. Onboarding: Help new developers understand project evolution 5. Project History: Maintain a readable development timeline

Usage

The skill activates automatically after development work is completed. Claude will:

1. Analyze all changes made during the session 2. Generate structured documentation following the workthrough template 3. Include code examples and verification results 4. Save to the workthrough/ directory with a timestamped filename

Example Output

See the test example in workthrougt-test/test.md which demonstrates:

• Clear title and overview
• Systematic documentation of changes
• Code examples with file paths
• Build verification results
• Professional formatting

File Organization

Documents are saved as:

workthrough/YYYY-MM-DD-brief-description.md

Or organized by feature:

workthrough/feature-name/implementation.md
workthrough/bugfix/issue-123.md

Integration

This skill works seamlessly with your existing workflow:

• No manual intervention required
• Activates automatically after development tasks
• Creates documentation in parallel with coding
• Captures both successes and failures (for learning)

Quality Guidelines

Good workthrough docs should:

• ✅ Explain the "why" behind changes
• ✅ Include concrete code examples
• ✅ Show verification/test results
• ✅ Be readable by other developers
• ✅ Capture important decisions

Avoid:

• ❌ Overly verbose descriptions
• ❌ Missing context or reasoning
• ❌ Incomplete verification steps
• ❌ Vague explanations

Tips

• Review generated docs occasionally to ensure quality
• Use workthrough docs during code reviews
• Reference past workthroughs when facing similar issues
• Archive old workthroughs periodically to keep repo clean
• Share particularly useful workthroughs with the team

License

MIT - Feel free to customize and adapt for your needs.

[Clear Descriptive Title of Work Completed]

Overview

[2-3 sentence summary of what was accomplished and why it was needed]

Context

• Problem/Requirement: [What issue was being addressed?]
• Initial State: [What was the situation before changes?]
• Approach: [High-level strategy taken]

Changes Made

1. [First Major Change Category]

• Description: [What was changed]
• Files Modified:
• path/to/file1.tsx - [Brief description]
• path/to/file2.ts - [Brief description]
• Key Points:
• [Important detail 1]
• [Important detail 2]

2. [Second Major Change Category]

• Description: [What was changed]
• Files Modified:
• path/to/file3.tsx - [Brief description]
• Rationale: [Why this approach was chosen]

3. [Dependencies/Configuration Changes]

• Packages Added:
• package-name@version - [Purpose]
• Packages Removed:
• old-package - [Reason for removal]
• Configuration Updates:
• config.json - [What changed]

Code Examples

[Feature/Component Name]

// src/path/to/file.tsx
[Show relevant code that illustrates the change]

// Before (if applicable)
const oldImplementation = () => {
  // Previous approach
}

// After
const newImplementation = () => {
  // Improved approach
}

[Another Key Change]

/* src/styles/component.css */
.new-class {
  /* CSS changes that are significant */
}

Verification Results

Build Verification

> pnpm build
   ▲ Next.js 16.0.3 (Turbopack)
   Creating an optimized production build ...
 ✓ Compiled successfully
 ...
Exit code: 0

Test Results

> pnpm test
 PASS  src/components/Example.test.tsx
 ✓ All tests passed

Test Suites: 5 passed, 5 total
Tests:       23 passed, 23 total

Manual Testing

• [x] Feature works as expected in development
• [x] No console errors or warnings
• [x] Responsive design verified
• [x] Cross-browser compatibility checked

Issues Encountered & Solutions

Issue 1: [Description of problem]

Error:

[Error message or description]

Solution: [How it was resolved]

Issue 2: [Another problem]

Solution: [Resolution steps]

Next Steps

• [ ] [Any follow-up tasks needed]
• [ ] [Performance optimization opportunities]
• [ ] [Future enhancements to consider]

Notes

• [Any important caveats or warnings]
• [Edge cases to be aware of]
• [Documentation updates needed]

References

• [Link to related PRs]
• [Documentation references]
• [External resources consulted]