learning_ai_common_plat/AI.dev/SKILLS/scan-repo-context.md

# Scan Repo & Update Context Skill

**Description**: Scan entire repository and generate comprehensive context documentation for AI assistants.

## When to Use

- Onboarding new AI assistants or developers
- After major architectural changes
- Creating project documentation
- Setting up Windsurf/Cursor/other AI tools

## Prerequisites

- Full repository access
- Read permissions on all files
- Understanding of project structure

## Quick Start

```bash
# From repo root
/.windsurf/workflows/scan-repo-and-update-windsurf-context.md
```

Or run the workflow directly if supported:

```bash
/windsurf-workflow scan-repo-and-update-windsurf-context
```

## Scanning Process

### Phase 1: Read Key Documentation

Start with high-level understanding:

```bash
# Core documentation files
cat AGENTS.md                    # AI agent guide
cat README.md                    # Project overview
cat ARCHITECTURE.md              # Technical architecture
cat CONTRIBUTING.md              # Contribution guidelines
cat .windsurfrules              # Windsurf-specific rules
```

### Phase 2: Understand Project Structure

Scan directory structure:

```bash
# Get overview
find . -type d -maxdepth 2 | sort

# Key source directories
find . -name "src" -type d
find . -name "lib" -type d
find . -name "components" -type d
find . -name "modules" -type d

# Configuration files
find . -name "package.json" -o -name "Cargo.toml" -o -name "pom.xml" -o -name "build.gradle*"
```

### Phase 3: Analyze Code Organization

For each major component:

```bash
# List key files
ls -la src/
ls -la lib/
ls -la components/

# Find main entry points
find . -name "main.*" -o -name "index.*" -o -name "App.*"

# Find configuration
find . -name "*.config.*" -o -name "*.env*" -o -name "settings.*"
```

### Phase 4: Identify Patterns

Look for common patterns:

```bash
# API routes
find . -path "*/api/*" -name "*.js" -o -name "*.ts" -o -name "*.py"

# Database models
find . -name "*model*" -o -name "*schema*" -o -name "*entity*"

# Test files
find . -name "*test*" -o -name "*spec*"

# Documentation
find . -name "*.md" -o -name "*.rst" -o -name "*.txt"
```

## Generating Context Documentation

### Structure Template

```markdown
# [PROJECT_NAME] Context Documentation

> Auto-generated on: YYYY-MM-DD HH:MM
> Regenerate with: /scan-repo-and-update-windsurf-context

## Project Summary

[Brief 1-paragraph description of the project]

## Architecture

[High-level architecture overview]

## Module Map

| Module | Purpose                        | Key Files              |
| ------ | ------------------------------ | ---------------------- |
| auth   | Authentication & authorization | src/auth/, lib/auth.js |
| api    | REST API endpoints             | src/api/, routes/      |
| db     | Database layer                 | src/db/, models/       |

## Technology Stack

- **Frontend**: [Framework], [Language]
- **Backend**: [Framework], [Language]
- **Database**: [Database type]
- **Deployment**: [Platform]

## Key Directories
```

project-root/
├── src/ # Main source code
├── tests/ # Test files
├── docs/ # Documentation
├── config/ # Configuration files
└── scripts/ # Build/utility scripts

````

## Important Files
| File | Purpose |
|------|---------|
| package.json | Dependencies and scripts |
| .env.example | Environment variables template |
| docker-compose.yml | Container orchestration |
| README.md | Project documentation |

## Development Workflow
1. Setup: [Setup instructions]
2. Development: [How to run locally]
3. Testing: [How to run tests]
4. Deployment: [How to deploy]

## Common Commands
```bash
# Install dependencies
npm install

# Run development server
npm run dev

# Run tests
npm test

# Build for production
npm run build
````

## Coding Conventions

- [Language 1]: [Conventions]
- [Language 2]: [Conventions]
- File naming: [Pattern]
- Commit messages: [Format]

## API Endpoints

| Method | Path            | Purpose      |
| ------ | --------------- | ------------ |
| GET    | /api/health     | Health check |
| POST   | /api/auth/login | User login   |

## Database Schema

[Key tables/collections and relationships]

## Environment Variables

| Variable | Required? | Description         |
| -------- | --------- | ------------------- |
| API_KEY  | Yes       | External API key    |
| DB_URL   | Yes       | Database connection |

## Troubleshooting

### Common Issues

1. **Problem**: Solution
2. **Problem**: Solution

### Debug Commands

```bash
# Check logs
tail -f logs/app.log

# Debug mode
DEBUG=1 npm run dev
```

````

## Implementation for Different Project Types

### JavaScript/TypeScript Project

```bash
# Scan package.json for dependencies
cat package.json | jq '.dependencies, .devDependencies'

# Find TypeScript config
find . -name "tsconfig.json"

# Check for framework-specific files
ls next.config.js webpack.config.js vite.config.js
````

### Python Project

```bash
# Check requirements
cat requirements.txt pyproject.toml setup.py

# Find Python modules
find . -name "__init__.py" | head -20

# Check for Django/Flask
ls manage.py app.py wsgi.py
```

### Mobile Project (React Native)

```bash
# Check React Native config
cat package.json | jq '.dependencies | keys | map(select(contains("react-native")))'

# Find platform-specific code
ls android/ ios/

# Check for native modules
ls android/app/src/main/java/ ios/YourApp/
```

### Java/Kotlin Project

```bash
# Check Gradle configuration
cat build.gradle settings.gradle gradle.properties

# Find main source directory
find . -name "src/main/java"

# Check for Spring Boot
ls src/main/resources/application*.yml
```

## Automation Script

Create `scripts/generate-context.sh`:

````bash
#!/bin/bash
# Generate context documentation

echo "Scanning repository..."
PROJECT_NAME=$(basename $(pwd))
OUTPUT_FILE="WINDSURF_CONTEXT.md"

# Header
cat > $OUTPUT_FILE << EOF
# $PROJECT_NAME Context Documentation

> Auto-generated on: $(date)
> Regenerate with: /scan-repo-and-update-windsurf-context

EOF

# Project summary
if [ -f "README.md" ]; then
    echo "## Project Summary" >> $OUTPUT_FILE
    head -20 README.md >> $OUTPUT_FILE
    echo "" >> $OUTPUT_FILE
fi

# Directory structure
echo "## Directory Structure" >> $OUTPUT_FILE
echo '```' >> $OUTPUT_FILE
tree -L 2 -I 'node_modules|.git|dist|build' >> $OUTPUT_FILE
echo '```' >> $OUTPUT_FILE
echo "" >> $OUTPUT_FILE

# Dependencies
if [ -f "package.json" ]; then
    echo "## Dependencies" >> $OUTPUT_FILE
    echo '```json' >> $OUTPUT_FILE
    cat package.json | jq '.dependencies' >> $OUTPUT_FILE
    echo '```' >> $OUTPUT_FILE
fi

echo "Context documentation generated: $OUTPUT_FILE"
````

## Best Practices

### What to Include

1. **Project purpose** - What does this project do?
2. **Architecture** - How is it structured?
3. **Key components** - Main modules and their purpose
4. **Development setup** - How to get started
5. **Common tasks** - Frequently used commands
6. **Important patterns** - Coding conventions
7. **Troubleshooting** - Common issues and solutions

### What to Exclude

1. **Sensitive data** - Never include real keys/passwords
2. **Temporary files** - build/, dist/, node_modules/
3. **Personal notes** - Keep it professional
4. **Outdated information** - Keep it current

### Formatting Tips

1. **Use consistent formatting** - Markdown tables, code blocks
2. **Include examples** - Show, don't just tell
3. **Cross-reference** - Link to related sections
4. **Keep it scannable** - Use headings, lists, bold text

## Integration with AI Tools

### Windsurf

The generated `WINDSURF_CONTEXT.md` is automatically picked up by Windsurf.

### Cursor

Add to `.cursorrules`:

```
Always reference WINDSURF_CONTEXT.md for project understanding
```

### GitHub Copilot

Include in `.github/copilot-instructions.md`:

```markdown
## Project Context

See WINDSURF_CONTEXT.md for full project understanding
```

## Maintenance

### When to Update

- After major feature additions
- When architecture changes
- On regular schedule (monthly/quarterly)
- When new developers join

### Version Control

```bash
# Commit generated context
git add WINDSURF_CONTEXT.md
git commit -m "docs: update AI context documentation"
git push
```

## Notes

- **Keep it current** - Outdated context is worse than no context
- **Be comprehensive** - Include everything a new developer would need
- **Use examples** - Concrete examples are more helpful than abstract descriptions
- **Review regularly** - Ensure accuracy and completeness

## Related Skills

- [Update Agent Documentation](./update-agent-docs.md) - For AI-specific docs
- [Architecture Patterns](./architecture-patterns.md) - Understanding architecture
- [Local Development Setup](./local-development.md) - Setting up to work
- [Documentation Standards](./documentation-standards.md) - Writing good docs