Windsurf rules

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