DEV Community: Sub Engel

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.

Dataview queries I'd put in any developer vault (and the gotchas that break them)

Sub Engel — Thu, 01 Oct 2026 17:30:15 +0000

A few days ago I posted Dataview queries worth having in a developer vault. The comments were better than the post. They pointed out three things that quietly break these queries.

This is the follow-up. Different queries, and the fixes baked in.

Same disclaimer as last time: Dataview only reads the Markdown notes in your vault. It doesn't read your code. It's for the notes about your code.

The three gotchas first

Cancelled tasks count as open. Dataview only treats [x] as completed. So !completed also matches [-], which is how the Tasks plugin (and many themes) mark cancelled tasks. Add status != "-". status is the character between the brackets.

While you're there, add text != "". Templates leave empty checkboxes behind, and they show up as open tasks too.

Sync bumps file.mtime. file.mtime is the time on disk. Obsidian Sync, iCloud and Syncthing can change it when they write a note to another device. So "recently modified" fills up with notes you didn't touch. The fix is a modified: field in frontmatter, with file.mtime as a fallback.

Orphan lists fill up with templates. Templates, daily notes and dashboards are unlinked on purpose. If you leave them in, the real orphans get buried. Excluding folders by name works until you rename a folder. A frontmatter flag doesn't have that problem.

Now the queries. Folder names are mine (Projects, Templates). Change the text after FROM to match yours.

1. Open tasks across the whole vault

Every unchecked task outside the templates folder, grouped by note. No fields needed, just checkboxes.

TASK
FROM -"Templates"
WHERE !completed AND status != "-" AND text != ""
GROUP BY file.link

That's all three task filters in one line.

2. Recently modified notes, sync-safe

Notes edited in the last 7 days, newest first.

TABLE file.folder AS "Folder", default(modified, file.mtime) AS "Modified"
FROM -"Templates"
WHERE default(modified, file.mtime) >= date(today) - dur(7 days) AND file.path != this.file.path
SORT min(default(modified, file.mtime), date(now) - dur(5 minutes)) DESC, file.name ASC

Two things going on here.

default(modified, file.mtime) uses your modified: field when a note has one. Older notes fall back to the file time.

The min(...) in the sort is a grace window. Anything edited in the last 5 minutes sorts as "5 minutes ago". So when a sync lands mid-read, the list doesn't reshuffle under you. (That idea came from a commenter on the last post.)

To fill modified: automatically, the Linter plugin's "YAML timestamp" rule works. Set the key to modified, the format to YYYY-MM-DDTHH:mm:ss, and "Date modified source of truth" to "user or Linter edits". The default source copies the file time, which is the thing sync bumps.

3. Orphan notes, with an opt-out flag

Notes nothing links to, newest first.

LIST
FROM -"Templates"
WHERE length(file.inlinks) = 0 AND exclude-from-orphans != true
SORT file.ctime DESC

Put exclude-from-orphans: true in the frontmatter of anything that's unlinked on purpose. Daily notes, dashboards, the note holding this query. Put it in your daily note template once and you're done.

Note this only checks inlinks. A note that links out but nothing links to is still hard to find again. That's the one I want to see.

4. Stale projects

Projects still marked active that nobody has touched in 30 days, oldest first.

TABLE default(modified, file.mtime) AS "Last edited", length(filter(file.tasks, (t) => !t.completed AND t.status != "-" AND t.text != "")) AS "Open tasks"
FROM "Projects"
WHERE type = "project" AND status = "active" AND default(modified, file.mtime) < date(today) - dur(30 days)
SORT default(modified, file.mtime) ASC

Expects type: project and status: active in frontmatter. Same modified: fallback as above, otherwise a sync makes every project look fresh.

The open task count comes from the checkboxes in the note. No counter field to keep in sync by hand.

When something shows up here, either pick it back up or change its status. "Active" should mean active.

If a query shows nothing

Dates in frontmatter need to be plain ISO (2026-09-27). Sept 27 is just text, and date comparisons silently return nothing.
Field names get normalized. Due Date becomes due-date.
Strip the query down to LIST FROM "Folder" and add clauses back one at a time. Usually it's the folder name.

The rest

I put all 10 in one note: these four, plus unfinished tasks from recent daily notes, an ADR log, ADRs due for review, active projects with open task counts, incident follow-ups and a tech debt register. Each one says what it shows and which fields it expects. It's free (pay what you want): https://subengel.gumroad.com/l/dzanl

If you'd rather start from a whole vault with the templates and dashboards already set up, that's Dev Second Brain.

An Obsidian + Git workflow for solo developers

Sub Engel — Tue, 29 Sep 2026 17:16:47 +0000

If you write code alone, your project knowledge is scattered in a predictable way: the code and its history live in git, and the reasons live in your head, a notes app, or nowhere. Putting your Obsidian vault under git doesn't solve that by itself, but it gets your notes into the same kind of history as your code: dated, diffable, and searchable with tools you already use.

This is the setup I'd recommend if you're starting from scratch.

Why git and not just a sync service

Obsidian Sync, iCloud, Dropbox and friends are good at one thing: making the same files show up on every device. Some keep version history too. What they don't give you:

Messages. A sync service knows a file changed at 14:02. It doesn't know you changed it because the retry logic was rewritten.
History you can query. git log -- notes/payments.md, git log -S "rate limit", git blame. Your notes get the same archaeology tools as your code.
One place for code and docs, if you choose to keep them in the same repo.

You can use both. A common pattern is Obsidian Sync for moving files between devices and git on one desktop as backup and history. The plugin docs cover this: you can disable the plugin on other devices, and set the pull merge strategy to "Other sync service" so git doesn't fight Sync over your files. Test any combination on a copy of the vault first.

Step 1: Put the vault in a repo

cd ~/vaults/dev-notes
git init
git branch -M main

Now the one decision that matters: what to do with .obsidian/. That folder holds your settings, installed plugins and hotkeys, plus some files that change constantly (open panes, recent files). Ignoring the whole folder is common advice, but it means a fresh clone opens with no plugins and default settings. I'd ignore only the noisy parts:

# Obsidian: per-device UI state
.obsidian/workspace.json
.obsidian/workspace-mobile.json

# Trash and OS junk
.trash/
.DS_Store

Two exceptions worth checking. Some plugins store API keys or tokens in their data.json under .obsidian/plugins/; ignore those plugin folders if the repo could ever be seen by anyone else. And if a file you didn't expect shows up in every commit, it probably belongs in .gitignore (remember to git rm --cached it, since ignoring an already-committed file does nothing).

Step 2: Add a remote

A private repo on GitHub, GitLab, Codeberg, or a self-hosted Gitea all work. Private repos are free on GitHub's free plan.

git remote add origin git@github.com:you/dev-notes.git
git add .
git commit -m "init: vault baseline"
git push -u origin main

Even solo, a remote is worth it: it's your off-machine backup, and it's how a second computer gets the vault.

One warning: don't put secrets in notes. It's easy to paste an API key into a debugging note. Once it's committed and pushed, it's in the history for good (rotating the key is the fix, not deleting the note).

Step 3: Install Obsidian Git

The community plugin Obsidian Git handles commits, pulls and pushes from inside Obsidian. After installing and enabling it:

Auto commit-and-sync interval: 10-15 minutes is a reasonable start. This commits any changes, pulls, and pushes.
Pull on startup: on. This is what saves you when you switch machines.
Commit message: the default is vault backup: {{date}}. Fine for automatic commits.

The plugin also has a source control view (stage, diff, commit) and a history view, so you rarely need the terminal. Its mobile support is marked experimental in the README, so don't make your phone a critical part of this.

Step 4: Two kinds of commits

Auto-commits are your safety net. They're noisy by design, and that's fine: nobody reads vault backup: 2026-09-27 14:10.

The commits worth writing by hand are the ones that capture why. When you change a note because something real happened (a decision, an incident, a surprising bug), commit it yourself with a message:

docs(auth): record why sessions moved from JWT to Redis

Refresh-token rotation kept breaking on multiple tabs.
See decisions/2026-09-auth-sessions.md

A loose convention like docs(area): ... for notes and your usual style for code is enough. The payoff comes months later:

# Everything that ever touched the auth notes, with messages
git log --oneline -- notes/auth/

# When did "idempotency key" first appear anywhere in the vault?
git log -S "idempotency key" --oneline

Don't bother rewriting history to squash auto-commits. Force-pushing main to make the log look tidy is risky once a second machine is pulling from it, and git log --grep/-S/-- path already let you ignore the noise.

Same repo as the code, or separate?

Separate vault repo works best when your notes span several projects, which for most solo developers they do. It also keeps notes out of any repo you might later open-source.

A docs/ or notes/ folder inside the project repo works when the notes are strictly about that one codebase. The upside is that a code change and its explanation can land in the same commit or PR, and git log shows them interleaved. You can still open that folder as its own Obsidian vault.

If you go with the same repo, keep the commits separate even when they're close in time:

git commit -m "refactor(api): split router into modules" -- src/
git commit -m "docs(api): note why routers are split by domain" -- notes/

That keeps git log -- src/ clean for code review and git log -- notes/ readable as a record of decisions.

When things go wrong

Merge conflicts. If you edit the same note on two machines between syncs, you'll get a normal git conflict with markers in the file. Resolve it like code. Pulling on startup and a short auto-sync interval make this rare.
Huge repo. Images and PDFs add up. Put attachments in one folder and consider Git LFS or keeping large files out of the vault.
Plugin stops syncing. Check the plugin's notices, then run git status in a terminal. Nine times out of ten it's an auth problem with the remote or a conflict that needs resolving.

What you end up with

A vault that's backed up off-machine without thinking about it, readable on any computer with a clone, and a history where the important changes have a sentence explaining them. It's not fancy. The value shows up the first time you need to know when and why you changed your mind about something, and git log just tells you.

P.S. If your vault also runs on Dataview, I put 10 ready-to-paste queries for a developer vault in one free note (pay what you want): https://subengel.gumroad.com/l/dzanl

Dataview queries worth having in a developer vault

Sub Engel — Mon, 28 Sep 2026 00:43:59 +0000

Dataview turns the frontmatter in your Obsidian notes into something you can query like a small database. For a developer vault, that means you can keep debt, decisions, incidents and review notes as plain Markdown files and still get live dashboards out of them.

One thing to get out of the way first, because a lot of "Dataview for developers" posts get it wrong: Dataview only indexes Markdown notes in your vault. It doesn't read .ts files, it doesn't parse imports, and there is no file.contents field to grep through. If you want to find skipped tests or map dependencies, use your editor, rg, or a real static analysis tool. Dataview is for the notes about your code.

This post assumes you know the basics (TABLE, LIST, TASK, FROM, WHERE). If not, the official docs are short and good.

1. Tech debt register, sorted by priority

Give each debt item its own note in a debt/ folder:

---
type: debt
area: auth
priority: 2        # 1 = fix now ... 4 = someday
status: open       # open | in-progress | resolved
created: 2026-09-14
estimate_hours: 6
---

Then:

```dataview
TABLE area, priority, estimate_hours AS "Est. h", created
FROM "debt"
WHERE status != "resolved"
SORT priority ASC, created ASC
```

Use a number for priority. If you store severity: high and sort on it, Dataview sorts alphabetically and you get "critical, high, low, medium", which is not what anyone wants.

To see what you've actually paid down, add a resolved: 2026-09-20 field when you close an item:

```dataview
TABLE area, resolved, resolved - created AS "Took"
FROM "debt"
WHERE resolved
SORT resolved DESC
LIMIT 10
```

Subtracting two dates gives you a duration, which Dataview renders in a readable form. That only works if both fields are real dates, so write them as plain ISO dates (created: 2026-09-14). A quoted date in an inline field (created:: "2026-09-14") stays a string, and so does anything not in ISO form; resolved - created then silently renders nothing. If a field comes through as text, wrap it in the query: date(resolved) - date(created).

2. ADRs that are due for a second look

Architecture decision records go stale quietly. The decision was right at the time; the constraints moved. A reviewed date in the frontmatter lets you surface old ones:

---
type: adr
status: accepted   # proposed | accepted | superseded | rejected
decided: 2025-06-02
reviewed: 2025-06-02
superseded_by:
---

```dataview
TABLE decided, reviewed, choice(reviewed < date(today) - dur(1 year), "revisit", "ok") AS "Freshness"
FROM "decisions"
WHERE status = "accepted"
SORT reviewed ASC
```

choice(condition, ifTrue, ifFalse) takes exactly three arguments. If you want three buckets, nest it:

choice(reviewed < date(today) - dur(1 year), "revisit",
  choice(reviewed < date(today) - dur(6 months), "soon", "ok"))

"Revisit" doesn't mean "wrong". It means "read this again and bump reviewed if it still holds."

3. Incidents with open follow-ups

Incidents get written up; the action items are what get forgotten. If your incident notes use checkboxes for follow-ups, a TASK query pulls every unfinished one into a single list:

```dataview
TASK
FROM "incidents"
WHERE !completed AND status != "-"
GROUP BY file.link
```

And a table view for the incidents themselves:

```dataview
TABLE severity, service, occurred, length(filter(file.tasks, (t) => !t.completed AND t.status != "-")) AS "Open items"
FROM "incidents"
WHERE length(filter(file.tasks, (t) => !t.completed AND t.status != "-")) > 0
SORT occurred DESC
```

No manual action_items_pending: 3 field to keep in sync. The count comes from the checkboxes.

Why status != "-": Dataview only counts [x] as completed, so !completed on its own also matches cancelled tasks. The Tasks plugin (and many themes) mark those [-], and status is the character between the brackets. If you use a different character for cancelled, swap it in.

4. PR reviews still waiting on something

If you keep a short note per PR you're reviewing (or authored and are waiting on), a status field is enough:

---
type: pr
repo: api
pr: 1234
status: waiting    # waiting | changes-requested | approved | merged
opened: 2026-09-18
---

```dataview
TABLE repo, pr, status, opened
FROM "reviews"
WHERE status = "waiting" OR status = "changes-requested"
SORT opened ASC
```

Want to flag the old ones? Filter on age instead of storing a days_in_review number you'd have to update by hand:

WHERE status = "waiting" AND opened < date(today) - dur(3 days)

5. Unfinished tasks from recent daily notes

This is the one I'd keep open most often. If your daily notes have a date in the filename (2026-09-27.md), Dataview exposes it as file.day:

```dataview
TASK
FROM "daily"
WHERE !completed AND status != "-" AND file.day >= date(today) - dur(14 days)
GROUP BY file.link
SORT file.day DESC
```

Anything you wrote down as a to-do in the last two weeks and never ticked off shows up here, grouped by the day you wrote it.

6. Orphan notes

Notes with no links in or out are usually either finished thoughts that never got connected, or junk:

```dataview
LIST
FROM "" AND -"90 Templates"
WHERE length(file.inlinks) = 0 AND length(file.outlinks) = 0 AND exclude-from-orphans != true
SORT file.mtime ASC
```

Template files and daily notes are usually unlinked on purpose. Prefer an exclude-from-orphans: true frontmatter flag over hardcoding folder names: a rename in the vault can't silently reintroduce them. Put the flag on dailies, weeklies, dashboards and scratchpads; keep the Templates folder out of the query by path (anything in a template's properties gets copied into notes made from it).

I'd run this during a weekly review, not keep it on a dashboard. Either link them to something or delete them.

7. What changed this week

Useful for writing a weekly summary or standup notes:

```dataview
TABLE file.folder AS "Folder", file.mtime AS "Modified"
FROM ""
WHERE file.mtime >= date(today) - dur(7 days)
SORT file.mtime DESC
```

One catch: file.mtime is the file's modification time on disk, and sync tools (Obsidian Sync, iCloud, Syncthing) can bump it when they write a note to another device. After a sync, this list can fill up with notes you didn't touch. If that happens, stamp a modified: field in the frontmatter and query that instead, falling back to file.mtime for notes that don't have it yet:

```dataview
TABLE file.folder AS "Folder", default(modified, file.mtime) AS "Modified"
FROM ""
WHERE default(modified, file.mtime) >= date(today) - dur(7 days)
SORT default(modified, file.mtime) DESC
```

The Linter plugin's "YAML timestamp" rule can write the field for you, or you can use a Templater hook. With Linter, set the modified key to modified, the format to YYYY-MM-DDTHH:mm:ss (the default format isn't one Dataview reads as a date), and "Date modified source of truth" to "user or Linter edits" (the default copies the file system time, which is the thing sync bumps).

On a synced vault, add a short grace window so mid-sync touches don't reorder everything by a few seconds. Cap recent edits to a floor age (for example five minutes) before sorting:

```dataview
TABLE file.folder AS "Folder", default(modified, file.mtime) AS "Modified"
FROM ""
WHERE default(modified, file.mtime) >= date(today) - dur(7 days)
SORT (date(now) - default(modified, file.mtime) < dur(5 minutes) ? dur(5 minutes) : (date(now) - default(modified, file.mtime))) ASC, file.name ASC
```

Notes touched inside the window sit together at the top; change dur(5 minutes) if you want a wider or tighter floor.

Things that trip people up

Dates must look like dates. Frontmatter values like 2026-09-27 are parsed as dates. Sept 27 is just text and date comparisons silently return nothing. Quoted dates in inline fields (due:: "2026-09-27") are text too: leave the quotes off, or wrap the field in date() in the query.
Field names are normalized. A field called Due Date becomes due-date in queries. Lowercase, no spaces saves you some confusion.
Test FROM first. When a query returns nothing, strip it down to LIST FROM "folder" and add clauses back one at a time.
Narrow FROM in big vaults. FROM "" scans everything. Pointing at a folder or tag keeps dashboards snappy.
Keep conventions written down. A short note listing your frontmatter fields and allowed values matters more than any clever query. Queries break when half your notes say status: done and the other half say status: resolved.

Where to start

Don't build all of this at once. Pick the one query that answers a question you actually ask every week (for most people that's #5 or #1), add the frontmatter to new notes going forward, and let the dashboard fill up. Backfilling old notes is rarely worth it.

Thanks to @contentclips_st on dev.to for the sync, date, cancelled-task, orphan-flag and grace-window fixes.

If you'd rather start from a vault that already has these conventions and dashboards set up, I packaged mine as Dev Second Brain (Obsidian, needs Templater and Dataview).