Find

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, "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 ", "improve ", "improve ", 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:

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 claude-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.
• claude-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:

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.

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.

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.