Skip to content
sdlc marketplace

api-enhancement-scan

Given a library or module name, survey every call site of it across the codebase — fanning out subagents over independent codebase sections — and surface recurring caller-side patterns (repeated boilerplate, copy-pasted wrappers, awkward argument plumbing, repeated post-processing) that a new or enhanced API on the called module would absorb. Returns ranked enhancement opportunities, each backed by real call-site citations. Use when asked to find API improvement or enhancement opportunities for a module, library, or package, to spot missing affordances, or to understand how a module is actually used by its callers. Pass --in to survey only named packages or directories instead of the whole project, and --workflow to have it propose a reusable Workflow script for the survey instead of running it ad hoc.

Plugincodebase
Invoke /codebase:api-enhancement-scan [module-or-library-name] [--in <path>…] [--workflow]
Allowed toolsRead Glob Grep Bash Task
SourceSKILL.md

Given a module or library, survey where the project’s own code works around its current API and turn those workarounds into concrete enhancement proposals.

Argument: the module/library/package name (or import path) to analyze.

Options:

  • --in <path>… — survey only these packages or directories. Repeatable, and accepts several paths in one flag. Defaults to the whole project.
  • --workflow — instead of running the survey ad hoc, propose a reusable Workflow script that performs it (see Step 6).

A path is never inferred from the positional argument: that argument names the module being analyzed, which may itself be an import path, so scope is only ever what --in says it is.

The rule that governs everything

The signal is not the call — it’s the glue around the call: the setup a caller writes before it, the argument-massaging it does to fit the current signature, the transformation it applies to the result, the guard it repeats. When the same glue appears at two or more independent call sites, the module is missing an affordance.

Every proposal must be backed by ≥2 real call sites cited as path:line. No speculative API design — if you can’t point at callers, don’t propose it.

The threshold counts call sites inside the surveyed scope, so a narrow --in cuts both ways: a pattern that recurs project-wide can look like a one-off, and one local to a single package can look universal. Say which it is when the scope is narrow enough for the distinction to matter.

Steps

  1. Resolve the target. From the argument, locate the module and read its public surface — exported functions, methods, types, options. For an external dependency, focus only on the subset of its API the project actually uses. Record this surface as the baseline.

  2. Partition the survey scope. The scope is the whole project, or just the paths given to --in. Enumerate the call sites within it — grep the module’s imports and usages — then group them into independent sections by package, top-level directory, or subsystem, each small enough that one agent can survey it without exhausting its context. Drop sections with no call sites.

    Scope bounds where callers are looked for, never where the target is: Step 1 resolves the module wherever it lives, including outside --in. If the scope holds no call sites at all, say so and stop — never widen it silently.

  3. Dispatch the survey — one subagent per section. Fan out a read-only agent per section (via the Agent tool; send independent sections concurrently in one message). Each agent scans only its section and returns a structured summary in a fixed shape so the results compose:

    • section — the path or subsystem surveyed.
    • callSites — a list of { path:line, symbol, glue }, where glue names the surrounding workaround: setup, argument-massaging, post-processing, a repeated guard, or a local wrapper fronting the module.
    • candidatePatterns — the recurrences the agent already sees within its own section, each with the call-site refs that share it.

    Keep only each agent’s structured summary, not its narration.

  4. Synthesize across sections — analyze for similarity. Collect the per-section summaries and cluster candidate patterns whose glue shape matches across sections. For a large result set, dispatch this too: group candidates by rough shape and give each group to an agent that confirms or splits the cluster. A cluster qualifies only when ≥2 independent call sites — across any sections — share the shape; drop the one-offs.

  5. Summarize the total results. For each surviving cluster, propose one concrete change to the module that would absorb the glue: a new function/overload, a new option or default, a richer return type, a built-in guard, or a batch variant. State the current versus proposed call shape, cite the call sites, and rank by callers-affected × glue-removed — most impactful first. Open the report by naming the scope surveyed, so a reader knows what the ranking is relative to. End by naming the single highest-leverage enhancement.

  6. --workflow: propose a Workflow script instead of running ad hoc. When the option is present, do Steps 1–2 to scope the work, then — rather than dispatching agents yourself — author a Workflow script that encodes Steps 3–5: a pipeline/parallel fan-out of one survey agent per section (each forced to a StructuredOutput schema matching the Step 3 summary shape), a similarity-clustering stage over the returned summaries, and a synthesis stage that emits the ranked opportunities. Present the script for the user to review and run — do not run it yourself unless they ask; Workflow is an explicit opt-in.

Notes

  • Read-only on the project. The only optional writes are a markdown summary the user asks for, or the proposed Workflow script under --workflow.
  • This finds enhancement opportunities; it does not implement them. Promote a chosen opportunity to a tracked task when the user wants it built.
  • Subagent dispatch keeps the main context small: each section agent returns only its structured summary, and the synthesis works over those summaries, not raw file dumps. Codebase-exploration discipline (search first, read narrowly, confirm against source) follows the explore-codebase skill beside this one.