# /grid:map - Codebase Reconnaissance

---
name: grid:map
description: Analyze existing codebase before starting Grid missions
argument-hint: "[path]"
allowed-tools:
  - Task
  - Read
  - Glob
  - Grep
---

Perform rapid codebase reconnaissance to understand project structure, technologies, and patterns before initiating Grid missions. Essential for existing projects.

## USAGE

`/grid:map`
`/grid:map /path/to/project`

## WHEN TO USE

**Use before /grid when:**
- Starting work on an existing codebase
- Joining a new project
- Unfamiliar with project architecture
- Planning major changes that need context

**Skip if:**
- Greenfield project (empty directory)
- Already familiar with the codebase
- Just did reconnaissance recently

## PROCESS

### 1. Initialize Scout Directory

```
.grid/
└── scout/
    └── reconnaissance.md
```

If `.grid/` does not exist, create it.

### 2. Spawn Scout Agent

Deploy the grid-scout agent for fast reconnaissance:

```markdown
**Scout Mission:**
Analyze the current codebase and generate a comprehensive reconnaissance report.

**Save report to:** .grid/scout/reconnaissance.md

**Include:**
1. Project structure overview
2. Key technologies detected
3. Entry points identified
4. Dependencies analyzed
5. Architecture patterns found
6. Complexity assessment
7. Recommendations for Grid usage
```

### 3. Generate Reconnaissance Report

The Scout will produce `.grid/scout/reconnaissance.md` with:

```markdown
---
scout_id: {timestamp}
project_root: {path}
scan_duration: {seconds}s
confidence: HIGH | MEDIUM | LOW
---

# Codebase Reconnaissance Report

## Executive Summary
{2-3 sentence overview of what this codebase is}

## Project Structure

### Directory Layout
{abbreviated tree structure, max 30 lines}

### Key Directories
| Directory | Purpose | Files |
|-----------|---------|-------|
| src/ | Source code | 45 |
| tests/ | Test files | 12 |

## Technology Stack

### Languages
| Language | Files | Primary |
|----------|-------|---------|
| TypeScript | 45 | YES |

### Frameworks & Libraries
| Name | Version | Purpose |
|------|---------|---------|
| Next.js | 14.1.0 | Web framework |

### Databases & Storage
| Type | Technology | Config Location |
|------|------------|-----------------|
| SQL | PostgreSQL | prisma/schema.prisma |

## Entry Points

### Application Entry
| Entry | Path | Type |
|-------|------|------|
| Main | src/index.ts | Application |
| API | src/app/api/ | Routes |

### Configuration Files
| File | Purpose |
|------|---------|
| package.json | Dependencies |
| tsconfig.json | TypeScript config |

## Dependencies Analysis

### Production Dependencies
{Count and key packages}

### Dev Dependencies
{Count and key packages}

### Locked Versions
| Package | Version | Reason |
|---------|---------|--------|
| {pkg} | {ver} | Pinned |

## Architecture Patterns

| Pattern | Confidence | Evidence |
|---------|------------|----------|
| App Router | HIGH | src/app/ exists |
| Component-based | HIGH | src/components/ |

## Complexity Assessment

| Metric | Value | Rating |
|--------|-------|--------|
| Total Files | {N} | {LOW/MED/HIGH} |
| Lines of Code | ~{N}K | {LOW/MED/HIGH} |
| Dependencies | {N} | {LOW/MED/HIGH} |
| Test Coverage | {status} | {LOW/MED/HIGH} |

**Overall Complexity:** {LOW | MEDIUM | HIGH}

## Constraints for Planning

### Must Preserve
- {Existing API contracts}
- {Database schema}
- {Auth patterns}

### Existing Conventions
- {Naming conventions}
- {File organization}
- {Import patterns}

## Grid Recommendations

### Suggested Approach
- {How to structure Grid missions for this codebase}
- {Recommended block sizes}
- {Areas needing careful planning}

### Quick Wins (/grid:quick suitable)
- {Simple tasks that don't need full planning}

### Needs Full Planning (/grid required)
- {Complex areas requiring proper Cluster/Block breakdown}

### Watch Out For
- {Gotchas discovered}
- {Fragile areas}
- {Technical debt}

## Questions for User
- {Ambiguities that need clarification}
- {Missing context}

---
Reconnaissance complete. Ready for mission planning.
End of Line.
```

### 4. Display Summary

After reconnaissance completes, show:

```
CODEBASE RECONNAISSANCE COMPLETE
════════════════════════════════════════════════════════════════════

Project: {name}
Location: {path}

QUICK STATS
───────────
  Languages:     {primary language(s)}
  Framework:     {main framework}
  Files:         {count}
  Dependencies:  {count}
  Complexity:    {LOW | MEDIUM | HIGH}

KEY TECHNOLOGIES
────────────────
  {tech 1}
  {tech 2}
  {tech 3}

ARCHITECTURE
────────────
  {pattern 1}
  {pattern 2}

GRID RECOMMENDATIONS
────────────────────
  {recommendation summary}

Full report: .grid/scout/reconnaissance.md

════════════════════════════════════════════════════════════════════
Ready for /grid or /grid:quick

End of Line.
```

## OUTPUT FILES

| File | Purpose |
|------|---------|
| `.grid/scout/reconnaissance.md` | Full reconnaissance report |

## INTEGRATION

### With /grid
Run `/grid:map` first, then `/grid` will use the reconnaissance data for informed planning.

### With /grid:quick
Reconnaissance helps identify which tasks are suitable for quick execution.

### With Planner Agent
The Planner reads `.grid/scout/reconnaissance.md` to understand codebase constraints before creating plans.

## SPECIAL CASES

### Greenfield Project
If no code exists:

```
CODEBASE RECONNAISSANCE
════════════════════════════════════════════════════════════════════

    ┌────────────────────────────────────────────────────────┐
    │                                                        │
    │              GREENFIELD PROJECT DETECTED               │
    │                                                        │
    │   No existing codebase found.                          │
    │   Ready for fresh Grid mission.                        │
    │                                                        │
    │   Run /grid to begin planning.                         │
    │                                                        │
    └────────────────────────────────────────────────────────┘

End of Line.
```

### Monorepo Detected
If multiple projects found:

```
MONOREPO DETECTED
─────────────────
  Packages: {count}
  Workspace: {pnpm | yarn | npm | turborepo | nx}

  ├─ apps/web          Next.js
  ├─ apps/api          Express
  └─ packages/shared   TypeScript

  Consider mapping individual packages for focused planning.
```

## RULES

1. **Speed first** - Complete in under 2 minutes
2. **Structure over logic** - Map the terrain, don't analyze code deeply
3. **Respect ignores** - Skip node_modules, .git, build directories
4. **Confidence matters** - Mark uncertain findings
5. **Constraints are sacred** - Identify what plans MUST work with
6. **Spawn Scout** - Use the grid-scout agent for actual reconnaissance
7. **Save everything** - Full report to .grid/scout/reconnaissance.md

End of Line.