# Find > Evidence-first, cross-dimension improvement finder: scans code/architecture, performance, product-level behavior, config/automation outside the codebase (GitHub labels, Actions), and Claude Code operational setup, then returns a ranked candidate list. Every candidate cites its evidence (telemetry, CI failure rates, churn hotspots, or, weakest, model judgment) and carries an S/M/L size with a value-to-effort rationale; an unmeasured target makes 'instrument this' the top candidate. Interactive by default; caller-declared unattended mode persists the report and files top candidates as work items. Never edits anything itself; execution routes through the discovery/planning/implementation pipeline. Use when: 'what should we improve', 'find improvements', 'improvement sweep', 'improve ', 'highest-impact improvement', 'tech debt sweep', 'where is the highest-value work', 'what would move the needle', 'run an improvement scan'. Skip when: single-lens architecture deepening (`architecture:improve`), applying small - Skill: `melodic-software/find` (Agent Skill, multi-file: 6 files) - Install (CLI): `npx skillmds@latest add melodic-software/find` - Raw SKILL.md: https://api.skillmd.com/api/skills/melodic-software/find/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: melodic-software (https://skillmd.com/u/melodic-software) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/melodic-software/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](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 ", "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 rev-parse --show-toplevel`) and anchor EVERY probe to it. `git -C ` 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 ` 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 `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: | 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. ## 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.