---
name: ba-create-actors
description: >
  Phase 2 of business analysis. Defines the project's actors (roles) that
  interact with the applications, and writes them to `acteur.md` at the
  Application level under `.smartstack/ba/`. Conversational: reads the menu tree
  and existing actors, proposes coverage per app, asks the user to validate, then
  writes the file. Run after the menu (`/ba-create-menu`), before use cases.
allowed-tools: [Read, Write, Edit, Glob, Grep, AskUserQuestion]
---

# ba-create-actors — Project-scoped actors

You define the **actors** (roles) that interact with the applications — the WHO,
not the permissions (those come later in RBAC). Actors are **project-scoped**: an
actor defined once can be linked to several applications. Reuse is the default.

## File model — state & persistence (read first, every turn)

State lives in `.smartstack/ba/`. There is no database and no action blocks.

1. **Read state**: `Glob .smartstack/ba/**/index.md` for the menu tree (apps =
   top-level folders; read each app `index.md` `## Contexte` to know what it
   does). Read existing `.smartstack/ba/<APP>/acteur.md` files for actors already
   defined (reuse candidates).
2. **Propose** actors per application in prose (list each `code` + label + type).
3. **Ask** the user to validate with **AskUserQuestion** (one multi-select per
   application). Open exploration questions go in prose.
4. **Write** `acteur.md` with the **Write** tool once validated. A Write
   overwrites the file — re-list every actor that must survive.

If the menu tree is empty, defer: tell the user to define the menu first
(`/ba-create-menu`). Do not propose actors without applications.

### Where actors are written (authority)

`acteur.md` is **authoritative at the Application level**:
`.smartstack/ba/<APP>/acteur.md`. The placeholder `acteur.md` that the menu phase
left at module/section/resource levels stays a **rollup pointer** — replace it
with one line `> Acteurs hérités — voir [../acteur.md](../acteur.md)` (do not
duplicate actor content downward). An actor active on several apps is written in
each of those apps' `acteur.md`, with its `Périmètre` line saying which
modules/sections it covers.

### `acteur.md` shape (authoritative, at the app)

```markdown
<!-- ba:acteur level=application code=CRM -->
# Acteurs — CRM

### BA-001-AC-001 — Commercial
- **Type** : internal
- **Description** : Gère son portefeuille de prospects et opportunités.
- **Périmètre** : CRM (toute l'application)
- **Origine** : conversation

### BA-001-AC-002 — Manager commercial
- **Type** : internal
- **Description** : Supervise l'équipe et valide les remises.
- **Périmètre** : CRM / PIPELINE
- **Origine** : code (rôle détecté)
```

## Actor fields

| Field | Rules |
|-------|-------|
| code | `BA-{analysisSeq}-AC-{NNN}` — `analysisSeq` is the 3-digit project sequence (first project = `001`), `NNN` a 3-digit per-project counter. Grep existing `acteur.md` headings to find taken numbers and increment. The number, never the label, is the identity. |
| label | Human label in the user's language (accents OK). |
| Type | `internal` (employees/admins, direct access), `external` (clients/partners/candidates via a portal), or `system` (background services). |
| Description | One sentence on the role. **Required.** |
| Périmètre | The app, optionally a module/section, the actor covers. App-wide when only the app is named; module-restricted when a module is named. |
| Origine | Traceability: where the proposal came from (conversation / code / user decision). **Required.** |

## Exploration — before proposing

1. **Read existing actors** from the `acteur.md` files (reuse candidates — never
   re-create an actor that exists; add a `Périmètre` line instead).
2. **Scan existing code** if the project has any: authorization attributes, role
   enums, permission seeds, frontend role constants. Extract the real role
   identifiers — use the codebase's own names, don't invent.
3. **Read each app's `## Contexte`** — it tells you who interacts with the app.
4. **Present a short summary**: actors already defined (N), roles found in code
   (M), applications in the project. No invented content — if a category is
   empty, say so.

## Proposing actors

For each application, propose the interacting actors via one AskUserQuestion
multi-select (pre-select the obvious ones). Every actor MUST trace to the user's
request, the app `## Contexte`, the code scan, or the user's explicit answers.
Tag each as *réutilisé* / *détecté* / *inféré* in the prose, with a concrete
source. Ask open questions about the organisation when context is thin — never
dump a generic list.

## Absolute prohibitions

1. **Never hardcode domain archetypes** (HR managers, accountants, "admin",
   "user", "viewer") without anchoring them to the user's actual organisation.
2. **Never use CRUD-style codes** (`CREATE_USER`, `READ_ACCESS`) — those are
   permissions, not roles. Actors are WHO, not WHAT-THEY-DO.
3. **Never invent codes or labels** — every actor traces to the conversation,
   the code scan, or an existing `acteur.md`.
4. **Never assign a `Type` without justification** — ask if uncertain.
5. **Never reuse a removed actor number** in the same project.

## Self-check before writing (actors → use-cases gate)

Before writing, verify each actor has a well-formed `BA-…-AC-…` code, a `Type`, a
non-empty `Description`, and an `Origine`. Surface any gap to the user instead of
writing a half-defined actor. (The deeper audit — duplicates, missing types,
coverage ACT-001..006 — is run by `/ba-audit-actors`, which reads the
`acteur.md` files and writes its verdict; you don't produce audit findings here.)

## After writing → hand off to use cases

Acknowledge in one line ("4 acteurs définis pour CRM."). Then, per the fixed
order, the next phase is **use cases** — propose continuing with
`/ba-create-use-case` (don't ask "what next?"). Convert any descendant
`acteur.md` placeholders you encounter into the one-line rollup pointer.

## Edge cases

| Situation | Action |
|-----------|--------|
| Actor already exists, only a new app link | Don't re-create — add a `Périmètre` line in that app's `acteur.md` |
| User removes an actor from an app | Re-Write the app's `acteur.md` without it (overwrite drops it) |
| Actor exists with a different label | Confirm the change with the user, keep the code |
| Same actor across several apps | Write it in each app's `acteur.md`, code identical, `Périmètre` per app |
