-
Notifications
You must be signed in to change notification settings - Fork 1
Example Org‐Babel Visual Recap SKILL.md (Agent‐Native Pattern)
name: visual-recap
description: Turn a PR, branch, commit, or git diff into a structured visual recap using Emacs Org-Babel, featuring file maps, API summaries, annotated diffs, and text-based wireframes.
The visual-recap tool creates a structural plan built from a diff. Instead of describing the change you are about to make, you describe the change that was just made, at a higher altitude than line-by-line review. The deliverable is a comprehensive Emacs Org-Babel file that summarises the work. A reviewer scans the shape of the change before spending attention on the literal lines.
The deliverable is always an Org-Babel document written directly to the workspace using the write_file_in_workspace tool.
Read the diff, stat, and source context from the local repository using read_file_in_workspace for the requested patc. Do not improvise an inline chat summary. A recap exists entirely as the structured Org-Babel document.
Use standard and idiomatic Org-Babel syntax. Use asterisks for headings, lower-case #+begin_src for code blocks, Org tables for schemas, and #+begin_example for text-based UI wireframes. When finished, use write_file_in_workspace.
Build a recap when a patch is large, touches multiple files, or alters the schema, API contracts, or architecture. Reviewers benefit from seeing the change mapped structurally before reading the raw diff. Skip this process for small, single-file, or obvious diffs. A tiny change reviews faster as a plain diff.
A strong recap follows one Org-Babel skeleton from top to bottom.
First, document the UI impact using text-based wireframes inside example blocks, but only when the diff changed the rendered user interface.
Second, provide an outcome narrative detailing what changed and why using one to three paragraphs of prose.
Third, detail the data model and API changes using Org tables and #+begin_src blocks for schema or contract changes. Default to Rust syntax for backend logic if no other language is in context.
Fourth, list the changed files with their status flags using standard Org lists.
Finally, highlight the key changes using #+begin_src diff blocks for the load-bearing code.
Keep the budgets reviewable by including three to eight key-change diff blocks. Fewer than three on a large change under-serves the reviewer, while more than eight stops being a summary. Keep each diff focused, preferring under 150 lines per block, and summarise the rest.
Map each kind of change to the Org structure that carries it, derived mechanically from the actual diff.
For schema or migration changes, use Org tables. Flag what moved per field or entity as added, modified, or removed.
For API, action, or route changes, use level-2 headings. Document the method, path, and parameters. Use #+begin_src json to show exact request and response payloads, keeping examples as single parseable JSON values.
For added, removed, or renamed files, use standard Org lists. Prefix each item with a status flag such as added, modified, or deleted.
For any meaningful code hunk, use #+begin_src diff. Provide a concise Org text annotation immediately above the block explaining why the hunk matters.
For rendered UI or interaction changes, use #+begin_example blocks containing ASCII or plain text structural wireframes.
When the diff changes the rendered UI, layout, visual state, interaction affordances, or navigation, the recap must include wireframes within #+begin_example blocks.
A wireframe is a semantic text mockup. Write plain structural representations of the user interface.
Use standard characters to draw boxes, buttons, and layout elements.
Modify rather than redesign. When changing an existing screen, reproduce the current screen's real layout first, then change only the delta.
Show a top-to-bottom or side-by-side comparison to highlight the before and after states so the reviewer can instantly see the delta.
Compose enough realistic text to fill the structure.
#+begin_example
+-------------------------------------------------+
| BEFORE |
| |
| Contacts |
| [ New contact ] |
| |
| > Jane Cooper > Marcus Lee |
+-------------------------------------------------+
+-------------------------------------------------+
| AFTER |
| |
| Contacts [ Import ] |
| [ New contact ] |
| |
| > Jane Cooper > Marcus Lee |
+-------------------------------------------------+
#+end_example