Walkthroughs
Step-by-step guides documenting real work as it happens. Walkthroughs capture the exact process, decisions, and commands used to complete tasks in the EmProps monorepo.
What Are Walkthroughs?
Walkthroughs are live documentation that gets written and updated as we perform tasks. Unlike static guides or post-hoc changelogs, walkthroughs capture:
- Real-time decisions: Why we chose approach A over B at the moment
- Actual commands: The exact commands run, with their output
- Problem solving: Issues encountered and how they were resolved
- Learning moments: Insights discovered during the work
How Walkthroughs Differ
| Type | Purpose | When Written | Detail Level |
|---|---|---|---|
| Walkthrough | Document the journey | During work (live) | High - every step |
| Changelog | Record what changed | After completion | Medium - key changes |
| ADR | Explain architectural decision | Before or after | High - rationale focus |
| Guide | Teach how to do something | Anytime | Medium - reusable steps |
Available Walkthroughs
- Miniapp Monorepo Integration - Live integration of miniapp into turbo monorepo (January 2026)
Walkthrough Format
Each walkthrough follows this structure:
1. Context
- What are we trying to accomplish?
- Why is this work necessary?
- What's the starting state?
2. Live Work Log
- Command by command execution
- Decision points and rationale
- Problems encountered and solutions
- Real output and errors
3. Verification
- How did we confirm it worked?
- What tests did we run?
- What are the success criteria?
4. Reflection
- What did we learn?
- What would we do differently?
- What patterns emerged?
Using Walkthroughs
For Developers: Reference walkthroughs when doing similar work to see the exact steps and avoid common pitfalls.
For Learning: Read walkthroughs to understand not just what was done, but how and why decisions were made in the moment.
For Debugging: When something breaks, check if a walkthrough documents similar work to understand what might have changed.
Creating Walkthroughs
Walkthroughs are most valuable when written during the work, not after. The format is flexible:
- Start with context and goals
- Document each command and its output
- Explain decisions as you make them
- Note problems immediately when they occur
- Summarize learnings at the end
Keep it authentic - include mistakes, dead ends, and course corrections. That's where the real learning happens.