DEV Community: Sub Engel

It broke again: a short about the same bug coming back, and the incident note I write now

Sub Engel — Sat, 31 Oct 2026 17:42:28 +0000

Episode 2 of our Rozz shorts is about a bug that comes back. Customers got three payment emails for one invoice. Rozz opens the Incidents dashboard, then the incident note, and works through it: symptom, root cause, fix, prevention.

The note on Rozz's screen is a real one from Dev Second Brain, the Obsidian vault template for developers. It's one of the example incident notes that comes with it: "Duplicate payment emails after deploy". A new step made a webhook handler slower than the provider's timeout. The provider retried, the handler wasn't idempotent, and each retry sent another email.

The Incident template has the same four parts the episode walks through:

Symptom: what users, alerts or logs actually showed, with room to paste the log lines
Root cause: the real cause, not just what set it off. Keep asking "why did that happen?"
Fix: what changed, and the PR or commit
Prevention: checkboxes for the test or alert that would have caught it

It asks you for a severity when you create it, files the note under 40 Incidents/ with the date in the name, and tracks status as open, mitigated, then resolved.

The Incidents dashboard (Dataview) is where "it broke again" gets easier. It lists incidents that aren't resolved yet, every unchecked Prevention item, and a log grouped by cause and by service. If the same service keeps coming up, you'll see it there. Prevention work you never got to also stays on the list until you check it off.

You need Obsidian (free) plus the free Templater and Dataview plugins. It's all plain Markdown files on your own disk.

Episode 3, "Standup amnesia", goes up tomorrow.

Dev Second Brain is $19 on Gumroad, one person per copy, personal and commercial use allowed: https://subengel.gumroad.com/l/uoybkd

More of what we make: https://engelailabs.com

Why did we do this? A short about losing context, and the vault I use for it

Sub Engel — Fri, 30 Oct 2026 17:40:36 +0000

We made a short with Rozz about a feeling every developer knows: you open old code, or an old decision, and nobody remembers why it's like that. Including you.

That's the problem Dev Second Brain is for. It's an Obsidian vault template for developers: one place for what you shipped, why you decided it, what broke and how you fixed it.

What's in it:

Six Templater templates: Daily note, Project, Decision record (ADR, auto-numbered), Incident, PR review, Weekly review
Four Dataview dashboards: Home, Decisions, Incidents, Weekly Rollup
A few clearly marked example notes so the dashboards aren't empty on first open. Delete them whenever you want.

You need Obsidian (free) and two free community plugins, Templater and Dataview. The README walks you through a five-minute setup. Everything is plain Markdown files on your own disk.

The "why did we do this?" moment is what the decision records are for. Write down the options and the reason when you choose, and the Decisions dashboard brings it back when someone asks months later.

Episode 2, "It broke again", goes up tomorrow.

Dev Second Brain is $19 on Gumroad, one person per copy, personal and commercial use allowed: https://subengel.gumroad.com/l/uoybkd

More of what we make: https://engelailabs.com

ghostwalk: an ofrenda for the forgotten files in your git repo

Sub Engel — Fri, 30 Oct 2026 16:23:47 +0000

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 4: Ghost in the Machine

What I Built

Every old repo has ghosts. Files nobody has opened in years. Branches someone started and walked away from. TODO and FIXME notes from people who left the team long ago.

ghostwalk is a small Python CLI that finds them. It walks a git repo and lists:

files nobody has touched in N days
abandoned branches
TODO/FIXME notes, with who left them (via git blame)

Then a small open-weight model running on your own CPU writes a one-line, Día de los Muertos style epitaph for each ghost. You can save the whole thing as ofrenda.md, a little altar for the code your team left behind.

I took the theme literally: honor the past of a codebase, and the people whose names are still in its history.

Demo

A real terminal recording (about 23 s): python ghostwalk.py records --days 365 --max 6 --out ofrenda.md finds 6 file ghosts, the local Qwen model writes their epitaphs in 2.9 s on CPU, and it saves ofrenda.md. Like the run below, the demo only shows file ghosts; the branch and TODO detectors are covered by tests.

Here's a real run on the public repo kennethreitz/records, on an 8-core CPU:

🕯  ghostwalk: 6 ghosts found in /tmp/records

👻 [file] .gitignore (untouched 4214 days, last by Kenneth Reitz)
   🌼 .gitignore, untouched 4214 days, last by Kenneth Reitz.
👻 [file] MANIFEST.in (untouched 3918 days, last by Kenneth Reitz)
   🌼 The file remains untouched 3918 days, a testament to its preservation.
👻 [file] tests/__init__.py (untouched 3914 days, last by Harold Cooper)
   🌼 `Unwritten Code: The Untouched File of Harold Cooper, 3914 days old.`
👻 [file] LICENSE (untouched 3348 days, last by Waldir Pimenta)
   🌼 `LICENSE` remains unchanged since Waldir Pimenta's last use, a reminder of forgotten knowledge.
👻 [file] tests/test_records.py (untouched 3179 days, last by Joakim Uddholm)
   🌼 This file is no longer needed, but Joakim Uddholm's touch made it worth remembering.
👻 [file] .travis.yml (untouched 3121 days, last by Jan Vlcinsky)
   🌼 Untouched, untouched, it remains.

Epitaphs written in 2.8s on CPU. No cloud, no API key, $0.
Ofrenda saved to /tmp/ofrenda.md

That run only turned up file ghosts. The branch and TODO detectors didn't find anything there, but each one has its own unit test (test_abandoned_branch and test_orphan_todo_blamed, which also checks the TODO gets blamed on the right author).

I'm leaving that output as-is, including the weak epitaphs. More on that below.

Code

https://gitlab.com/engelstands-hue/ghostwalk

MIT licensed. 5 tests pass in CI: latest test job.

To try it:

pip install -r requirements.txt --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cpu
curl -L -o models/qwen2.5-0.5b-instruct-q4_k_m.gguf https://huggingface.co/Qwen/Qwen2.5-0.5B-Instruct-GGUF/resolve/main/qwen2.5-0.5b-instruct-q4_k_m.gguf
python ghostwalk.py path/to/repo --days 365 --out ofrenda.md

--days defaults to 180; I used 365 above. Other flags:

--no-ai lists the ghosts without running the model
--max caps how many ghosts you get (default 12)
--out ofrenda.md saves the ofrenda
--model <path to .gguf> swaps the model (default is the Qwen2.5-0.5B-Instruct Q4 GGUF above)

How I Built It

Model: Qwen2.5-0.5B-Instruct (Apache-2.0), as a Q4_K_M GGUF file, about 490 MB.
Inference: llama.cpp through llama-cpp-python 0.3.36, on CPU. No GPU needed.
Everything else: plain git. Last-touched dates come from git history, abandoned branches from the branch list, and TODO/FIXME authors from git blame.

The git part finds the facts. The model only gets one job: turn each fact into a short epitaph. After the one-time model download, it needs no API key and no network.

Honest limits: the 0.5B model is fast, but it sometimes just restates the facts instead of writing something nice. "Untouched, untouched, it remains." is a real example. A bigger GGUF writes better epitaphs, just more slowly. Since it's an open model, swapping one in is one flag:

python ghostwalk.py path/to/repo --model models/your-bigger-model.gguf

Why Does Open Innovation Matter?

A repo's history is a team's private memory: who left, and what they never finished. That's not something I'd want to ship off to a cloud API just to get a joke epitaph.

Because ghostwalk runs an open-weight model locally:

the history never leaves your machine
it works offline
each run costs nothing
you're not stuck with my model choice. Since the model is open, you can point --model at a bigger or fine-tuned one

A closed API would have meant sending names and commit history to someone else's server, needing a key, and paying per run, for a tool whose whole point is a little Halloween fun with your own repo.

The Spirit of It

What got me wasn't the epitaphs, it was the names. Real people wrote those files years ago, and the repo still remembers them. ghostwalk just lights a candle for them.

License: MIT. Built by Engel AI Labs.

I made a free Windows board for all my AI account limits

Sub Engel — Fri, 30 Oct 2026 16:20:00 +0000

I pay for more AI tools than I'd like to admit, and a few of them have more than one account. Every week the same thing happened: one account would reset with half its usage never touched, while I was burning through another one that still had days left.

So I made a small free Windows app for it, Engel Usage Meters.

What it does

You add every account you have. Several accounts for the same tool is fine, each one gets its own row.

For each account you can type in two things: how much is still left (as a percent) and how many days until it resets. Hit save and it goes on the board.

The board sorts itself:

Accounts that reset within 3 days and still have at least 20% left go on top, under "Finish these first".
Everything else comes after, soonest reset first.

The header gives you the totals: how many accounts, how many have usage set, and how many to use before they reset.

It can read some of them for you

On Windows, after you sign in or hit Refresh, it reads your usage on its own for Codex / ChatGPT CLI, Cursor and Grok Bot, so you don't have to type anything for those. Everything else you fill in by hand for now.

Here's a short clip of it reading usage on a real Windows run:

Get it

It's a free download here: Engel Usage Meters

It's part of what we're building at Engel AI Labs. If you juggle a pile of AI seats too, I'd like to hear how you keep track of them.

slothnotes: let a tiny local model read your notes so you don't have to

Sub Engel — Sun, 25 Oct 2026 14:43:12 +0000

This is a submission for the Hacktoberfest Open-Source AI Challenge: Week 3: Slow and Steady.

What I Built

I have a folder full of notes I never reread. Standups. A grocery list. An email to my landlord. Book club plans.

slothnotes is a small Python CLI that reads that folder for me. You point it at a folder of .md or .txt files. It prints one summary line per note. If you want, it also writes a digest.md you can skim in about ten seconds.

It runs a small open-weight model (Qwen2.5-0.5B-Instruct, Q4_K_M GGUF, about 490 MB) on the CPU through llama.cpp. After the model download, it needs no API key and no network.

The effort it saves is the boring part: opening every file to remember what was in it. One command does that.

Demo

This is a real run on four sample notes: standup, groceries, landlord, book club. On an 8-core CPU with no GPU, it summarized all four in about 3 seconds.

One honest limit: the tiny model got a grocery detail wrong. It listed "half a loaf of bread" when the note actually says to skip bread. A bigger GGUF should be more accurate, but it will be slower. For a quick skim it's fine. For anything that matters, read the note.

Code

https://gitlab.com/engelstands-hue/slothnotes

MIT licensed. It has a README, three pytest tests that run without the model, and a GitLab CI job.

How I Built It

Python and llama-cpp-python, running on the CPU.
Qwen2.5-0.5B-Instruct (Apache-2.0) as a quantized GGUF.
One prompt per note, one line back, then an optional markdown digest.
--model takes any GGUF, so you can swap models without touching code.

To try it:

pip install llama-cpp-python --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cpu
curl -L -o models/qwen2.5-0.5b-instruct-q4_k_m.gguf https://huggingface.co/Qwen/Qwen2.5-0.5B-Instruct-GGUF/resolve/main/qwen2.5-0.5b-instruct-q4_k_m.gguf
python slothnotes.py demo_notes --out digest.md

Why Open Innovation Matters Here

Notes are personal. Standups, landlord emails, grocery lists. Because slothnotes runs an open-weight model locally, none of that leaves the machine. It works offline, and each run costs nothing. Since the model is open, you can swap in a bigger or fine-tuned one with a single flag.

A closed API would mean an account, a key, a bill, and sending my notes to someone else's server. For a tool whose whole point is being lazy, that's too much setup.

Prize Categories

None. This entry doesn't use partner technology.

More of what I build: https://engelailabs.com

Dev Second Brain: the Obsidian vault I use for daily notes, ADRs, incidents and PR reviews

Sub Engel — Fri, 16 Oct 2026 16:04:06 +0000

Most of what I learn at work ends up scattered: a decision explained in a Slack thread, an incident fix in a terminal history, a good PR review comment that disappears once the branch merges. A few months later I need it and can't find it.

So I put together a plain Obsidian vault that gives each of those a place, and lets Dataview pull them back together. I'm selling it as Dev Second Brain, and this post is a walk through what's in it.

What's inside

Six templates (Templater):

Daily note: a quick log of what you worked on and what's still open
Project
Decision record (ADR): auto-numbered, so you don't have to track the next ID
Incident: what broke and how you fixed it
PR review
Weekly review

Four dashboards (Dataview):

Home: today, open loops, open incidents, recent decisions, active projects
Decisions
Incidents
Weekly rollup

The dashboards are only useful once there's something in them, so the vault ships with a few clearly marked example notes. It isn't empty on day one, and you can delete the examples whenever you like.

What you need

Obsidian (free)
Two free community plugins: Templater and Dataview

The README has a five-minute setup guide, including installing those plugins and switching on the one Templater setting you need per device. I tested it in Obsidian 1.13.7 with Templater 2.25.1 and Dataview 0.5.68.

How I use it

The habit is small: write the daily note, and when something worth keeping happens (a decision, an incident, a review you'd want to find again), make a note from the matching template. The dashboards do the gathering. At the end of the week the weekly review and rollup show what actually happened, without me reconstructing it from memory.

If you'd rather build your own, the earlier posts in this series cover the Dataview queries and linking decision records to git commits that this vault is built around.

Get it

Dev Second Brain is $19 on Gumroad, personal-use license: https://subengel.gumroad.com/l/uoybkd

My other templates are at https://forge.engelailabs.com.

grasscard: a local model that prints you a pocket card of outdoor quests, then gets out of the way

Sub Engel — Fri, 09 Oct 2026 16:17:27 +0000

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 1: Touch Grass

What I Built

Most "go outside" apps want you to keep looking at them. grasscard does the opposite. You run one command, it prints a small card with five short outdoor quests that fit how much time you have, where you are, the season and the light outside right now, and then it's done. The screen part takes about a minute. The rest happens outside.

After the walk, grasscard log "..." adds one line to a journal file on your own machine, so you have a record of what you actually did without posting it anywhere.

It's for people like me who spend the whole day in a terminal and need a nudge that doesn't come with a feed attached.

Demo

This is a real 32-second run on Gemma 3 1B, in real time with no edits: a card for a 45-minute trail walk in light rain with a dog, the printable version, and a journal line afterwards.

Here's a real card, printed by Gemma 3 1B running locally. Open it on your phone and tap a quest to tick it off:

Try it:

ollama pull gemma3:1b
python -m grasscard card --minutes 30 --place park

You can add a note like "light rain, with my dog" and the quests adjust. --mock runs it with no model at all, which is handy for a quick look.

Code

grasscard on GitLab: https://gitlab.com/engelstands-hue/grasscard

Python 3.9+, no dependencies, MIT licensed, 13 unit tests.

How I Built It

The flow is small on purpose:

It works out the season from today's date and your hemisphere, and the light from the current hour.
It asks a local open-weight model for one-line quests that fit your time, your place and your note.
A short filter drops any quest that would send you back to a screen: taking photos, opening an app, looking something up.
It prints a fixed-width card for the terminal, or one self-contained HTML card with no network requests. Open that on your phone and tap quests to tick them off (the ticks stay in that browser), or print it as a plain black-and-white pocket card.

The prompt and the no-screens filter are each one short Python file, so changing what counts as a good quest is a quick edit, not a config hunt.

On CPU only, a card takes a few seconds to under a minute depending on the machine (the recorded run took about 5 seconds; a cold first run on a busy shared machine took about 45). That's fine for something you run once before heading out.

Why open matters here

The whole point is a tool that respects the walk, so the model runs where you are:

No signal needed. Once Gemma is downloaded, grasscard works fully offline. You can make a card at the trailhead.
Your location stays with you. Where you walk and what you write in your journal never leaves your machine. There's no server to trust.
Costs nothing to run. No API key, no account, no per-card bill.
Swap the model. Any Ollama model works with --model, and you can rewrite the prompt or the filter yourself.

A hosted model would have made the cards a bit faster, but it would have meant an account, a key and sending where you are to someone else's server, which is the opposite of what a "go outside" tool should ask for.

Prize Categories

Best Use of Gemma: Gemma 3 1B is the default model and does all of the quest generation, locally.

Built by the Engel AI Lab team: https://engelailabs.com

Building a second brain from PR reviews and tickets

Sub Engel — Thu, 08 Oct 2026 18:38:55 +0000

A lot of real engineering reasoning gets written down in two places: pull request reviews and ticket comment threads. "Why not just use a queue here?" "Because ordering matters for refunds." That exchange is the most useful sentence in the whole change, and it disappears the moment the PR is merged.

You can search for it later, in theory. In practice you don't remember which PR it was, or the repo got migrated, or the ticket tracker changed. This post is about keeping the useful parts somewhere you control, without turning code review into a documentation chore.

I'll use GitHub and Linear in the examples and Obsidian for the notes, but the idea carries over to GitLab, Jira, or a plain folder of Markdown.

What's worth keeping

Most reviews produce nothing worth saving, and that's fine. The things worth keeping fall into a few buckets:

Decisions: "we chose X over Y because Z". Often buried in a reply to a review comment.
Gotchas: behavior that surprised someone. "Postgres NULL is ignored by COUNT(column) but not by COUNT(*)."
Patterns: "this is the third PR where we've needed a retry wrapper." A repeat is a hint that something should exist.
Context from tickets: the business reason for a change, which almost never makes it into the code or the commit message.

Capture right after the review

The cheapest moment to capture is right after you submit (or respond to) a review, while the details are in your head. Ask one question: did a decision or a surprise happen here? If not, move on. If yes, spend three to five minutes on a short note.

An illustrative example:

---
type: pr
repo: web
pr: 482
ticket: ENG-217
date: 2026-09-18
tags: [dependencies]
---

# Replace lodash.groupBy with a local helper

**Decision:** Use a 10-line `groupBy` in `lib/collections.ts` instead of importing lodash.

**Why:** It was the only lodash function left in the client bundle. The local version is typed the way we use it.

**Trade-off:** One more function we own and test.

**Link:** https://github.com/acme/web/pull/482

Short, dated, linked. The link matters most: the note is an index into the original discussion, not a replacement for it.

Tickets: the reasoning is in the comments

Ticket descriptions tend to say what. The why, and the changes of direction, are in the comment thread: a PM explaining why the scope changed, a lead pushing back on an approach. When you close a ticket that had a real discussion, summarize it in two or three lines:

# ENG-217 Faster search on the orders page

**Problem:** Support staff wait 5+ seconds searching orders by email.
**What changed during the ticket:** Started as "add an index"; turned out the query was doing a case-insensitive scan. Switched to a lowercased generated column.
**Related:** [[PR web#482]], [[PR api#1190]]

That second line is the part nobody will reconstruct later.

Pulling the week's activity with scripts

Capturing in the moment is best, but a weekly sweep catches what you missed. The GitHub CLI can list the PRs you reviewed recently:

# PRs in the current repo you reviewed, closed in the last 7 days
since=$(date -d '7 days ago' +%F)   # macOS: date -v-7d +%F
gh pr list --state closed --limit 50 \
  --search "reviewed-by:@me closed:>=$since" \
  --json number,title,url \
  --jq '.[] | "- [#\(.number)](\(.url)) \(.title)"' >> "notes/reviews/week-$(date +%F).md"

gh pr list has no --reviewed-by flag, but its --search option accepts GitHub's search qualifiers, and reviewed-by:@me is one of them.

To read the discussion on a specific PR:

# Description, conversation comments and review summaries
gh pr view 482 --json title,body,comments,reviews

# Inline review comments (the line-by-line ones) come from a different endpoint
gh api repos/{owner}/{repo}/pulls/482/comments --jq '.[] | "\(.path):\(.line) \(.user.login): \(.body)"'

gh api fills in {owner} and {repo} from the repo you're in. The inline comments are where most of the interesting back-and-forth happens, and gh pr view doesn't include them.

Exporting Linear tickets

Linear has a GraphQL API at https://api.linear.app/graphql. With a personal API key (Settings > API), a small script can turn recently completed issues into notes:

import json, os, pathlib, urllib.request

QUERY = """
query($since: DateTimeOrDuration!) {
  issues(first: 50, filter: { completedAt: { gte: $since } }) {
    nodes {
      identifier title url description estimate
      comments { nodes { body createdAt user { name } } }
    }
  }
}
"""

def fetch(since="-P7D"):  # ISO 8601 duration: last 7 days
    req = urllib.request.Request(
        "https://api.linear.app/graphql",
        data=json.dumps({"query": QUERY, "variables": {"since": since}}).encode(),
        headers={"Content-Type": "application/json",
                 "Authorization": os.environ["LINEAR_API_KEY"]},
    )
    with urllib.request.urlopen(req) as r:
        return json.load(r)["data"]["issues"]["nodes"]

out = pathlib.Path("notes/tickets")
out.mkdir(parents=True, exist_ok=True)
for i in fetch():
    lines = [
        "---", f"type: ticket", f"ticket: {i['identifier']}",
        f"estimate: {i['estimate']}", "---", "",
        f"# {i['identifier']} {i['title']}", "", i["url"], "",
        "## Description", i["description"] or "", "", "## Discussion",
    ]
    for c in i["comments"]["nodes"]:
        who = c["user"]["name"] if c["user"] else "unknown"
        lines += [f"- **{who}** ({c['createdAt'][:10]}): {c['body']}"]
    lines += ["", "## Summary", "_Two lines: what changed and why._"]
    (out / f"{i['identifier']}.md").write_text("\n".join(lines))

Two notes on this:

Linear's estimate is in points on whatever scale your team configured, not hours. Don't do "estimate vs actual hours" math on it.
The script dumps raw comments. The valuable part is the ## Summary you write by hand afterwards; a vault full of unread exports isn't a second brain, it's a backup.

Keep the API key in an environment variable, never in the vault.

Linking it together

Once PR notes and ticket notes exist, wiki links connect them. A ticket note links to its PRs, a PR note links to its ticket and any decision record, and backlinks give you the reverse direction for free. When you later wonder why the orders search uses a generated column, you land on the ticket, which links to both PRs and the reasoning.

If you use Dataview, a simple dashboard helps during the weekly sweep:

```dataview
TABLE repo, pr, ticket, date
FROM "reviews"
WHERE date >= date(today) - dur(7 days)
SORT date DESC
```

Keeping it from going stale

Advice from an old PR can be wrong now: a dependency got upgraded, the team changed its mind, the service was rewritten. Two cheap habits help:

Mark superseded notes instead of deleting them. Add a line at the top: "Superseded by [[new note]]: we moved from Redux to Zustand in 2026." The old reasoning stays findable and nobody follows it by accident.
Add a reviewed: date to notes you rely on. When you use a note and it still holds, bump the date. Notes nobody has touched in a year are the first to question.

The weekly sweep

Once a week (Friday works), do a quick pass:

Run the gh command above and skim the list for reviews where something was decided that you didn't capture.
Look at tickets you closed this week and write the two-line summary for any with a real discussion.
Scan the week's notes for repeats: the same gotcha twice is a candidate for a lint rule, a helper or a README section.

Expect around half an hour, less on quiet weeks. The in-the-moment captures do most of the work; the sweep catches what slipped through.

Start small

You don't need the scripts on day one. Start with the habit: after any review where a decision or surprise came up, write five lines and paste the link. After a month you'll have a small, searchable record of why your codebase looks the way it does, which is more than most teams have.

Dev Second Brain, my Obsidian vault for developers, includes a PR review template if you want somewhere to start.

More templates and a free Dataview starter pack are at forge.engelailabs.com.

Writing docs that survive framework churn

Sub Engel — Wed, 07 Oct 2026 17:15:18 +0000

Most of us have opened a project's docs, followed the setup steps, and hit a wall by step three. The CLI flag was renamed, the config file moved, the recommended package is deprecated. Usually the explanation of how the system works in that same document is still mostly right. But because it sits next to steps that are visibly broken, you stop trusting any of it.

That's the core problem: docs contain information with very different lifespans, and we tend to mix it all together. Separate it, and most of the rot becomes contained and easy to fix.

Sort information by how fast it goes stale

Roughly four layers:

Why (slow to change). Principles, architecture, trade-offs, the reasoning behind big decisions. "We keep business logic out of route handlers so it can be tested without HTTP." This stays true across framework rewrites.

Patterns (changes occasionally). How we usually do things. "Validate input at the edge, pass typed objects inward." "Every async UI state is one of idle, loading, success, error." The details shift; the idea holds.

How-to (changes with major versions). Setup, deployment, "how to add a new endpoint". Tied to specific tools and versions.

Reference (changes every release). CLI flags, config schemas, API endpoints. Ideally generated from the code, not written by hand.

The mistake is putting all four in one README section. A single framework upgrade then makes the whole thing look abandoned.

Keep "why" and "how" in separate documents

A typical setup doc mixes both:

# Getting started
1. Run `npm install`
2. Run `npm run dev`
3. Open http://localhost:3000

The app uses the Next.js App Router, so pages live in `app/` and data fetching happens in server components...

When the project moves to a different framework, or even changes its dev port, every line here is suspect.

Split it instead. The architecture doc explains the idea and links to the current implementation:

# Architecture: rendering and data loading

Pages render on the server by default and fetch their own data, so the client bundle
stays small and there's no separate API layer for page data. Interactive pieces are
isolated client components.

Current implementation: Next.js App Router. See [Setup (Next.js)](./how-to/setup-next.md).
Previous approach: see [archive/pages-router.md](./archive/pages-router.md).

And the setup doc is openly version-specific:

# Setup (Next.js)

Last verified: 2026-09-01 with Node 24, Next.js 16.

1. ...

When the framework changes, you rewrite the setup doc and change one line in the architecture doc. The explanation, which is the expensive part to write, survives.

Describe contracts, not syntax

The same idea works at the level of individual examples. Instead of documenting "here's how we use useState for errors", document the shape of the thing:

type AsyncState<T> =
  | { status: "idle" }
  | { status: "loading" }
  | { status: "success"; data: T }
  | { status: "error"; error: Error };

Then explain the rules in plain language: a retry moves from error back to loading, so stale errors never show next to fresh data. That holds whether the implementation is React hooks, a state machine library, or something that doesn't exist yet. Link to the current implementation for the framework-specific part.

Put a date and versions on anything that can go stale

Every how-to page gets a line at the top:

Last verified: 2026-09-01 · Node 24 · pnpm 10 · Next.js 16

This does two things. Readers can judge at a glance whether to trust the page. And you get an obvious list of what to re-check when you bump a major dependency: search for the old version number.

If your docs have frontmatter, make it a field (last_verified: 2026-09-01) so a script can list pages that haven't been verified in, say, six months.

Deprecate instead of deleting

When a doc is outdated but some code still depends on it, don't delete it. Mark it:

> **Deprecated (2026-03).** This describes the Create React App setup.
> New projects: see [Setup (Vite)](./setup-vite.md).
> Kept for the legacy admin app, which still uses CRA.

New readers get sent to the right place immediately, people maintaining old code still have what they need, and you have an explicit list of docs to remove once the legacy code is gone. Moving them into an archive/ folder with the banner intact works too.

Record decisions where the docs can link to them

Big "why" questions (why this database, why a monorepo, why this auth model) deserve short decision records: context, options considered, what was chosen, consequences. Keep them in the repo, link to them from the architecture docs, and mark them superseded rather than deleting them when things change. The architecture doc then stays short, and the detailed reasoning is one click away.

Review on a schedule, triggered by events

Different layers need different attention. A starting point:

Layer	When to review
Architecture / why	Once a year, or when the architecture actually changes
Patterns	A few times a year, or when the team's habits shift
How-to / setup	On every major dependency or tooling upgrade
Reference	Every release (automate it if you can)
Deprecated docs	When the legacy code they support is removed

The event-based triggers matter more than the calendar. Add "update the setup doc" to the checklist for dependency upgrades, and "does this PR change how someone uses the system?" to your review habits.

Let tooling catch the mechanical rot

Some rot is easy to detect automatically:

Broken links. Run a link checker like lychee or markdown-link-check in CI. Internal links break every time someone renames a file.
Code examples drifting from code. Where possible, embed examples from real source or test files instead of pasting them, or keep examples as small tests that run in CI. An example that's compiled is an example that's still true.
Stale pages. A small scheduled script that reads last_verified from frontmatter and opens an issue for anything older than six months turns review into a to-do list instead of a good intention.
Versioned doc sites. If users run old versions of your software, publish docs per version. Docusaurus has built-in versioning; for MkDocs, mike is the common choice.

Give each layer an owner

"Everyone owns the docs" means nobody does. Even on a small team, assign names: someone reviews the architecture docs yearly, whoever does a major upgrade updates the setup docs, reference docs are generated as part of the release. On a solo project the owner is you, but writing down when you'll review each layer still helps.

Where to start

You don't need to restructure everything. Start with the next doc you touch:

Pull the "why" paragraphs out of setup instructions into their own page.
Add a Last verified line with versions to every how-to you edit.
Add a link checker to CI; it takes ten minutes and catches real problems immediately.

Over time the pages that explain your system stop being dragged down by the pages that describe this month's commands, and the parts that do go stale are small, dated, and obvious to fix.

More templates and a free Dataview starter pack are at forge.engelailabs.com.

Linking decision records to git commits

Sub Engel — Tue, 06 Oct 2026 17:09:21 +0000

Six months after a change, git log tells you what happened and git blame tells you who. Neither tells you why you picked this approach over the two you rejected. That reasoning usually lived in a meeting, a chat thread, or your head.

Architecture decision records (ADRs) fix half of this by writing the reasoning down. The other half is linking each decision to the commits that carried it out, so you can go from code to reasoning and back. This post shows a setup that uses nothing more exotic than a notes folder, a naming convention, and git's own features.

I'll use Obsidian for the notes, but everything here works with any folder of Markdown files.

What counts as a decision

Not every commit needs one. I'd write a decision note when:

there were real alternatives and you rejected some of them,
the choice is expensive to reverse (a database, a framework, an auth model, a public API shape), or
you can imagine someone (including you) asking "why did we do it this way?" later.

Renaming a variable doesn't qualify. Switching your session store does.

Step 1: Give every decision a stable ID

The ID is the glue, so it has to be boring and predictable. A date plus a short slug works well and sorts nicely:

decisions/adr-20260927-session-store.md

The filename is the ID. Here's a Templater template that creates the frontmatter and structure (save it as templates/decision.md):

---
id: <% tp.file.title %>
status: proposed   # proposed | accepted | superseded | rejected
decided: <% tp.date.now("YYYY-MM-DD") %>
reviewed: <% tp.date.now("YYYY-MM-DD") %>
superseded_by:
tags: [decision]
---

# <% tp.file.title %>

## Context
What problem, what constraints, what forced a decision now.

## Options considered
1. **Option A**: what it is. Pros / cons.
2. **Option B**: what it is. Pros / cons.

## Decision
We chose ... because ...

## Consequences
What gets easier, what gets harder, what we're now committed to.

## Commits
Filled in from git, see below.

Create the note with a filename like adr-20260927-session-store, apply the template, fill it in. It takes ten minutes when the decision is fresh and an hour of archaeology if you wait.

Step 2: Reference the ID in commits with a trailer

Git has a built-in convention for structured lines at the end of a commit message, called trailers (Signed-off-by: is the best-known one). Use one for decisions:

Replace JWT refresh flow with server-side sessions

Refresh-token rotation was racing across browser tabs.
Sessions now live in Redis with a 30-day sliding expiry.

Decision: adr-20260927-session-store

You can add the trailer from the command line too:

git commit -m "Move session reads to Redis" --trailer "Decision: adr-20260927-session-store"

(--trailer needs git 2.32 or newer.)

If you want a reminder, add a commit template to the repo and point git at it:

# .gitmessage in the repo root
# Subject line (~50 chars)

# Why this change?

# Decision: adr-YYYYMMDD-slug   (delete if not applicable)

git config commit.template .gitmessage

Lines starting with # are stripped from the final message, so the hints cost nothing.

Forgot the trailer on a commit that's already pushed? You don't have to rewrite history. git notes can attach the ID after the fact (thanks to shieldx in the comments for the nudge):

git notes add -m "Decision: adr-20260927-session-store" <hash>
git log --notes --oneline --grep="Decision: adr-20260927-session-store"

Two catches: --grep only searches notes when you pass --notes, so add it to any git log --grep in this post if you use notes. And notes don't travel with a normal push or clone, so share them with git push origin refs/notes/commits and pull them with git fetch origin refs/notes/commits:refs/notes/commits.

Step 3: Querying the link from the git side

This is where the trailer pays off. No script needed:

# Every commit that implemented a given decision
git log --oneline --grep="Decision: adr-20260927-session-store"

# All commits that reference any decision, with the ID shown
git log --format='%h %s  [%(trailers:key=Decision,valueonly,separator=%x2C)]' --grep="^Decision:"

# Which decision explains this line? blame first, then read the commit
git blame -L 40,60 src/auth/session.ts
git show <hash>   # the trailer is at the bottom

The second command prints each commit with its decision ID in brackets, which makes a decent audit log on its own.

Step 4: Catch typos with a commit-msg hook

Links are only useful if they point at something real. A small commit-msg hook rejects IDs that don't match a note. (It must be commit-msg, not pre-commit: only commit-msg receives the message file as $1.)

#!/bin/sh
# .git/hooks/commit-msg  (or .husky/commit-msg)
DECISIONS_DIR="docs/decisions"   # adjust to where your notes live

ids=$(grep -oE '^Decision: adr-[0-9]{8}-[a-z0-9-]+' "$1" | sed 's/^Decision: //')

for id in $ids; do
  if [ ! -f "$DECISIONS_DIR/$id.md" ]; then
    echo "commit-msg: no decision note found for '$id' in $DECISIONS_DIR" >&2
    exit 1
  fi
done
exit 0

Make it executable (chmod +x). It uses grep -E rather than grep -P so it also works with the BSD grep on macOS.

If your vault is a separate repo, point DECISIONS_DIR at its checkout path, or drop the hook and live with the occasional typo.

Step 5 (optional): Show commits inside the note

Going from commit to decision is covered by git. Going from decision to commits is covered by git log --grep too, but it's nice to see the list inside the note itself. A small script can rebuild a ## Commits section from git:

#!/bin/sh
# scripts/decision-commits.sh adr-20260927-session-store
id="$1"
note="docs/decisions/$id.md"
git log --reverse --format='- `%h` %ad %s' --date=short --grep="Decision: $id" > /tmp/commits.md
# Replace everything after the "## Commits" heading with the fresh list
awk '/^## Commits/{print; while((getline l < "/tmp/commits.md")>0) print l; skip=1; next} !skip' "$note" > "$note.tmp" && mv "$note.tmp" "$note"

It assumes ## Commits is the last section of the note, which the template above guarantees. Run it by hand when you finish a decision; I wouldn't wire it into a post-commit hook, because a hook that edits files after every commit leaves your working tree permanently dirty.

Seeing decisions in Obsidian

With Dataview, a small dashboard shows what's in flight and what's gone stale:

## Proposed, not yet decided
```dataview
LIST
FROM "decisions"
WHERE status = "proposed"
SORT decided ASC
```

## Accepted, not reviewed in a year
```dataview
TABLE decided, reviewed
FROM "decisions"
WHERE status = "accepted" AND reviewed < date(today) - dur(1 year)
SORT reviewed ASC
```

Decisions that span many commits

A migration might take a dozen commits over several weeks. Nothing changes: every commit carries the same trailer, and git log --grep returns them in order. If phases matter, say so in the subject line ("Phase 2: dual-write sessions to Redis") rather than inventing more metadata.

Keep the rejected ones

When you decide not to do something, write that down too and set status: rejected. The next time someone proposes the same idea, there's a note with the context and the reasons, and you can judge whether those reasons still hold instead of having the whole discussion again. Same for superseded decisions: link the old note to the new one with superseded_by instead of deleting it.

An example, start to finish

To make it concrete, here's what a small one might look like (illustrative, not a real project):

Note: adr-20260310-drop-axios.md. Context: we only use axios for simple JSON requests, and Node 18+ ships a global fetch. Options: keep axios, switch to fetch with a small wrapper. Decision: switch, with a wrapper in lib/http.ts that handles retries and JSON errors. Consequence: we lose interceptors and write our own retry helper.
Commit 1: "Add fetch wrapper with retry" + Decision: adr-20260310-drop-axios
Commit 2: "Migrate API handlers to lib/http" + same trailer
Commit 3: "Remove axios dependency" + same trailer

A year later, someone runs git blame on lib/http.ts, opens the commit, sees the trailer, and reads the note. Total overhead at the time: one note and one extra line per commit.

The short version

Name decision notes with a stable ID, reference it in a commit trailer, and let git do the searching. Add the hook if typos bother you and the Dataview dashboard if you use Obsidian. Everything else is optional.

If you want a ready-made starting point, Dev Second Brain, my Obsidian vault for developers, includes an ADR template along with Dataview dashboards.

More templates and a free Dataview starter pack are at forge.engelailabs.com.

n8n vs GitHub Actions for side-project automation

Sub Engel — Mon, 05 Oct 2026 17:13:37 +0000

Once a side project has users, the chores start: deploy on merge, sync payments into your database, send a welcome email, post a note somewhere when something breaks. Two tools come up constantly for this: GitHub Actions and n8n.

They overlap, and you can force either one to do almost anything. But they're built around different centers of gravity, and picking the right one per job saves a lot of friction.

The short version

GitHub Actions is built around your repository. It shines when the trigger is a git event (push, pull request, tag, release) or the job needs your code checked out.
n8n is built around moving data between services. It shines when the job is "when X happens in service A, do Y in services B and C", especially with SaaS APIs you don't want to write auth and pagination code for.

Most of the time the choice is obvious once you ask: does this job start from my code, or from someone else's service?

GitHub Actions: what it's good at

Workflows are YAML files in .github/workflows/. They run on GitHub-hosted runners (or your own) in response to events.

Good fits:

tests and linting on every PR,
building and deploying on push to main,
publishing a package or release notes when you push a tag,
scheduled jobs that need the repo, like regenerating a sitemap or updating a dependency report.

A minimal deploy-on-push workflow:

name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm test
      - run: npm run build
      - run: ./scripts/deploy.sh
        env:
          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}

What you get for free: no server to run, secrets management, logs for every run, and direct access to commit and branch context. Actions also supports scheduled workflows with cron syntax (on: schedule: - cron: '0 6 * * *'), with a few caveats covered below.

Where it gets awkward: anything that's mostly calling third-party APIs. You can do it with a script step, but you're writing and maintaining the API client, retries and error handling yourself.

Cost

At the time of writing, public repositories get GitHub-hosted runner minutes on standard runners for free. Private repositories draw from a monthly allowance (2,000 minutes on the Free plan, more on paid plans), then bill per minute. Check GitHub's current pricing before relying on this; it has changed before.

The detail that bites people: GitHub rounds each job up to the nearest whole minute. A job that runs for 5 seconds costs a full minute.

n8n: what it's good at

n8n is a workflow automation tool with a visual node editor. You chain triggers (webhook, schedule, an app event) with nodes for specific services (Stripe, Postgres, Slack, Notion, Gmail, GitHub and many more), and drop into JavaScript or Python when you need custom logic. You can self-host it (the source is available under n8n's Sustainable Use License) or use their paid cloud.

Good fits:

a Stripe event creates or updates a row in your database,
a new signup triggers a welcome email and a note in your CRM or Notion,
a form submission lands in a spreadsheet and pings you,
a daily digest pulls numbers from a few APIs and emails them to you.

For example, a "new paying customer" workflow might be:

Stripe Trigger on checkout.session.completed
Postgres node: upsert the customer
HTTP Request node: call your own API to provision their account
Send Email (or Gmail) node: welcome message
An error workflow that notifies you if any step fails

Each of those would be a chunk of code in an Actions script. In n8n the nodes handle credentials and API details, and you mostly write the data mapping.

n8n can also react to repo events: its GitHub Trigger node registers a webhook for things like pushes or new issues. So "n8n can't do git events" isn't true; it's just not where it's strongest, because it doesn't have your code checked out.

Cost

Self-hosting is free in license terms, but it's a server you now own: updates, backups of its database (which holds your workflows and credentials), HTTPS, and monitoring. For many indie developers that's a small VPS they already have. n8n Cloud removes the ops work for a monthly fee; plans and execution limits change, so check their pricing page.

The trap: frequent schedules on Actions

A pattern that looks cheap and isn't: using Actions as an uptime monitor with a cron every five minutes.

Every 5 minutes is 288 runs a day, roughly 8,640 a month.
Each run is billed as at least one minute.
On a private repo, that's around 8,640 billed minutes a month, over four times the Free plan's allowance, for a job that runs curl for two seconds.

It's also not a great monitor. GitHub's docs note that scheduled workflows can be delayed during periods of high load, five minutes is the shortest interval allowed, and in public repositories scheduled workflows are automatically disabled after 60 days without repository activity.

For uptime checks, use a dedicated uptime monitoring service or a schedule trigger in n8n (which runs on your server, so frequency doesn't cost minutes). Keep Actions schedules for jobs that run a few times a day at most and genuinely need the repo.

When to use both

A split that works well: Actions owns everything up to "the new version is live", and n8n owns what happens after.

      # last step of the deploy job
      - name: Tell n8n about the deploy
        if: success()
        run: |
          curl -fsS -X POST "$N8N_WEBHOOK_URL" \
            -H "Content-Type: application/json" \
            -d "{\"sha\": \"${GITHUB_SHA}\", \"ref\": \"${GITHUB_REF_NAME}\"}"
        env:
          N8N_WEBHOOK_URL: ${{ secrets.N8N_DEPLOY_WEBHOOK }}

The n8n workflow behind that webhook can post to Discord, update a status page, add a changelog row, and email beta users, without any of that logic living in your repo's CI config. If the n8n side fails, your deploy still succeeded, which is usually what you want.

If you add a webhook like this, protect it: at minimum a hard-to-guess URL kept in secrets, ideally a shared token checked in the workflow.

A quick way to decide

List the chores you currently do by hand and note two things for each: what triggers it, and what it touches.

Chore	Trigger	Touches	Pick
Run tests on PRs	Pull request	Your code	Actions
Deploy on merge	Push to `main`	Your code, host	Actions
New Stripe customer -> DB + welcome email	Stripe event	Stripe, DB, email	n8n
Weekly metrics email	Schedule	Several APIs	n8n
Regenerate docs site	Push	Your code	Actions
Uptime check every few minutes	Schedule	Your site	Uptime monitor or n8n
Announce a release	Tag push	Discord, email, status page	Actions -> n8n webhook

If a chore takes you five minutes a month, automating it with either tool may not be worth the maintenance. Automate the ones that are frequent, error-prone, or that you tend to forget.

Bottom line

Start with GitHub Actions, because you probably already have it and it covers everything code-shaped. Add n8n when you catch yourself writing API glue in YAML, or when a job has nothing to do with your repository. And be careful with frequent cron schedules on private repos; that's where Actions gets surprisingly expensive.

If you're running a few side projects and want one place to track them (ideas, launch checklist, revenue), I made a Side Project Tracker Notion template.

More templates and a free Dataview starter pack are at forge.engelailabs.com.

A weekly review for engineers that isn't about tasks

Sub Engel — Fri, 02 Oct 2026 17:09:30 +0000

The classic weekly review (from Getting Things Done) is about tasks and commitments: empty your inboxes, update your lists, look at your calendar. That's useful, and your issue tracker probably covers most of it already.

What it doesn't cover is the stuff developers lose all the time: why you picked that library, what the fix was for that weird timezone bug, which config flag finally made the build work. You solve a problem, move on, and meet it again six months later with no memory of the answer.

This is a review built around that problem. It has two parts: a tiny daily habit and a fixed weekly session, plus an optional monthly skim.

During the week: one line per thing worth remembering

Keep a section in your daily note (or a single running file, if you don't do daily notes) and add one line whenever something happens that you'd be annoyed to rediscover:

a bug that took more than half an hour to understand,
an API or library that didn't behave the way you assumed,
a choice between two approaches,
a command, flag or config you had to look up.

Keep the format dumb so you actually do it:

## Log
- Postgres: ILIKE treats `_` and `%` in user input as wildcards. Escape them before building the pattern. PR #412
- Chose server-side sessions over JWT refresh; token rotation raced across tabs. -> needs decision note
- `git log -S "term"` finds when a string first appeared. Keep forgetting this.

Problem, answer, link if there is one. No tags required, no templates to fill in. If you're adding more than a couple of minutes a day, you're overdoing it.

Friday: 45 minutes, same questions every week

Put it on your calendar. Friday afternoon works for most people because the week is still fresh and it's rarely prime focus time anyway. Open the week's log lines and go through four questions.

1. What happened more than once?

Scan for repeats. Same kind of bug twice, same lookup twice, same review comment on two PRs. A repeat is a signal that a small artifact would pay off:

a snippet you can paste next time,
a checklist (e.g. "things to check when a query gets slow"),
a lint rule or test that stops it happening again,
a line in the project README.

Make the artifact now, while you remember the details. Don't make one for things that only happened once; most of those never come back.

2. What did I decide?

Any line that's really a decision (you picked X over Y and there were trade-offs) gets promoted to its own note with context, options and reasons. It takes ten minutes on Friday and saves the "why on earth did we do this" conversation later. If you link decisions to commits, add the ID to the relevant commits now.

3. What did I have to look up, and should I actually learn it?

Things you looked up once are fine. Things you looked up three times are a gap. Keep a short "learn next" list, and be honest about priority: only put something at the top if it keeps costing you time. A line like this is enough:

## Learn next
- Postgres window functions (hit twice this month writing reports)
- TypeScript conditional types (fought inference on the API client again)

Then actually block time for the top item. An hour of reading the docs properly beats another three rounds of copying from Stack Overflow.

4. What's still open?

Last: anything from the log that's unresolved. A workaround you shipped that needs a real fix, a question you never answered, a follow-up from an incident. Turn each into a task in whatever tracker you use, or delete it if you honestly won't get to it. The point is that nothing unresolved lives only in the log.

The weekly note

The output of all this is one short note per week. A template like this keeps it consistent:

# Week 2026-W39

## Repeats -> artifacts
- ILIKE escaping: added `escapeLike()` helper + test

## Decisions
- [[adr-20260924-session-store]]

## Learn next
- Postgres window functions

## Open -> tasks
- Replace retry workaround in webhook handler (#431)

## One sentence on the week
Mostly auth work; lost a day to the tab race before understanding it.

If a section is empty, leave it empty. Some weeks nothing repeats and you decide nothing interesting. That's fine; the review takes fifteen minutes those weeks.

Once a month: skim, don't audit

On the first Friday of the month, spend an extra twenty minutes reading the last four weekly notes in a row. You're looking for things that only show up at that distance:

the same area of the codebase appearing in "repeats" every week (a refactor candidate),
a "learn next" item that's been sitting at the top for a month (block the time or drop it),
decisions that contradict each other.

Write two or three bullets at the top of the month's first weekly note and move on. No spreadsheets, no scoring yourself.

Why it's built this way

The usual failure mode of review systems is that they're more work than the problems they solve, so they get dropped after a few weeks. This one tries to avoid that:

Capture costs almost nothing. One line, no structure, in a note you already have open.
The weekly session has fixed questions. You're never staring at a blank page.
Every question produces something concrete (a snippet, a decision note, a task) or produces nothing and you move on.
There's no metric to maintain. Tracking "hours saved" by your notes is itself a job, and the numbers are guesses anyway.

Getting started this week

Add a ## Log section to today's daily note (or create log.md).
Add one line every time something annoys you or surprises you.
Put a 45-minute block on Friday and run the four questions.

Skip the monthly skim until you've done four weekly reviews. If you only ever do the Friday part, you're already ahead of where most of us are.

Dev Second Brain, my Obsidian vault for developers, includes a weekly review template, if you'd rather start from one than build it yourself.