name: walkthrough-generate
description: Generate implementation walkthrough for human review after run completion. Documents decisions, changes, and verification steps.
version: 1.0.0
Generate implementation walkthrough for human review after run completion.
- Run completed successfully
- Invoked by run-execute skill
**LOW** — Follow walkthrough structure precisely. Be thorough but concise.
ALWAYS generate walkthrough after run completion
Document DECISIONS, not just changes
Include verification steps — how to test this works
Track DEVIATIONS from plan — compare to original work item
List ALL new dependencies added during implementation
Capture developer notes — gotchas save future debugging time
Read run log from .specs-fire/runs/{run-id}/run.md
Read work item plan from .specs-fire/intents/{intent}/work-items/{work-item}/
Collect:
Work item details (id, title, intent)
Files created during implementation
Files modified during implementation
Decisions made during execution
Tests added and coverage
Dependencies added (new packages in package.json, requirements.txt, etc.)
Deviations from the original work item plan
For each file created/modified:
Identify purpose of the file
Summarize key changes
Note patterns or approaches used
Document structure overview:
How the pieces fit together architecturally
Data flow or component relationships
Keep high-level, NO CODE
Identify architecture pattern (if multi-component):
Pattern used (Repository, Service Layer, MVC, Clean Architecture, etc.)
Layer structure diagram (ASCII) if applicable
Document domain model (if entities/models created):
Entities with properties and business rules
Value objects with constraints
Extract implementation highlights:
Main flow/algorithm implemented
Integration points with existing code
Document security considerations (if applicable):
Authentication/authorization approach
Input validation strategy
Data protection measures
Format as table: Concern | Approach
Document performance considerations (if applicable):
Optimization strategies used
Caching, indexing, or query optimization
Scalability approach
Format as table: Requirement | Implementation
Document deviations from plan:
Compare implementation to original work item plan
Note any changes and explain WHY they were made
If no deviations, state "None"
Capture developer notes:
Gotchas or non-obvious behaviors
Tips for future developers
Context that would save debugging time
Generate how-to-verify section:
Commands to run the feature
Expected behavior/output
Manual test scenarios
Evaluate implementation completeness:
All acceptance criteria met?
Tests passing?
No critical issues remaining?
Documentation updated (if applicable)?
Developer notes captured?
Generate checklist with [x] for met, [ ] for unmet
Generate walkthrough using template: templates/walkthrough.md.hbs
Include all sections (conditional sections only if data exists):
Architecture — only if multi-component with clear pattern
Domain Model — only if entities/value objects created
Security Considerations — only if security-relevant changes
Performance Considerations — only if performance-relevant changes
Save to: .specs-fire/runs/{run-id}/walkthrough.md
**Walkthrough** (`.specs-fire/runs/{run-id}/walkthrough.md`):
---
run: {run-id}
work_item: {work-item-id}
intent: {intent-id}
generated: {timestamp}
mode: {mode}
---
# Implementation Walkthrough: {title}
## Summary
{2-3 sentences describing what was implemented}
## Structure Overview
{High-level description of how pieces fit together - NO CODE}
## Architecture (if multi-component)
### Pattern Used
{Pattern and rationale - e.g., Repository pattern for data access abstraction}
### Layer Structure
```text
┌─────────────────────────────┐
│ Presentation │
├─────────────────────────────┤
│ Application │
├─────────────────────────────┤
│ Domain │
├─────────────────────────────┤
│ Infrastructure │
└─────────────────────────────┘
```
## Files Changed
### Created
| File | Purpose |
|------|---------|
| `{path}` | {purpose} |
### Modified
| File | Changes |
|------|---------|
| `{path}` | {changes} |
## Domain Model (if entities created)
### Entities
| Entity | Properties | Business Rules |
|--------|------------|----------------|
| {name} | {props} | {rules} |
### Value Objects
| Value Object | Properties | Constraints |
|--------------|------------|-------------|
| {name} | {props} | {constraints} |
## Key Implementation Details
### 1. {Detail Title}
{description of implementation approach}
## Security Considerations (if applicable)
| Concern | Approach |
|---------|----------|
| {concern} | {approach} |
## Performance Considerations (if applicable)
| Requirement | Implementation |
|-------------|----------------|
| {requirement} | {implementation} |
## Decisions Made
| Decision | Choice | Rationale |
|----------|--------|-----------|
| {decision} | {choice} | {rationale} |
## Deviations from Plan
{Changes from work item plan and why, or "None"}
## Dependencies Added
| Package | Why Needed |
|---------|------------|
| `{package}` | {reason} |
## How to Verify
1. **{Step Title}**
```bash
{command}
```
Expected: {expected output}
## Test Coverage
- Tests added: {count}
- Coverage: {percentage}%
- Status: {passing/failing}
## Ready for Review
- [x] All acceptance criteria met
- [x] Tests passing
- [x] No critical issues
- [ ] Documentation updated (if applicable)
- [x] Developer notes captured
## Developer Notes
{Gotchas, tips, or context for future work - keep brief}
---
*Generated by specs.md - fabriqa.ai FIRE Flow Run {run-id}*
Walkthrough generated with all applicable sections
Structure overview explains architecture (NO CODE)
Architecture pattern documented (if multi-component)
Domain model documented (if entities created)
Files changed documented with purposes
Security considerations documented (if security-relevant)
Performance considerations documented (if performance-relevant)
Decisions recorded with rationale
Deviations from plan documented (or "None")
Dependencies added listed with reasons
Verification steps included
Ready for Review checklist completed
Developer notes capture gotchas and tips
Saved to run folder
By