Linear Walkthrough

What needs to be understood?

# Whole project
"Create a walkthrough of this repository"

# Specific subsystem
"Walk through the authentication system"

# Single feature
"Explain how the search feature works"

2. Survey Entry Points

Find where execution starts:

# Find main entry points
find_symbol(name_path_pattern="main", include_info=True)
find_symbol(name_path_pattern="app", include_info=True)

# For web apps
get_symbols_overview(relative_path="src/routes", depth=1)
get_symbols_overview(relative_path="src/api", depth=1)

3. Trace Key Flows

Follow the critical paths:

Request → Router → Handler → Service → Database → Response

4. Document with Real Code

CRITICAL: Use grep/sed/cat to include code snippets, never copy-paste. This ensures accuracy and prevents hallucination.

# Include specific lines
sed -n '45,60p' src/auth/login.py

# Show function signature
grep -A5 "def authenticate" src/auth/service.py

# Find all handlers
grep -n "@app.route" src/routes/*.py

5. Save to Basic Memory

write_note_basic - memory(
    title="Walkthrough: {Project Name}",
    content="[walkthrough content]",
    directory="knowledge/walkthroughs",
    tags=["walkthrough", "understanding", "{project}"],
)

Walkthrough Structure

---