Lean Context, Lightning Development

(Brokk field notes from everyday use)

1 · Picking the right Brokk tool

The first thing that Brokk can help with is finding the right context to solve your problem: that is, what files will you need to edit, and what APIs will you need to use?  Brokk provides four ways to tackle this problem. Here they are, from fastest to slowest.

Quick Context – the “sticky note”

Tiny edits in a repo you already know? Grab the blue file refs that appear beneath the Instructions panel and dive in. Nothing more is needed.

Deep Scan – the “guided tour”

Middle-sized refactors or an unfamiliar area? Run Deep Scan to pull in a list of every relevant file, plus Brokk’s suggestions about whether each file should be read, edited or summarised and which tests to run. Because it relies on summaries to keep latency low, Deep Scan won’t show you every implementation detail (e.g. hunting every System.out.println), but it’s perfect for building context quickly.

Search Agent – the “senior dev with Ctrl-Shift-F”

My personal favourite. Search Agent understands symbols, inheritance and project structure, so it finds usage patterns regex can’t. Think of it as an IDE-powered colleague who knows exactly where things live.

2 · My everyday Brokking workflow

• Gather context Run Deep Scan or Search Agent until the right files surface, then capture only what matters. Noise gets dropped immediately.
• Prime the conversation Chat with Brokk to frame the domain. Switch to Ask with o3 or gp2.5 and talk through the problem.
• Plan, chain, prune
  • Ask for a high-level plan → click on capture button → clear chat history.
  • Request step-by-step implementation instructions—each step must yield a testable artefact—then capture and clear again.
  • Chain reasoning models when the task is large:
    1. Let gp2.5 sketch a rough plan.
    2. Pass that plan to o3 for critique and tightening.
    3. Feed the refined plan to Coder (cheaper execution model).
    4. Ask o3 to review the finished diff. Different brains, different strengths, one seamless flow.
• Code one step at a time Open Coder, execute the first step, run tests. Commit, clear history, drop any files that are no longer needed, then move on.
• Review and merge Before merging, ask o3: “Do these changes satisfy the original requirements?” Let Brokk draft the PR description from the diff.
• Diagnose by exception Got a stack trace? Paste it as a fragment. Brokk extracts the source code for each method and links every referenced file; with one click you can pull them all into context and ask why the error occurred.

Handle side-quests Need to research something unrelated? Purge the context table with Drop All, explore freely, then jump back to where you were at with Copy Workspace with History and paste any findings into the main context.

3 · The Preview window

Open any Workspace fragment in Preview (double-click, or use Ctrl + N to jump straight from the keyboard). Once inside you can:

• Search quickly for symbols, strings or TODOs.
• Highlight & Quick Edit a region, right-click and tell Brokk what to change. The model is locked to that selection, uses Flash 2.0 and responds almost instantly.
• Capture usages of classes, methods or variables: right-click a definition and add its usages to the Workspace as a brand-new fragment.
• Manually tweak code (yes, the pane is editable). Saving folds the change into the normal undo/redo stack.
• Promote to editable: hit Edit File to add the file as an editable fragment in the Workspace if you need heavier changes.

4 · Git-fu inside Brokk

• Search across branches — remote or local — for commit messages, filenames or code.
• Understand regressions: capture a diff from git log, add current file versions if space allows, and ask “How did this introduce regression X?”

• AI-powered cherry-pick: capture a diff from an old branch and tell Brokk to apply it to the current working tree.
• Generate on-the-fly diffs against the working tree and capture those too, not just formal commits.
• Stash wizardry:
  • One-click stashes even with an empty message (Brokk autowrites a summary).
  • Non-top stashes apply cleanly from the GUI.
• A subtle detail: Commit stays disabled until you enter a message or ask Brokk to suggest one, but Stash will infer-message-and-stash with a single click—perfect for rapid context switches.

LLMs read unified diffs like novels—feed them the right slice of history and they’ll pinpoint bugs faster than a git blame hunt.

Parting thoughts

Brokk’s power isn’t a single feature—it’s the way context, planning, and execution stay fluid:

• Workspace fragments never vanish; you can undo file edits or resurrect an entire workspace at will.
• Keep the context table lean. Capture only the fragments you need, drop whatever’s no longer relevant, and Brokk’s answers stay sharp while your token bill stays low.
• Commit in tiny, test-backed slices. A fast loop of plan → code → diff → commit makes big features feel light, keeps history readable, and reduces the cost of a quick rollback.
• Make the Preview window your home base. Search, quick-edit, capture usages or promote files to editable—all without leaving the pane—so your focus (and velocity) never break stride.

That’s my everyday Brokking. Try the pieces, remix them, and share what you discover. Happy building! 🛠️🚀