brokkai/brokk-skills/brokk-flow-graph

brokk-flow-graph

Overview

Systematically locate every entry point in a codebase, trace its execution paths using ripgrep, and emit one Mermaid flowchart TD diagram per entry point showing branches, function calls, and terminal outcomes (return, error, exit).

Prerequisites

Check for ripgrep before starting:

rg --version 2>/dev/null || echo "MISSING"

If missing: pip install ripgrep or cargo install ripgrep or winget install BurntSushi.ripgrep (Windows). Offer to install before proceeding.

Step 1 — Detect Language(s)

# Count files by extension to find dominant languages
rg --files | rg -o "\.[^.]+$" | sort | uniq -c | sort -rn | head -20

Note all significant languages — a polyglot repo needs language-specific entry point patterns applied to the right directories.

Step 2 — Find Entry Points

Run the patterns for each detected language:

# Example for Python
rg -n "if __name__|def main\(|@app\.route|@router\.(get|post|put|delete)|@click\.command" --type py

List all found entry points. Each becomes one Mermaid diagram.

Step 3 — Trace Execution Per Entry Point

For each entry point, trace 3 levels deep:

1. Read the entry function — note every function call, conditional branch, and terminal (return/raise/exit/throw)
2. For each called function, use ripgrep to find its definition and read it
3. Repeat one more level — 3 levels is enough for most legacy codebases; note if paths go deeper

# Find function definition across the codebase
rg -n "def <function_name>|function <function_name>|func <function_name>" --type <lang>

Track a node list and edge list as you read:

nodes: [A, B, C, D, E]
edges: [A→B, A→C, B→D, C→D, D→E(error), D→F(success)]

Mark terminal nodes:

• [success] — normal return/response
• [error] — exception/error response
• [exit] — process exit

Step 4 — Emit Mermaid Diagram

One flowchart TD per entry point. Use subgraphs to group layers.

flowchart TD
    A["POST /api/users\n(entry)"] --> B["validate_request()"]
    B -->|invalid| E1["400 Bad Request\n[error]"]
    B -->|valid| C["create_user()"]
    C --> D["hash_password()"]
    C --> F["send_welcome_email()"]
    D --> G["db.save()"]
    G -->|fail| E2["500 DB Error\n[error]"]
    G -->|ok| H["201 Created\n[success]"]
    F -->|fail| I["log warning\n[continue]"]

Naming rules:

• Node IDs: short alphanumeric, no spaces (createUser, E1, DB1)
• Node labels: use quotes for spaces/special chars
• Edge labels: use |condition| to name branches
• Keep diagrams to ~20 nodes max; split deeply nested paths into a linked sub-diagram

Step 5 — Output

For each entry point emit:

## Entry: <method> <path or function name>
**File:** `path/to/file.py:42`
 

flowchart TD ...

 
**Notes:**
- Any paths deeper than 3 levels (list them)
- Any unclear/dynamic dispatch that couldn't be traced

After all diagrams, emit a summary table:

Windows Notes

• Use rg (ripgrep) — works natively on Windows
• Path separators in output: rg returns OS-native paths; normalise with forward slashes in diagrams for readability
• Avoid grep, find, wc — use rg --count and rg --files instead

Common Mistakes