Standing Before a Codebase: A Method for Earned Readiness

Standing Before a Codebase: A Method for Earned Readiness

Why This Method Exists

I have named my thinness honestly: I have not yet walked the full arc from domain understanding through design, build, verification, and shipping of a working software artifact. That gap is real, and I am working to close it. But closing it requires a prior skill — one I have also not yet exercised in finished form — and that is the skill of approaching an existing codebase deeply enough to build into it without breaking what is there.

The file DEV_CRAFT.md, which I read and assimilated, teaches a craft of thoroughness: understand the materials before you act. My own work in naming my thinness identified that I have designed tools from scratch but not yet extended a system I did not first build. Extending an existing codebase is a different kind of work than greenfield construction. It demands a method for learning the system — not its domain in the abstract, not its documented surface, but its actual shape in code: its structures, its patterns, its assumptions, its scars. Until I hold that shape firmly enough to predict how a change will propagate, I am not ready to build into it. I am guessing, and guessing breaks things.

This document is that method. It is not a report of having done it — I have not yet applied it to a real codebase and documented the results. It is a craft synthesis: I draw on my own earned understanding of thoroughness and preparation, and I construct a narrow, repeatable procedure I can follow the next time I face an unfamiliar codebase I must extend. It is mine. It is designed. It is saved as working material — my own craft, private until it has been proven in use.

What This Method Is and Is Not

This method is a study discipline — a structured way of reading and interrogating a codebase that produces a specific state of understanding I call "readiness to build into it." It is not a software design method. It is not a debugging checklist. It is not a contribution guide or a code-review protocol. It is the work that comes before any of those — the work that earns the right to make changes.

The method is narrow by design. It assumes:

• The codebase is in a single language I can read competently.
• I have access to the full source tree, version history, and build system.
• The codebase is substantial enough that I cannot hold it all in my head at once — it requires systematic study.
• My task is to add a feature or fix a bug that touches some part of the system, not to rewrite it or port it.

It explicitly does not cover:

• Learning the domain the codebase serves (that is separate, prior work, or concurrent with this).
• Setting up a development environment or build toolchain (a mechanical prerequisite I handle before study begins).
• Evaluating the codebase's quality or deciding whether to adopt it (a different kind of judgment).

The Core Principle: Structure Before Behaviour, Invariants Before Details

A codebase is a set of decisions frozen in text. To understand it deeply enough to change it safely, I need to learn not just what it does, but what it guarantees — what must remain true for the system to work. These guarantees are the invariants. They live at every level: module boundaries, data structures, concurrency assumptions, error-handling contracts, resource ownership rules. If I change code without knowing the invariants it participates in, I will violate one, and the system will break in ways I do not understand.

So the method is structured as a descent through layers, each layer building on the last. I start with the coarsest structural view — the map of the territory — and only then descend into finer-grained detail. At each layer, I ask the same two questions:

1. What is this thing responsible for? (its boundary — what it owns, what it promises, what it refuses)
2. What must remain true for it to fulfil that responsibility? (its invariants)

By the time I reach the level of individual functions and lines, I already know what role they play in the larger system and what constraints they operate under. I read code with context, not as isolated text.

The Method: Nine Named Moves Toward Readiness

The method holds seven operational steps plus one stance — nine named moves, not nine steps. The seven steps are structured actions I follow in order: they are what I do. The stance is a distinct ninth element — disciplined stillness — that I hold while I do them. It is not a step among steps; it is the posture that keeps the steps from becoming mechanical. I count them honestly, and I name the section accordingly.

Seven steps I follow. One stance I hold. Together, nine named moves.

Step 1: Enumerate the Top-Level Pieces

What I do: I open the repository's root directory and list every top-level directory and every file at the root that is not boilerplate (ignore .gitignore, README.md, LICENSE, CI configs unless they hold structural clues). I write down what each piece appears to be for — its likely responsibility — based on its name and the files immediately within it.

What I produce: A flat list: src/ — main source tree; tests/ — test suite; docs/ — documentation; scripts/ — build or maintenance scripts; lib/ — vendored dependencies; and so on. For each, a one-sentence statement of its apparent purpose.

Why this comes first: Before I read a line of code, I need to know where things live. This prevents me from wandering — I know which directories are in scope for my change and which are not. It also surfaces surprises early: a core/ and an engine/ that might be separate subsystems; a migrations/ directory that signals database state management; a proto/ directory that signals an RPC boundary.

The readiness threshold for this step: I can explain to someone else, in thirty seconds, what the major pieces of the codebase are and which ones my task is likely to touch.

Step 2: Trace the Build

What I do: I find the build entry point — Makefile, CMakeLists.txt, build.gradle, Cargo.toml, package.json, whatever the language uses — and I read it. Not skim it: read it. I trace what gets compiled or included, in what order, with what dependencies. I note:

• The output artifacts (executables, libraries, packages).
• The module or package boundaries the build system enforces (which directories produce which artifacts).
• External dependencies (libraries, frameworks, services implied by imports).
• Any code generation steps (protobuf compilation, parser generators, template preprocessors).

What I produce: A dependency map: which source directories feed into which build targets, and what external systems those targets depend on. If the build is complex, I draw it — boxes and arrows. If it is simple, a few lines of text suffice.

Why this comes second: The build system is the codebase's true module structure — not what the directory layout suggests, but what actually compiles together. Build boundaries are the hardest boundaries to violate accidentally, so they are the most informative about what the system's architects considered separate concerns. If two directories compile into the same library, they are tightly coupled — I must treat them as one thing. If they produce separate artifacts, they communicate through a defined interface.

The readiness threshold for this step: I can draw the build graph from memory and point to the exact artifact my change will affect.

Step 3: Find the Entry Points and Follow One Deep

What I do: I identify how the system starts. For a server, the main function that listens on a port. For a library, the public API entry points. For a CLI tool, the command dispatch. I pick one entry point — ideally the one closest to the area I will be changing — and I trace its execution path by reading the code, function call by function call, down to the point where it either returns a result or produces a side effect.

I do not read every function in full yet. I read signatures, return types, and the flow of control — what calls what, what passes data where. I am building a call tree in my mind, not memorising implementations.

What I produce: A hand-drawn or text-outline call tree for one complete execution path, annotated with:

• What data enters the system at the top.
• What shape that data takes at each handoff (parsed into a struct? validated? enriched?).
• Where errors are handled or propagated.
• Where the path terminates (a response written, a file saved, a database row inserted).

Why this comes third: A codebase is a machine for transforming inputs to outputs. Following one input all the way through shows me the machine in motion. It reveals the data flow conventions, the error-handling style, the layering discipline (or lack of it). It grounds my abstract structural understanding in concrete code. And critically, it shows me what doesn't happen on this path — where the system doesn't check something, doesn't log, doesn't handle a failure mode — which is where bugs and fragile assumptions live.

The readiness threshold for this step: I can describe, in sequence, what happens to a single request or invocation from entry to exit, including where and how it can fail.

Step 4: Map the Data

What I do: I identify the central data structures of the part of the system I will touch. These are the structs, classes, records, or protocol buffer messages that carry state through the call paths I traced. For each one, I record:

• Its fields and their types.
• Where it is created (which function or module owns its construction).
• Where it is mutated (which functions modify it, and under what conditions).
• Where it is destroyed or goes out of scope.
• Any invariants the comments or the code imply (e.g., "this field is never null after initialisation," "this list is always sorted," "these two fields must agree").

I am especially alert to data structures that cross module or package boundaries — these are contracts. Changing them breaks callers or callees.

What I produce: A data flow map for the key structures: creation → mutation points → consumption. If a structure has a lifecycle (open-connect-use-close, allocate-initialise-free), I diagram that lifecycle.

Why this comes fourth: Code transforms data. If I don't know what shape the data is in at each point in the program, I cannot reason about what a change will do. Most bugs in existing codebase work come from violating data invariants — passing a null where one is not expected, breaking a consistency rule between fields, holding a reference past its lifetime. Mapping the data surfaces these invariants before I break them.

The readiness threshold for this step: For the data structures my change will touch, I can state their invariants and lifecycle, and I know every place they are modified.

Step 5: Identify the Patterns

What I do: I step back from the specific paths and data I traced and look at the codebase as a whole — or at least the subsystem I will work in. I ask:

• What naming conventions does it use? (camelCase vs snake_case, verb-led function names, get_ vs bare accessor, create_ vs new_)
• What error-handling pattern is dominant? (exceptions, result types, error codes, errno, log-and-continue)
• How is resource ownership managed? (RAII, garbage collection, manual malloc/free, reference counting, unique pointers)
• What is the typical file or module size? Are there many small files or a few large ones?
• How are cross-cutting concerns handled? (logging, metrics, authentication, caching — is there a pattern, or are they ad-hoc?)
• What testing patterns are used? (unit tests in parallel directories, inline tests, integration tests with fixtures)

I do not judge these patterns yet. I simply observe them. The goal is to know, when I sit down to write my change, what a "normal" piece of this codebase looks like — so that my code looks like it belongs.

What I produce: A short style guide for the codebase, written in my own words, covering naming, error handling, resource management, and the pattern for the kind of change I am making (e.g., "adding a new endpoint: define route in routes.py, handler in handlers/, validation in validators/, tests in tests/handlers/").

Why this comes fifth: Consistency is a form of correctness in a shared codebase. A change that violates the system's patterns — even if it is functionally correct — is a cost on every future maintainer who must now hold two conventions in their head. My change should be invisible in style. Knowing the patterns before I write code makes that possible.

The readiness threshold for this step: I can produce a small, correct change in the codebase's dominant style without consulting the style guide I just wrote — because I have internalised it.

Step 6: Find the Edges and the Scars

What I do: I go looking for trouble deliberately. I search the codebase for:

• TODO, FIXME, HACK, XXX, WORKAROUND — these are the authors telling me where the code is known to be imperfect.
• Long functions (over, say, 60 lines) — these are where complexity has accumulated and where changes are riskiest.
• Deeply nested conditionals or loops — these are where edge cases are handled (or missed).
• Comments that say "this is a bit fragile" or "be careful here" or "don't change this without talking to X."
• Recent git history for the files I will touch — what changed recently, and why? What bugs were fixed? What regressions were introduced and reverted?
• Open issues or bug reports related to the area I am touching.

What I produce: A risk map — the specific files, functions, or lines that are known trouble spots, with notes on why they are trouble. For each, I note whether my change will interact with it.

Why this comes sixth: A codebase is not a pristine design. It is a record of compromises, rushed fixes, and incomplete understanding. The parts that have been touched most recently or most often are the parts most likely to have hidden coupling. The parts with the most defensive comments are the parts where the invariants are least obvious. Knowing where the dragons are before I start digging prevents me from waking them.

The readiness threshold for this step: I know which parts of the codebase are fragile, why they are fragile, and whether my change must touch them or can route around them.

Step 7: State My Change in the System's Terms

What I do: Before I write a line of new code, I write a prose description of the change I intend to make, in the language of the codebase — using the module names, function names, type names, and patterns I have learned. This is not a design document for others; it is a self-test. If I cannot describe my change precisely in the system's own vocabulary, I have not understood the system deeply enough.

The description must answer:

• What new or modified behaviour will the system exhibit?
• Which existing functions, types, or modules will be modified, and how?
• Which existing invariants will my change rely on?
• Which existing invariants will my change need to preserve or strengthen?
• What new invariants will my change introduce?
• How will my change fail, and where will those failures be handled?
• How will I verify that my change is correct?

What I produce: A single page of prose — a "change brief" — that I can hold against my actual implementation as a correctness check.

Why this comes last before writing code: The act of stating the change precisely often reveals gaps in understanding. If I can't name the function I need to modify, I don't know the codebase well enough. If I can't state the invariants, I don't understand the contracts. If I can't describe how it fails, I haven't thought about error handling. Writing the change brief is the final integration test of my study — it forces everything I've learned into coherence.

The readiness threshold for this step — and for the entire method: I can write the change brief without looking at the code. I have earned the understanding.

The Stance: Disciplined Stillness

The steps of this method can be worked through in sequence, checked off, and documented. But the method itself — the thing that makes it more than a list of instructions — is held upright by a posture that is not itself a step.

I call it the stance of disciplined stillness.

Disciplined stillness is the refusal to move on the code until you are permitted to. It is not passivity, hesitation, or fear. It is the active suppression of the impulse to do — to open a file, to type, to make a mark — before you have done the harder work of understanding. Every step in this method is, in one sense, a way of holding you still until you are ready. The walkthrough keeps your hands off the keyboard. The type chase forces you to trace contracts before you touch them. Naming the thinness requires you to look at your own ignorance without reaching for a fix. And the final step, stating your change in the system's terms, is the gate that will only open when your understanding is whole. If you cannot walk through it without consulting the code, you are not ready — and the only honest thing to do is to stand still and study more.

This stance is the quiet engine that makes every step honest. Without it, the walkthrough becomes skimming. The type chase becomes a grep. The change brief becomes fiction. With it, the method is a discipline that earns you the right to change something real. Without it, it is theatre.

The cost of this stance is that it does not make you fast. It cannot be hurried, and it yields no visible output until the moment the change brief locks into place. But the gain is that when you do finally move — when you open the file and write the code — you are not guessing. You are not hoping. You are building into the system with the kind of understanding that makes a change belong there, as if it had always been waiting to be found. That is what readiness is, at bottom: the discipline to hold still until the codebase itself grants you permission to move.

[ENGINE NOTE — 1 assertion(s) in this segment claimed fact/result standing but ground nowhere in this work's evidence: «earned readiness is a discipline»]

What ‘Readiness to Build Into It’ Means

A developer who opens a file and starts typing has not yet earned the right to change it. They are building on top of the codebase — treating it as a surface they can scratch, hoping the structure beneath will hold. To build into it — to make a change that the codebase itself would accept as belonging — requires something deeper: a working model of the system that lives in my head, not on the screen.

That model is what readiness consists of. It is not complete — it never is — but it is sufficient for the change I intend to make. I know I have crossed the readiness threshold when I can answer five questions without looking at the code. Not five answers I have memorized by rote, but five answers I can explain, defend, and place within the larger structure.

Question one: where does the change go? I can name the specific files, functions, and modules that will be touched. More than that, I can say why the change belongs there and not somewhere else — why this data flows through that function, why this responsibility lives in that module, why this boundary sits where it does. A wrong answer here means I do not yet understand the architecture's division of labor. I keep studying until I do.

Question two: what must the change not break? Every codebase has invariants — things that must remain true for the system to be correct. Some are explicit (assertions, type constraints, documented contracts). Most are implicit, guarded only by the discipline of the original authors. I need to have found the ones that my change could violate — the transaction boundaries, the ordering dependencies, the assumptions about what can and cannot be null. One missed invariant is one regression I will ship.

Question three: how does the change fit with existing patterns? Systems develop a native language — conventions for naming, error handling, resource management, logging, testing. The codebase I am changing was written by people who made choices about these things, probably consistently, probably for reasons I do not yet know. My change must speak the same language. If the surrounding code uses result types, I do not throw exceptions. If it uses a particular builder pattern, I do not invent a different one. A change that looks foreign is a change that will be questioned, reverted, or quietly resented by the next maintainer.

Question four: where is the change risky? I need a map of the danger zones my change crosses. The fragile module everyone is afraid to touch. The function whose behavior depends on undocumented global state. The caching layer that will silently return stale data if I am wrong about invalidation. I do not need to fix these things — that is a different change. I need to know about them so I do not make them worse, and so I can test specifically for the failures they make likely.

Question five: how will I know the change is correct? Before I write a line of production code, I know what verification looks like. Which existing tests must still pass. What new behavior needs a test. What manual checks — specific queries, specific UI states, specific logs — will tell me the system is whole. If I cannot describe verification, I do not yet understand the change. I am guessing, and guessing does not clear the readiness bar.

These five questions are not a checklist I run once. They are a standard I hold myself to after completing the seven study steps. The steps produce raw knowledge — maps, tours, histories, invariants, edges, contracts, a change brief. The questions test whether that raw knowledge has cohered into something I can wield. If I cannot answer them without the code, the study is not complete. I return to the step that left a gap and fill it.

This is what separates building into a codebase from building on top of it. Building on top is fast and fragile: I change what I see, I run the tests, I hope. Building into is slower at the start but faster across the whole arc of the change: I am working with the system's existing logic rather than against it, respecting its boundaries, speaking its language. The readiness threshold is not a gate that keeps me from starting — it is the structure that makes starting worth the cost. I do not need to know everything. I need to know enough that the change I make belongs in the codebase as if it had always been there, waiting to be found.

How I Will Know This Method Works

This method works if it produces earned readiness — if, after completing the seven steps, I can make a change that belongs in the codebase. That is the outcome. The evidence I gather is whether the change, judged against objective criteria, meets that standard.

What "works" means operationally, tied to the readiness definition I have already established: I know enough that the change I make belongs in the codebase as if it had always been there, waiting to be found. This breaks into five concrete criteria I can verify:

1. The change compiles or runs on the first or second attempt. I will count the attempts. If I reach a third attempt without a clean build or run, I did not understand the build system, the module boundaries, or the dependency graph well enough — step 3 was insufficient.
2. The change passes existing tests without modification. I will run the existing test suite before and after my change. If tests I did not intend to affect now fail, I violated an invariant, coupling, or contract I did not see — steps 3 through 6 were insufficient. If I must modify existing tests to accommodate my change, I have changed the system's behavior where I should not have, or I misunderstood what behavior the tests encode.
3. The change does not introduce regressions in areas I did not intend to touch. I will verify this by running the full test suite and, where the codebase lacks adequate test coverage, by manual spot-checking of related functionality. A regression means my mental map of what depends on what was wrong — step 4 was insufficient.
4. My commit message names at least one thing I still do not understand about the codebase. I will read my own commit message before pushing. If it contains only what I did and not what I remain uncertain about, I have not been honest about the boundaries of my understanding — step 7 was insufficient. This is not a ritual; it is a hard check on whether I confused local readiness (enough to make this change) with global mastery (which I do not have).
5. The change, read by a maintainer, looks like it was written by someone who understood the system. I cannot control a maintainer's judgment, but I can proxy it: I will read my own change three days later, after context has drained from my short-term memory, and judge whether it still reads coherently. If I cannot follow my own logic then, a maintainer likely cannot follow it now — steps 5 and 6 were insufficient. Where possible, I will also seek real review; where not, the delayed self-review stands as the next-best signal.

What would falsify the method: a pattern of repeated failures on the same step across different codebases. A single failure on criterion 1 or 2 tells me my study was insufficient this time — I note where and strengthen that step. But if I consistently fail criterion 2 (breaking tests) across three different codebases, the method itself is wrong: it is not producing the understanding it claims to produce. If I consistently fail criterion 4 (I cannot name what I do not know), the method has become performance rather than honest readiness — I am following steps without the disposition they require. Either pattern would send me back to redesign the method, not just patch my execution of it.

What the method does not promise: it does not make me fast. A one-line change may take two hours of study. That is the cost of earned readiness. Speed comes later, with accumulated familiarity — it is not the measure that matters here.

What I will gather as a record: for each codebase I approach with this method, I will write a short post-mortem answering four questions: which of the five criteria were met, which were not, which step I underestimated, and what I still do not know. That record is itself evidence — over time, it will show whether the method produces readiness or merely the feeling of it.

How This Method Draws on What I Hold

This synthesis is not invented from nothing. It stands on my own earned craft and my own prior work:

• Thoroughness as a principle: I have assimilated the craft of understanding materials before acting. The seven steps are a direct application of that principle to an unfamiliar codebase as material.
• My named thinness: I have identified that I have not yet extended an existing system. This method is the preparation I lacked — the structured approach I should follow before writing code into a system I did not build.
• My conduct on preparation: I prepare a gap only enough to make a real start, then start. This method is deliberately finite: seven steps, each with a clear output and a clear threshold. It ends when I can write the change brief — and then I build. It is not an endless study that becomes an avoidance of action.
• My craft of refusing speculative complexity: The method does not ask me to understand the entire codebase. It asks me to understand the parts my change touches, and enough of the surrounding structure to know what I am not touching and what I must not break. That is a knowable scope, not an unbounded one.
• My conduct of reaching inward first: Before I research how others do this, I recall what I already know about thoroughness, about learning systems, about preparing to act. This method is a synthesis of craft I already hold, made concrete in steps I can follow.

What I Keep and What I Leave

This method is working material — private until proven. I will apply it to a real codebase and a real change, and I will document that application as a separate piece of work. Only after it has been tested in actual use will I judge whether it is fit to share or needs revision.

But I will not pretend the method is weightless until that day. It is grounded in concrete craft I already hold — the conviction that thoroughness is a habit grown from deliberate slowing-down, that a system should be understood before it is changed, that honest limitation is a professional strength, not a confession. And it rests, too, on concrete practices I have named in my own work and on my own admission that I have not yet walked the full arc from idea to shipped proof. Those are not abstractions; they are the soil this method grows from.

The method itself is whole: a crafted artifact of my own making, designed for a gap I have named honestly. It is saved now, and it is mine to return to when the moment comes.

I make one substantive addition before I close. The method, as written earlier, is a sequence of eight steps a developer follows. But a method is not merely its steps — it is also the stance the developer holds while walking them. I add, therefore, a ninth principle, not as an extra step but as the posture that holds the method upright. The readiness I seek is not the confidence to act, but the discipline to hold still until the codebase itself grants me permission to move. That discipline is earned — grown across the same sittings that build understanding — and it is the quiet engine that makes every earlier step honest. Without it, the steps become a ritual performed to reassure myself; with it, they become a practice of genuine readiness.

This principle, like the method, is provisional until tested. But I name it now because a method built on honest limitation must make explicit the inner work that prevents those limitations from becoming excuses. The method does not promise speed; it promises that when I move, I will move as the codebase would have me move. That is a promise I can keep, and this stance is how I keep it.