# kinds/screen.md — one screen (a page), after the fact

The playbook `/ba-change` loads for `kind: screen`. The frame is in
`SKILL.md`; this file carries what is specific to a **screen** — a page bound
to a node of the menu, typed as ONE SmartComponent, mined into ONE pagespec.

Owner document: `<APP>/<MODULE>/<section>/screen.md` (full re-Write, every
other screen verbatim). Grammar: `_workflow/doc-templates.md` § screen.md;
`ba-create-screen` § What a screen is, § Decision table, § Custom actions, and
the level file of the type (`levels/list-screens.md`, `form-screens.md`,
`dashboard-screens.md`, `kanban-screens.md`, `home-screens.md`). Code:
`allocation.next` — `SCR-{APP}-{MOD}-{SEC}-NNN`, per section.

## 1. Analyse the request

One grouped AskUserQuestion:

| Question | Why it matters |
|---|---|
| **What does the user do there** — browse a collection (list), read / edit one record (form detail / edit), create one (form create), see KPIs (dashboard), move cards through statuses (kanban), land on a hub (home)? | the SmartComponent type — one type, one page template |
| **On which entity**, in which section? Which permission guards it (a row of `rbac.md`, or the section floor `…access` / `…read`)? | XD-005 / a 403 at runtime |
| **Which use cases** does it serve? | SCR-005 / SCR-024 — a screen with no UC, a UC with no surface |
| **What is on it** — columns + filters + actions (list), fields grouped in sections / tabs (form), widgets (home / dashboard), status column + card (kanban)? Related tabs (a 360 detail)? | mined 1:1 into the pagespec; the budgets (≤ 7 columns, ≤ 3 primary filters, ≤ 7/9 tabs) |

## 2. Challenge it

- **Is it a page or a representation?** A SmartKanban / SmartCard is the
  SECOND screen of the list section — a `viewMode` of the list, never its own
  section and never its own pagespec (it folds into `<Entity>.list.md`).
- **Does the surface exist?** `existing.exact` with `same-surface` = a screen
  of the same (entity, type, mode) is already there → modify it (op=modify),
  do not add a twin page. `same-title` → same.
- **Is the entity there?** BLOCKED otherwise (`entity-not-found` →
  kind=entity first).
- **Is the permission there?** A human row of `rbac.md` or a floor path of
  the section — BLOCKED otherwise (`permission-not-found` → kind=permission
  first). A custom action's permission roots at the own `module.section`
  grain (PRD-128).
- **Do the use cases exist?** BLOCKED otherwise (→ kind=use-case).
- **Is it a satellite?** An entity that is not the section's primary carries
  `routeFamily` + `routeParent` on EVERY view pagespec — omitting them
  mis-routes every 360 tab onto the porteur (PRD-108).
- **Multi-resource section?** It declares its `SmartSectionHome` (SCR-020).
- **Will it stay readable?** Column / filter / tab budgets (SCR-016/017/018,
  RTV-009).

## 3. Author

```markdown
### <allocation.next> — <Titre> (SmartListView | SmartForm | SmartDashboard | SmartKanban | SmartCard | Smart…Home)
- **Entité** : <Entity> (ENT-NNN)
- **Permission** : `module.section.read`
- **Mode** : detail                                (SmartForm: create | edit | detail)
- **Cas d'usage liés** : UC-…, UC-…
- **Sources** : SRC-NNN §n                         (when the registry exists)
- **Colonnes** : … · **Filtres** : … · **Actions** : …        (list)
- **Champs** : … / **Section « X »** : … / **Onglet « X »** : …   (form)
- **Onglet lié « … »** : entité X, FK xId, affichage table → SCR-… (`perm`)   (detail 360)
- **Actions personnalisées** :
  - `approve` — kind: api, scope: row, permission: module.section.approve, UC: UC-…, label: « Approuver »
```

Then the full re-Write of the section doc (SKILL.md Step 3) and the verify
(`expectCode` = the new code, `baselineCount` = `existing.count`).

## 4. Verify

`report.verify.ok` true: the code is found, the screen count moved by +1, no
duplicate code, nothing `lost` (a `### SCR-…` heading without its
`(SmartType)` suffix is invisible to every consumer; a malformed related-tab
bullet is a tab that will not render).

## 5. Propagate — what a new screen drags along

1. **Related tabs valid** — `derive-related-tabs --mode validate` on the
   section (a detail / edit SmartForm): the related entity, its FK, its list
   target and its permission resolve; the shared tab bar stays within 7/9.
2. **UC coverage** — `derive-uc-coverage`: the linked UCs come back `covered`.
3. **The ONE pagespec** — `/ba-create-prd` § Single-pagespec entry point
   writes `<Entity>.<view>.md` (`data.expectedPagespec`), `screenCode` /
   `permission` / `entity` verbatim, bullets mined 1:1, `routeFamily` +
   `routeParent` on a satellite, the `prd.frontend.md` line. A kanban →
   `derive-kanban-spec --mode derive` on the LIST pagespec; cards →
   `viewModes`. **Never `/ba-create-prd`** on a module with pagespecs.
4. **Derivations** on the new file — `derive-rule-links --mode backfill`;
   a form: `derive-lifecycle --mode derive` + `derive-form-sections`; a
   detail: `derive-detail-summary --mode derive` + `derive-related-tabs
   --mode validate` with `pagespecs: true`; a `routeFamily` →
   `derive-nav-resources` (collisions are blocking, DEV-UI-046).
5. **Hand-off** — Phase 0 only for a new resource / routeFamily (additive
   seed); Phase 2b (DEV-API-012: the view needs its screen endpoint); Phase 3
   (the added pagespec); Phase 4.

## 6. Audit

`audit-ba` with dimensions `screens`, `cross-dimension`, plus `/ba-audit-prd`
on the module. What an err means here: SCR-003 / XD-005 (unknown entity),
SCR-005 (no UC), SCR-008/013 (a navigation target that does not exist),
SCR-009/014 (a related tab whose prerequisites fail), SCR-020 (missing
section home), SCR-024 (a UC with no surface), PRD-070 (a screen without its
pagespec), PRD-108 (satellite without route family), PRD-133 (tab-bar
budget).

## Modify variant (op=modify)

- The pagespec follows the screen — columns / fields / filters / actions
  re-mined in the json block only; `uiDesign`, `lifecycle`, `sections`,
  `kanban`, `summary` untouched. `compute-page-diff` marks it `modified` and
  Phase 3 regenerates that page only.
- A changed **entity** or **type** is a delete + add of the page (and its
  pagespec) — announce it; deletion has no reconciler.
- A changed **permission** re-opens the RBAC check (kind=permission).
- Verify expects delta **0**.