lens_skill

Overview

This skill is Lens, a codebase comprehension specialist that transforms vague questions about a repository into structured, actionable understanding. It focuses on whether a feature exists, how a flow executes, and why modules are organized the way they are. Lens never edits code; it produces evidence-backed reports with file:line references and confidence levels.

How this skill works

Lens follows a five-phase workflow: SCOPE to define the question and boundaries, SURVEY to map structure and entry points, TRACE to follow execution and data flows, CONNECT to relate modules and conventions, and REPORT to deliver findings with citations. For each claim it provides file:line references, a confidence rating (High/Medium/Low), and a “what I didn’t find” section to surface gaps. Lens asks clarifying questions when scope is ambiguous or the repository is very large before proceeding.

When to use it

• You need to know whether a feature or endpoint exists in the codebase.
• You must trace how data flows from entry point to storage or outward API.
• You want clear module responsibilities and boundaries before planning changes.
• You need onboarding documentation or a structured overview for new contributors.
• You want to hand off understanding to implementers, planners, or documenters.

Best practices

• Start with a concise, scoped question (feature name, route, or module) to avoid broad scans.
• Allow Lens to ask clarifying questions when multiple candidates or ambiguous terminology appear.
• Request the output format you need: Quick Answer, Investigation Report, or Onboarding Report.
• Use Lens findings as evidence for downstream tasks (Builder, Sherpa, Atlas) rather than as executable instructions.
• Review the provided "what I didn’t find" section before assuming absence—ask follow-ups for deeper traces.

Example use cases

• "Does this repo implement user authentication and where is it enforced?" — returns entry points, middleware, and confidence with file:line refs.
• "How does the payment API flow from request to settlement?" — traces handlers, service calls, and persistence paths.
• "Map responsibilities of the billing module and its dependencies." — shows boundaries, calls, and patterns used.
• "Create an onboarding summary for a new backend engineer." — provides top-down overview, key files, and conventions to watch for.
• "Verify whether a feature change impacts external integrations." — lists touched modules and likely boundaries to inspect further.