investigating-a-codebase_skill

Overview

This skill helps you inspect a Python codebase to ground design and planning in reality. It finds files, verifies assumptions about structure, exposes patterns, and gives definitive answers about what exists and where. Use it to prevent hallucinations about file locations, APIs, or architecture.

How this skill works

I start from likely entry points (main files, setup/config, package files) and run targeted searches: glob for candidate paths, grep for keywords and symbols, then read and follow imports to trace implementations. For design assumptions I extract claims, search for each item, compare reality with expectations, and report with exact paths, snippets, and the search strategy used.

When to use it

• Before implementing features that depend on existing files or modules
• When verifying design assumptions about file names, functions, or locations
• To locate implementations or patterns to follow (auth, routing, error handling)
• When you need a definitive yes/no about whether a feature or symbol exists
• To document architecture and conventions before writing new code

Best practices

• Always verify with glob/grep/read rather than assuming file paths
• Search broadly and follow import/reference traces, not just first hit
• Report exact file paths and line numbers, plus small evidence snippets
• Document the search strategy when something isn’t found
• Compare design assumptions explicitly: confirmed, discrepancy, addition, missing

Example use cases

• Design assumes auth.py exists in src/auth — verify and provide exact path or equivalent file
• Find how API errors are handled across the codebase and extract the canonical pattern
• Locate where user routing and registration are implemented and list entry points
• Check if a specific utility function or class exists and report exact matches or absence with search scope
• Verify package/config declarations (setup.cfg/pyproject.toml) and report dependency clues relevant to feature design