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
| TITLE | REV | DRAWN | SHEET |
|---|---|---|---|
| Seriousdevelopment skill | 1.7.1 | retoor <retoor@molodetz.nl> | 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.
A change that cannot name its spec ID or ADR.
HALTScope absorbed without re-baselining date and cost.
HALTA mirror edited without its canonical source, or the reverse.
DRIFTDocs updated later instead of in the same PR.
DRIFTA gate waved through red, or narrowed to pass.
HALTAn agent inventing policy the ADRs never approved.
HALTTest and prod sharing state, or prod data flowing into test.
HALTA migration with no rollback, or an edit to one that already ran.
HALTThree 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.
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.
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.
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.
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.
- 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.
- Write the spec before any product codeTop-down: control, goals, scope, normative requirements, architecture, data, API, security, ops, estimates, risks, decisions.
- Close every gapNo product code until zero untracked opens. Every X-or-Y stack clause resolves to one pinned choice with a PIN-ID.
- 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.
- Audit, read-onlyInventory docs, rules, stack, tests, CI, versioning, changelog habits. Nothing is written yet.
- Gap reportGrade A to F on spec completeness, decision traceability, dev tracking, verification, doc freshness, estimation honesty.
- Apply, smallest diffs firstAdopt the missing pieces from the templates. Backfill the spec from the code: code wins on facts, spec wins on intent.
- Upgrade reportUPGRADE-REPORT.md with applied changes, grades before and after, and every conflict.
If an existing project rule clashes with the method, the skill keeps their rule and records the clash in the upgrade report. The only exception is a rule that is illegal or demonstrably destructive, which is flagged loudly and left for the human.
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.
| ID | STANDING ORDER | ENFORCER |
|---|---|---|
| SO-01 | Patch 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-02 | Static assets serve immutable under versioned URLs.A release never changes bytes under a live URL; new bytes get a new version. | review gate |
| SO-03 | DRY: 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-04 | New code matches existing code.Same helpers, patterns, names, file shapes. A reviewer should not tell which lines are new. | review gate |
| SO-05 | The 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-06 | Python 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-07 | Frontend is plain ES modules, one class per file.No framework, no build step. This page is built exactly that way. | structure check |
| SO-08 | No new dependency without an ADR entry.What, why not stdlib, license, maintenance status. Each release removes one dependency nobody can justify. | dependency audit |
| SO-09 | Every 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-10 | The 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-11 | Secrets 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-12 | Docs 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-13 | Logs rotate under a hard cap.Debug by default, rotation mandatory, never unbounded, never secrets or PII. | config check |
| SO-14 | Backups 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 |
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
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 --strictpress run: 5 checks, one verdict
BUILD TRACK / STALENESS RULE
| MILESTONE | OWNER | STATUS | DRIFT |
|---|---|---|---|
| M1 | Spec intakellm: model/2026-10 | IN-PROGRESS | fresh |
session history, newest first
REPORT CARD / SIX AXES
| AXIS | MODE B BEFORE | MODE B AFTER |
|---|---|---|
| G-01 | Spec completeness | C to A |
| G-02 | Decision traceability | D to A- |
| G-03 | Dev tracking | F to A |
| G-04 | Verification | C+ to A- |
| G-05 | Doc freshness | D to A |
| G-06 | Estimation honesty | C to A- |
A run below A- overall says so and names what is missing. Grades are reported before and after, every time.
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.