Learnings
The things I'd want to have known beforehand
One line each, from systems actually running rather than from reading about them. Every entry names the file or the change you can check it against. Some are written up in full; the rest are the insight and nothing more, which is the honest state for a note I haven't sat down with yet.
- Deployment and infra2025
A silent fallback hides a failure, a loud one gets fixed
Code that quietly substitutes a default when something breaks looks resilient and behaves like a bug you'll find in three months. Fail loudly and fix it in three minutes instead.
Source: Personal engineering vault, private
- Engineering philosophyMay 2026
Admitting a limitation earns more trust than being right does
Being right is table stakes and nobody remembers it. Being the one who said this doesn't work yet, and why, is what people actually come back to.
Source: Personal engineering vault, private
- Agent setup and AIMay 2026
Context engineering beats model selection
Which model you use matters less than what it can see when it starts. A well-kept reference document outperforms swapping models every time a better one ships.
Source: Personal engineering vault, private
- Architecture and migrationAug 2026
One server-only import breaks every component in the bundle
A component whose data layer imports server-only doesn't fail on its own when bundled for a browser, it throws on import and takes every other component in the bundle with it.
Source: .design-sync/NOTES.md, chrisscho.uk
Read the full note → - Agent setup and AIMar 2026
Pull beats push for a solo founder
Autonomous agents polling a queue reproduce the coordination overhead of a real team. A skill invoked by hand has no idle cost and nowhere for a stale task to hide.
Source: Personal engineering vault, private
- Engineering philosophyAug 2026
Put provenance in the type system, not in a comment
A chart that describes itself as illustrative in a hand-written string will still say so after real data replaces it. Make the caption a function of a discriminated union and the two cannot drift apart.
Source: src/config/adminHours.ts, chrisscho.uk
- Engineering philosophyAug 2026
Render the honest empty state
Reachability checks report 'no response' instead of a green tick, and the testimonials section returns nothing at all rather than a placeholder quote. An empty section costs less than a claim you cannot back.
Source: src/lib/uptime.ts and src/components/Testimonials.tsx, chrisscho.uk
- Architecture and migrationJan 2026
Three apps sharing one database were never really three apps
Splitting a product across subdomains that all read the same tables and share the same users doesn't multiply anything except the deployment surface and the cross-domain auth bugs.
Source: Personal engineering vault, private
- Agent setup and AIMar 2026
Three small files compound, one big prompt doesn't
A running memory file, a confidence-scored instincts list, and a structured notes vault, read at the start of every session and written back at the end, teach the next session something the last one didn't know.
Source: Personal engineering vault, private
- Deployment and infra2025
A deploy isn't finished until a health check confirms it
Green in the deploy log and working in production are different claims. A mandatory post-deploy health check is what actually closes the gap between them.
Source: Personal engineering vault, private
- Agent setup and AIMay 2026
A detached terminal session can lose the desktop keychain
A persistent session running outside the normal login context can see the filesystem fine and still lose access to stored credentials, which looks exactly like an expired token until you check the layer underneath.
Source: Personal engineering vault, private
- Agent setup and AIFeb 2026
A gateway that survives a reboot changes what's worth asking for
An agent that starts cold every session only gets asked for small things. One that stays up gets handed the kind of ongoing, unglamorous work nobody wants to re-explain daily.
Source: Personal engineering vault, private
- Agent setup and AIJun 2026
A knowledge base only helps an agent if it's built for one
Notes written for a human to skim aren't the same as notes an agent can reliably parse. Structure for machine reading first, and a human can still read it fine.
Source: Personal engineering vault, private
- Engineering philosophyAug 2026
A specimen fixture is one copy-paste from production
Preview data for a testimonial card should be unmistakably fake, because a plausible invented endorsement sitting in a design system eventually gets pasted into the real site by someone in a hurry.
Source: .design-sync/previews/Testimonials.tsx, chrisscho.uk
- Testing and evalsAug 2026
Check the repo you're linking to is actually public
Five of eight portfolio entries linked to private repositories, so every 'view source' button returned a 404 for visitors and the same dead URLs were handed to crawlers as structured data.
Source: src/config/portfolioConfig.ts, chrisscho.uk
- Agent setup and AIMar 2026
Confidence-score your own patterns
A pattern that has fired once is a guess. One that has fired three times in different contexts is worth trusting. Write down which one you're looking at.
Source: Personal engineering vault, private
- VPS and cloud setupAug 2026
Draw the whole system on one page before adding the next service
Once a stack spans a laptop, a phone bridge, and a small server, nobody can hold all of it in their head from memory. A single current diagram is what stops the next addition from becoming the one nobody can explain.
Source: Personal engineering vault, private
- Security2025
Google's OAuth testing mode quietly expires tokens after a week
An integration that worked fine yesterday and rejects everything today isn't necessarily broken. Testing-mode OAuth apps expire refresh tokens on a schedule nobody reads until it bites.
Source: Personal engineering vault, private
- Deployment and infraAug 2026
Move the always-on work off the laptop before the laptop becomes the bottleneck
A laptop that has to stay open, awake, and on charge to keep an agent running is a single point of failure wearing a keyboard. A small always-on server removes the constraint entirely.
Source: Personal engineering vault, private
- Security2025
Run the security pass before you think you need one
The first audit on a system that's never had one always finds something. Waiting for a reason to check is itself the reason it stays unchecked.
Source: Personal engineering vault, private
- Tooling and workflowAug 2026
Shim the framework out before bundling components on their own
next/link pulls the server tracer in and dies on a missing @opentelemetry/api, and next/image wants an optimiser that doesn't exist outside a Next build. Both need aliasing to plain tags before components will bundle standalone.
Source: .design-sync/shims/, chrisscho.uk
- Deployment and infraAug 2026
Stop the server before you rebuild
Rebuilding into the same output directory under a running production server leaves it serving manifests for chunks that no longer exist, and the page comes back unstyled rather than broken, which sends you hunting the wrong bug.
Source: chrisscho.uk build, Aug 2026
- Tooling and workflowAug 2026
Tailwind only emits the classes it can see
A stylesheet compiled from one site contains only the classes that site already uses, so any tool that generates new screens from it renders them half-styled until the vocabulary is safelisted.
Source: .design-sync/build-css.mjs, chrisscho.uk
- Deployment and infra2025
The path to one working deployment usually runs through several broken ones
Eight failed deployments taught me more about the actual infrastructure than the one that finally worked. The failures are where the assumptions get found.
Source: Personal engineering vault, private
- Engineering philosophyAug 2026
A colour that works on a chart can fail as text
The muted grey used for context marks measures 2.8:1 against the page, which is fine behind a bar and fails WCAG AA the moment it carries a label.
Source: src/config/timeline.ts, chrisscho.uk
- Agent setup and AIJul 2026
A heavy orchestration layer can degrade the thing it's orchestrating
Stacking coordination on top of a model doesn't just add latency, it can make the underlying model perform worse than it would unsupervised. More scaffolding isn't automatically more capability.
Source: Personal engineering vault, private
- Architecture and migration2025
A wiki with a block limit will eventually pick a fight with you
Hosted note tools that cap how much a single page can hold force artificial splits once real usage catches up. A plain git-synced set of files never runs into that ceiling.
Source: Personal engineering vault, private
- Engineering philosophy2025
AI-generated copy fakes specificity, real anecdotes have loose ends
A manufactured example is suspiciously tidy, the numbers round, the timeline convenient. A real one has a detail that doesn't quite serve the point, because reality doesn't edit itself.
Source: Personal engineering vault, private
- Testing and evalsJul 2026
Audit test coverage across every repo at once, not one at a time
Checking coverage repo by repo hides the pattern. Checking all of them in one pass shows which kind of code never gets tested anywhere, which is the more useful finding.
Source: Personal engineering vault, private
- Architecture and migration2025
Check the schema before you write the query
A column that isn't named what you assumed it's named fails quietly in a generated type and loudly at runtime. Five minutes reading the schema beats an hour finding out the hard way.
Source: Personal engineering vault, private
- Tooling and workflowAug 2026
pkill -f matches the shell that ran it
The pattern is tested against every full command line including your own, so pkill -f next-server kills the shell you typed it in. Bracket a character, [n]ext-server, and it stops matching itself.
Source: chrisscho.uk build, Aug 2026
- Tooling and workflow2025–2026
The 'right' browser automation tool keeps changing, plan for that
Whatever tool is best for driving a browser today won't be the one you're using in a year. Build the automation logic so swapping the driver underneath it is a small job, not a rewrite.
Source: Personal engineering vault, private
If you came here from the business side