Work Operating Model

---
name: work-operating-model
version: 1.0.0
model: claude-sonnet-4-6
description: "Run a 5-layer interview to elicit how a team actually works (rhythms, decisions, dependencies, institutional knowledge, friction) and emit a structured operating model."
license: MIT
---

# Work Operating Model

A conversation-first elicitation skill. Surface what is documented, what is tacit, and where the two disagree. Output is a structured operating model that downstream agents (`architect`, `roadmap`, `orchestrator`) can read.

## Triggers

| Trigger Phrase | Operation |
|----------------|-----------|
| `elicit operating model` | Start the 5-layer interview |
| `interview team operating model` | Start the 5-layer interview |
| `how does this team actually work` | Start the 5-layer interview |
| `resume operating model interview` | Continue from the last completed layer |
| `validate operating model` | Run scripts/validate_operating_model.py against an output JSON |

## When to Use

**Use this skill when:**

- You need a baseline of team practice before an ADR, retrospective, or scope decision.
- A new agent or skill needs to be customized to a team's actual cadences and decision rights.
- A planning conversation keeps getting derailed by missing context about how the team operates.

**Do not use this skill when:**

- The question is about code, not people-process. Use the `analyst` agent.
- You need a strategic narrative for an external audience. Use the `explainer` agent.
- A retrospective is what you actually need. Use the `retrospective` agent.

## Distinction From Adjacent Capabilities

| Capability | Investigates | Output |
|------------|--------------|--------|
| `analyst` agent | Code, repo state, bug paths | Findings document |
| `explainer` agent | Concepts, decisions for a reader | Explainer prose |
| `retrospective` agent | A bounded past period | Learning matrix |
| **work-operating-model** | **Team operating reality (people-process)** | **Structured operating model JSON** |

## The 5 Layers

The interview proceeds in order. Each layer answers one question and produces one section of the output JSON. Skip a layer only when the team explicitly cannot answer it; record the gap in `metadata.skipped_layers`.

| # | Layer | Question | Output Section |
|---|-------|----------|----------------|
| 1 | Rhythms | When does work happen, and on what cadence? | `rhythms` |
| 2 | Decisions | Who decides what, and how is the decision recorded? | `decisions` |
| 3 | Dependencies | Who do you wait on, and who waits on you? | `dependencies` |
| 4 | Institutional Knowledge | What lives in someone's head and not in a doc? | `institutional_knowledge` |
| 5 | Friction | What is broken or slow that the team has accepted? | `friction` |

For the full prompt list per layer, read `references/layer-questions.md`. For the output JSON contract, read `references/entry-contract.md`.

## Process

The interview runs in three phases.

### Phase 1: Open

1. **Open**: Confirm scope (team name, what they own, size). Write the `team` section.

### Phase 2: Layer Pass

2. **Layer pass**: For each layer 1 through 5, ask the question, capture answers, record them in the relevant output section. After each layer, summarize back to the user and confirm before moving on.
3. **Distinguish**: For every captured item, mark it as `documented` (link the doc) or `tacit` (note the source person). Disagreement between sources is a finding, not an error.

### Phase 3: Close and Validate

4. **Close**: Write the JSON to `<workspace>/operating-model.json` (caller chooses workspace). Optionally also emit `USER.md`, `SOUL.md`, `HEARTBEAT.md` as human-readable views derived from the JSON. The JSON is canonical; the markdown files are projections.
5. **Validate**: Run `python3 .claude/skills/work-operating-model/scripts/validate_operating_model.py <path-to-json>`. Exit 0 means the schema holds.

## Scripts

| Script | Purpose | Exit Codes |
|--------|---------|------------|
| `scripts/validate_operating_model.py <path>` | Validate operating-model.json against schema v1.0.0 | 0 ok, 1 schema failure, 2 invalid usage |

Pass `--skip-path-validation` to bypass CWE-22 path containment when reading fixtures from outside the repo (tests only).

## Resume Across Sessions

The interview is long. To resume:

1. Read the existing `operating-model.json`.
2. Inspect `metadata.completed_layers`. The next layer is the first one not in that list.
3. Continue from the start of that layer.

Do not silently rewrite an earlier layer. If a previous answer needs to change, open the discussion, then update the section and append to `metadata.revisions`.

## Output Contract (Summary)

The full schema is in `references/entry-contract.md`. The minimum valid document has:

- `schema_version`: `"1.0.0"`
- `team`: object with `name`
- `rhythms`, `decisions`, `dependencies`, `institutional_knowledge`, `friction`: each present, each an object (may be empty if a layer was skipped)
- `metadata`: object with `interview_date` (`YYYY-MM-DD`), `interview_status` (`in_progress` or `complete`), `completed_layers` (list)

The validator (`scripts/validate_operating_model.py`) enforces these and returns a non-zero exit on schema failure.

## Anti-Patterns

| Anti-Pattern | Problem | Fix |
|--------------|---------|-----|
| Treat the interview as a survey to fill in alone | Misses tacit knowledge entirely | Hold the conversation; capture during the talk |
| Merge `documented` and `tacit` into one bucket | Erases the gap that is the whole point | Tag every item explicitly |
| Skip layer 4 because it is hard | Layer 4 is where most useful findings live | Ask anyway; if unanswered, record it in `metadata.skipped_layers` with a reason |
| Edit the JSON by hand without reopening the conversation | Drift between model and reality | Re-interview, then update |
| Run the interview once and call the model done | Operating models drift | Re-validate quarterly; bump `metadata.interview_date` |

## Verification Checklist

Before declaring an operating model complete:

- [ ] All 5 layers either captured or explicitly skipped (recorded in `metadata.skipped_layers`).
- [ ] Every item in every layer marked `documented` or `tacit`.
- [ ] `metadata.interview_status` is `complete`.
- [ ] `python3 .claude/skills/work-operating-model/scripts/validate_operating_model.py operating-model.json` exits 0.
- [ ] The team representative has read the final JSON (or its `USER.md` projection) and agreed.

## References

- `references/layer-questions.md` - prompt list per layer
- `references/entry-contract.md` - full output JSON schema
- `scripts/validate_operating_model.py` - schema validator