# RD-09 — Update the two documents that teach the deleted submit idiom

Status: done
Source: PLAN.md 1c (A5, as corrected)

## Why

RD-05 through RD-08 replaced the hand-called `runIfSubmitting` with `createStore`'s effect
map, and `grep` now finds the method nowhere in `apps/` or `libs/`. Two teaching documents
still present it as the house idiom, in a code block, as the answer to "how does a submit
happen?".

Both blocks are doubly stale: they teach a deleted idiom **and** call
`submitHerregistratie(s.data)`, a function that no longer exists either.

A document that teaches a deleted idiom is worse than no document — a reader who follows it
reintroduces the silent-failure bug RD-06 fixed.

## Read first

- `libs/shared/src/application/store.ts` — the effect map, the trigger rule, the `Seed`
  exemption, and the "must never throw" contract. This is the new idiom to document.
- Any migrated call site, as a worked example — `besluit-form.component.ts` is the smallest.
- `docs/reference/architecture/ARCHITECTURE.md` §2d (the block at 306-322) and the write
  walkthrough mention at :574.
- `docs/reference/fp-tea-atomic-design.md` (the block at 336-350).

## Decisions (pre-made, don't relitigate)

1. **Scope is exactly two documents.** An earlier version of this plan claimed
   `plop-templates/form-machine.hbs` generates `runIfSubmitting` and that
   `.claude/skills/form-machine/SKILL.md` teaches it. **Both are false**, verified by grep:
   the plop template is machine-only (74 lines, no `@Component`), and the skill never mentions
   it. Do not "fix" either file. If you find yourself editing a `.hbs` or a `SKILL.md`, stop.

2. **Rewrite the code block, do not delete the section.** §2d ("Side effects (HTTP) without
   polluting the reducer") and its fp-tea counterpart answer a real question and answer it
   well. The answer changed; the question did not.

3. **The new block shows the effect map.** Same worked example (a herregistratie submit with
   its optimistic `begin`/`confirm`/`rollback`), expressed as a registration:

   ```ts
   private store = createStore<WizardState, WizardMsg>(initial, reduce, {
     Submitting: async (s, store) => { … },
   });
   ```

   Keep the numbered inline comments — they are what makes the block teachable.

4. **State the two properties the old idiom lacked**, because they are the reason for the
   change and a reader should see them:
   - Entering the state runs the effect. A `dispatch` cannot silently skip it.
   - Double-submit protection is structural: the effect fires only on a tag **transition**, so
     a second `Submit` while already submitting is a reducer no-op and fires nothing.

5. **Document the `Seed` exemption where the idiom is taught**, in one sentence: a mount or
   restore message must not trigger a submit. That is the non-obvious part of the rule, and
   `store.ts` explains it in full for anyone who needs more.

6. **Fix `ARCHITECTURE.md:574`'s write walkthrough** too — it opens with `runIfSubmitting()
(§2d) → createSubmitChangeRequest`. Replace the first hop with the effect map. Leave the
   rest of §6a alone: **RD-31 rewrites that section**, including its stale `L<n>` citations and
   two dead file paths. Touch only the `runIfSubmitting` hop here.

7. **Drop the `submitHerregistratie(...)` call from both blocks.** That module no longer
   exists (`submit-herregistratie.ts` was deleted). Use `draftSync.submit(...)`, which is what
   the two herregistratie wizards actually call today.

## Files

- `docs/reference/architecture/ARCHITECTURE.md` (§2d block, and the one hop at :574)
- `docs/reference/fp-tea-atomic-design.md` (the block at 336-350)

No code files. No `.hbs`. No `SKILL.md`.

## Steps

1. Rewrite `ARCHITECTURE.md` §2d's code block per decisions 3-5.
2. Fix the first hop of the write walkthrough at :574 per decision 6.
3. Rewrite the equivalent block in `fp-tea-atomic-design.md` per decisions 3-5 and 7.
4. Update this ticket's `Status:` to `done` and the README's RD-09 row to `done`.
5. Commit all of it together.

## Acceptance criteria

The deleted idiom is no longer taught anywhere:

```bash
grep -rn "runIfSubmitting\|runIfIndienen" docs/ apps/ libs/ .claude/   # MUST return nothing
grep -rn "submitHerregistratie" docs/                                  # MUST return nothing
```

Every code identifier the new blocks name must exist:

```bash
grep -n "StoreEffects\|effects?" libs/shared/src/application/store.ts   # the API is real
grep -rn "draftSync.submit" apps/ssp | head -3                          # the call is real
```

```bash
npm run ci   # exits 0
```

## Verification

`npm run ci`. This ticket touches only two Markdown files under `docs/reference/`, so
`--full` is not required — neither is globbed by Storybook.

Read both rewritten blocks end to end and check a reader could follow them without opening
`store.ts`. That is the actual acceptance test for a teaching document, and no command
checks it.

## Out of scope

- The rest of `ARCHITECTURE.md` §6a — its stale `L<n>` line citations, its two non-existent
  file paths, and its post-RD-16 `parseDashboardView` claim. **RD-31.**
- `fp-tea-atomic-design.md`'s 11 broken pre-monorepo `src/app/…` paths and its broken anchor.
  **RD-32.**
- `plop-templates/form-machine.hbs` and `.claude/skills/form-machine/SKILL.md` (decision 1).
- CLAUDE.md. **RD-33.**

## Risks

- **Do not chase the other staleness in these two files.** Both are also targets of RD-31 and
  RD-32. Editing their line citations or paths here creates a conflict with those tickets for
  no gain. Change only what teaches the submit idiom.
- **`fp-tea-atomic-design.md`'s surrounding paths are already broken** (they use the
  pre-monorepo `src/app/…` prefix). Leaving them broken in this commit is correct — RD-32 owns
  them. Do not half-fix the file.
- **Prettier formats Markdown.** Run `npx prettier --write` on both files, or `format:check`
  fails.