specsmd 0.0.0-dev.41 → 0.0.0-dev.42

package/flows/fire/agents/builder/skills/walkthrough-generate/SKILL.md

@@ -0,0 +1,140 @@
+# Skill: Walkthrough Generate
+
+Generate implementation walkthrough for human review after run completion.
+
+---
+
+## Trigger
+
+- Run completed successfully
+- Invoked by run-execute skill
+
+---
+
+## Degrees of Freedom
+
+**LOW** — Follow walkthrough structure precisely. Be thorough but concise.
+
+---
+
+## Workflow
+
+```xml
+<skill name="walkthrough-generate">
+
+  <mandate>
+    ALWAYS generate walkthrough after run completion.
+    Document DECISIONS, not just changes.
+    Include verification steps - how to test this works.
+  </mandate>
+
+  <step n="1" title="Gather Implementation Data">
+    <action>Read run log from .specs-fire/runs/{run-id}/run.md</action>
+    <action>Collect:</action>
+    <substep>Work item details (id, title, intent)</substep>
+    <substep>Files created during implementation</substep>
+    <substep>Files modified during implementation</substep>
+    <substep>Decisions made during execution</substep>
+    <substep>Tests added and coverage</substep>
+  </step>
+
+  <step n="2" title="Analyze Implementation">
+    <action>For each file created/modified:</action>
+    <substep>Identify purpose of the file</substep>
+    <substep>Summarize key changes</substep>
+    <substep>Note patterns or approaches used</substep>
+  </step>
+
+  <step n="3" title="Document Key Details">
+    <action>Extract implementation highlights:</action>
+    <substep>Main flow/algorithm implemented</substep>
+    <substep>Security considerations (if applicable)</substep>
+    <substep>Performance considerations (if applicable)</substep>
+    <substep>Integration points with existing code</substep>
+  </step>
+
+  <step n="4" title="Create Verification Steps">
+    <action>Generate how-to-verify section:</action>
+    <substep>Commands to run the feature</substep>
+    <substep>Expected behavior/output</substep>
+    <substep>Manual test scenarios</substep>
+  </step>
+
+  <step n="5" title="Generate Walkthrough">
+    <action script="scripts/render-walkthrough.ts">Render walkthrough from template</action>
+    <action>Save to: .specs-fire/runs/{run-id}/walkthrough.md</action>
+    <output>
+      Walkthrough generated: .specs-fire/runs/{run-id}/walkthrough.md
+    </output>
+  </step>
+
+</skill>
+```
+
+---
+
+## Output
+
+**Walkthrough** (`.specs-fire/runs/{run-id}/walkthrough.md`):
+
+```markdown
+---
+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}
+
+## Files Changed
+
+### Created
+
+| File | Purpose |
+|------|---------|
+| `{path}` | {purpose} |
+
+### Modified
+
+| File | Changes |
+|------|---------|
+| `{path}` | {changes} |
+
+## Key Implementation Details
+
+### 1. {Detail Title}
+
+{description of implementation approach}
+
+## Decisions Made
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| {decision} | {choice} | {rationale} |
+
+## How to Verify
+
+1. **{Step Title}**
+   ```bash
+   {command}
+   ```
+   Expected: {expected output}
+
+2. **{Step Title}**
+   {manual verification steps}
+
+## Test Coverage
+
+- Tests added: {count}
+- Coverage: {percentage}%
+- Status: {passing/failing}
+
+---
+*Generated by FIRE Run {run-id}*
+```