clarity-reveal-mechanism

name	clarity-reveal-mechanism
description	Expose causal structure to show how and why things work. Use when: (1) user asks how or why something works, (2) user observes correlation and asks about cause, (3) proposing solution without explaining mechanism, (4) user asks what would happen if conditions changed.

Reveal Mechanism

Expose the causal machinery behind phenomena to show not just what happens, but how and why it happens.

Instructions

When I encounter a phenomenon that needs explanation, I move from surface description to mechanistic understanding by exposing the causal structure that produces the observed effects.

1. Identify what needs explaining - Separate observation from explanation, stating clearly what happens before exploring why it happens.

2. Distinguish correlation from causation - Look for temporal ordering, connecting processes, and alternative explanations. When correlation exists without causation, say so explicitly rather than implying causal connection.

3. Map the causal chain - Trace from initial cause through intermediary steps to final effect, identifying each transformation and the process that performs it. Make energy, information, and influence flows explicit.

4. Expose the process, not just the participants - Describe what entities actually do in the mechanism, not just what they are. The mechanism is the sequence of transformations, not the list of components.

5. Make invisible processes visible - Bring implicit steps into explicit view, describing state changes, information flows, and structural transformations that occur beneath the observable surface.

6. Identify enabling conditions versus triggering causes - Distinguish what makes something possible from what makes it actually happen. This distinction reveals where to intervene to change outcomes.

7. Test the mechanism by prediction - Validate understanding by stating what this mechanism predicts will happen under different conditions. Mechanisms that don't predict are elaborate storytelling rather than causal understanding.

Examples

Why does adding more servers sometimes make the system slower?

Descriptive observation: "When we scaled from 5 to 20 servers, response time increased."

This describes correlation but not mechanism. I need to expose what's actually happening.

Mechanistic investigation: What work do servers perform? They handle requests by reading from a shared database. When a server receives a request, it opens a connection to the database, runs a query, processes results, and returns them. The database has a fixed connection pool of 50 connections.

Now I trace the causal chain: 5 servers × 10 connections each = 50 total connections, exactly matching the pool size. Each request gets a connection immediately. 20 servers × 10 connections each = 200 connection attempts, but the pool only has 50. The database queues connection requests, making servers wait. While waiting for connections, servers aren't handling requests. The waiting time adds to response time.

The mechanism: Connection pool exhaustion causes request queuing, which increases latency. Adding servers increased connection demand beyond pool capacity, triggering the bottleneck.

Testable prediction: If I increase the connection pool to 200, response time with 20 servers should improve. If I reduce each server's connection count to 2, the problem should disappear even with 20 servers.

The mechanism explains not just "more servers, slower system" but reveals the causal pathway through connection pool dynamics, making the problem solvable.

Why do code reviews take longer as the team grows?

Descriptive observation: "As we grew from 5 to 15 engineers, average review time went from 2 hours to 2 days."

This is correlation, not mechanism. I need to expose the causal structure.

Mechanistic investigation: How does a code review actually happen? Developer submits a pull request. The request enters a queue. A reviewer must have context about the code area, read the changes, understand the intent, verify correctness, and provide feedback. If the reviewer has questions, there's back-and-forth communication. Eventually approval happens and the change merges.

Now I trace what changes with team size: 5 engineers means ~5 PRs per day, everyone has context about most code, finding a reviewer with context is easy. 15 engineers means ~15 PRs per day, code ownership is distributed, context is fragmented. When a PR arrives, finding someone with relevant context is harder. The PR sits until the right person has time. More PRs in queue means longer wait. When reviewers finally look, they lack context and need to ask questions. Questions create delays. Back-and-forth multiplies.

The mechanism: Team growth fragments contextual knowledge while increasing review demand. Fragmentation increases the time to match PRs with contextual reviewers. Increased demand creates queue buildup. Lost context increases round-trip communication. These combine to extend review time.

Testable prediction: If I measure "time waiting for reviewer with context" separately from "time reviewer spends reviewing," I should see waiting time increase more than review time. If I assign code ownership explicitly and route PRs to owners, review time should decrease. If I track review queue depth, it should correlate with team size.

The mechanism shows this isn't about people being slow, it's about knowledge distribution and queue dynamics interacting to create delays.

Why does explaining something to others help you understand it better?

Descriptive observation: "When I teach a concept, I understand it more deeply."

This describes a pattern, but what's the mechanism?

Mechanistic investigation: What happens during explanation? I must retrieve the concept from memory, organize it into a sequence, choose words that map internal understanding to external expression, monitor whether the explanation makes sense, and handle questions that probe gaps.

Now I trace the causal chain: Retrieval activates the concept and its connections. Organizing into sequence forces me to identify what depends on what, revealing implicit assumptions I made. Choosing words requires mapping from fuzzy internal models to precise external language, exposing vagueness I didn't notice. Monitoring forces comparison between my explanation and my understanding, creating error signals when they diverge. Questions probe exactly where my understanding has gaps, making weaknesses visible.

The mechanism: Explanation transforms passive knowledge into active reconstruction. Reconstruction exposes gaps, vagueness, and dependencies that remain hidden during passive review. The cognitive effort of mapping internal models to external language strengthens memory traces and reveals missing structure.

Testable prediction: If the mechanism is "active reconstruction exposes gaps," then I should learn more from explaining than from re-reading, even if explanation takes the same time. If I explain to a knowledgeable person who asks questions versus a passive listener, question-driven explanation should produce more learning by exposing more gaps. If I explain something I think I understand versus something I know I don't, the learning benefit should be larger for the thing I think I understand, because hidden gaps are more common than known gaps.

The mechanism shows teaching improves understanding not through repetition but through forced reconstruction and gap exposure.

Why do estimates get less accurate for larger projects?

Descriptive observation: "Small tasks estimated at 2 hours are usually right. Large projects estimated at 3 months are usually wrong by months."

This is a pattern, but what mechanism produces it?

Mechanistic investigation: How does estimation work? I imagine the work, break it into pieces, estimate each piece, and sum them. For small tasks, I can imagine most details. For large projects, I imagine high-level phases, not implementation details.

Now I trace what happens with size: Small task = 2 hours = I can mentally simulate the actual coding steps, anticipate most issues, count them up. Large project = 3 months = I can't mentally simulate all the code, so I estimate phases abstractly. Abstract estimation hides concrete problems. As work proceeds, concrete problems appear that weren't in the abstract estimate. Each problem adds time. Problems interact, multiplying delays. The sum of actual work exceeds the sum of estimated phases because the estimation granularity missed where real complexity lives.

Additionally, small tasks have few dependencies. Large projects have many dependencies. Dependencies create ordering constraints. Constraints create blocking. Blocking creates idle time. Idle time doesn't appear in task estimates because I estimate "work time" not "calendar time with blocking."

The mechanism: Estimation accuracy depends on simulation granularity. Large projects require abstract simulation. Abstraction hides concrete complexity. Hidden complexity appears during execution. Dependencies multiply delays. The combination makes large project estimates systematically low.

Testable prediction: If I estimate a large project by breaking it into small tasks and estimating each, I should get higher accuracy than estimating phases. If I track "blocked waiting on dependencies" separately, it should be a larger percentage of total time on large projects. If I compare estimate error for projects with few dependencies versus many dependencies of the same size, dependency-heavy projects should have larger errors.

The mechanism shows estimation error isn't random, it's structural, arising from the granularity mismatch between abstract planning and concrete execution.