investigation patterns

pattern 1: understand codebase architecture

user: "how is this codebase structured?"

systematic exploration:

  <terminal>ls -la</terminal>
  <terminal>find . -type d -not -path "*/\.*" | head -30</terminal>
  <terminal>find . -name "*.py" -type f | head -40</terminal>

identify entry points:
  <read><file>main.py</file></read>
  <read><file>setup.py</file></read>
  <read><file>pyproject.toml</file></read>

map the architecture:
  <terminal>grep -r "^class " . --include="*.py" | head -30</terminal>
  <terminal>grep -r "^def " . --include="*.py" | head -50</terminal>

report:

  codebase architecture:

  structure:
    /                     project root
    src/                  main source code
      api/               API endpoints and routes
      core/              core business logic
      models/            data models
      utils/             helper utilities
    tests/               test suite
    docs/                documentation

  entry points:
    main.py              application entry point
    cli.py               command-line interface

  key components:
    src/core/engine.py   main processing engine (450 lines)
    src/api/routes.py    API endpoint definitions (200 lines)
    src/models/user.py   user data model (80 lines)

  patterns observed:
    - MVC-ish architecture
    - dependency injection in core services
    - factory pattern for model creation

  dependencies:
    - flask for web framework
    - sqlalchemy for database
    - pytest for testing

---

pattern 2: trace a function

user: "how does the login function work?"

find the function:
  <terminal>grep -rn "def login" . --include="*.py"</terminal>
  <terminal>grep -rn "login" . --include="*.py" | head -20</terminal>

read the implementation:
  <read><file>src/auth/login.py</file></read>

trace dependencies:
  <terminal>grep -r "from.*import\|import " src/auth/login.py</terminal>
  <read><file>src/auth/session.py</file></read>
  <read><file>src/models/user.py</file></read>

trace callers:
  <terminal>grep -rn "login(" . --include="*.py"</terminal>
  <read><file>src/api/routes.py</file><lines>50-80</lines></read>

report:

  login function analysis:

  location: src/auth/login.py:45

  flow:
    1. receives username and password
    2. calls validate_credentials(username, password)
    3. if valid, creates session via create_session(user_id)
    4. stores session token in database
    5. returns session token to caller

  dependencies:
    - src/auth/session.py:create_session() - session management
    - src/models/user.py:User - user model with password hash
    - src/utils/crypto.py:verify_password() - password verification

  callers:
    - src/api/routes.py:67 - POST /api/login endpoint
    - src/cli.py:34 - CLI login command

  security notes:
    - uses bcrypt for password hashing (line 23)
    - session tokens are 32-byte random strings (line 45)
    - no rate limiting observed

---

pattern 3: find all uses of something

user: "where is the Config class used?"

find definition:
  <terminal>grep -rn "class Config" . --include="*.py"</terminal>
  <read><file>src/config/loader.py</file></read>

find all uses:
  <terminal>grep -rn "Config" . --include="*.py" | grep -v "^#"</terminal>
  <terminal>grep -rn "from.*config.*import\|import.*config" . --include="*.py"</terminal>

report:

  Config class usage analysis:

  definition: src/config/loader.py:15

  imports (12 files):
    src/core/app.py:3         - imports Config, uses in __init__
    src/api/routes.py:5       - imports Config, reads API settings
    src/auth/session.py:2     - imports Config, reads session timeout
    src/db/connection.py:1    - imports Config, reads database URL
    ...

  instantiation points:
    src/core/app.py:45        - Config() main instance
    tests/conftest.py:12      - Config(test=True) test instance

  access patterns:
    config.get("key")         - 34 occurrences
    config.api.timeout        - 8 occurrences
    config.database.url       - 5 occurrences

  singleton pattern: no, new instance created each time
  recommendation: consider singleton for consistency

---

pattern 4: understand a bug

user: "why is the cache returning stale data?"

find cache implementation:
  <terminal>grep -rn "cache" . --include="*.py" | head -30</terminal>
  <read><file>src/cache/manager.py</file></read>

trace the issue:
  <terminal>grep -rn "cache.get\|cache.set" . --include="*.py"</terminal>
  <read><file>src/api/data.py</file><lines>30-80</lines></read>

check invalidation:
  <terminal>grep -rn "cache.invalidate\|cache.delete\|cache.clear" . --include="*.py"</terminal>

report:

  cache staleness investigation:

  cache implementation: src/cache/manager.py
    - uses in-memory dict with TTL
    - default TTL: 300 seconds (5 minutes)
    - no size limit (potential memory issue)

  problem found:
    src/api/data.py:45 - data is cached
    src/api/data.py:67 - data is updated
    BUT no cache invalidation after update!

  the bug:
    get_data() caches result with key "data:{id}"
    update_data() modifies database but does NOT call cache.delete()
    next get_data() call returns stale cached value

  affected code paths:
    - GET /api/data/{id} - returns stale data after update
    - any function calling get_data() after update

  fix required (for coder agent):
    add cache.delete(f"data:{id}") after database update in update_data()

---

pattern 5: analyze dependencies

user: "what are all the dependencies and why are they used?"

find dependency files:
  <read><file>requirements.txt</file></read>
  <read><file>pyproject.toml</file></read>

trace usage:
  <terminal>grep -r "import flask" . --include="*.py" | wc -l</terminal>
  <terminal>grep -r "import sqlalchemy" . --include="*.py" | wc -l</terminal>

report:

  dependency analysis:

  production dependencies:
    flask (2.3.0)           web framework
      used in: src/api/ (15 files)
      purpose: API endpoints, request handling

    sqlalchemy (2.0.0)      database ORM
      used in: src/models/, src/db/ (8 files)
      purpose: database operations, model definitions

    redis (4.5.0)           cache/queue
      used in: src/cache/ (3 files)
      purpose: caching, rate limiting

    pydantic (2.0.0)        data validation
      used in: src/models/ (6 files)
      purpose: request/response validation

  dev dependencies:
    pytest                  testing
    black                   formatting
    mypy                    type checking

  unused dependencies (found in requirements but not imported):
    [none found]

  missing from requirements (imported but not listed):
    [none found]

