walkthrough-generate

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

<degrees_of_freedom> LOW — Follow walkthrough structure precisely. Be thorough but concise. </degrees_of_freedom>

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 generated: .specs-fire/runs/{run-id}/walkthrough.md

<output_template> 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}*

</output_template>

<success_criteria> 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 </success_criteria>