Reshape

reshape

Consumer-driven API review. Point it at a library the project depends on; it maps every call site, diagnoses the friction, and proposes the highest-impact changes to the library's API — the ones that would most simplify the code that uses it. It reasons only; it edits nothing.

Keep the proposals on the library surface. The consumer simplification is the payoff shown in before/after, not the change itself — never propose refactoring only the call sites with the API left as-is.

Sources of truth:

• ../style/SKILL.md (eager) — Go idioms the proposals must respect (accept

interfaces, functional options, %w, ErrXxx, useful zero value).

• [references/change-catalog.md](references/change-catalog.md) (on-demand: per

archetype) — each archetype's detail + Go example, keyed to the list below. Consult an entry when drafting that proposal; don't preload it.

Target

Resolve the invocation:

• library — reshape where `` is an import path

(github.com/x/y/pkg/must), a module path, or a short package name the project imports. Consumer scope defaults to the current module.

• scoped — reshape in ./pkg/foo restricts the consumer to that

package (or path list).

• Control: max=N caps the proposals reported (default 8), highest impact first.

State the resolved library, the consumer scope, and the call-site count before proposing.

Modifiability

Detect whether the library source is editable, and say which:

• local — in this repo, reachable via a replace directive, or a go.work

module. Source is readable → propose concrete signature/type diffs.

• external — a normal module dependency. Work from the public surface

(godoc / the exported API) → propose at the API-shape level; note you can't diff internals, and offer a local wrapper as the fallback when a proposal can't land upstream.

Workflow

High-freedom analysis — reason from the steps, the archetypes, and the rubric; no rigid script.

1. Resolve target + modifiability (above); list the symbols the consumer uses.
2. Map usage with the LSP tool: findReferences on each imported symbol

(workspaceSymbol/hover for shape), falling back to grep on the import path if no language server is configured. Record every call site.

1. Diagnose friction per usage pattern: repeated setup boilerplate, options

built inline, an interface the consumer declares itself, error-string matching, awkward multi-returns, type assertions, a hand-rolled loop that wants an iterator, test scaffolding the library could ship.

1. Brainstorm broadly across the archetypes below — force at least one

structural option, not only local tweaks.

1. Score and rank by the impact rubric.
2. Report (below). Change nothing.

Change archetypes

The brainstorm engine — reach past the obvious.

• options-constructor — functional options replace inline struct-building or

a long positional param list.

• default-away-a-param — a useful zero value removes an arg every call passes

the same.

• absorb-the-sequence — move a repeated call-site sequence into one library

call.

• batch-or-variadic — collapse a consumer loop into one call.
• iterator — a range-over-func replaces cursor/index boilerplate.
• result-type — return a named struct instead of an awkward multi-value tuple.
• sentinel-error — an ErrXxx + errors.Is support replaces string matching.
• expose-the-interface — ship the interface the consumer keeps re-declaring.
• testing-helper — ship a spy/fake/helper so consumers drop hand-rolled

scaffolding.

• builder — a fluent builder for staged config done awkwardly inline.
• split-the-god-func — separate the modes a consumer switches a flag on.
• invert-control — take a callback or return the finished value instead of

making the consumer orchestrate.

• generics — remove per-type duplication and call-site type assertions.
• move-responsibility-upstream — the library owns what consumers keep

reimplementing (retry, pagination, normalization).

• shed-a-leaky-return — drop an error that can't occur, or presentation the

caller shouldn't be forced to handle.

Impact rubric

Rank each candidate by net impact, biggest first:

• reach — how many call sites it simplifies (the LSP count).
• savings — boilerplate / lines / steps removed per site.
• quality — readability, testability, fewer error-prone steps.
• cost (discount) — API breakage (additive beats breaking), implementation

effort, blast radius on other consumers.

Net = reach × savings × quality, discounted by cost. Label each High / Med / Low and lead with the single biggest-impact change. A change that touches many sites and is additive outranks a flashy structural rewrite that breaks everyone.

Output

Open with the ranked payload — no preamble.

1. One line: library · consumer scope · modifiability · N call sites · M proposals.
2. A table ranked by impact:

| # | Change (archetype) | Reach | Impact | Breakage | Effort |

1. Then each proposal, top-down:

• the API change — the new signature/type; a concrete diff when local, an

API-shape sketch when external;

• a representative call site before → after proving the payoff;
• one line tying it to the rubric (why this impact).

1. Note anything deferred or needing the user's judgment; for an external library

offer a local wrapper where an upstream change can't land.

Report tersely: no preamble or narration; state each fact once; don't restate output the user can already see.

Self-learning

Read this skill's lessons and obey them: sibling LESSONS.md, else $HOME/.agent-data/ctx42-skills/lessons/golang/reshape.md when this directory is read-only. On a correction or self-caught mistake, append a one-line rule to whichever is writable (creating it) and report where.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ctx42
• Source: ctx42/skills
• License: MIT

Install and usage instructions live in the source repository linked above.