Process-as-Code

Operational processes, specified like software: versioned in git, cited to code, and able to prove they still work.

By Jennifer Morse. Companion project: Praxis (source-traceable agent memory). MIT licensed — take it, use it, adapt it.

---

The problem

When code breaks, teams reach for the spec of how it was supposed to work — and find nothing. The process lives in a stale wiki page, a departed teammate's head, or a slide deck from two reorgs ago. Escalation and incident teams feel this hardest: they sit at the exact point where intended behavior and actual behavior diverge, with no artifact describing the intent.

Meanwhile every "AI-native" initiative wants to point retrieval (RAG) at company knowledge. Retrieval over stale, contradictory, unowned documents produces confident garbage — the corpus is the ceiling on the assistant. Wikis rot because nothing makes them prove themselves.

The mechanism

Treat each operational process as a spec file in git, with five properties ordinary documentation never has:

1. Versioned & reviewed — process changes are pull requests: diffed, approved, historied. A recommendation to another team is a PR against their process spec, not a slide deck. PRs get accepted or rejected explicitly; decks just evaporate.
2. Cited to code — every step in the flow references the implementing repo/file:line. Intent and implementation are linked, so when either changes, the drift is findable.
3. Verifiable — each spec ends with a runnable verification recipe: the exact commands/queries that prove the process works today, and a last_verified date stamped by actually running them. Docs stop being "hopefully true."
4. Honest about failure — failure modes are first-class sections, each marked with its alarm (or ⚠️ no alarm, which is itself a finding and usually the first fix).
5. AI-consumable — structured frontmatter + consistent sections make specs ideal retrieval targets. An agent handed a broken system reads the spec, knows the intended behavior, and can diff intent against reality. Verified corpus in, trustworthy assistance out.

The loop

flowchart LR
    A[Audit reality] --> B[Write/refresh the spec]
    B --> C[Findings become tracked issues]
    C --> D[Fixes ship as PRs citing the spec]
    D --> E[Re-run verification, stamp last_verified]
    E --> A

Loading

Writing the spec is the audit. In the pilot deployment of this method, drafting the first three specs surfaced: a scheduled job that had silently stopped running months earlier, an integration whose events never reached their destination system, two intents in a capture bot that acknowledged success while persisting nothing, and an authentication regression silently breaking a linking feature — none previously known. Truth documents find bugs.

The template

See TEMPLATE.md. Frontmatter carries process, owner, systems, status (active / active-with-gaps / broken / deprecated), and last_verified. Sections: Purpose → Trigger → Flow (with code citations) → Data & source of truth → Failure modes (with alarm status) → Verification (runnable) → Open decisions.

A worked example: examples/email-to-calendar-sync.md.

Applying it to escalation / critical-incident operations

Escalation teams are the natural owners of this method: they are the only function that routinely observes the delta between intended process and actual behavior, across organizational boundaries, on the paths that matter most.

Pilot design (any org):

1. Spec the team's top ~20 escalation paths using the template — the audit-while-writing effect alone typically pays for the pilot.
2. At triage time, retrieve: the spec + the last N similar escalations + the known-delta history. (This is where retrieval/agents plug in — over a verified corpus.)
3. Every closed escalation ends with a process diff: what the spec said, what reality did, what changed. File it as an issue or PR against the spec.
4. Cross-org recommendations ship as PRs against other teams' specs — reviewable, versioned, explicitly accepted or declined.

Metrics that move: time-to-mitigate (triage starts from intent, not archaeology), routing accuracy, repeat-escalation rate on spec'd paths, and % of specs with fresh last_verified — the corpus-health number that also bounds how much you can trust any AI assistant built on top.

Relationship to knowledge graphs and RAG

Make git the source of truth; derive the graph and the index from the files. Graphs and embeddings are build artifacts — rebuildable, disposable, never load-bearing. This kills the two classic enterprise-KG deaths (ontology committee paralysis; the stale graph nobody trusts) and gives retrieval a corpus with freshness semantics (last_verified) to rank and filter on. The Praxis project explores the same principle for agent memory generally: nothing becomes memory without provenance, audit, and rollback.

Provenance

This method was developed and battle-tested on a real multi-system estate (task management, document pipelines, knowledge graph, automation) in July 2026, where the pilot specs immediately surfaced the production defects described above. This repository is the public, timestamped record of the method.