---
# Author: retoor <retoor@molodetz.nl>
name: seriousdevelopment
description: Scaffold a new project or upgrade an existing one to seriousdevelopment quality (spec-first docs, ADRs, build track sheet, verification gates, living-docs discipline). Use when starting a greenfield project or when an existing project needs its engineering and documentation bar raised.
---

# Serious Development

One method for building software seriously, whether the project is new or
already exists. The method has three pillars: a canonical spec with zero
open gaps, a decision + tracking system that survives multi-month and
multi-model builds, and mechanical verification after every change.

Skill version: 1.7.1 (history in `CHANGELOG.md`).

## Modes

Ask which mode applies if it is not obvious from the request. Do not run
both modes in one run. (Mode B itself is audit-then-apply; that is one
mode, not mixing.) For partial work, see Scoped runs.

### Mode A: new project

Scaffold the project skeleton, then write the spec before any product
code. Minimum skeleton:

- `SPEC.md` (canonical spec, from `assets/templates/SPEC.md`)
- `BUILD-TRACK.md` (from `assets/templates/BUILD-TRACK.md`)
- `docs/adr/` with `0001` recording why this method was adopted
- `docs/runbooks/` (empty, indexed in the spec runbook list)
- `CHANGELOG.md` (spec + product changes, ascending versions)
- `roadmap/` only once the spec passes 500 lines (milestone split, see
  "Roadmap split" below)
- `AGENTS.md` (or the harness equivalent) in three layers: personal base
  rules, root project rules, nested subsystem files next to the code

Fill the spec top-down: control + changelog, goals/non-goals, scope,
requirements with normative IDs, architecture, data model, API, security,
compliance, ops, estimates, risks, decisions. No product code until the
spec has zero TBDs (see "No open gaps"). Then grade the spec A-F on:
completeness, consistency, testability, estimation honesty, decision
traceability. Fix everything found without deleting or degrading
content, re-run the mechanical checks, and report before/after grades.
Below A- overall, say so and name what is missing.

### Mode B: upgrade an existing project

1. **Audit, read-only.** Inventory: existing docs, rules files, stack,
   tests, CI, versioning, changelog habits. Write nothing yet.
2. **Gap report.** List what is missing against the checklist in
   "Upgrade checklist" below. Grade the project A-F on: spec
   completeness, decision traceability, dev tracking, verification,
   doc freshness, estimation honesty.
3. **Apply, smallest diffs first.** Adopt the missing pieces using the
   templates. Backfill the spec from the code (code wins on facts,
   spec wins on intent; record conflicts, see below).
4. **Upgrade report.** Write `UPGRADE-REPORT.md` (template provided)
   listing applied changes, grades before/after, and every conflict.

### Conflict rule (Mode B, binding)

If the existing project has a rule that clashes with this method, DO
NOT overwrite it. Keep their rule, mention the clash in the upgrade
report (what clashed, why the method prefers its own, what was kept),
and move on. The only exception is a rule that is illegal or
demonstrably destructive: flag it loudly, propose the fix, and still
wait for the human before changing it.

### Scoped runs

Full-mode runs are the default, but partial application is allowed when
the user asks for it: ADRs only, track sheet only, runbooks only. Rules
for scoped runs: run the Mode B audit first (read-only, even for one
piece), record the narrowed scope in the upgrade report, and list what
was deliberately left out so a later run can continue. The conflict
rule still applies.

## The method

### No open gaps

Anything that would normally be "TBD" gets a decided default with
rationale in the decisions section instead. Tracked assumptions are
allowed only with: owner, verify-by date, and a fallback if the
assumption fails. A spec with an untracked open ends the run as
incomplete: say so, do not ship it quietly.

### Normative IDs

Every requirement, rule, and surface gets a stable ID from a family
prefix: FR (functional), SEC (security), BIL (billing), OPS (ops), NFR
(non-functional), UX, PG (pages/surfaces), D (decisions), PIN (stack
pins), A (assumptions), TRK/DOC (tracking/docs). IDs are never reused
once retired. Cross-reference by ID, never by prose paraphrase.

### Caps and floors

Everything unbounded gets a hard cap: rates, sizes, counts, intervals,
memory. Every automated process gets a floor it may never cross on its
own (retention windows, minimum intervals, protected paths); when a
floor is hit, page a human instead of deleting. Prefer static ceilings
to autotuning.

### Safety

Destructive operations are dry-run by default, confirmed explicitly,
and scoped as narrowly as possible. Loud skips beat silent corruption:
reject unverifiable input with a clear reason and a counter. Verify
before you write (checksums, integrity checks, pre-action snapshots).
A delete that does not reclaim is not a delete.

### Proof

Measure, do not theorize: numbers in docs come from runs on real
machines. Test through the real path (real filesystem, real
concurrency, failure injection), not just units around it. After
behavior changes, run the suite. After deploys, verify live.

### Research first, then decide with an opinion

Load-bearing decisions (stack, vendors, money flows, compliance) start
with web research: log the queries, synthesize into the spec with
normative defaults, keep the log in an appendix. Then decide: a clear
rule with stated tradeoffs beats a configurable maybe. Revisit only
with new evidence, filed as a new ADR (never by editing history).

### Decisions and stack pins

Spec-level decisions live in the spec as D-IDs (one line each, with
rationale). Repo-level decisions live as ADRs in `docs/adr/`, one file
per decision (`NNNN-short-title.md`) with a MADR-lite body: Status,
Date, Context, Decision, Consequences, Links. Accepted ADRs are immutable; change
means a new ADR that supersedes. Every D-ID, PIN, or requirement
change needs an ADR number in the PR. Agent prompts MUST cite ADR
constraints, never silently invent new ones. Hedged "X or Y" stack
clauses MUST be pinned to one choice with a PIN-ID before build.

### Estimates

Person-weeks with drivers, ranges not theater: each line names what
drives the cost. Recompute totals on every scope change and state the
consequences honestly (date moves, cost moves). Freeze scope with a
D-ID; new ideas go to a later release unless a launch gate forces
them. If the owner overrules the freeze, re-baseline the freeze the
same day and record the new date and cost. Never absorb scope
silently.

### Changelog and versioning

One changelog table: version, date, change text, strictly ascending.
Every spec change gets a row. Patch = additions/clarifications,
minor = scope or phasing changes, major = breaking contract changes.
Every markdown doc carries a versioned header:
`<!-- doc: file | version | updated -->`. Project prose rules hold
everywhere (for this author: no em-dashes anywhere, code, docs,
comments, commits, chat).

### Single source, synced mirrors

One file is canonical. Split-offs (roadmap, runbooks, API docs) are
mirrors, synced in the SAME commit as the canonical change. Never let
a mirror drift: verify sync mechanically after every edit round.

### Roadmap split

When the spec passes ~500 lines, split a build-order roadmap with a
zero-loss proof: account for every source line mechanically (count
them; declared duplicates counted exactly). Each part gets a header
comment naming source file, source version, and covered sections.
Keep a coverage map (every section, exactly one home) and a build
table (order, file, milestone, weeks, exit criteria).

### Verification gates

Define launch gates per phase (tests green, pentest criticals zero,
restore drill pass, billing zero-diff over N days, docs synced, legal
pack signed). All green or no launch. After every change round, run
the mechanical checks: sync between canonical and mirrors, ID
uniqueness, changelog order, forbidden-pattern scan, and the repo's
own test suite for the touched area. A confident patch you never saw
pass is not done. Sample mechanics (adapt paths to the project):

```sh
# ID uniqueness: must print nothing (no duplicate requirement IDs)
rg -o '[A-Z]{2,3}-[0-9]+' SPEC.md | sort | uniq -d
# changelog order: versions must ascend top to bottom
rg '^\| [0-9]+\.[0-9]+' SPEC.md
# forbidden patterns: project rules, e.g. untracked TBDs, em-dashes (U+2014)
rg -n 'TBD|\u2014' SPEC.md BUILD-TRACK.md docs/
```

### Build tracking (multi-month, multi-model safe)

`BUILD-TRACK.md` at repo root is the single source of build status.
One row per milestone and per gate drill: Milestone, Owner, Status,
Updated, Evidence, Drift. Owner is a human name or
`llm:model/version`. Status enum: NOT-STARTED, IN-PROGRESS, BLOCKED,
IN-REVIEW, DONE. Update triggers, all same-day: any status change,
end of every work session, every gate pass or fail, every merged PR.
Staleness: 7 days without update marks the row STALE (CI fails);
14 days escalates to the owner as BLOCKED. Context passes ONLY
through the track sheet, ADRs, and code, never through chat memory.
LLM output is reviewed by a human or a second model before merge;
billing, auth, and security merges need human sign-off.

### Living docs

Maintain a register: doc, owner, update trigger, max staleness.
Minimum register: canonical spec + mirrors (same commit, 0 days),
track sheet (7 days), ADRs (before merge), runbooks (incident/drill
+ 30 days), API changelog (CI-generated, 0 days), cost book (vendor
price change, same day), risks (monthly + incident), postmortems
(48h after SEV-2+). Same-PR rule: a behavior/API/config/ops change
updates its docs in the SAME PR; reviewers verify docs impact;
maintainers block merges with stale docs on user-facing changes.
Generated docs regenerate in CI; drift fails the build. Quarterly
audit: re-verify the register, delete what stopped being true.

### Craft and ops

Exact, minimal diffs: edit existing files, reuse helpers, one way of
doing anything. Boring technology, dumb backends, smart edges. Docs
state what the system does today, gaps listed next to the code that
will close them. Commit, deploy, verify, in that order, same
session. Schedules live inside the system on a loop (retention,
cleanup, checks) with human-readable states, not silent hope.

### Writing decent software

Shape: one language, one database, server-rendered first, no build
step unless earned. One data root with every path derived in one
config module. Layout mirrors URLs: if you cannot guess the file
from the URL, the layout is wrong.

House stack (defaults when nothing else is picked; override per
project with an ADR, never by drifting):

- Backend: Python + FastAPI, one typed framework. Routers mirror the
  URL tree: flat file per resource (`routers/feed.py`), package per
  sub-resource (`routers/projects/`), each leaf owning an APIRouter,
  the package `__init__` aggregating. One app factory, middleware in
  fixed order (timing outermost, then security headers, rate limit,
  maintenance gate, error handlers).
- Templates: Jinja2 server-side, one shared instance, one `base.html`,
  page CSS/JS in standard blocks, shared partials for repeated UI.
- Frontend: no framework, no build step. Plain ES modules, one class
  per file, small shared utilities. The server renders what exists at
  request time; the client only handles live content, sanitized
  fail-closed.
- Database: SQLite via the `dataset` ORM, WAL mode, busy timeout, one
  embedded file under the data root for small to medium scale.
  Graduate to Postgres only on measured need (write concurrency,
  size, or managed backups), filed as an ADR.
- Tests mirror the tree: `tests/unit`, `tests/api` (live server plus
  temp DB), `tests/e2e` (browser).

One way of everything: one auth resolver, one response helper, one
validation style, one outbound HTTP client (with SSRF guard), one
queue pattern. A second implementation of an existing helper is a
bug, not a choice.

DRY, enforced: no logic in two places. If it appears twice, hoist
it into the one helper, predicate, or constant both callers use.
Single source per fact in code exactly as in docs; copy-paste is
never the answer, not even "just this once".

Consistency, enforced: new code matches the existing code first.
Same helpers, same patterns, same naming, same file shapes; a
reviewer should not be able to tell which lines are new. If the
existing pattern is bad, either fix all usages in the same change
or follow it and file the cleanup (never a third style alongside).
Read before you write, always.

Object-oriented, enforced: model the domain as objects with the
behavior living next to the data it acts on. Small classes with one
job, composition over inheritance, no god objects, no procedural
blobs where an object fits. Python: dataclasses and Pydantic models
for data, service objects for operations. Frontend: one class per
file as the house stack already demands.

Data: opaque IDs, soft delete everywhere with garbage collection
doing the hard deletes, ownership checked by one helper, no N+1
(batch loaders are the only way to load related rows), idempotent
schema init.

Daily loop, eight steps in order, a failed step blocks the rest:
understand (match an existing example or agree the new pattern
first), data, server, view, safety, agent+docs (the most-forgotten
step: tool action, endpoint doc, user doc), document, validate.

Testing: three tiers (unit, HTTP integration on temp DB, browser
E2E), serial runs, full suite green before done, cheapest-first
triage, never narrow a run to pass. For money, state machines, and
read-then-write races add: property checks, stateful fuzzing,
real-process concurrency tests, static analysis on touched files.

Ops: every repeated action is a named command (no tribal one-liners),
DTAP pipeline with CI green before merge, destructive ops dry-run
first and explicitly confirmed, retention CLIs per expirable domain,
production data guarded by written confirmation, deploy then verify
live.

Runtime: every project ships a container, Podman preferred, Docker
accepted. Debian-slim-based image, a compose file for the full stack
(app, db, workers), one command to boot it. No "works on my machine":
CI builds the image, prod runs the image.

Makefile: required and self-sufficient. It assures its own
environment: creates the venv (or pulls images) when missing,
installs pinned deps, then runs every target inside it. Standard
targets: `install`, `dev`, `prod`, `test`, `test-fast`, `lint`,
`clean`, `up`, `down`, `logs`. No target may assume a
hand-prepared machine.

Python packaging: traditional `pyproject.toml` (setuptools or
hatchling, src layout), version as the single source read live by
the app, one console-script binary declared under
`project.scripts` that is THE way to execute the software (no bare
`python app.py` in docs or deploy). Deps pinned, dev extras
separated.

Versioning: one version source read live by the app, patch
auto-bumped per commit, minor/major manual release commits, assets
served immutable under versioned URLs, trunk plus short ticket
branches plus a production promotion target, annotated tags and one
changelog for releases. Every markdown doc versioned: header
comment plus history table, bumped in the same commit as the
content change.

Agent docs: three layers (personal base, root project rules under
~500 lines, nested subsystem files next to the code). Every
statement marked hard rule, convention, or guidance, each with a
named enforcer (test path, hook, review gate). A rule without an
enforcer is a wish: the quarterly audit deletes one. Docs update in
the same change as the code, state today with no fiction, and die
with the feature they describe.

Logging: stdlib `logging` configured once via `dictConfig` in one
module, `getLogger(__name__)` per module. Debug log by default:
DEBUG goes to a rotating debug file, INFO+ to the console, levels
tunable via env. Rotation is mandatory, never unbounded:
RotatingFileHandler for the app log (10 MB x 5), timed rotation
for debug/audit (midnight, keep 7-14), plus a total cap on the log
directory (default 500 MB) enforced by a prune check. Format: UTC
ISO timestamp, level, logger, message; JSONL only when a shipper
consumes it. QueueHandler for threaded workers; lazy %-formatting
and level guards in hot paths. Never log secrets or PII (token
fingerprints, redaction as backstop); bare except without logging
is forbidden. Files first; stdout only for container runtimes.

Backups: 3-2-1 minimum (3 copies, 2 media, 1 off-site at a
different provider/location, not the same DC). Anything holding
money or PII gets 3-2-1-1-0 (one immutable copy, zero-error
verified restores). Default tool restic (or Borg): encrypted,
automated on schedule, calendar retention (7 daily, 4 weekly,
6 monthly), prune wired to the same tool. RPO/RTO stated per
domain and measured, not assumed. Test restores monthly into an
empty directory (quarterly minimum); an untested backup fails the
ops gate, and a missing scheduled run pages like any other alarm.
Named commands (`backup-run`, `backup-verify`, `backup-prune`),
keys backed up separately from the data they unlock.

Secrets are human-only. AI MUST never print, copy, transmit, modify,
rotate, or delete secret values (passwords, tokens, keys, connection
strings), and MUST never commit them. Referencing an env var NAME to
wire config is fine; its VALUE stays unread and unmoved. Servers are
closed from outside by default; secret storage and rotation are the
owner's task. If a secret is missing, expired, or appears where it
should not (logs, diffs, chat), stop and page the human. No
workarounds, ever.

Dependencies: fewest possible. Stdlib first, one well-chosen library
per need, no new dependency without an ADR entry justifying it (what,
why not stdlib, license, maintenance status). Pinned versions,
automated audit on schedule, CVE fix-or-remove with a deadline. Each
release, remove one dependency nobody can justify.

Environments: DTAP, usually on one platform. Dev, test, accept, and
prod coexist without colliding: separate database, data dir, ports,
and env-prefixed resource names per environment; no shared state
between test and prod, ever. Test data is marked and isolated;
production data never flows into test. Accept mirrors prod (same
images, same flags). Promotion is deliberate: merge, deploy, verify
live.

Incidents: every alert names an owner and a runbook; unowned alerts
are forbidden. On-call rotation with a human reachable; agents hold
and page instead of improvising past a floor. SEV-2+ gets a
postmortem within 48h (template provided). Customer-visible incidents
update the status page in the same hour; an incident is not closed
until comms, fix, and action items all landed.

Minimum CI: lint touched files, serial full suite, doc-header check
(every `.md` carries a version line), generated-docs drift check,
dependency audit. All green before merge, no exceptions.

Migrations: every schema change ships with its rollback, reviewed
together. Expand before contract (additive first, removal later);
destructive migrations need a snapshot plus a rehearsed restore.
Never edit a migration that already ran in prod; write a new one.

## Checklists

### New project

- [ ] Skeleton files exist from templates
- [ ] Spec: zero untracked opens, IDs on everything, changelog started
- [ ] Stack pins: no "X or Y" clauses remain
- [ ] Engineering shape chosen: layout, data conventions, test tiers, commands
- [ ] Logging + backups: rotation caps set, 3-2-1 scheduled, restore drill dated
- [ ] DTAP coexistence verified: separate state per env, no test/prod sharing
- [ ] Incident loop defined: alert owners, on-call, status page, postmortem rule
- [ ] Assumptions have owner + verify date + fallback
- [ ] Estimates have drivers; scope freeze D-ID recorded
- [ ] Gates defined per phase; first gate (spec review) passed
- [ ] Spec graded A-F and fixed to A- or better, grades reported
- [ ] BUILD-TRACK.md has one row per milestone, all NOT-STARTED
- [ ] ADR 0001 records method adoption

### Upgrade existing project

- [ ] Read-only audit complete, nothing written yet
- [ ] Gap report with A-F grades on the six axes
- [ ] Missing pieces applied, smallest diffs first
- [ ] Conflicts kept-as-is and recorded (never overwritten)
- [ ] UPGRADE-REPORT.md written with before/after grades
- [ ] Mechanical checks pass (sync, IDs, changelog, tests)

## Red flags (stop and say so)

- A change that cannot name its spec ID or ADR.
- Scope absorbed without re-baselining date and cost.
- A mirror edited without its canonical source (or vice versa).
- Docs updated "later" instead of in the same PR.
- A gate waved through red, or narrowed to pass.
- An agent inventing a new queue, cache, or retry policy the ADRs
  never approved.
- AI touching secret values (print, copy, change, delete), or working
  around a missing secret instead of paging the human.
- Test and prod sharing state, or prod data flowing into test.
- A migration with no rollback, or an edit to one that already ran.

## Templates

In `assets/templates/`: `SPEC.md` (spec skeleton), `BUILD-TRACK.md`,
`ADR.md`, `RUNBOOK.md`, `POSTMORTEM.md`, `UPGRADE-REPORT.md`
(Mode B report with conflicts table), `CHANGELOG.md`, `AGENTS.md`
(root rules file, three-layer header). Copy, never link: the target
project owns its copies from day one.
