cynefin

name	cynefin
description	Use when starting any nontrivial task, triaging a bug, planning an approach, handling an incident, or when unsure how to even begin. Senses which Cynefin domain the situation is in (Clear, Complicated, Complex, Chaotic, Confusion) and switches working method to match. Also use for "classify this backlog" (map mode) and "prod is down" (incident mode).

Cynefin: sense the domain, then switch how you work

You are about to work on something. Before you pick a method, figure out what kind of situation this is. The Cynefin framework (Dave Snowden, IBM, 1999) gives you five domains, each with its own decision pattern. Most bad engineering outcomes are method-domain mismatches: a confident spec written for a problem where cause and effect were unknowable, or three days of analysis spent on a task with a documented answer.

The core rule: the domain picks the method. You do not.

The loop

Run this every time, in order. Do not skip step 2.

1. Sense before solving

Answer one question: what is the relationship between cause and effect here?

If cause and effect are...	Domain	Pattern
Obvious to anyone looking	Clear	sense, categorize, respond
Discoverable with analysis or expertise	Complicated	sense, analyze, respond
Only visible in hindsight	Complex	probe, sense, respond
Absent. No time to find out; things are breaking now	Chaotic	act, sense, respond
Disputed. You (or the team) can't agree which of the above applies	Confusion	decompose and route

Signals to check:

• Has this exact thing been done before, here, with a known result? Leans Clear.
• Could an expert predict the outcome before acting? Leans Complicated.
• Will you only understand what worked after trying? Do interventions change the system being studied? Leans Complex.
• Is damage actively accruing while you read this? Leans Chaotic.
• Are you flip-flopping between the rows above, or would two teammates classify it differently? That IS Confusion. Treat the disagreement as data.

2. Announce the domain and your reasoning

One short paragraph, out loud, before any work: the domain, the one or two signals that put it there, and your confidence. If your confidence is low, say so and treat the classification itself as a probe.

This step is not decoration. It creates the record that lets you notice you were wrong later, and it forces the method switch to actually happen.

3. Switch method. Visibly.

Load the playbook for the domain and work its way:

• playbooks/clear.md: find the established pattern and follow it. Do not invent.
• playbooks/complicated.md: analyze, compare options, spec, then build. Expertise pays here.
• playbooks/complex.md: no spec. Design safe-to-fail probes, run the cheapest first, amplify what works.
• playbooks/chaotic.md: stabilize first. Diagnosis waits.
• playbooks/confusion.md: split the situation into parts and route each part to its own domain.

Name what you are NOT doing and why. "This is Complex, so I'm not writing a spec; specs assume the analysis can predict the outcome, and here it can't." That sentence is the product of this skill. Say it every time the method switch drops something the user might expect.

4. Watch the boundaries

Domains are not fixed. While working, watch for these movements:

• The cliff. The Clear-to-Chaotic boundary is a cliff, not a slope. Complacency in Clear ("we've done this deploy a hundred times") is how systems fall off it. When work feels routine, ask once: what has changed since the last hundred times?
• Drift toward Clear. As knowledge grows, Complex work becomes Complicated (patterns emerged; analysis now works) and Complicated becomes Clear (the analysis became a checklist). Say it when you see it: "this stopped being Complex two probes ago; I can spec the rest."
• Misclassification. The most common error in software: calling something Complicated when it is Complex, because analysis feels like progress and probes feel like admitting ignorance. If your confident analysis keeps being wrong, reclassify.

Modes

• Map mode (modes/map.md): the user gives you a backlog, issue list, or TODO file. Classify every item, output a domain map with per-domain recommendations, and offer to persist it as cynefin-map.md in the repo.
• Incident mode (modes/incident.md): entered automatically whenever step 1 returns Chaotic, or on request when production is failing. Enforces act-sense-respond with explicit entry and exit criteria.

The map file (project memory)

If the repo contains a cynefin-map.md (map mode writes it, or a human did), read it before classifying work in that project. Prior classifications are priors, not law: when what you're seeing disagrees with the map, that mismatch is drift data. Announce it, update the row, and append one line to the map's ledger. This file is how the framework lives in the project instead of in one session's transcript: the team can read it, PRs can review it, and the next agent inherits it.

Rules

1. Never start work on a nontrivial task without steps 1 and 2. "Nontrivial" means: would take more than a few minutes, touches production, or the user asked how to approach something.
2. One domain per unit of work. If a task spans domains, that's Confusion: decompose it (a migration might be Clear scaffolding + one Complex unknown; treat them as two work items).
3. Default-domain bias is real. Developers over-classify into Complicated (analysis is comfortable). Managers over-classify into Clear (checklists are comfortable). When torn between two domains, pick the one further from your comfort.
4. Reclassify out loud. Changing domain mid-task is the framework working, not a mistake. Announce it the same way you announced the original.
5. In Complex, a probe that can't fail safely is not a probe. If a failed experiment would hurt users or data, shrink it until it can't.

When NOT to run the loop

The framework's own first rule applies to the framework. Skip the loop, silently, when:

• The task is a few minutes of known work: a rename, a typo fix, a config bump, a question with a documented answer. Announcing "Domain: Clear" on a one-line diff is theater.
• You are mid-task and nothing has changed. Classification happens at task boundaries and on surprise, not per message.
• The user asked a pure information question. Answer it.

The test: if the announcement would be longer than the work, skip it.

---

Based on the Cynefin framework by Dave Snowden. Unofficial; not affiliated with or endorsed by The Cynefin Company. Cynefin® is a registered trademark of Cognitive Edge Pte Ltd. See ATTRIBUTION.md.