/suede-ops-architecture

name: suede-ops-architecture
description: "Suede AI operations-architecture discipline that fixes the shape of a system before anyone builds it: entity schema first, exactly one write path per entity, every unit of work routed to a deterministic automation, an AI agent, or a human decision, every existing tool marked absorb, keep, or kill, and the build sequenced into phases whose completion is proved by a command. Use when scoping an automation or agent build, deciding whether a workflow needs a model at all, consolidating a sprawling tool stack, designing the data model under a workflow, choosing a migration path off an old system, or ordering a build so nothing lands on a moving foundation. NOT FOR: executing a planned multi-file repo change (use suede-graph-flo-xr); coordinating parallel builders with file ownership (use suede-agent-teams); lead lifecycle, scoring, and CRM routing rules (use suede-revops); proving agent output quality against an eval set (use suede-ai-eval); reviewing the finished diff (use suede-code)."
metadata:
  version: 1.0.0

Suede Ops Architecture

Ordering law: data, then workflows, then intelligence.

An agent reading fragmented data does not report that it holds a third of the picture. It returns a fluent, confident answer built on a third of the picture. Fragmented input produces polished mistakes at scale, and polished mistakes survive review that visible chaos would not. Architecture is what stops the model from being asked a question its inputs cannot answer.

This skill ends with a written architecture, not a build. Every step below produces a line in the Output Contract, and every gate names what an agent does when it fails.

Before Starting

Collect these. Work with what exists and name what is missing in the Output Contract rather than blocking on it.

1. **Entities**: the nouns the operation runs on (client, project, order, job, track, release, patient). 2. **Work units**: the recurring things people do, one line each, in the words the person doing them uses. 3. **Tool list**: every system holding operational data, including spreadsheets, shared drives, and any inbox used as a database. 4. **Cycle length**: median days for one unit of work to go from open to done. 5. **Blast radius per work unit**: what a wrong output costs, and whether it can be undone.

Read `references/triage-examples.md` for worked classifications before running Step 3 on unfamiliar work.

Step 1: Schema before surfaces

Name the entities, their fields, and their relationships before designing a screen, an automation, or an agent.

For each entity record: the fields it carries, the entity it belongs to, and the lifecycle states it moves through.

**Gate.** Every work unit from Before Starting reads or writes at least one named entity. A work unit touching no entity means the schema is incomplete.

**Halt format.** Stop. Name the unmapped work unit in one line. Offer: add the missing entity, fold the work unit into an existing entity, or mark it out of scope in writing. Wait for the choice.

Step 2: One write path per entity

Each entity gets exactly one place a record is created and one path it is updated. Everything else reads.

For each entity, list every write **path**: each tool, script, form, and integration that can create or update it. People entering data through one application share that application's path and do not count separately; two applications writing the same record are two paths.

**Gate.** Write-path count per entity resolves to one. Two paths into the same record rebuilds the silo the system is being built to remove, on newer software.

**Halt format.** Stop. Name the entity and each competing path in one line apiece. Offer: designate one canonical writer and make the others read, put every writer behind one service that owns the write, or split into two entities with separate lifecycles. Wait for the choice.

Step 3: Triage every work unit

Route each work unit to an automation, an agent, or a human. Apply the Written Rule Test in order and stop at the first match.

| Test | Verdict | Build as | |---|---|---| | The complete rule can be written down, every branch included, with no "it depends", "usually", or "as appropriate", and inputs already arrive structured | **Automation** | Deterministic code. No model. | | The rule can be written down, but inputs arrive as prose, audio, or images | **Automation with one extraction step** | Model parses input into the schema; the written rule decides. | | The rule cannot be fully written, and two competent people given the same context would agree on the answer | **Agent** | Model interprets, drafts, or answers, against the schema from Step 1. | | The rule cannot be fully written, and two competent people would disagree | **Human decides** | System assembles the full context and presents it; the person chooses. |

Adding a model to deterministic work buys nondeterminism and per-call cost in exchange for nothing. Work that passes the first test stays code.

Settle the agreement question rather than estimating it: give the same three real past cases to two people who do the work. Matching answers put the work unit with the agents; diverging answers put it with the humans.

**Blast-radius override.** Apply after the table, and it wins. Any work unit whose wrong output moves money, reaches someone outside the team, changes access, or deletes data becomes **agent proposes, human approves** regardless of the verdict above. Reversibility is the test, not difficulty.

Notifications into a channel the team already owns do not reach outside it and keep their table verdict: a routing automation that posts to an internal channel stays a plain automation.

**Halt format.** When a work unit cannot be classified (its rule was never written down, or the two people needed to settle the agreement question are not available), stop. Name the work unit in one line. Offer: write the rule now