SERIOUSDEVELOPMENT / SKILL 1.7.1

SKILL BRIEF 001 / ENGINEERING METHOD

Software that survives its own authors.

Seriousdevelopment is a working method for AI-assisted engineering. It scaffolds new projects and upgrades existing ones to the same bar: a canonical spec with zero open gaps, decisions on record, and mechanical verification after every change.

MODES
2
TEMPLATES
8
OPEN GAPS
0
EXT. DEPS
0
Engineering drawing sheet for the seriousdevelopment method, stamped with minimum grade A minus
FIG. 00 / METHOD DRAWINGSCALE 1:1
TITLEREVDRAWNSHEET
Seriousdevelopment skill1.7.1retoor <retoor@molodetz.nl>01 / 01
01

Failure lives in the gaps.

Most projects do not fail at launch. They fail in the unnamed space between decisions: the TBD that ships, the choice that lives only in chat memory, the mirror that drifts from its source. The method treats each finding below as a stop condition, not a style preference.

RF-01

A change that cannot name its spec ID or ADR.

HALT
RF-02

Scope absorbed without re-baselining date and cost.

HALT
RF-03

A mirror edited without its canonical source, or the reverse.

DRIFT
RF-04

Docs updated later instead of in the same PR.

DRIFT
RF-05

A gate waved through red, or narrowed to pass.

HALT
RF-06

An agent inventing policy the ADRs never approved.

HALT
RF-07

Test and prod sharing state, or prod data flowing into test.

HALT
RF-08

A migration with no rollback, or an edit to one that already ran.

HALT
02

Three pillars, no exceptions.

One method for greenfield and legacy alike. The pillars reinforce each other: the spec gives verification something to check, and the record gives the future something to trust.

P-01

Canonical spec, zero open gaps

Anything that would be TBD becomes a decided default with rationale, or a tracked assumption with an owner, a verify-by date, and a fallback. A spec with an untracked open ends the run incomplete, stated plainly.

P-02

Decisions and tracking that survive months and model swaps

Spec decisions carry D-IDs. Repo decisions live as immutable ADRs. BUILD-TRACK.md is the single source of build status. Context passes only through the sheet, the ADRs, and the code, never through chat memory.

P-03

Mechanical verification after every change

Sync between canonical and mirrors, ID uniqueness, changelog order, forbidden-pattern scan, and the repo suite for the touched area. All green or no launch. A confident patch you never saw pass is not done.

03

Two modes of operation.

The skill asks which mode applies when the request does not say. It never runs both in one run. Partial runs are allowed when asked, with the audit first and the omissions on record.

  1. Scaffold the skeletonSPEC.md, BUILD-TRACK.md, CHANGELOG.md, AGENTS.md, docs/adr with 0001, docs/runbooks. The roadmap waits until the spec passes 500 lines.
  2. Write the spec before any product codeTop-down: control, goals, scope, normative requirements, architecture, data, API, security, ops, estimates, risks, decisions.
  3. Close every gapNo product code until zero untracked opens. Every X-or-Y stack clause resolves to one pinned choice with a PIN-ID.
  4. Grade and fixSelf-grade A to F on completeness, consistency, testability, estimation honesty, traceability. Fix everything found without deleting content, re-run the checks, report before and after.
04

Standing orders.

What the method enforces on its own, on every project, without being asked twice. Each order names its enforcer: a rule without one is a wish.

IDSTANDING ORDERENFORCER
SO-01Patch version auto-bumps per commit; minor and major ship as manual release commits.One changelog, strictly ascending. Every markdown doc carries a version header, bumped in the same commit as its content.changelog order check
SO-02Static assets serve immutable under versioned URLs.A release never changes bytes under a live URL; new bytes get a new version.review gate
SO-03DRY: logic that appears twice hoists into the one helper both callers use.Single source per fact in code exactly as in docs. Copy-paste is never the answer.review gate
SO-04New code matches existing code.Same helpers, patterns, names, file shapes. A reviewer should not tell which lines are new.review gate
SO-05The domain is modeled as objects.Behavior lives next to the data it acts on. Small classes, one job each, composition over inheritance.review gate
SO-06Python and FastAPI by default; any deviation needs an ADR, never drift.House stack holds until a recorded decision with rationale replaces it.PIN check
SO-07Frontend is plain ES modules, one class per file.No framework, no build step. This page is built exactly that way.structure check
SO-08No new dependency without an ADR entry.What, why not stdlib, license, maintenance status. Each release removes one dependency nobody can justify.dependency audit
SO-09Every project ships a container plus a compose file for the full stack.Podman preferred, Docker accepted, Debian-slim base. CI builds the image; prod runs the image.CI image build
SO-10The Makefile assures its own environment.Creates the venv or pulls images when missing, installs pinned deps, then runs every target inside it. No hand-prepared machine assumed.clean-machine run
SO-11Secrets are human-only.The agent never prints, copies, or moves secret values, and pages the human instead of working around a missing one.secret scan
SO-12Docs update in the same PR as the behavior change.Mirrors sync in the same commit as the canonical source. Drift fails the build.drift check
SO-13Logs rotate under a hard cap.Debug by default, rotation mandatory, never unbounded, never secrets or PII.config check
SO-14Backups follow 3-2-1 with tested restores.An untested backup fails the ops gate. A missing scheduled run pages like any other alarm.restore drill
05

What lands in the repo.

Mode A scaffolds the skeleton before a line of product code exists. Left: this skill package. Right: a new project under the method.

THE SKILL PACKAGE

seriousdevelopment/
  SKILL.md            method, modes, checklists
  CHANGELOG.md        skill history, ascending
  index.html          this brief
  assets/
    templates/        copied, never linked
      SPEC.md         spec skeleton
      BUILD-TRACK.md  status sheet
      ADR.md          decision record
      RUNBOOK.md      ops procedure
      POSTMORTEM.md   48h after SEV-2+
      UPGRADE-REPORT  Mode B report
      CHANGELOG.md    product history
      AGENTS.md       root rules file
    css/ js/ img/     this page, no build

MODE A OUTPUT

acme/
  SPEC.md             canonical, zero TBDs
  BUILD-TRACK.md      single source of status
  CHANGELOG.md        product history
  AGENTS.md           root rules, 3 layers
  Makefile            self-sufficient env
  compose.yaml        full stack, one cmd
  Containerfile       Debian-slim
  pyproject.toml      console binary
  docs/adr/
    0001-method.md    why this method
  docs/runbooks/      indexed in spec
  roadmap/            past 500 spec lines
  src/acme/routers/   mirrors URL tree
  tests/unit api e2e  mirrored tiers
06

Proof, not promises.

Verification is mechanical and runs after every change round. Below: the shape of the gate run, and the staleness rule that keeps the track sheet honest. Both are live.

LAUNCH GATES / MECHANICAL CHECKS

$ gates --all --strict
press run: 5 checks, one verdict

BUILD TRACK / STALENESS RULE

DAY 0
MILESTONEOWNERSTATUSDRIFT
M1Spec intakellm: model/2026-10IN-PROGRESSfresh
session history, newest first

REPORT CARD / SIX AXES

AXISMODE B BEFOREMODE B AFTER
G-01Spec completenessC to A
G-02Decision traceabilityD to A-
G-03Dev trackingF to A
G-04VerificationC+ to A-
G-05Doc freshnessD to A
G-06Estimation honestyC to A-

A run below A- overall says so and names what is missing. Grades are reported before and after, every time.

07

A house stack with opinions.

Defaults when nothing else is picked. Override per project with an ADR, never by drifting.

BACKEND
Python and FastAPI, one typed framework. Routers mirror the URL tree, one app factory, middleware in fixed order.
TEMPLATES
Jinja2 server-side. One shared instance, one base.html, shared partials for repeated UI.
FRONTEND
Plain ES modules, one class per file. The server renders; the client only handles live content, sanitized fail-closed.
DATABASE
SQLite via the dataset ORM, WAL mode, one embedded file. Postgres only on measured need, filed as an ADR.
TESTS
Three tiers mirroring the tree: unit, HTTP integration on a temp DB, browser E2E. Serial, full suite green before done.
RUNTIME
One container per project, Podman preferred, Debian-slim. CI builds the image; prod runs the image.
PACKAGING
Traditional pyproject.toml, src layout, one console-script binary. The binary is the way to run the software.
PIPELINE
DTAP on one platform, separate state per env. Merge, deploy, verify live.