melech-roi

Files (5)

• README.md
• SKILL.md
• melech-roi-tip-diagram.png · assets/
• analogies.md · references/
• output-examples.md · references/

SKILL.md (first lines)

# ROI

## The core question

The whole thing in one story:

> Your tap drips. Fix A reroutes the pipes for the whole house so that tap
> stops dripping. Fix B replaces the washer in that one tap. Both fix the
> drip. Only one of them means every future plumber has to understand the
> whole house's new plumbing just to work on a different tap someday.

That's it. That's the entire skill. It just asks, every time:

> **Are we rerouting the house, or replacing the washer?**

- **Replacing the washer** — a local, contained fix at the exact leak.
- **Rerouting the house** — a shared boundary, new persisted state, a new
  lifecycle, or broad blast radius, paid to fix one drip.

`melech-roi` exists to catch the second disguised as the first — on code that
already exists or on an idea that hasn't been coded yet. It evaluates the
solution in front of it; it does not design a replacement.

If the plumbing picture isn't landing for whoever you're talking to, four
other everyday pictures for the same question (packing, renovation permits,
toolbox, alterations) are in
[`references/analogies.md`](references/analogies.md).

## What it judges

**Benefit** — how real and large is the drip: severity, reach (how many
users/paths), frequency, durability of the fix, strategic value.

**Burden** — how much of the house does this reroute: shared boundaries
touched, new persisted state or lifecycle, regression exposure, new concepts a
future maintainer must learn, reversibility.

**Verdict** — does the burden match the benefit, or is the house being
rerouted for one drip?

**Receipt** — where the solution earned and lost ROI: problem reach versus
solution reach, value received, cost charged, and the largest charge.

## Sources you can point it at

- an existing PR (diff + description + discussion),
- a local diff (staged/unstaged, branch vs base),
- an idea or direction still only discussed in conversation — no diff exists
  yet, so flag confidence as lower and call assumptions out as assumptions.

Resolve the source from context. Ask only if genuinely ambiguous.

## Workflow

1. **Name the drip.** State the actual benefit being pursued in one line. If
   the benefit itself is unclear or unproven, mark confidence low and name the
   missing evidence. Do not silently invent benefit.
2. **Trace the touched surface.** For code: shared modules, persisted state,
   public contracts, new dependencies, call sites, concepts. For an idea:
   what it would require touching once built.
3. **Compare reach using the same unit.** Show who experiences the problem
   beside who must carry the solution: paths, callers, users, jobs, records, or
   another grounded unit. Use `unknown` rather than fake precision.
4. **Itemize the receipt.** List concrete value received and permanent costs
   charged. Mark cost severity `LOW`, `MEDIUM`, or `HIGH`.
5. **Find the largest charge.** State the single clearest source of
   disproportionality, or explain why the broad reach is justified.
6. **Grade the current solution.** The score measures proportionality, not how
   close the developer came to an imaginary perfect implementation.
7. **Rank only existing candidates.** If the PR or discussion already contains
   multiple concrete solutions, evaluate and rank those. Never invent an
   alternative to complete a ranking.
8. **Render the receipt.** Use the visual contract and adapt the examples in
   [`references/output-examples.md`](references/output-examples.md).

## Output shape

The default output is one itemized receipt:

1. solution name;
2. ROI score and letter grade;
3. rank only when two or more solutions were already raised;
4. problem-reach and solution-reach bars in a comparable unit;
5. value received;
6. cost charged with severity;
7. the largest charge;
8. a one-sentence verdict about the current solution.

The receipt diagnoses; it does not prescribe. Do not add a replacement design,
an improvement plan, or a "do this instead" section.

Interpret grades consistently:

- **A (85–100):** burden is clearly proportionate to the benefit.
- **B (70–84):** worthwhile with real but bounded cost.
- **C (55–69):** works, but has a meaningful reach or complexity mismatch.
- **D (40–54):** burden exceeds the demonstrated benefit.
- **F (0–39):** severely disproportionate or mostly unsupported.

Use `+` or `−` only to express a position near a grade boundary. A developer
does not need to reach 100; the grade answers whether this solution is
proportionate. The itemized charges explain why.

Read [`references/output-examples.md`](references/output-examples.md) before
rendering the result. It contains examples for disproportionate, justified,
operationally costly, ranked, and low-confidence solutions.

## Boundary with other skills

- **`melech-distill-need`** — establishes whether the drip is real when the
  benefit itself is in doubt.
- **`melech-8020`** — designs a cheaper shape after `melech-roi` diagnoses a
  mismatch. `melech-roi` itself does not propose that shape.
- **`melech-tidy`** — executes the adaptive diff reduction (purging dead residue,
  narrowing seam blast radius, and shaking prompt bloat) once `melech-roi` has
  graded the existing diff. `melech-roi` evaluates; `melech-tidy` changes.
- **`melech-challenge`** — pressure-tests a whole direction with open
  questions. `melech-roi` asks one narrower question: is the touched surface
  proportionate to the benefit.

From AdirD/agent-shell-hamelech, MIT.

More from AdirD/agent-shell-hamelech