skills.rest
EpicenterHQ
EpicenterHQOFFICIAL
Explore all skills by this author →
Website𝕏@EpicenterHQGitHub

change-proposal

Presents proposed code changes as before/after diffs, ASCII diagrams, and comparison tables.

4.8k|376|Updated Mar 16, 2023
Search Tags:#diff#Refactoring#architecture diagram#change proposal#comparison table#Code review
One-click install
npx skills add https://github.com/EpicenterHQ/epicenter --skill change-proposal
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: change-proposal
Source: https://github.com/EpicenterHQ/epicenter/tree/main/.agents/skills/change-proposal
Command: npx skills add https://github.com/EpicenterHQ/epicenter --skill change-proposal

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Non-trivial code changes are hard to evaluate when described only in prose. This Skill makes reasoning visible before any file is edited, so reviewers can see what will change, why, and what alternatives were considered.

Core Features & Use Cases

  • Before/After Diffs: Shows the smallest meaningful fenced diff per file with enough context lines to understand placement.
  • ASCII Architecture Diagrams: Draws ownership and control-flow diagrams using box-drawing characters to show how components relate before and after a change.
  • Comparison Tables: Lays out competing approaches across trade-off dimensions, with the recommendation stated after the table.
  • Use Case: When refactoring a Svelte workspace module to move lifecycle ownership into an auth module, present a diagram of the new ownership, a diff of the hardest file, and a table comparing self-managed versus slot-based approaches before editing anything.

Quick Start

Ask the assistant to propose the refactor as a visual change proposal with diffs and a comparison table before making any edits.

Frequently Asked Questions about change-proposal

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I propose a code change before editing files?▼

Present a one-sentence summary, an architecture diagram showing before and after, concrete diffs for the hardest files, and an explicit trade-off list. End by asking whether to proceed with the recommendation or an alternative.

What should a good code change proposal include?▼

A good proposal includes a before/after diff with file paths and context lines, an ASCII ownership diagram, and a comparison table when multiple approaches exist. It leads with the recommendation rather than burying it.

When should I use a comparison table for code changes?▼

Use a comparison table whenever multiple approaches exist or an architecture decision is being made, even with only two options. Rows should be dimensions the reviewer cares about, columns the approaches, with the recommendation stated after the table.

How much detail should a change proposal show for large refactors?▼

Scale detail by scope: one file needs only a diff, two to five files need a diff plus one diagram, and five or more files need a full proposal with comparison table and diffs for the hardest two or three files.

Why are prose-only change proposals discouraged?▼

Prose descriptions force reviewers to mentally reconstruct the change, which hides trade-offs and invites miscommunication. Showing diffs and diagrams makes the exact edit visible and keeps fake precision out of the proposal.

Related Skills

Explore More Software Engineering Skills→
lightseekorglightseekorg
11

map

Map SMG crate ownership and inter-crate dependencies into a graph.

Official
Intermediate
mica-agentmica-agent

single-file-edit

Guide staged multi-file TypeScript edits with type-checking between changes.

Official
Intermediate
klaidliadonklaidliadon

go-style

Standardize Go code style across source files and reviews.

Community
Intermediate
abhishekmmgnabhishekmmgn

diagram

Convert text or Mermaid code into a diagram triplet with an editable Excalidraw file.

Community
Advanced