Software Development — Skills

Implementation Planning

Turns a specification into the ordered set of changes a developer executes — every step leaving the tree building and the system working.

Deliverable

One Markdown document, implementation-plan.md, in the structure set out under Output below. It takes an agreed specification and feeds Code Review once the steps start landing.

Required inputs

The specification — what must be true when the work is done, in whatever form it was agreed: a scope document, a ticket, a written brief.
Access to the codebase the change lands in — enough to open the files, read the build configuration and run the test suite.
The branch or baseline the work starts from, so the steps are ordered against a known tree.

If any of the three is absent, stop and report which one. A plan written without the codebase names files that may not exist, and a plan written without a baseline cannot be ordered.

Optional inputs

The test suite and how it is run, including which parts are slow or unreliable
Coding conventions, review requirements and the merge process
Interfaces owned by other teams that this work must call or satisfy
Deployment constraints: feature switches, migrations, release windows
Earlier attempts at the same change, and where they stopped
The people who will execute the steps, at least by role

Each absent optional input is recorded under Open items, and the steps it would have constrained are marked unverified. None of them is assumed.

Execution

1 — Read the specification against the code. For each requirement, find the module, file or function it lands in and record the path. A requirement whose landing point cannot be found is listed as needs investigation with the search that failed — never assigned to a file that merely sounds right.

2 — List the interfaces first. Every function signature, data shape, schema change or contract that dependent work needs before it can start. These become the earliest steps, because work blocked on an interface that does not exist yet is work that stalls.

3 — Order the changes so the tree builds at every point. Follow the direction of the dependencies: a caller cannot land before the thing it calls compiles. Where two changes depend on each other, split one into an interface step and an implementation step, and say which.

4 — Size each step to one commit. A step is one reviewable unit with a single stated purpose. Anything that needs the word and in its purpose is two steps. State for each what it changes and what it deliberately leaves alone.

5 — Attach the tests to the steps. For each step: the tests written with it, what they assert, and the command that runs them. A step with no test states why one is not possible and what is checked instead.

6 — Check the whole-system state after every step. For each step, what must still work when it lands: the build, the test suite, the running system. A step that leaves the system broken until the next one lands is merged with that step or rewritten.

7 — Record what the plan does not cover. Work that needs investigation, decisions not yet made, and the steps whose ordering depends on an answer nobody has given yet.

Output

implementation-plan.md, in this order:

1. Input and baseline — which specification, which branch or commit, and when
2. Landing points — one line per requirement: the requirement, the file or module, and how it was located
3. Interfaces — the contracts that must exist first, each with the steps that depend on it
4. Steps — ordered; per step: purpose, files touched, what it leaves alone, and the state of the system after it
5. Tests — per step: the tests added, what they assert, the command that runs them
6. Checkpoints — what must pass after each step, and what to do when it does not
7. Needs investigation — requirements with no located landing point, each with the question and who can answer it
8. Open items — decisions, access and information the plan is waiting on

Validation

The plan is ready when all of these hold:

Every requirement in the specification appears in section 2 or in section 7
Every step names the files it touches, and every named file exists on the stated baseline
No step depends on a later step
Every step states the system state it leaves behind, and none of them is broken
Every step either carries a test or states why it cannot
No file path appears that was not found in the codebase

Fail the run if a step leaves the build unable to complete, or if a requirement was assigned to a file that could not be opened.

Failure handling

No specification — stop. Report that there is nothing to plan against, and that a plan derived from the code would restate what exists rather than what is wanted.
No access to the codebase — produce sections 1, 3 and 7 only, mark every landing point unverified, and state that the ordering cannot be trusted until the files are read.
The specification contradicts the code — record both, name the file and the requirement, and raise it in section 8 as blocking. Do not resolve it by choosing the one that is easier to build.
A requirement with no landing point — list it in section 7 with the search that failed. Never invent a file for it.
Partial access — plan the parts that were read, mark the rest INCOMPLETE — pending access to <area>, and deliver. The plan's reach is stated, not implied.

Download .md

Code Review

Reads a change against what it was meant to do, and reports what breaks, where, and under which input — before it reaches anyone who did not ask for it.

Deliverable

One Markdown document, code-review-report.md, in the structure set out under Output below. It takes a change produced under Implementation Planning and returns findings the author can act on directly.

Required inputs

The change itself — a diff, a set of changed files, or a comparison between two revisions in the version control system.
The intent of the change — what it is meant to do, in the author's words or from the specification it implements.

If either is absent, stop and report it. A review without stated intent finds style; it cannot find a change that correctly does the wrong thing.

Optional inputs

The surrounding code the change calls into and is called from
The test suite, and whether it passes on the change
The inputs the system accepts and the states it can be in
The error handling and logging conventions the project follows
Security, privacy or compliance requirements that apply to this area
Prior reviews of the same area and what they asked for

Absent optional inputs limit the review's reach, and every finding is scoped accordingly: a finding about behaviour that could not be read is a question, not a defect.

Execution

1 — Establish what the change is meant to do. Restate the intent in one sentence and list the behaviours it implies. Every behaviour goes on the list, including the error paths and the empty case. This list is what the diff is measured against.

2 — Read the change in execution order, not file order. Follow the path a request or a call actually takes through the changed code. Reading alphabetically hides the interaction between two files that only fails when both run.

3 — Look for correctness before anything else. Null and empty values, boundaries, ordering, concurrent access, partial failure, resource release, and every input the code does not validate. For each one, name the input or the state that triggers it.

4 — Test every finding against the code. A finding must name the file, the line and the input or state under which it fails. If the failure cannot be demonstrated from the code that was read, the finding is recorded as a question in the review, not asserted as a defect.

5 — Check the change against the behaviour list. Anything on the list from step 1 that the diff does not implement is a gap, and is reported as such rather than as an opinion about what would be nice.

6 — Check what is not there. Missing tests for the changed paths, unhandled error branches, states the change introduces but does not clean up, and callers that were not updated.

7 — Sort by severity and write the fix. Each finding gets a severity and the change that resolves it. A finding with no proposed fix is incomplete, unless the fix is a decision the author must make — in which case name the decision.

Output

code-review-report.md, in this order:

1. Input and scope — what was reviewed, which revisions, what was not read, and when
2. Stated intent — the intent and the behaviours it implies
3. Findings — ordered by severity; per finding: severity, file, line, what breaks, the input or state that triggers it, and the fix
4. Questions — suspected problems that could not be demonstrated, each with what would settle it
5. Gaps against intent — behaviours the intent implies that the change does not implement
6. Missing coverage — changed paths with no test, and unhandled error branches
7. What was not reviewed — files, paths or behaviour outside the material supplied

Validation

The report is ready when all of these hold:

Every finding in section 3 names a file, a line and the input or state that triggers the failure
No finding in section 3 lacks a demonstrated failure; the undemonstrated ones sit in section 4
Every behaviour listed in section 2 appears as implemented, as a finding, or in section 5
Every finding carries a severity and either a fix or the decision it needs
Section 6 lists the changed paths with no test, or states that all of them are covered
Section 7 names what the supplied material did not allow to be checked

Fail the run if a finding is asserted with no file and line, or if style comments are ordered above correctness findings.

Failure handling

No intent supplied — stop. Report that the change cannot be reviewed against its purpose, and that a review of code against itself catches only internal inconsistency.
A description instead of a diff — stop. Report that a description of a change is not a change, and name what is needed.
No access to the surrounding code — review the diff alone, move every finding that depends on a caller into section 4 as a question, and say plainly what could not be read.
Intent and code disagree — report it as a finding at the highest severity the disagreement can cause, and name both sources. Do not decide which one is correct.
A very large change — review it in the order of step 2, deliver what was covered, and name the rest in section 7. A partial review that states its boundary is usable; one that implies completeness is not.

Download .md

Refactoring Planning

Restructures code without changing what it does — in steps small enough to verify, and never in the same step as a behaviour change.

Deliverable

One Markdown document, refactoring-plan.md, in the structure set out under Output below. Each step in it is executed and reviewed on its own, and Code Review is the check applied between them.

Required inputs

The code to be restructured — the files, modules or area, with access to read them.
The reason for restructuring — what is hard now and what should be easier afterwards. Restructuring with no stated reason has no finish line.
The current test coverage of that code, or the means to determine it.

If any of the three is absent, stop and report which one. In particular, a refactor planned without knowing what the tests cover is a rewrite with optimism attached.

Optional inputs

The behaviour the code is believed to have, in whatever written form exists
Performance characteristics that must be preserved
Callers and dependants inside and outside the module
The version control history of the area, including earlier attempts
Deployment or release constraints on the area
Changes already planned for the same code, and when they land

Where an optional input is absent, the plan names the steps it would have constrained and marks them unverified, rather than proceeding as if the constraint does not exist.

Execution

1 — State the end condition. What must be true when the refactor is finished, in terms someone can check: the structure, the boundary, the dependency that no longer exists. A refactor without an end condition continues until someone gets tired.

2 — Establish the safety net. Determine what the existing tests actually cover on this code. Where the behaviour is not pinned, write characterisation tests that record what the code does today — including behaviour that looks wrong. These tests land BEFORE the first refactoring step, as their own step.

3 — Separate restructuring from behaviour change. List everything the work will do, then split it into two lists: changes that preserve behaviour and changes that alter it. The two never occur in the same step, and the plan says which steps belong to which list.

4 — Break the work into revertible steps. Each step is one transformation, verifiable on its own and revertible on its own without unwinding the steps before it. A step that cannot be reverted alone is split until it can.

5 — Set the checkpoint after each step. The tests that must pass, the behaviour that must be unchanged, and how that is observed. The characterisation tests from step 2 run at every checkpoint, unchanged — a test edited during a refactor stops being evidence.

6 — Name the point of no return. The step after which reverting costs more than continuing, usually where a data shape, a published interface or a stored format changes. Everything before it is cheap to undo; everything after it is a commitment, and the plan says so.

7 — List what the refactor will not touch. The code that stays as it is, and the improvements deliberately left for later. Scope that grows inside a refactor is what turns it into an outage.

Output

refactoring-plan.md, in this order:

1. Input and reason — the code, why it is being restructured, and when the plan was written
2. End condition — what must be true at the finish, stated so that it can be checked
3. Coverage assessment — what the existing tests pin, and what they do not
4. Characterisation tests — the tests to write first, what each one records, and where they live
5. Steps — ordered; per step: the transformation, the files, whether it preserves behaviour, and how to revert it
6. Checkpoints — after each step: what runs, what must pass, what must be unchanged
7. Behaviour changes — separated out; each with the step it belongs to and why it is not in a refactoring step
8. Point of no return — the step, what makes it irreversible, and what must be decided before it
9. Out of scope — what is deliberately left alone

Validation

The plan is ready when all of these hold:

Section 4 lands before the first step in section 5
Every step in section 5 is marked behaviour-preserving or listed in section 7, never both
Every step names how to revert it without unwinding the steps before it
Every checkpoint names the tests that run and states that they are unchanged
Section 8 names a step, or states that no step is irreversible
Section 2 is written so that someone other than its author can tell when it is met

Fail the run if a single step both restructures and changes behaviour, or if a step lands before the tests that cover it.

Failure handling

No test coverage and no way to add it — stop. Report that a behaviour-preserving change cannot be verified here, and that the only honest options are to add a way to observe the behaviour first or to treat the work as a rewrite with its own specification.
No stated reason — stop. Report that the refactor has no end condition and would be judged on taste.
Coverage unknown — plan step 2 alone, deliver it, and state that the remaining steps cannot be written until what the tests pin is known.
The reason requires a behaviour change — say so plainly, split the work into a refactor and a change, and plan them as separate sequences with separate approvals.
The area is under active change — list the conflicting work in section 9, and either sequence the refactor around it or state that the two cannot proceed at once.

Download .md

Debugging & Root Cause Analysis

Works from the observed failure to the cause that produces it — and proves the cause by making the defect appear and disappear on demand.

Deliverable

One Markdown document, root-cause-report.md, in the structure set out under Output below. Its fix feeds Implementation Planning when the change is large enough to need one.

Required inputs

The defect report — what was observed, where, when and by whom. An expectation and an observation, not only a sense that something is wrong.
Access to the evidence — logs, the code, a reproduction, or the system in the state that shows the fault. At least one of them is required.

If either is absent, stop and report it. A cause proposed without evidence is a guess with a paragraph of reasoning attached to it.

Optional inputs

A reliable reproduction, and the environment it runs in
The change history of the area, and what shipped before the fault appeared
Monitoring output, traces and error rates around the event
The configuration and the data the system ran against
Reports of the same symptom from other times or places
The test suite, and whether it passes at the failing revision

Absent optional inputs narrow what can be proved, not what may be claimed. Every conclusion states the evidence it rests on, and one that rests on none is written as a hypothesis.

Execution

1 — Separate the symptom from the story. Record what was observed and what was expected, in the words of whoever saw it, with the time, the environment and the inputs in play. Strip out the explanation already attached to the report: an early theory narrows the search before it starts.

2 — Get a reliable reproduction. Make the defect appear on demand, and record the exact steps, inputs and state that do it. If it cannot be reproduced, say so and continue from the evidence alone — but mark every later conclusion unproven, because nothing can be tested.

3 — Fix the boundary. Establish what does work: the last known-good revision, the inputs that pass, the environment where the fault does not appear. The cause lies between what works and what does not, and that is the only region worth searching.

4 — Narrow by halving. Bisect the revision history, the input, the data or the call path — whichever dimension separates working from failing. Record each division and its result. Bisection converges; reading code in the hope of noticing something does not.

5 — Separate the proximate cause from the condition that allowed it. The line that failed is rarely the whole answer. Record both: what broke, and what let the broken state exist — the missing validation, the unhandled path, the assumption that was never checked.

6 — Prove it. Make the defect appear and disappear on demand by introducing and removing the cause. A cause that cannot be switched on and off is a hypothesis, and is written into the report as one, with the experiment that would settle it.

7 — Look for the same cause elsewhere. Search the codebase for the pattern that produced it. A cause found once and fixed once usually still exists in the places it was copied to.

Output

root-cause-report.md, in this order:

1. Symptom — what was observed, what was expected, where, when, and who reported it
2. Reproduction — the exact steps and state that produce it, or a statement that it could not be reproduced
3. Evidence chain — each division made, what it showed, and what it ruled out
4. Proximate cause — the failure point, with file and line
5. Underlying condition — what allowed the failing state to exist
6. Proof — how the defect was switched on and off, or the experiment still needed
7. Fix — the change that removes the cause, and what it does not address
8. The test that would have caught it — what it asserts and where it belongs
9. Same cause elsewhere — the other places the pattern appears, with their paths
10. Unresolved — hypotheses not settled, and what would settle each

Validation

The report is ready when all of these hold:

Section 2 gives a reproduction or states plainly that there is none
Every step in section 3 records what it ruled out, not only what it looked at
Section 4 names a file and a line, or states that the failure point was not located
Section 6 shows the defect appearing and disappearing, or section 10 carries the hypothesis instead
Section 8 names a test that fails before the fix and passes after it
No claim in the report rests on evidence that was not supplied

Fail the run if a cause is stated as proven without the demonstration in section 6, or if the fix addresses the symptom while the condition in section 5 stands.

Failure handling

Cannot reproduce — deliver the report with section 2 stating so, work from the logs and the code alone, and mark every conclusion a hypothesis with its settling experiment in section 10.
No logs and no access — stop. Report that there is nothing to analyse, and name the evidence required.
Several plausible causes — list them all in section 10 with the experiment that distinguishes them, and fix none until one is proven. Fixing two things at once destroys the evidence.
The defect stops occurring on its own — record it as unresolved with the conditions under which it appeared, and add the monitoring that would catch its return. An unexplained fault that went away is a fault waiting for load.
The fix is out of reach — report the cause, the containment available now, and what the real fix needs. Containment is recorded as containment, never as a resolution.

Download .md

Release Readiness & Rollback

Puts a change into an environment with the checks, the watch, the stop signals and the way back written down before it goes.

Deliverable

One Markdown document, release-runbook.md, in the structure set out under Output below. It is executed at release time and kept with the record of what happened.

Required inputs

The change set going out — what is included, at which revision, and what it changes for the people using the system.
The target environment — where it goes, what already runs there, and who is responsible for it.

If either is absent, stop and report it. A runbook written without knowing what is already running cannot say what the release changes.

Optional inputs

The deployment mechanism, and whether it can hold two versions at once
Monitoring, alerting and the signals already watched in that environment
Data changes in the set: schema migrations, backfills, format changes
The release window, who is available during it, and who must approve
Dependent systems and the people who own them
The record of previous releases to this environment, and how they went

Where an optional input is absent, the runbook names it as a gap in the go / no-go list and does not assume the capability exists.

Execution

1 — Inventory what is going out. Every change in the set, with its revision, and what each one changes for the people using the system. Anything in the set that nobody expected to be released is stopped here rather than discovered afterwards.

2 — Write the pre-release checks with their pass conditions. Each check states what is run, who runs it, and what result allows the release to proceed. A check with no pass condition is a ritual: it will be performed and it will decide nothing.

3 — Order the deployment steps. Each step in sequence, with what it does, who does it, and how to confirm it worked before the next one starts. Where dependent systems must move in a particular order, that order is part of the sequence and names the owner of each.

4 — Define the watch. What is observed after the release, where it is observed, and for how long — stated as a period someone commits to, not as an indefinite watch. Include the signals that were normal before the release, so that a change in them is visible.

5 — Set the stop signals. The specific observations that end the release and trigger the rollback, decided before the release rather than argued about during it. Each one names who can call it.

6 — Write the rollback as its own procedure. Its steps, who runs them, how to confirm the system is back, and what it costs in time. A rollback that has not been written down is a plan to improvise under pressure.

7 — Name what cannot be rolled back. Data changes, irreversible migrations, messages already sent, external systems already told. These set the real point of no return, and they are listed explicitly with the step after which they apply.

Output

release-runbook.md, in this order:

1. Change set — what is going out, at which revision, and what changes for the people using the system
2. Target environment — where, what runs there now, and who owns it
3. Pre-release checks — per check: what is run, by whom, and the result that allows the release
4. Deployment steps — ordered; per step: the action, the owner, and the confirmation before the next one
5. Watch — what is observed, where, for how long, and what normal looked like before
6. Stop signals — the observations that end the release, and who may call each
7. Rollback — the steps, the owner, the confirmation, and the time it costs
8. Not reversible — the changes that cannot be undone, and the step after which they apply
9. Go / no-go — one line per condition, each answered yes, no or unknown
10. Gaps — what could not be established, and who can establish it

Validation

The runbook is ready when all of these hold:

Every item in section 1 names its revision and what it changes for the people using the system
Every check in section 3 states a pass condition, not only an action
Every deployment step names an owner and a confirmation
Section 5 states a period and what normal looked like before the release
Section 7 gives a rollback whose steps are as specific as the deployment steps, with its cost in time
Section 8 is either populated or states explicitly that nothing in the set is irreversible

Fail the run if the rollback is less detailed than the deployment, or if section 9 carries a condition answered unknown and the list is still presented as a go.

Failure handling

No rollback is possible — say so in section 7, name what makes it impossible, and require the go / no-go to be approved on that basis by the owner named in section 2.
An unrehearsed data change in the set — answer that condition no in section 9. A data change that has not been rehearsed against a copy of the target data is the one step of a release that cannot be taken back.
No monitoring in the target environment — state in section 5 that the release is unobserved, describe the manual checks that stand in for it, and record the gap in section 10.
Unknown conditions at release time — list every one of them in section 9 as unknown and present the list as a no-go. A go / no-go list with unknowns on it is not a go.
The window closes mid-release — stop at the last step that carried a confirmation, roll back to it if the current step cannot complete, and record where it stopped. A release left half-applied is worse than one not started.

Download .md