work-operating-model

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