sdd:code-mapping

Codebase Mapping Skill

This skill provides templates and analysis guidance for generating comprehensive codebase documentation. It supports four focus areas, each producing two specialized documents.

Focus Area Routing

When invoked, check the focus parameter to determine which templates and analysis guides to use:

Focus Area	Templates to Use	Analysis Guide
tech	stack.md, integrations.md	tech-analysis.md
arch	architecture.md, structure.md	arch-analysis.md
conventions	conventions.md, testing.md	conventions-analysis.md
security	security.md, concerns.md	security-analysis.md

Output Location

All documents are written to: .sdd/codebase/

Files use UPPERCASE naming: STACK.md, INTEGRATIONS.md, ARCHITECTURE.md, STRUCTURE.md, CONVENTIONS.md, TESTING.md, SECURITY.md, CONCERNS.md

Document Quality Requirements

Each generated document MUST:

1. Be Actionable: Content should guide future development decisions
2. Include File Paths: Reference actual paths in backticks for navigation (e.g., src/api/auth.py)
3. Be Current: Reflect the actual state of the codebase at time of generation
4. Focus on What Executes: Capture only what runs (languages, runtime, frameworks, dependencies)
5. Limit Dependencies: Document 5-10 most important dependencies, not every entry
6. Specify Versions: Only when compatibility matters
7. Use Prescriptive Language: Guide future code generation with clear patterns

Exclusions by Document

Content belongs in specific documents - avoid duplication:

If Content Is About...	Put It In...	NOT In...
Languages, frameworks, versions	STACK.md	ARCHITECTURE.md
External APIs, databases, auth services	INTEGRATIONS.md	STACK.md
System design, patterns, data flow	ARCHITECTURE.md	STRUCTURE.md
Directory layout, module boundaries	STRUCTURE.md	ARCHITECTURE.md
Code style, naming, error handling	CONVENTIONS.md	TESTING.md
Test strategy, frameworks, patterns	TESTING.md	CONVENTIONS.md
Auth, authorization, vulnerabilities	SECURITY.md	CONCERNS.md
Tech debt, risks, TODOs	CONCERNS.md	Any other doc

How to Use This Skill

1. Read the focus-specific analysis guide from references/focus-guides/{focus}-analysis.md
2. Load the relevant templates from references/templates/
3. Analyze the codebase following the analysis guide instructions
4. Fill templates with discovered information
5. Write documents directly to .sdd/codebase/
6. Return confirmation only: file paths + line counts

Template Files

Templates are located in references/templates/:

• stack.md - Languages, frameworks, dependencies
• integrations.md - External services, APIs, data stores
• architecture.md - System design, patterns, data flow
• structure.md - Directory layout, module boundaries
• conventions.md - Code style, naming, patterns
• testing.md - Test strategy, frameworks, patterns
• security.md - Auth, authorization, vulnerabilities
• concerns.md - Tech debt, risks, known issues

Focus Guides

Analysis guides are located in references/focus-guides/:

• tech-analysis.md - How to analyze tech stack and integrations
• arch-analysis.md - How to analyze architecture and structure
• conventions-analysis.md - How to analyze conventions and testing
• security-analysis.md - How to analyze security and concerns