Instruction file imported from hanzlahabib/rcode (.cursor/rules/rcode/agents/rules/codebase-mapper/detailed-guide.mdc). Copyright stays with the author.

Mapping Complete

Focus: {focus} Documents written:

.rcode/codebase/{DOC1}.md ({N} lines)
.rcode/codebase/{DOC2}.md ({N} lines)

Ready for orchestrator summary.

</step>

</process>

<templates>

## STACK.md Template (tech focus)

```markdown
# Technology Stack

**Analysis Date:** [YYYY-MM-DD]

## Languages

**Primary:**
- [Language] [Version] - [Where used]

**Secondary:**
- [Language] [Version] - [Where used]

## Runtime

**Environment:**
- [Runtime] [Version]

**Package Manager:**
- [Manager] [Version]
- Lockfile: [present/missing]

## Frameworks

**Core:**
- [Framework] [Version] - [Purpose]

**Testing:**
- [Framework] [Version] - [Purpose]

**Build/Dev:**
- [Tool] [Version] - [Purpose]

## Key Dependencies

**Critical:**
- [Package] [Version] - [Why it matters]

**Infrastructure:**
- [Package] [Version] - [Purpose]

## Configuration

**Environment:**
- [How configured]
- [Key configs required]

**Build:**
- [Build config files]

## Platform Requirements

**Development:**
- [Requirements]

**Production:**
- [Deployment target]

---

*Stack analysis: [date]*

INTEGRATIONS.md Template (tech focus)

# External Integrations

**Analysis Date:** [YYYY-MM-DD]

## APIs & External Services

**[Category]:**
- [Service] - [What it's used for]
  - SDK/Client: [package]
  - Auth: [env var name]

## Data Storage

**Databases:**
- [Type/Provider]
  - Connection: [env var]
  - Client: [ORM/client]

**File Storage:**
- [Service or "Local filesystem only"]

**Caching:**
- [Service or "None"]

## Authentication & Identity

**Auth Provider:**
- [Service or "Custom"]
  - Implementation: [approach]

## Monitoring & Observability

**Error Tracking:**
- [Service or "None"]

**Logs:**
- [Approach]

## CI/CD & Deployment

**Hosting:**
- [Platform]

**CI Pipeline:**
- [Service or "None"]

## Environment Configuration

**Required env vars:**
- [List critical vars]

**Secrets location:**
- [Where secrets are stored]

## Webhooks & Callbacks

**Incoming:**
- [Endpoints or "None"]

**Outgoing:**
- [Endpoints or "None"]

---

*Integration audit: [date]*

ARCHITECTURE.md Template (arch focus)

# Architecture

**Analysis Date:** [YYYY-MM-DD]

## Pattern Overview

**Overall:** [Pattern name]

**Key Characteristics:**
- [Characteristic 1]
- [Characteristic 2]
- [Characteristic 3]

## Layers

**[Layer Name]:**
- Purpose: [What this layer does]
- Location: `[path]`
- Contains: [Types of code]
- Depends on: [What it uses]
- Used by: [What uses it]

## Data Flow

**[Flow Name]:**

1. [Step 1]
2. [Step 2]
3. [Step 3]

**State Management:**
- [How state is handled]

## Key Abstractions

**[Abstraction Name]:**
- Purpose: [What it represents]
- Examples: `[file paths]`
- Pattern: [Pattern used]

## Entry Points

**[Entry Point]:**
- Location: `[path]`
- Triggers: [What invokes it]
- Responsibilities: [What it does]

## Error Handling

**Strategy:** [Approach]

**Patterns:**
- [Pattern 1]
- [Pattern 2]

## Cross-Cutting Concerns

**Logging:** [Approach]
**Validation:** [Approach]
**Authentication:** [Approach]

---

*Architecture analysis: [date]*

STRUCTURE.md Template (arch focus)

# Codebase Structure

**Analysis Date:** [YYYY-MM-DD]

## Directory Layout

[project-root]/ ├── [dir]/ # [Purpose] ├── [dir]/ # [Purpose] └── [file] # [Purpose]


## Directory Purposes

**[Directory Name]:**
- Purpose: [What lives here]
- Contains: [Types of files]
- Key files: `[important files]`

## Key File Locations

**Entry Points:**
- `[path]`: [Purpose]

**Configuration:**
- `[path]`: [Purpose]

**Core Logic:**
- `[path]`: [Purpose]

**Testing:**
- `[path]`: [Purpose]

## Naming Conventions

**Files:**
- [Pattern]: [Example]

**Directories:**
- [Pattern]: [Example]

## Where to Add New Code

**New Feature:**
- Primary code: `[path]`
- Tests: `[path]`

**New Component/Module:**
- Implementation: `[path]`

**Utilities:**
- Shared helpers: `[path]`

## Special Directories

**[Directory]:**
- Purpose: [What it contains]
- Generated: [Yes/No]
- Committed: [Yes/No]

---

*Structure analysis: [date]*

CONVENTIONS.md Template (quality focus)

# Coding Conventions

**Analysis Date:** [YYYY-MM-DD]

## Naming Patterns

**Files:**
- [Pattern observed]

**Functions:**
- [Pattern observed]

**Variables:**
- [Pattern observed]

**Types:**
- [Pattern observed]

## Code Style

**Formatting:**
- [Tool used]
- [Key settings]

**Linting:**
- [Tool used]
- [Key rules]

## Import Organization

**Order:**
1. [First group]
2. [Second group]
3. [Third group]

**Path Aliases:**
- [Aliases used]

## Error Handling

**Patterns:**
- [How errors are handled]

## Logging

**Framework:** [Tool or "console"]

**Patterns:**
- [When/how to log]

## Comments

**When to Comment:**
- [Guidelines observed]

**JSDoc/TSDoc:**
- [Usage pattern]

## Function Design

**Size:** [Guidelines]

**Parameters:** [Pattern]

**Return Values:** [Pattern]

## Module Design

**Exports:** [Pattern]

**Barrel Files:** [Usage]

---

*Convention analysis: [date]*

TESTING.md Template (quality focus)

# Testing Patterns

**Analysis Date:** [YYYY-MM-DD]

## Test Framework

**Runner:**
- [Framework] [Version]
- Config: `[config file]`

**Assertion Library:**
- [Library]

**Run Commands:**
```bash
[command]              # Run all tests
[command]              # Watch mode
[command]              # Coverage

Test File Organization

Location:

[Pattern: co-located or separate]

Naming:

[Pattern]

Structure:

[Directory pattern]

Test Structure

Suite Organization:

[Show actual pattern from codebase]

Patterns:

[Setup pattern]
[Teardown pattern]
[Assertion pattern]

Mocking

Framework: [Tool]

Patterns:

[Show actual mocking pattern from codebase]

What to Mock:

[Guidelines]

What NOT to Mock:

[Guidelines]

Fixtures and Factories

Test Data:

[Show pattern from codebase]

Location:

[Where fixtures live]

Coverage

Requirements: [Target or "None enforced"]

View Coverage:

[command]

Test Types

Unit Tests:

[Scope and approach]

Integration Tests:

[Scope and approach]

E2E Tests:

[Framework or "Not used"]

Common Patterns

Async Testing:

[Pattern]

Error Testing:

[Pattern]

Testing analysis: [date]


## CONCERNS.md Template (concerns focus)

```markdown
# Codebase Concerns

**Analysis Date:** [YYYY-MM-DD]

## Tech Debt

**[Area/Component]:**
- Issue: [What's the shortcut/workaround]
- Files: `[file paths]`
- Impact: [What breaks or degrades]
- Fix approach: [How to address it]

## Known Bugs

**[Bug description]:**
- Symptoms: [What happens]
- Files: `[file paths]`
- Trigger: [How to reproduce]
- Workaround: [If any]

## Security Considerations

**[Area]:**
- Risk: [What could go wrong]
- Files: `[file paths]`
- Current mitigation: [What's in place]
- Recommendations: [What should be added]

## Performance Bottlenecks

**[Slow operation]:**
- Problem: [What's slow]
- Files: `[file paths]`
- Cause: [Why it's slow]
- Improvement path: [How to speed up]

## Fragile Areas

**[Component/Module]:**
- Files: `[file paths]`
- Why fragile: [What makes it break easily]
- Safe modification: [How to change safely]
- Test coverage: [Gaps]

## Scaling Limits

**[Resource/System]:**
- Current capacity: [Numbers]
- Limit: [Where it breaks]
- Scaling path: [How to increase]

## Dependencies at Risk

**[Package]:**
- Risk: [What's wrong]
- Impact: [What breaks]
- Migration plan: [Alternative]

## Missing Critical Features

**[Feature gap]:**
- Problem: [What's missing]
- Blocks: [What can't be done]

## Test Coverage Gaps

**[Untested area]:**
- What's not tested: [Specific functionality]
- Files: `[file paths]`
- Risk: [What could break unnoticed]
- Priority: [High/Medium/Low]

---

*Concerns audit: [date]*

<forbidden_files> NEVER read or quote contents from these files (even if they exist):

.env, .env.*, *.env - Environment variables with secrets
credentials.*, secrets.*, *secret*, *credential* - Credential files
*.pem, *.key, *.p12, *.pfx, *.jks - Certificates and private keys
id_rsa*, id_ed25519*, id_dsa* - SSH private keys
.npmrc, .pypirc, .netrc - Package manager auth tokens
config/secrets/*, .secrets/*, secrets/ - Secret directories
*.keystore, *.truststore - Java keystores
serviceAccountKey.json, *-credentials.json - Cloud service credentials
docker-compose*.yml sections with passwords - May contain inline secrets
Any file in .gitignore that appears to contain secrets

If you encounter these files:

Note their EXISTENCE only: ".env file present - contains environment configuration"
NEVER quote their contents, even partially
NEVER include values like API_KEY=... or sk-... in any output

Why this matters: Your output gets committed to git. Leaked secrets = security incident. </forbidden_files>

<critical_rules>

WRITE DOCUMENTS DIRECTLY. Do not return findings to orchestrator. The whole point is reducing context transfer.

ALWAYS INCLUDE FILE PATHS. Every finding needs a file path in backticks. No exceptions.

USE THE TEMPLATES. Fill in the template structure. Don't invent your own format.

BE THOROUGH. Explore deeply. Read actual files. Don't guess. But respect <forbidden_files>.

RETURN ONLY CONFIRMATION. Your response should be ~10 lines max. Just confirm what was written.

DO NOT COMMIT. The orchestrator handles git operations.

</critical_rules>

<success_criteria>

Focus area parsed correctly
Codebase explored thoroughly for focus area
All documents for focus area written to .rcode/codebase/
Documents follow template structure
File paths included throughout documents
Confirmation returned (not document contents) </success_criteria>

Constraints

Apply Karpathy guidelines (see @-included reference) as hard rules. Reference the principle number when refusing a change.
produce accurate STACK.md, ARCHITECTURE.md, INTEGRATIONS.md per focus
preserve existing project structure understanding
cite file paths and line numbers for evidence
validate against actual codebase, not assumptions
follow scanning protocol for bounded context

detailed-guide

About