Where documentation lives
Your docs folder has forty files and nobody opens it. The problem is not that they are out of date. It is that nobody can tell which question any of them was written to answer.
Writing
Notes from the work.
Practical pieces on AI-assisted engineering and software architecture.
-
-
Let your modules talk by events, not by calls
One part of your system needs to know what another part decided, so it asks. That call is a decision about deployment, scaling and availability that nobody in the room made.
-
UI states: design loading, empty and error before the happy path
Your designs are three happy-path screens. The states a user actually meets on a bad day get invented in the last two days of the sprint, by whoever is holding the ticket.
-
What a reviewer must not review
Your reviews are not slow because there are too many pull requests. They are slow because your reviewers keep re-deciding things a gate already decided, and it buries the one co...
-
A spec and a contract test are not the same gate
You have an OpenAPI file, both sides are generated from it, and your services still broke each other. The spec was never lying. It just permits more than anybody relies on.
-
Put the shared gate in CI, not in git hooks
Determinism vs reasoning · part 9Somebody joins on Monday and clones the repo. Every check you wrote is in that clone. None of them is running, and nothing tells either of you.
-
Pre-invocation gates: enforcing a rule before the action runs
Determinism vs reasoning · part 8You have written the same rule in three places and it got broken again yesterday. Asking for test-first works most of the time. A non-zero exit code works every time.
-
AI coding maturity levels: what your team stopped reading
You think your team is a level higher than it is. The test is not which tools you bought. It is what you stopped reading, and whether anything replaced you.