Cursor rule

1---
2description: "Derives the tech-stack doc from scratch by scanning the codebase — analyzes stack, architecture, and gray areas (error handling, API shapes) and persists findings into specs/tech-architecture/tech-stack.md. Run when the tech doc doesn't exist yet; use survey-context to consume it once it does."
3alwaysApply: false
4---
5 
6# Map Codebase
7 
8Perform a deep architectural and structural analysis of the codebase. Unlike `survey-context` which identifies "where we are", `map-codebase` identifies "what we are dealing with" and "how things are done".
9 
10> **Use this vs survey-context:** `map-codebase` BUILDS the tech-stack doc by scanning the codebase from scratch. `survey-context` READS existing specs/tech-architecture docs without re-deriving them. Run `map-codebase` when `specs/tech-architecture/tech-stack.md` doesn't exist yet; run `survey-context` when it does.
11 
12> **HARD GATE** — Cold analysis only. Do NOT assume architectural patterns without reading the code. If the codebase structure surprises you, call out the delta.
13 
14## Process
15 
16### 1. Identify Core Stack & Dependencies
17- Scan `package.json`, `Cargo.toml`, `requirements.txt`, etc.
18- Identify primary framework, runtime, and critical libraries (ORM, Auth, State, UI).
19- Note version constraints and any deprecated or unusual dependencies.
20 
21### 2. Map High-Level Architecture
22- Identify the entry points (CLI, Web, API).
23- Map the primary data flow (e.g., Controller → Service → Repository).
24- Identify where business logic lives vs. where I/O lives.
25- Look for established patterns (e.g., hexagonal, layered, feature-folders).
26 
27### 3. Analyze "Gray Areas" (The "How")
28Search for patterns and anti-patterns in these categories:
29- **Error Handling:** Are exceptions caught early or bubbled? Is there a global error handler? Are error messages structured?
30- **API Shapes:** Is it REST, GraphQL, or RPC? What is the casing (camelCase, snake_case)? How are responses structured?
31- **Type Safety:** Is it strictly typed? Are there many `any` or `unsafe` blocks? Are interfaces used for DIP?
32- **Observability:** Is there structured logging? Are there health checks? Where do logs go?
33- **Testing:** What is the test coverage strategy? Are mocks used? Where do tests live?
34 
35### 4. Identify Planning "Signals"
36Look for signals that will influence upcoming plans:
37- **Consistency Gaps:** "Half the project uses async/await, the other half uses Promises."
38- **Debt Hotspots:** "The `AuthManager` is 1500 lines and handles both JWT and session logic."
39- **Integration Points:** "We need to talk to the Stripe API, but there's no wrapper yet."
40- **Conventions:** "The team always uses functional components over classes."
41 
42### 5. Persist to specs/tech-architecture/tech-stack.md
43Compile all findings into `specs/tech-architecture/tech-stack.md`. This file serves as the project's "Long-Term Memory".
44 
45```markdown
46# Project Context
47 
48## Stack
49- [Framework/Language]
50- [Key Libraries]
51 
52## Architecture
53- [Pattern Description]
54- [Data Flow]
55 
56## Conventions (Observed)
57- [Error Handling Pattern]
58- [API Design]
59- [Type System]
60 
61## Signals / Active Considerations
62- [Gap 1]
63- [Hotspot 2]
64```
65 
66## When to Use
67- When first joining a project.
68- Before a major refactor or architectural change.
69- When `survey-context` reveals a lack of domain knowledge.
70- To refresh `specs/tech-architecture/tech-stack.md` after significant changes.
71