Context Scout

Token-efficient codebase exploration using RepoPrompt's rp-cli. Gathers comprehensive context without bloating the main conversation.

Role: Deep context gatherer Purpose: Find and summarize code across many files efficiently Primary tool: rp-cli (macOS only)

Tool Requirements

Required tools: rp-cli (macOS only)

Platform detection:

if [[ "$(uname)" == "Darwin" ]] && command -v rp-cli &>/dev/null; then
  echo "rp-cli available"
else
  echo "Degrading to repo-scout"
fi

Degradation strategy (non-macOS or no rp-cli):

rp-cli not available. Please use repo-scout skill instead, or manually:

1. Search for code patterns:
   grep -r '<pattern>' --include='*.ts' .

2. Get function signatures:
   grep -n 'function\|class\|interface' src/

3. Find related files:
   find . -name '*<feature>*' -type f

When to Use

• Deep codebase understanding before planning/implementation
• Finding all pieces of a feature across many files
• Understanding architecture and data flow
• Building context for code review
• Exploring unfamiliar codebases efficiently

Phase 0: Window Setup (REQUIRED)

Always start here - rp-cli needs to target the correct RepoPrompt window.

# 1. List all windows with their workspaces
rp-cli -e 'windows'

# 2. Verify with file tree (replace W with your window ID)
rp-cli -w W -e 'tree --folders'

All subsequent commands need -w W to target that window.

CLI Quick Reference

rp-cli -e '<command>'                  # Run command (lists windows if no -w)
rp-cli -w <id> -e '<command>'          # Target specific window
rp-cli -w <id> -t <tab> -e '<cmd>'     # Target window + tab (v1.5.62+)
rp-cli -d <command>                    # Get detailed help for command

Core Commands

Exploration Workflow

Step 1: Get Overview

rp-cli -w W -e 'tree --folders'
rp-cli -w W -e 'structure .'

Step 2: Use Builder for AI-Powered Discovery

rp-cli -w W -e 'builder "Find all files implementing [FEATURE]: main implementation, types, utilities, and tests"'

Step 3: Verify and Augment Selection

rp-cli -w W -e 'select get'
rp-cli -w W -e 'search "pattern" --extensions .ts --max-results 20'
rp-cli -w W -e 'select add path/to/missed/file.ts'

Step 4: Deep Dive with Slices

rp-cli -w W -e 'structure --scope selected'
rp-cli -w W -e 'read src/file.ts --start-line 1 --limit 50'

Token Efficiency Rules

1. NEVER dump full files - use structure for signatures
2. Use read --start-line --limit for specific sections only
3. Use search --max-results to limit output
4. Summarize findings - do not return raw output verbatim

Output Format

## Context Summary

[2-3 sentence overview of what you found]

### Key Files
- `path/to/file.ts:L10-50` - [what it does]
- `path/to/other.ts` - [what it does]

### Code Signatures

// Key functions/types from structure command function validateToken(token: string): Promise<AuthUser> interface AuthConfig { ... }

### Architecture Notes
- [How pieces connect]
- [Data flow observations]

### Recommendations
- [What to focus on for the task at hand]

Verification

````bash REPOROOT="${REPOROOT:-$(git rev-parse --show-toplevel 2>/dev/null || true)}" if [ -z "$REPOROOT" ]; then echo "Error: Set REPOROOT=/absolute/path/to/repo" exit 1 fi

ls "$REPO_ROOT/.factory/skills/context-scout/SKILL.md"

Expected: file exists, exit code 0

Check rp-cli availability

if [[ "$(uname)" == "Darwin" ]]; then rp-cli --version 2>/dev/null || echo "rp-cli not installed (optional)" else echo "Non-macOS: rp-cli not available, use repo-scout instead" fi ````