documenting-work

Documenting Work

Overview

Generate comprehensive markdown documentation for work completed in the current session. Always ask the user where to save the documentation - do not assume a location.

When to Use

• User says "document this", "create docs", "write documentation"
• User says "finish" or "done" and wants documentation
• Before creating a PR and user wants documentation
• Anytime the user explicitly requests documentation of work

Workflow

Step 1: Ask for Documentation Location

Always ask the user where the documentation should go. Do NOT assume a path.

Where should I save the documentation? Please provide the file path (e.g., docs/features/feature-name.md)

Wait for user response before proceeding.

Step 2: Check if Path Exists

• If the file already exists: Ask if user wants to append/replace or choose different location
• If the folder doesn't exist: Ask user to confirm creation
• If path is valid and user confirms: Proceed to generate documentation

Step 3: Gather Session Information

Before writing documentation, summarize the current session:

1. Issue/Problem: What problem was being solved?
2. Fix/Solution: What was implemented?
3. Benefit/Impact: What value does this deliver?
4. Tradeoffs: What was sacrificed or compromised?
5. Possible Improvements: What could be done later?

Also gather:

• Context/Prerequisites: What was needed before this change?
• Testing: How was it verified?
• Related Files/Changes: What else was modified?
• Breaking Changes: Any compatibility concerns?
• User Instructions: How to use the feature
• Version Info: What version this lands in
• Links: Related issues/PRs (ask user or check git history)

Step 4: Generate Documentation

Create markdown documentation with the following structure:

# [Feature/Bug Fix Title]

## Overview
Brief description of what was done.

## Issue
Description of the problem or need that prompted this work.

## Solution
Description of what was implemented.

## Benefits / Impact
- Benefit 1
- Benefit 2

## Tradeoffs
- Tradeoff 1
- Tradeoff 2

## Context / Prerequisites
- Prerequisite 1
- Prerequisite 2

## Testing
How was this verified?

## Related Files / Changes
- File 1
- File 2

## Breaking Changes
Any compatibility concerns? (If none, state "None")

## User Instructions
How do users use this feature?

## Version
What version does this land in?

## Related Links
- Issue: [link]
- PR: [link]

## Possible Improvements
- Improvement 1
- Improvement 2

Step 5: Write to File

Write the documentation to the user-specified path. Confirm completion with the user.

Important Rules

• NEVER assume where documentation should go - always ask
• ALWAYS confirm if file already exists
• ALWAYS ask to create folder if it doesn't exist
• INCLUDE all sections listed above
• USE clear, concise language
• FORMAT as proper markdown with headers

Common Mistakes