---
name: three-audiences 
description: Use when the user wants to work with the three-audiences documentation paradigm. Triggers on drift detection ("detect drift", "check drift", "align docs", "are docs up to date"), or on adding something to the docs ("add concept X", "add decision X", "add use case X", "add workflow X", "add constraint X", "where does X go", "document X"). 
license: MIT 
compatibility:  opencode 
---
# three-audiences skill

This project uses the three-audiences documentation paradigm. Read `.agent/three-audiences.md` for the full protocol before doing anything.

Identify the user's intent and route to the correct mode below.

---

## Mode: drift-detection

**Triggers:** "detect drift", "check drift", "align", "are docs up to date", "check documentation", or any variation asking whether docs match the code.

Drift is when the documentation says one thing and the code does another. In a three-audiences project, drift has three forms — check all three.

### 1 — Living docs drift

Living docs in `docs/business/` and `docs/architecture/` must stay in sync with the code. For each file found:

- Read the file
- Read the relevant source code it describes
- Identify any discrepancy: missing use cases, removed use cases, changed steps, renamed components, new external dependencies not listed, etc.

Report each discrepancy as:

```
DRIFT — docs/business/use-cases.md
  Missing: "Cancel subscription" use case (found in app/services/subscription_service.py)
  Stale: "Submit invoice" — step 3 references approval_service which no longer exists
```

### 2 — Structural drift

Content placed in the wrong audience layer. Check:

- `.agent/AGENTS.md` — contains rationale or history? → move to `decisions/`
- `docs/business.md` or `docs/architecture.md` — contains explanations longer than one sentence? → move to `docs/business/` or `docs/architecture/`
- `docs/business/` or `docs/architecture/` — contains static definitions that don't change with the code? → move to `concepts/`
- `concepts/` — contains things that change when the code changes? → move to `docs/`
- `decisions/` — contains accepted decisions marked as superseded but `superseded-by` not filled in? → flag for cleanup

Report each as:

```
MISPLACED — .agent/AGENTS.md
  "We chose JWT because Redis adds infrastructure complexity" is rationale,
  not a working norm. Move to decisions/.
```

### 3 — Tech debt drift

Read `README.md` tech debt section. For each open item:

- Check if it can now be answered from the codebase or recent sessions
- If yes: resolve it, remove the checkbox, place the answer in the right file
- If no: leave it, note it in the report as still open

Report:

```
RESOLVED — README.md tech debt
  "What is the current focus?" → answered in sessions/api-add-billing-PROJ-42.md
  → updated docs/business.md current focus section

STILL OPEN — README.md tech debt
  "How does deployment work in staging?" → cannot determine from codebase
```

### Drift-detection report format

After checking all three forms, output:

```
## three-audiences drift report

### Living docs drift
[list of discrepancies, or "None found"]

### Structural drift
[list of misplaced content, or "None found"]

### Tech debt drift
[list of resolved and still-open items, or "None found"]

### Actions taken
[list of fixes applied automatically]

### Actions needed
[list of fixes that need human input or confirmation]
```

Fix what you can automatically. Flag what needs human input.

---

## Mode: add

**Triggers:** "add X", "add concept X", "add decision X", "add use case X", "add workflow X", "add constraint X", "where does X go", or any request to document something new.

The agent decides where the new item belongs based on what it is. Explain the placement decision to the user before creating the file.

### Placement rules

Ask yourself: **what kind of thing is this?**

**It is a static definition** — describes what something _is_, does not change when the code changes → `concepts/business/` or `concepts/technical/`

Examples: "what is an energy meter", "what is the repository pattern", "what is a DSO", "what is idempotency"

First check if a concept file already exists by listing the directory. Do not load existing concept files — check filenames only. If it exists, reference it. If not, create it.

**It is something the system currently does** — a use case, workflow, or business rule that changes when the code changes → `docs/business/`

Examples: "add use case: cancel subscription", "add workflow: dispatch energy", "document the invoice approval flow"

Read the relevant source code first to extract the actual implementation. Update `docs/business/use-cases.md` or create a new file if the topic warrants it. Update `docs/business.md` index if adding a new top-level item.

**It is a technical description of something the system does** — the technical view of a use case or component → `docs/architecture/`

Examples: "document how the payment webhook is handled technically", "add the billing component to the architecture"

Read the relevant source code. Update `docs/architecture/use-cases.md` or the appropriate file. Update `docs/architecture.md` index if needed.

**It is an architectural decision with rationale** — a choice that was made and should not be revisited without a new decision → `decisions/`

Examples: "we decided to use JWT", "document why we use the repository pattern", "add a decision: no direct SQL"

Create `decisions/[slug].md` using the ADR format with frontmatter and `## For agents` section. Add to `decisions/INDEX.md`.

**It is a hard constraint for the agent** — a rule with no rationale needed, just enforcement → `.agent/AGENTS.md` constraints section

Examples: "always run lint before committing", "never write raw SQL"

If it has rationale, it belongs in `decisions/` instead.

### Add workflow

1. Identify what kind of thing is being added
2. State the placement decision and why, in one sentence
3. If placing in `concepts/`: check directory listing first, create only if missing
4. If placing in `docs/`: read the relevant source code before writing
5. Create or update the file
6. Update the relevant index (`docs/business.md`, `docs/architecture.md`, or `decisions/INDEX.md`) if a new top-level item was added
7. Report what was created and where

### Add report format

```
## three-audiences add

Added: [filename]
Type: [concept | living-doc | decision | constraint]
Audience: [human | both | agent]
Reason: [one sentence explaining the placement]
Index updated: [yes/no — which index]
```