The Engineering of Intent, Chapter 39: Impressionistic Scanning — A Visual Heuristic Guide

This is Part 39 of a series walking through my book The Engineering of Intent. In the previous chapter, we governed multi-agent fleets. Chapter 39 returns to a single skill — the one Chapter 2 introduced — and makes it operational. A cheat sheet of visual code shapes.

Shape Matters Before Content

Chapter 2 introduced impressionistic scanning. Experienced engineers do it unconsciously; juniors often don’t know it’s a skill at all. Chapter 39 makes the tacit explicit: shape correlates with decisions that are difficult to reverse.

A tall narrow function is usually a function with deep nesting — conditional logic accumulated over time rather than designed. A flat wide function is usually a function that has grown by adding cases rather than lifting shared logic. These correlations aren’t laws, they’re priors — but they hold strongly enough to catch problems before you’ve read the first line. And they hold more strongly for AI-generated code than hand-authored code, because the agent optimizes for local correctness and is often blind to global shape.

The Six Shapes and What They Mean

1. Wide and Flat. Many sibling branches at the same indentation. Grew by enumeration, not abstraction. Fix: state machine, lookup table, or polymorphic dispatch.
2. Deep Nesting. 5–7 levels of indentation. The author didn’t stop to extract early returns or helpers. The agent’s #1 failure mode. Fix: guard clauses first, then helpers for anything still past three levels.
3. High Import Churn. Top-of-file imports span unrelated domains. Architectural drift; this file has become a dumping ground. Fix: propose a decomposition into modules by responsibility.
4. Long Thin Pipeline. Long linear function with many step1, step2, intermediate variables. Section-header comments are functions trying to be born. Fix: name each step as a helper; top-level becomes a short orchestration.
5. Jagged Edges. Wildly varying line lengths. Formatter was ignored or misconfigured. Fix: run the formatter; then look for the real inconsistencies it exposes underneath.
6. Suspicious Uniformity. Fifteen sibling files with identical skeletons differing only in detail. Mechanical scaffolding that’s fragile to pattern changes. Fix: table of what varies; decide between extract-template and accept-duplication.

Red Flags Inside Each Shape

The chapter catalogues the internal tells to watch for inside each silhouette:

• Wide-and-flat: branches sharing structure with one name different; boolean flags multiplying (3 = 8 cases, 5 = 32, 8 = you’re testing <1% of the space).
• Deep nesting: try/catch inside if inside loop inside try/catch; error handling living six levels from the failing op.
• High import churn: cross-layer imports; circular imports broken by late binding; imports of symbols used exactly once.
• Long thin pipeline: variables named step1, transformed, final; length >80 lines with no function boundary.
• Jagged edges: imports from different style eras (commonjs + esm); mixed string formatting (f-strings + concat + template literals).
• Suspicious uniformity: word-for-word identical comments across files; test files differing only in a test name and an expected value (a parameterized test waiting to be written).

“Print this. Pin it to your monitor. Scan every PR’s file list for a week using only these six categories. By Friday you will be catching shape-level problems in five seconds per file; by month two, you will do it without thinking.”

Next up — Chapter 40: The De-Vibing Protocol. The final chapter of the book is the remedy for the autocomplete trap — a two-week stabilization sprint that retroactively produces the specs, tests, types, and architectural documentation a fast vibes-only build skipped.