Analyze Source Code for Agent Performance Insights

Examine the repository's source code to identify characteristics that help or hinder coding agent performance.

Scope: Focus on source code, project configuration, and build files. Avoid analyzing agent context files (.cursor/rules, AGENTS.md, etc.) — that's handled by analyze-agent-context.

Before You Start

Read the shared reference files:

• APEX taxonomy — insight categories
• Insight report schema — report structure

Resolving reference paths: The links above use relative paths (../../references/...) that work when this skill is read from its tile directory. If those paths do not resolve (e.g. when activated via a .claude/skills/ symlink), find the shared references at .tessl/tiles/*/agent-insight-experiment/references/ relative to the repository root.

Your report prefix is SRC (e.g., SRC-001).

Analysis Strategy

Step 1: Repository Overview

# Top-level structure
ls -la
find . -maxdepth 2 -type f -name "*.json" -o -name "*.toml" -o -name "*.yaml" -o -name "*.yml" -o -name "Makefile" -o -name "Dockerfile" | head -30

# Languages and size
find . -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.py" -o -name "*.go" -o -name "*.rs" \) | wc -l
find . -type f -not -path "*/node_modules/*" -not -path "*/.git/*" | wc -l

# Monorepo detection
ls packages/ services/ apps/ libs/ modules/ 2>/dev/null

Checkpoint: If the repo has <10 source files, adjust scope — analyze everything rather than sampling.

Step 2: Identify Key Areas

# Internal libraries: shared packages in monorepos
find . -maxdepth 3 -name "package.json" -not -path "*/node_modules/*" | xargs grep -l '"private": true' 2>/dev/null

# High-import modules: most-referenced files
rg -l "^import|^from|require\(" --type ts --type js --type py 2>/dev/null | head -5 | while read f; do
  basename_f=$(basename "$f" | sed 's/\.[^.]*$//')
  echo "$(rg -c "$basename_f" --type ts --type js --type py 2>/dev/null | wc -l) $f"
done | sort -rn | head -20

# Documentation density
find . -name "README.md" -not -path "*/node_modules/*" | wc -l
find . -name "*.md" -not -path "*/node_modules/*" -not -path "*/.git/*" | wc -l

Step 3: Pattern Analysis

For each of 5-10 representative modules, check:

• Error handling: Is it consistent? (try/catch vs error callbacks vs Result types)
• Logging: One library or many? Structured or ad-hoc?
• Auth/data access: Consistent patterns or multiple approaches?
• Naming: camelCase vs snake_case consistency, term uniformity
• Types: Comprehensive or scattered any / untyped functions?

# Quick inconsistency scan
rg "console\.(log|error|warn)" --type ts --type js -c 2>/dev/null | sort -t: -k2 -rn | head -10
rg "catch\s*\(" --type ts --type js -c 2>/dev/null | head -10
rg "\bany\b" --type ts -c 2>/dev/null | sort -t: -k2 -rn | head -10

Step 4: Complexity Assessment

• Deep nesting: directories >5 levels deep
• Circular deps: spot-check imports in 3-5 key modules
• Non-obvious build: look for custom scripts, codegen, multi-stage Dockerfiles
• Implicit config: scan for process.env, os.environ, magic strings
• Reinvented wheels (SCX-7): custom implementations where standard packages exist
• Undocumented complexity (SCX-8): non-trivial algorithms, subtle invariants, or performance-critical paths with no explanatory comments or docs
• Undocumented dangers (KCG-7): destructive operations, irreversible side effects, or data-loss footguns that aren't flagged anywhere

# Environment variable usage
rg "process\.env\.|os\.environ|getenv" --type ts --type js --type py -c 2>/dev/null | wc -l

# Custom scripts
find . -name "*.sh" -o -name "Makefile" -o -name "Justfile" | head -20

# Generated code markers
rg -l "DO NOT EDIT|auto-generated|codegen" --type ts --type js --type py 2>/dev/null | head -10

Step 5: Unfamiliar Surface Area

Look for areas where an agent is likely to have no priors to fall back on. These almost always classify as KCG-1 (undocumented internal API surface) or SCX-3 (unclear navigation) depending on whether the pain is "I don't know how this works" vs "I can't find my way around this":

• Custom DSLs, template languages, or config formats
• Internal frameworks wrapping standard tools
• Proprietary integrations or protocols
• Non-standard architectural patterns that diverge from common practice in the language/framework

Scope Limits

• Read contents of up to 500 files
• Traverse up to 50 directories for structure
• For monorepos, sample at least 3-5 representative packages
• Prioritize central code (many importers) over peripheral

Output

Save the report to the path provided by the orchestrator, or .tessl-insights-poc/reports/source-code.json if standalone.

Validation before saving:

• Verify report has all required metadata fields
• Confirm at least 8 insights with evidence
• Check every insight has id, category, subcategory, impact, effort, priority_score
• Verify affected_areas contains actual file paths, not vague descriptions

Set scope.metrics: files_examined, directories_traversed, total_loc_sampled.

Example insight shape:

{
  "id": "SRC-001",
  "category": "KCG",
  "subcategory": "KCG-1",
  "title": "Internal auth library has no documentation",
  "description": "packages/auth exports 12 functions used across 47 files but has zero JSDoc comments and no README.",
  "evidence": [{"type": "file_reference", "location": "packages/auth/src/index.ts", "detail": "12 exports, 0 documented"}],
  "impact": {"score": 8, "level": "high", "reasoning": "Every auth-related task requires reverse-engineering"},
  "effort": {"score": 3, "level": "low", "reasoning": "Types are clear; generating docs from signatures is straightforward"},
  "priority_score": 2.67,
  "affected_areas": ["packages/auth/"],
  "confidence": "high",
  "data_source_exclusive": true
}