Code is cheap now.
Judgment is the product.

00How to use this handbook

This is a book, not an article. Nobody is expected to read it in one sitting.

This handbook describes how the best WooCommerce developers work, and it is the standard we hold ourselves to at the agency. It is long on purpose. Every chapter is meant to be read, tried on real work for a few days, and then returned to.

What to expect

• Part I is about how top-tier developers think and work: solving problems, writing code, reading unfamiliar codebases, releasing safely, recovering from disasters, estimating, and communicating.
• Part II is about how we train for it in a world where AI writes most of the code, including the program, the review rubric, and the drills.
• Each chapter ends with a drill. The drills are not optional reading. They are the part that changes how you work.

How the reader works

• Your place is saved in this browser. When you come back, you will be offered the chapter you were reading.
• Use Mark as read at the end of a chapter to track progress in the sidebar. It only tracks; it does not judge.
• Use the arrow keys or the buttons at the bottom to move between chapters. Press / to search chapter titles.
• Switch to Scroll view in the top bar if you prefer to read everything as one long page.
• The Aa button opens reading settings: text size (also Ctrl++ / −), five themes including Paper and Dark, line spacing, and reading width. Everything is remembered on this device.

A suggested pace

One chapter per working day. Read it in the morning, look for it in your work that day, and note one thing you would do differently. That is 22 working days for the whole book, and it will do more for you than reading it all in one weekend.

01The seven mindset shifts

Every trait in this handbook grows out of one of these shifts. Many developers never make them, and it shows in their work for years.

A junior and a top-tier developer can know the same hooks and the same APIs. What separates them is a set of beliefs about what the job is. These shifts are the real curriculum. The rest of the handbook is what the shifts look like in daily practice.

How each shift shows up in a WooCommerce agency

• Why the ticket exists. "Add a bulk export of orders" often means "finance spends 3 hours every Monday reconciling." The real fix might be a scheduled report, not an export button.
• Requirements as hypotheses. "Require phone number at checkout" is a hypothesis that phone numbers reduce failed deliveries. Ask for the data. A required field can cost 2% of conversions.
• Proof. After fixing a double-order bug, they show the log of the race being blocked, not just a week without complaints.
• Outcome ownership. The ticket is closed, the client's stock sync is still wrong. They reopen it themselves.
• Reducing uncertainty. First check: does it happen with all plugins except WooCommerce disabled? That one test rules out 60 suspects at once.
• Unblocking. Staging access is pending. They set up a local copy from the last backup and keep moving.
• Force multiplier. They spend an hour writing a WP-CLI command for the migration instead of running it by hand, so the next three migrations take minutes and anyone can run them.

02How they solve a problem

They fix the cause, and they can prove it is the cause before they change anything.

An average developer sees a symptom and starts editing. A top-tier developer treats a bug as a claim that needs checking. What is really happening, in what order, and why? They keep what they know separate from what they assume, and they will not ship a fix they cannot explain.

The root-cause ladder

1. Observe precisely. Get the exact error, the exact request (URL, method, user role, session, cache state, gateway), and the exact time. Read the log line, not someone's summary of it.
2. Reproduce deterministically. If you cannot make it happen on demand, you do not understand it yet. Use staging with a copy of production data, the same plugins, and the same cache setup.
3. Locate the boundary. Narrow it down. Plugin on or off, hook priority, theme or mu-plugin, cache on or off. Find the last good state and the first bad one.
4. Explain the mechanism. Write one paragraph, like: "X fires before Y because Z, so the session is not ready when the gateway reads it." If you cannot write that paragraph, keep digging.
5. Fix at the right layer. Fix it where the rule was broken, not where the problem was noticed.
6. Prevent recurrence. Add a log line, an alert, a test, or a guard. Something that tells you if this comes back.

03How they code

Boring, defensive, and written for the hostile environment the code will actually live in.

Top-tier WooCommerce code assumes the worst. It will run next to 60 other plugins, on a PHP worker that is already busy, with a cache that may be stale, on a request that may be a bot. It does not try to be clever. It tries to be correct under load and hard to misuse.

Their mental checklist before writing a line

• Which request contexts run this code? Front-end, admin, AJAX, REST, cron, WP-CLI, Store API/Blocks checkout?
• How many times per request, and per second at peak, does this hook fire?
• What happens if this runs with a cached page, a stale object cache, or no session at all?
• What happens if it runs twice, concurrently, for the same order?
• How does it fail? Fail open, fail closed, or fail loud?
• Can it be turned off without a deploy?

04How they maintain a codebase

They leave every file a little better than they found it, and they leave a trail.

Maintenance is where agencies win or lose margin. A codebase that only one person understands is a risk with a salary attached. Top-tier developers write for the next person, who is often themselves six months later with no memory of why.

• One place for each concern. Checkout rules in one module, shipping rules in another, integrations each in their own. No "misc" file that grows forever.
• Feature flags for anything risky. A constant, an option, or a filter that lets ops disable a behavior in seconds without a deploy.
• Decision records. A short DECISIONS.md: "We bypass the gateway's built-in retry because it double-charged in March 2024. Do not re-enable." This is the most valuable file in the repo.
• Dependency hygiene. Knows every plugin's purpose, owner, and last review date. Removes plugins that duplicate owned code. Pins versions where a silent update could break checkout.
• Deletes code. Dead hooks, commented-out blocks, "temporary" fixes from 2022. Every line that exists is a line someone has to understand.
• Upgrade discipline. Reads WooCommerce changelogs before every major, tests the checkout and order flows on staging, knows which templates are overridden and diffs them against the new versions.

05Entering a 100k-line unfamiliar codebase

They do not read it. They map it, starting at the entry points and following the money.

Nobody reads 100k lines. A top-tier developer builds a working picture of the system in a few hours by asking a few structural questions, then reads only the paths that matter for the task.

1. Find the entry points. mu-plugins, active plugins, theme functions.php, registered REST routes, registered AJAX actions, scheduled actions, WP-CLI commands, webhooks. This is the surface area.
2. Follow the money. Trace one order end to end: product page → add to cart → checkout → payment → order created → status transitions → fulfillment → email. Note every custom hook that touches this path. That's 80% of the risk in 5% of the code.
3. Grep the hooks. add_action/add_filter across custom code, grouped by hook name. The hooks with the most listeners are the hotspots; the priorities tell you the load order.
4. Map the data model. What is stored where: order meta keys, custom tables, options, transients, external system IDs. Which one is the source of truth for stock, price, and customer status.
5. Find the integrations. Every outbound HTTP call and every inbound webhook. Each is a place the system can hang, duplicate, or silently diverge.
6. Read the git log, not the code. Last 200 commits. Hotfix clusters show where the fragile parts are. Names show who to ask.
7. Run it with tracing on. Query Monitor, Xdebug, or a plain error_log() on the path in question. Watching execution beats reading execution.

# Where is checkout being customized?
grep -rn "woocommerce_checkout\|woocommerce_after_checkout\|woocommerce_payment_complete" wp-content/ --include=*.php | grep -v "/plugins/woocommerce/"

# Who touches order status?
grep -rn "update_status\|woocommerce_order_status_" wp-content/mu-plugins wp-content/themes

# Every outbound HTTP call in custom code
grep -rn "wp_remote_\|curl_init\|new Client(" wp-content/mu-plugins wp-content/plugins/client-*

# Every scheduled job
wp action-scheduler list --status=pending --per-page=50

06Blast radius and edge cases, spotted fast

They ask "what else uses this?" by reflex, and they carry a standard list of edge cases in their head.

Spotting edge cases quickly is not intuition. It is a memorized checklist applied without thinking. After enough WooCommerce projects, the checklist becomes reflex. Teach it directly and juniors get the reflex in months instead of years.

Blast-radius questions for any change

• Who else hooks this filter, and at what priority? Am I now running before or after them?
• Does this code path also run in REST / Store API / admin order edit / CLI / cron / subscription renewal?
• Does this change what gets cached? Page cache, object cache, WooCommerce transients, CDN?
• Does any external system read this field (ERP, Zoho, ShipStation, Klaviyo, fraud tool)?
• What happens to orders already in flight when this deploys?
• What does this do to a PHP worker under 10× traffic?

The WooCommerce edge-case list

07How they think about failure modes

They do not ask "will it work?" They ask "how will it fail, who will notice, and how fast can we undo it?"

Every production change is designed with its failure already in mind. Before deploying, top-tier developers decide what the system should do when the change goes wrong. They build the undo before they build the feature.

Pre-mortem questions

• If this fails at 2 a.m. on Black Friday, what does the customer see?
• What is the worst thing this code can do to money, stock, or customer data? Can it do that twice?
• What external dependency does this add, and what's its timeout?
• Which metric would show this is broken, and are we watching it?
• What's the blast radius if the underlying assumption (e.g. "orders always have a billing email") is false for 0.1% of orders?

08Why they are much faster than average

They do not type faster. They do less, redo less, and never get stuck.

Over a month, top-tier developers are 3 to 10 times faster than average ones. Almost none of that comes from typing. It comes from work that never has to happen.

09Choosing between options under time limits

They pick the option that is easiest to undo, and they say clearly what they are giving up.

Under deadline pressure, average developers pick the option they already know how to build. Top-tier developers pick by a fixed ranking, and they name the trade-off so the business makes the choice, not the engineer.

1. Reversibility first. If two options are close, take the one you can back out of in minutes. A feature flag beats a schema change. A filter beats a template override.
2. Safety over elegance. The boring, well-trodden approach (a WooCommerce hook that's been stable for 8 years) beats the clever one under deadline.
3. Smallest change that fully solves the stated problem. Not the general solution. Not the platform. The problem.
4. Explicit debt. If you are taking a shortcut, write the ticket for the proper version now, link it in the code comment, and tell the PM. Debt nobody has written down is the debt that hurts you later.
5. Timebox the decision. 15 minutes to decide is almost always enough. Analysis past that point is usually anxiety, not diligence.

10Handling "ASAP" and incidents

They slow down for the first five minutes so the next hour goes quickly.

Urgency is where average developers cause the second incident. The instinct to act right away is the thing that needs to be trained out. Top-tier developers follow a fixed protocol so they do not have to think about process while they think about the problem.

1. Confirm impact (2 min). Is checkout down, or is one customer confused? Revenue-affecting or cosmetic? Check the last hour's order count against a normal hour. Impact determines everything after this.
2. Stabilize before diagnosing. If a recent deploy correlates, revert it. If a plugin updated, roll it back. If it's a traffic spike, enable stricter caching / rate limits. Get money flowing first; understand later.
3. Communicate on a cadence. One message now: what is affected, what you are doing, next update in 20 minutes. Then keep that promise even if the update is "still investigating."
4. Diagnose with the ladder from section 2, but with a time limit. If you do not have a cause in 30 minutes, escalate or widen the mitigation.
5. Fix minimally, deploy carefully. The incident fix is the smallest safe change. No refactoring during a fire. Verified on staging if at all possible; if not, deployed with a revert command already typed.
6. Write it down. Timeline, cause, fix, detection gap, follow-ups. Blameless. Within 24 hours. This is how the team gets faster next time.

11How they test before going live

They test the way real customers behave, on a system that looks like production.

Testing on a WooCommerce site is not just a test suite (though they write those too). It is the discipline of checking the money paths under realistic conditions before a change reaches a customer.

The layers

The staging checklist for anything touching checkout

• Guest checkout, new account checkout, returning customer checkout
• Each active payment gateway, including a declined card and a 3DS challenge
• Coupon applied, coupon removed, coupon that makes the total $0
• Cart edited on the checkout page; browser back after payment
• Order emails render correctly (customer and admin)
• Order appears correctly in every integration (fulfillment, ERP, CRM)
• Page cache and object cache enabled. Most bugs hide behind a disabled cache
• Query Monitor: no new slow queries, no N+1, no new PHP notices

12Development and release workflow, by situation

There is no single right workflow. There is the right workflow for this project, this client, and this level of urgency.

Average developers use the same process for everything, which means it is too heavy for small fixes and too light for risky ones. Top-tier developers scale the process to the risk. The question they ask is: what is the cost if this goes wrong, and how fast could we notice and undo it?

The factors that set the workflow

Four workflow tiers

Adjusting for the client

• Small client, low volume. Tier 1 and 2 cover most work. Do not make them pay for enterprise process on a $50/day store. But their checkout is still Tier 3, because it is 100% of their revenue.
• High-traffic client. Nothing is Tier 1 if it touches a template that renders on every page. A CSS change that breaks the cache key is a Tier 3 event. Deploy windows and monitoring are not optional.
• Client with their own team. Heavier documentation, lighter ceremony. They will maintain it after you, so the PR description and the DECISIONS entry matter more than the meeting.
• Retainer vs. project. On a retainer, invest in tooling that makes future deploys cheaper (staging refresh scripts, deploy pipelines). On a fixed project, keep it simple and document the handover.

Branching and environments

• Trunk-based with short-lived feature branches for most agency work. Long-lived release branches only for clients with formal release calendars.
• Three environments minimum for Tier 3 clients: local, staging (refreshed from production regularly, with customer data masked), production.
• Staging must have the same plugin set, the same cache stack, and the gateway in sandbox mode. A staging site that does not look like production is a false sense of safety.
• Deploys are scripted and repeatable. If a deploy requires remembering steps, it will be done wrong under pressure.
• Every deploy has a tag. Every tag can be redeployed in under five minutes.

13Backups and disaster recovery

A backup you have never restored is a hope, not a backup. And code rollback, data rollback, and external-system rollback are three different problems.

Most agencies believe they have backups because the host says so. Top-tier developers know what is backed up, how often, how long a restore takes, and what would be lost. They have tested it. And they understand that "roll back" means three different things depending on what went wrong.

Three kinds of rollback

What a real backup strategy covers

Disaster recovery on a WooCommerce store

• Define the scenarios. Host down, database corrupted, site hacked, bad deploy, bad plugin update, domain or DNS compromised, key staff unavailable. Each has a different runbook.
• Know the two numbers. How much data can we afford to lose (hours of orders)? How long can we afford to be down? The client decides these, and they set the backup frequency and the hosting budget.
• Plan for partial recovery. Restoring to a clean copy from four hours ago and replaying the orders from the gateway's transaction log is often better than a full restore. Payment gateways and email logs are your secondary record of what happened.
• Keep a maintenance mode that works. A static page that tells customers the truth, served from the CDN, that can be turned on in one minute. Better than a broken checkout taking money it cannot record.
• Practice. Once a quarter, restore production to a fresh staging environment from backups alone. Time it. Fix what broke. This is also how you refresh staging.

14Realistic estimation

Timeboxing controls how long you spend. Estimation predicts how long it will take. Top-tier developers do both, and they know they are different skills.

Timeboxing is a discipline: "I will spend two hours on this, then reassess." Estimation is a forecast: "This will take about two days." The first protects you from sinking time. The second is what the client is asking for when they say "how long?" Average developers estimate the typing. Top-tier developers estimate the whole job.

Why developer estimates are wrong

• They estimate the happy path and forget the edge cases, the review round, the staging test, and the deploy.
• They estimate for themselves on a good day, with full focus and no interruptions.
• They do not count the unknowns: an undocumented plugin, a client who takes two days to answer, a gateway sandbox that behaves differently from live.
• They give one number when the honest answer is a range.

How top-tier developers estimate

1. Break it down until each piece is under half a day. Anything larger is hiding an unknown. If you cannot break it down, that is the estimate's biggest risk, and you say so.
2. Count the whole lifecycle. Understanding, building, edge cases, review, staging test, deploy, monitoring, client communication. On a Tier 3 change, typing is often less than a third of the total.
3. Name the unknowns and price them. "Two days if the gateway supports partial capture, four if we have to work around it. I will know by tomorrow noon." An estimate with a named risk is worth more than a confident number.
4. Give a range, and a confidence. "Three to five days, likely four." Ranges tell the client how sure you are. A single number hides that.
5. Check against history. How long did the last three similar tasks actually take? Most developers are consistently off by the same factor. Learn yours.
6. Re-estimate at the first checkpoint. After the first few hours you know far more. Update the estimate then, not on the due date.

When timeboxing and estimation meet

• Use a timebox to produce the estimate: "Give me two hours to investigate, then I will give you a real number."
• Use a timebox inside the work to catch overruns early: if a half-day piece hits a full day, stop and report, do not push through silently.
• Never let a timebox become a deadline promise. "I will spend a day on it" and "it will be done in a day" are different sentences, and clients hear the second one.

15The quality model

"Working" is one dimension out of eight. Top-tier developers check all eight before calling something done.

Ask an average developer if their feature is finished and they will tell you it works. Ask a top-tier developer and they will tell you how it scores on each of these. This is the agency's definition of quality, and it is the checklist for every review.

Using the model

• In planning: which dimensions does this change touch? A checkout change touches all eight. An admin report touches maybe four. That decides the workflow tier.
• In review: the reviewer walks the eight dimensions, not just "does the code look right." Most missed bugs live in a dimension the reviewer did not think about.
• In done criteria: "done" means each relevant dimension has evidence, not a feeling. A screenshot of Query Monitor, a keyboard walk-through, a test order with the right tax.
• In trade-offs: when time is short, say which dimension you are trading. "We are shipping without the accessibility pass; ticket filed for Tuesday." Never trade security or business correctness.

16How they know a problem actually matters to the business

They turn every ticket into revenue, cost, or risk before deciding how much attention it deserves.

Average developers treat every ticket as the same kind of engineering problem. Top-tier developers know that a slightly ugly admin screen and a 2% drop in checkout conversions are not the same kind of problem, and they spend their attention accordingly, even when the client is loudest about the admin screen.

The three questions

• Does it touch money? Cart, checkout, payment, pricing, stock, refunds. If yes, it's P1 until proven otherwise.
• How many customers, how often? "One customer once" and "every mobile Safari user" are different tickets with the same description.
• What's the cost of being wrong? A wrong shipping label costs $8. A wrong tax calculation costs an audit. A leaked customer list costs the client's business.

They also know the client's numbers: average order value, daily order count, conversion rate, peak hours, top products. With those numbers, "checkout is 400ms slower" becomes "roughly X fewer orders per day," and priorities set themselves.

17How they communicate

Short, structured, honest about what they do not know, and always with a recommendation.

Templates the team should use

They also write for non-engineers. The client hears "orders will no longer be held when the fraud service is slow," not "I deferred the webhook via a queue."

18Teamwork and how they add value

They multiply the team, not just their own output.

• Their reviews teach. Comments explain the principle ("this runs on every page load; move it to a transient with a 10-minute TTL because…"), not just the fix. Juniors level up from reading them.
• They make themselves unnecessary. Documentation, runbooks, feature flags, and clear code mean anyone on the team can operate their work. Bus factor of one is a failure, not a flex.
• They disagree early and commit fully. Push back in planning with reasons; once decided, execute without relitigating.
• They own outcomes, not tickets. If the ticket is closed and the client still has the problem, the work is not done.
• They notice the unasked question. "You asked for a CSV export. Did you know the ERP already has an API that would make this unnecessary?" Sometimes the highest-value work is the work you talk the client out of.
• They reduce the team's risk. Standards, checklists, automation, and the occasional "please don't merge that on a Friday."

How they work on other people's code

• They assume the previous developer had a reason, and they look for it (git blame, comments, tickets) before removing anything.
• They match the existing style even when they would have done it differently. Consistency beats preference.
• They do not rewrite what they can extend. A rewrite is a business decision, not a personal preference.
• They add tests around legacy code before changing it. The tests describe current behavior, so the change shows up as a clear difference in behavior.
• They leave the file better: a clarifying comment, a removed dead branch, a renamed variable. Small, safe, every time.

19What AI actually changed

It made producing code almost free. It did nothing to the cost of being wrong.

A junior developer's value used to be "can produce working code." That value is now close to zero. An AI produces working-looking code faster, and the client can prompt it too. What is still valuable, and has become more valuable, is everything in Part I: knowing what to build, knowing whether what was built is correct, knowing what it will do to the rest of the system, and being accountable when it breaks.

The new failure mode to train against

A developer who accepts generated code they cannot explain has not become faster. They have become a bigger risk. The rule for the agency: if you cannot explain every line in a PR to a senior without looking, you cannot submit it. AI is allowed for everything; understanding is required for everything.

How top-tier devs use AI

• They write the spec, constraints, and edge cases first, the same discipline as before, and hand that to the AI. Vague prompt, vague code.
• They use it for the parts they can verify in seconds and do the parts they cannot verify by hand.
• They ask it to attack its own output: "list the ways this fails under concurrent requests," "what assumptions does this make about the order object?"
• They use it to read: summarize a plugin's architecture, find every hook that touches X, explain a legacy function.
• They never let it make the architectural decision. They make it, then use AI to execute.
• They keep project context in the repo (a CLAUDE.md / AGENTS.md with stack, conventions, and forbidden patterns) so generated code starts from the team's standards, not the internet's average.

20The training program

A 14-week structure you can repeat. Every week has the same theme: judgment, verification, ownership.

Principles for the program

• Train on real client code, anonymized. Toy projects do not have plugin conflicts, cache layers, or five years of snippets.
• Grade explanations, not output. A dev who ships a correct fix and cannot explain it scores lower than one who ships a partial fix with a full root-cause write-up.
• Make seniors teach. The fastest way to make a senior top-tier is to have them articulate their instincts for a junior. Pair every drill.
• Timebox everything. Speed under a limit is the skill. Unlimited time produces gold-plating.
• Every drill ends in writing. A one-page document: what, why, risk, what they would do with more time. Communication is trained every week, not as a separate module.

Ongoing rituals after the 14 weeks

• Weekly bug autopsy (30 min): one real bug from the week, walked from symptom to mechanism by whoever fixed it. Everyone learns the pattern.
• Monthly "explain this AI code" session: a generated PR, reviewed live. Find the flaw.
• Every incident gets a blameless post-mortem shared with the whole team within 24 hours.
• Review comments must teach. Enforce it. "Fix this" is not a review comment.
• Maintain the team's DECISIONS.md and forbidden-patterns list. Every incident adds a line.

21Review rubric and levels

What "junior," "senior," and "top-tier" actually mean, so promotions are based on evidence, not feelings.

PR review checklist (apply to every PR, human or AI-written)

• Can the author explain every line without looking?
• Which request contexts execute this? Is it guarded for the ones it should not run in?
• Nonce, capability, permission_callback, sanitize, escape: all present where needed?
• Any query or remote call that runs per page load or per loop iteration?
• HPOS-safe? Blocks-checkout-safe? Works with caches on?
• Safe to run twice? Safe under concurrent requests for the same order?
• What breaks if this is wrong, and how is it turned off?
• Tested how? Evidence in the PR?
• Which of the eight quality dimensions does this touch, and is there evidence for each?
• If this needs undoing, what is the code, data, and external-system rollback?
• Would a new hire understand this file in six months?

22Drill library

Short exercises you can repeat. Rotate them. Score them. The scores show you where the team needs work.