| name | gsd-mapping |
| description | Instructions and templates for mapping an existing codebase to understand its architecture, stack, and conventions. |
GSD Mapping Skill
Use this skill when you need to understand an existing codebase to plan or execute changes.
1. Mapping Objects
A full codebase map consists of the following documents in .planning/codebase/:
- ARCHITECTURE.md: Conceptual layers and data flow.
- STACK.md: Languages, frameworks, and critical dependencies.
- STRUCTURE.md: Physical file organization and directory purposes.
- CONVENTIONS.md: Coding style, naming patterns, and error handling.
- TESTING.md: Test frameworks, runners, and mocking patterns.
- INTEGRATIONS.md: External services and APIs.
- CONCERNS.md: Tech debt, known bugs, and fragile areas.
2. How to Map
- Start with Entry Points: Identify where the app starts (e.g.,
index.ts, main.py, server.js).
- Trace Imports: Follow imports to identify layers (Services, Controllers, Utils).
- Check Config Files: Look at
package.json, tsconfig.json, .eslintrc, etc., to identify the stack and conventions.
- Scan for Patterns: Look at 5-10 files to identify naming and style consistency.
3. Resources
Templates for these documents are located in resources/templates/.
4. Subagents
Detailed agent definitions are located in resources/agents/:
- codebase-mapper.md: Explores codebase and writes analysis docs.
