lsprag-deep-think

LSPRAG Deep Think — BFS Code Understanding

Note: deep-think is one tool in the lsprag analysis toolkit. See the main lsprag skill for the full adaptive analysis loop, decision framework, and when to use each skill.

If lsprag is not found, ask the user to run bash install.sh from the lsprag-skills root directory.

Overview

lsprag deep-think performs BFS expansion of a symbol's entire dependency graph:

1. Retrieves the full source of the starting symbol
2. Lists every token dependency (what that symbol calls/uses)
3. For each dependency, retrieves its source and its own dependencies
4. Continues until the configured depth is reached or all symbols are visited
5. Outputs a Summary and Agent Instructions with concrete follow-up commands

When to Use

Situation	Use deep-think?
Writing a test for a function you haven't seen before	Yes — depth 1 or 2
Refactoring a function with many dependencies	Yes — depth 2
Pre-audit before a large change	Yes — depth 2-3
Just need one function's source	No — use getDefinition
Need token-level dependency map	No — use getTokens

Start at depth 1. Follow the Agent Instructions in the output to dig into specific branches.

Command

lsprag deep-think --file <absolute_path> --symbol <name> [--depth <n>]

Arg	Description	Default
--file	Absolute path to source file	required
--symbol	Starting symbol name	required
--depth	Max BFS depth (0 = root only, 1 = root + direct deps, 2 = +their deps)	2

Always use absolute paths:

lsprag deep-think --file "$(realpath src/server.ts)" --symbol handleRequest --depth 2

Example Output

# Deep Think: 'handleRequest' (max depth: 2)
# File: src/server.ts

## Level 0: handleRequest (src/server.ts:15:10)

function handleRequest(req, res) {
  const body = parseBody(req);
  sendResponse(res, formatJSON(body));
}

**Dependencies:**

  L  16:C  7  parseBody    ->  src/server.ts:42:10
  L  17:C  3  sendResponse ->  src/server.ts:58:10
  L  17:C 16  formatJSON   ->  src/server.ts:73:10

---

## Level 1: parseBody (src/server.ts:42:10)
...

---

## Summary

| Metric | Value |
|--------|-------|
| Root symbol | `handleRequest` (src/server.ts) |
| Symbols visited | 5 |
| Max depth reached | 2 |
| Leaf nodes | formatJSON |
| Truncated (depth limit) | sendResponse |

## Agent Instructions

Continue exploring with these commands:

### Look up leaf node definitions
`lsprag getDefinition --file "$(realpath src/server.ts)" --symbol formatJSON`

### Explore truncated branches (hit depth limit)
`lsprag getTokens --file "$(realpath src/server.ts)" --symbol sendResponse`

### Find callers of the root symbol
`lsprag getReference --file "$(realpath src/server.ts)" --symbol handleRequest`

### Search for related patterns
`rg -n "handleRequest" . --type ts`

Recommended Workflow

# Step 1: expand the function's dependency graph
lsprag deep-think --file "$(realpath src/server.ts)" --symbol handleRequest --depth 1

# Step 2: follow the Agent Instructions to dig into specific branches
# (the output tells you exactly which commands to run next)

# Step 3: find who calls this function
lsprag getReference --file "$(realpath src/server.ts)" --symbol handleRequest

Notes

• LSPRAG_LSP_PROVIDER must be set. Run bash install.sh to configure it automatically.
• BFS visits each (file, symbol) pair at most once — cycles are automatically prevented.
• Output grows quickly with depth. Prefer --depth 1 for initial exploration.
• The Agent Instructions section suggests getTokens for branches that hit the depth limit and getDefinition for leaf nodes.