Skip to content
sdlc

/sdlc:api-enhancement-scan

Generated from solutions/ontological/skills/api-enhancement-scan/SKILL.md.

Description

Section titled “Description”

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 —workflow to have it propose a reusable Workflow script for the survey instead of running it ad hoc.

Allowed tools

Section titled “Allowed tools”
  • Read
  • Glob
  • Grep
  • Bash
  • Agent

Source

Section titled “Source”

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. Option: --workflow — instead of running the survey ad hoc, propose a reusable Workflow script that performs it (see Step 6).

The rule that governs everything

Section titled “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.

Steps

Section titled “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 codebase for survey. Enumerate the call sites — 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.

  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. 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

Section titled “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 task with /sdlc:task-new 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 /sdlc:explore-codebase.