Find

---
description: "Rank improvements across code, performance, product, config, Claude Code setup, evidence-cited and sized S/M/L; unmeasured targets yield 'instrument this'. Never edits; unattended files work items. Use when: 'what should we improve', 'improvement sweep', 'improve X', 'tech debt sweep', 'where is the highest-value work', 'what would move the needle', 'run an improvement scan'. Skip: `architecture:improve`, `code-tidying:tidy`, `codebase-health:audit`, `review:fanout`, `work-items:scan-todos`."
argument-hint: "[target] [--small|--medium|--large] [--unattended] [repo-path]"
user-invocable: true
disable-model-invocation: false
metadata:
  workflow-stage: anytime
  summary: Rank evidence-cited improvement candidates across dimensions; execution goes to the pipeline
---

## Repository context. Gather first

Collect these with **individual** Bash calls, one command per call, never combined into a single
invocation:

- Current branch, `git branch --show-current`
- Recent commits, `git log --oneline -15`
- Working tree status (empty = clean), `git status --porcelain | head -10`
- Shallow repository, `git rev-parse --is-shallow-repository`

The pipe is the bound and belongs in the command. A read-time cap ("read only the first 10 entries")
bounds nothing: the Bash tool returns the command's complete output into context before there is
anything to decide about.

Treat a failure (not a repository, git unavailable) as an unknown value and carry on. A
worktree-isolated session refuses a compound command that contains git, which is why each call
above stays on its own. The dated record for that refusal, and for the pre-compute composition that
makes it bite, is the `source-control` plugin's
[worktree/reference/gather-block.md](https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/plugins/source-control/skills/worktree/reference/gather-block.md),
"The pre-compute block runs as one shell invocation".

## Variables

Arguments: `$ARGUMENTS`

## Purpose

This skill answers "what should we improve here, and how do we know?", the second half of that
question is its identity. Review evaluates a diff; planning designs already-chosen work; the
specialized finders each hunt one lens. This skill forms its own cross-dimension judgment about
what is worth improving in a target: code, product behavior, process surfaces, operational setup, and grounds every proposal in cited evidence, so ranking reflects measurement, not taste. It
discovers and deliberates only: execution always flows through the repo's normal pipeline
(interview → discovery → planning → implementation → verification).

## Prompt interpretation

Parse `$ARGUMENTS` and the invoking prompt for four independent narrowings; each defaults open:

- **Target scope.** Bare invocation scans the whole repo across every dimension below. A targeted
  ask, "improve <feature>", "improve <path>", "improve <concept>", narrows the scan: map the
  named feature/path/concept to its concrete surfaces (files, workflows, config, ops touchpoints)
  before gathering evidence, and gather evidence for those surfaces only. A concept with no
  resolvable surface is itself a finding (likely instrument-first, below).
- **Size band.** `--small` / `--medium` / `--large` (or equivalent prose: "quick wins only", "big
  swings") restricts candidates to that size band. Default: all sizes, ranked together.
- **Repo as parameter.** One repo per invocation. An explicit repo path in the arguments makes that
  checkout the target; otherwise the current repo is. When the target is not the session's working
  directory, resolve its root once (`git -C <repo-path> rev-parse --show-toplevel`) and anchor
  EVERY probe to it. `git -C <root>` for every git command here and in the `context/` recipes,
  and file reads under that root, so the evidence never silently comes from the invoking repo.
  The branch/log calls above describe the session's cwd, not the target; re-run them
  with `-C <root>` in that case. Fleet-wide sweeps are out of scope. Compose with
  `repo-fleet-hygiene` externally, one invocation per repo.
- **Mode.** Interactive is the default. Unattended is entered ONLY when the caller declares it (see
  Unattended mode), never inferred from context.

## Scan dimensions

The scan walks this inventory explicitly, so it cannot silently collapse to code-only. For each
dimension, gather whatever evidence its tier sources yield, then propose candidates:

| Dimension | Examples of what to look at |
|---|---|
| Code / architecture | Churn×complexity hotspots, coupling and seam friction, dead or duplicated surface |
| Performance | Slow CI, slow tests, slow builds, known-slow runtime paths named by telemetry |
| Product-level behavior | Error rates, failure-prone user flows, gaps between documented and measured behavior |
| Config / automation outside the codebase | GitHub labels, Actions workflows, synchronizations, branch protections, bot config |
| Claude Code operational setup | Cloud environments, MCP servers, hooks, permission rules, plugin/skill configuration |

**Docs/markdown improvement is OUT**. Owned lanes (`docs-hygiene`, `codebase-health`) cover it;
finding a docs candidate means naming the owning lane, not adding it to this list.

## Evidence ladder

The skill's core mechanic. Every candidate cites its evidence, and its rung on this ladder sets the
confidence attached to the ranking (strongest first):

1. **Measured telemetry**. Production/application metrics, error rates, cost or latency data from
   a Tier 1/2 source.
2. **Repo and CI history**. Churn×complexity hotspots, CI failure ratios and duration trends,
   dependency staleness. Mechanical, reproducible, repo-native.
3. **Structural presence signals**. Test-coverage presence/absence, TODO density, missing
   automation where a class of toil demonstrably recurs.
4. **Model judgment**, the weakest rung: this session's read of the target. Always labeled as
   such, never dressed up as measurement.

Two hard rules follow:

- **Instrument-first.** When the target has no measurement at all (no telemetry, no usable CI
  history, nothing above rung 4), the top-ranked candidate becomes "instrument this so future runs
  can rank on data": a concrete baseline/instrumentation proposal (what to measure, where the
  signal lands), handed to the pipeline like any other improvement. This mirrors the SRE
  error-budget posture: measurement precedes prioritization.
- **Gaps are recorded, never papered over.** An evidence source that is unavailable (no GitHub
  access path, shallow clone, no telemetry configured) produces an explicit evidence-gap line in
  the output. Absence of evidence is reported; it is never fabricated, estimated, or silently
  skipped.

## Evidence sources (tiered, presence-gated)

- **Tier 0. Repo-native, always available.** Git churn/hotspot analysis (recipe:
  context/hotspots.md, including its shallow-history gate), CI health via GitHub Actions run data
  (recipe: context/ci-health.md), dependency staleness from the repo's own manifests,
  test-coverage presence, TODO density. These ship with the skill and need nothing installed.
- **Tier 1. Local Claude Code telemetry.** When `harness-ops:observability` is installed, consult
  it for session/cost/hook telemetry relevant to the operational-setup dimension.
- **Tier 2. Configured application telemetry.** Whatever MCP telemetry sources the consumer
  declares through the `.claude/improvement.md` config cascade (team file + `.local` overlay +
  user-global; key contract in the plugin's reference/config.md). Never hardcode a vendor; if no
  source is configured, Tier 2 is an evidence gap, and product-level candidates fall back down the
  ladder.

**GitHub access-path probe ladder.** For CI and repo-platform data, probe in order: GitHub MCP
tools (`actions_*` and repo tools) → `gh` CLI → none. On "none", record the evidence gap and rank
without CI evidence, never reconstruct CI health from guesswork.

## Lane delegation as scan input

Where an installed specialized finder covers a dimension more deeply, consult it presence-gated and
fold its findings into this skill's candidate list as inputs. Delegate, never re-inline its
method:

- `architecture:improve` (deepening lens). Depth for the code/architecture dimension.
- `harness-config:audit-automation-gaps`. Depth for the Claude Code operational-setup dimension.
- Other installed finders that announce an improvement-shaped scan may be consulted the same way.

Delegated findings keep their lane attribution in the evidence citation, and they compete in the
same ranked list as native candidates. Where no lane is installed, the skill's own Tier 0 scan for
that dimension stands alone. Reuse-or-replace: never re-implement what an owned lane already does.

In unattended mode, consult only lanes that run without interaction; a lane whose flow is
interview- or confirmation-driven is skipped with a `gap:` line naming it, and Tier 0 stands
alone for that dimension, never simulate a user to drive an interactive lane.

## Candidate output shape

One ranked list, highest value-to-effort first. Every row carries:

| Field | Content |
|---|---|
| Rank | Position; the highest-impact candidate leads |
| Candidate | One-line improvement statement, concrete enough to hand to an interview |
| Dimension | Which scan dimension it belongs to |
| Size | S / M / L |
| Evidence | Citation: source + specifics (e.g. "hotspot: 14 commits/90d × high indentation"), and its ladder rung |
| Confidence | Derived from the evidence rung, stated plainly |
| Value-to-effort | WSJF-style rationale: cost of delay (value, urgency, risk reduction) against job size |

Scoring and dedupe mechanics: context/ranking.md. Evidence-gap lines appear after the list so the
reader knows what the ranking could not see.

## Interactive flow

1. Present the ranked candidate list (shape above), evidence gaps included.
2. The user picks a candidate.
3. Interview on the pick. Invoke `/planning:interview` via the Skill tool when available, to reach a shared shape:
   what improvement, why now, what evidence, what done looks like.
4. Hand off to the pipeline, invoking each via the Skill tool: `/discovery:explore` (internal
   unknowns) or `/discovery:research` (external unknowns) as needed, then `/planning:plan`. The handoff artifact is the interview's
   output, with the candidate's evidence citation attached.
5. Offer the remainder: unpicked candidates can be filed via `/work-items:track` when installed; the user decides which, if any.

Where a named pipeline skill is not installed in the consuming project, summarize the equivalent
handoff shape inline instead of blocking, but absence of a pipeline skill is never license to
implement the improvement in this session.

## Unattended mode

Entered only when the **caller declares it** in the invocation prompt (a routine wrapper, a
scheduled job, an orchestrating skill), never sniffed from the environment, per the fleet's
declared-by-the-caller convention. In unattended mode:

- **No questions.** No interview, no picks, no confirmation prompts. Decisions resolve by the
  defaults below or by the invocation prompt's overrides.
- **The report is persisted**, the full ranked list plus evidence-gap lines, under
  `${CLAUDE_PLUGIN_DATA}`, keyed per project per the plugin-data-report-keying convention (report
  shape and keying: context/unattended.md).
- **Top candidates are filed** via `work-items:track` when installed (absent tracker = report
  only, noted in the report). Filing behavior:
  - *Dismissed-candidate memory, at candidate assembly*. Candidates an operator previously
    dismissed are suppressed before ranking, so they never consume a cap slot or a tracker query.
    A soft default the invocation prompt can override.
  - *Dedupe against open work items, at filing time*. Search before creating each item. Baseline
    behavior, not a tuning knob; filing a duplicate is a bug.
  - *Adaptive filing cap*, a soft default bounding how many items one run files (following
    `work-items:work-loop`'s adaptive-cap precedent), overridable by the invocation prompt.

  Consultation order and its rationale: context/ranking.md.
- **Nothing else mutates, and nothing self-disposes.** The run is read-only apart from the report
  and the filed items; it never picks a candidate, never prioritizes the queue, never starts
  implementation. Prioritization of filed items is human-gated always, the autonomy catalog's
  `tech-debt-sweep` C1 contract.

## Execution requests

"Go implement this", interactively or as a follow-up, routes through the pipeline, never through
this skill's own hands: interview the pick → `/discovery:explore` / `/discovery:research` →
`/planning:plan` → `/implementation:implement` → `/verification:confirm`, each delegated to its
skill by invoking it via the Skill tool. An execution request changes where the handoff goes,
not what this skill is allowed to touch.

## What this skill does NOT do / Skip when

Reuse-or-replace posture: each boundary below names an owned lane this skill delegates to or steps
aside for. It re-implements none of them.

| Skip when the ask is | Owned by | Why not here |
|---|---|---|
| Single-lens architecture depth (shallow modules, Design-It-Twice) | `architecture:improve` | That lens is consulted as a scan input; going deep on architecture alone is its job |
| Applying small safe code edits | `code-tidying:tidy` | This skill never edits; tidying mutates by contract |
| Verifying docs/config/code drift claims | `codebase-health:audit` | Claim verification, not improvement discovery |
| Reviewing a diff before merge | `review:fanout` | Diff-scoped and reactive; this skill scans existing state proactively |
| Sweeping TODO/FIXME markers into items | `work-items:scan-todos` | Marker sweep is one narrow signal; here TODO density is evidence, not the deliverable |

**Verb contract.** `find` reads as read-only, and it is: bare invocation reports and stops. The
caller's unattended declaration IS the explicit mutation override that authorizes work-item filing, the same shape as the `audit` verb's autofix override, and it authorizes exactly that: report
persistence and presence-gated filing. No other mutation exists in any mode; there is no flag,
prompt, or mode that makes this skill edit the target.

## Spoke paths

The `context/` files write the plugin's root directory as `<plugin-root>`, which is
`${CLAUDE_PLUGIN_ROOT}`. Put that path in place of the placeholder before running a command or
writing it into a brief. Those files arrive through the Read tool as plain bytes, so a `${…}` token
in them would reach the Bash tool unsubstituted, and the Bash tool's environment has no
`CLAUDE_PLUGIN_ROOT` to expand it from. Basis: the plugins reference,
<https://code.claude.com/docs/en/plugins-reference#where-each-variable-resolves>, verified
2026-09-30; recheck when that table adds supporting files to where a `${…}` reference resolves.

## Gotchas

Known traps, seeded from the research this skill was grounded on:

- **Shallow or truncated clones poison churn rankings.** The hotspot recipe's history-depth gate
  (context/hotspots.md) runs first; a window the history does not cover downgrades churn to a
  recorded evidence gap. Confidently-wrong rankings from partial history are worse than no
  ranking.
- **Never call the Actions `/timing` endpoint**. GitHub marks it as closing down; the dated record
  for that, and for the documented 1,000-result bound behind the windowing rule, is in
  context/ci-health.md. CI health iterates `/actions/runs` by `created` date windows (never deep
  pagination) and derives failure ratios, duration trends, and `run_attempt` retries per that file.
- **Unattended is declared, never detected.** There is no supported way to observe
  non-interactivity; guessing it converts an interactive user's session into a silent filing run.
- **No access path ≠ healthy CI.** A missing GitHub access path is an evidence-gap line, not a
  reason to estimate CI health from the working tree's vibes.