codebase-recon_skill

Overview

This skill is a structured codebase analysis assistant for investigating architecture, patterns, and root causes with evidence-backed findings. It guides a systematic, confidence-tracked investigation and produces clear, cited deliverables with caveats when certainty is below complete. Use it to explore TypeScript projects, map dependencies, or prepare actionable reports.

How this skill works

It gathers evidence from multiple prioritized sources: code, docs, tests, history, and external references, then updates a calibrated confidence bar as investigation proceeds. At each step it emits concise outputs (Confidence, Found, Patterns, Gaps, Next) and routes to specialized micro-skills for pattern extraction, root-cause diagnosis, or report synthesis when needed. Final delivery lists findings, supporting evidence, implications, and a confidence assessment.

When to use it

• Exploring a new or unfamiliar TypeScript codebase
• Understanding or mapping system architecture and dependencies
• Extracting recurring patterns or anti-patterns in code
• Investigating bugs, regressions, or unexpected behavior
• Preparing evidence-based technical reports or recommendations

Best practices

• Prioritize direct observation: read code and targeted files before inferring intent
• Collect evidence from at least two independent sources (code + tests or docs + history)
• Start broad (file tree, imports) then narrow to targeted reads and traces
• Constantly calibrate and emit a confidence level; flag uncertainties with △ Caveats
• Document file paths, tests, and commit references for every substantive claim
• When deeper analysis is required, load specialized skills for patterns, root causes, or reporting

Example use cases

• Map how modules and services interact in a TypeScript monorepo to inform refactoring
• Analyze a failing test suite to identify likely root causes with supporting commits and tests
• Extract architecture-level patterns (e.g., layering, event flows) to inform onboarding docs
• Produce a confidence-rated findings report for a security or performance review
• Triage a regression by tracing call paths, test expectations, and recent history