templateThe Codices
Template — Interaction specification
Codex 6 companion template: interaction.
- Authority rank
- 6
- Version
- v1.0
- Adopted
- unrecorded
- Held by
- Executive Office
- System
- SYS-09
Source · docs/codices/CODEX-6/TEMPLATE-interaction.md · registered by rule
Copy this file for any flow, form, or single consequential interaction before it is built. Interactions are where trust is won or lost, so they are specified separately from the surface that hosts them. See RUBRIC.md.1. Identity
- Name.
- Surface(s).
SURF-__ - Workflow stage.
WF-__stage, if this interaction advances one (Codex 0 Chapter 09) - Owning division.
DIV-__ - Consequential? yes | no — consequential means it changes a person's standing, money, data, or access. If yes, §6 and §7 are mandatory.
2. Intent
- What the person is trying to accomplish, in their words.
- What the institution needs from them to accomplish it.
- Preconditions. State, role, scope, and data that must already exist.
- Success. What is true afterwards that was not true before.
3. Steps
| # | Step | What the person must hold in mind | Inputs | Can they leave and return? |
|---|---|---|---|---|
| 1 | ||||
| 2 | ||||
| 3 |
Rules to check against:
- No step asks for information the institution already holds.
- No step exceeds five simultaneous inputs.
- Nothing the person must remember across steps; the interface carries it for them.
- Progress is preserved on interruption, or the interaction states plainly that it cannot be.
4. Guidance without instruction
- Defaults, and why each is the right default for a first-time person.
- Structure and sequencing that make the correct path the obvious one.
- Instructional copy present, and what structural change would let it be deleted.
5. Reversibility
| Action | Reversible? | How, and for how long | If not, how the person is told beforehand |
|---|---|---|---|
Irreversible actions state their consequence in the confirmation itself, in plain language, never in a tooltip or a link.
6. Confirmation and human checkpoint
- What is confirmed, and at which step.
- Wording of the confirmation, verbatim.
- Human checkpoint. If any part is automated or AI-assisted: what the machine proposes, what the person decides, and the explanation shown alongside the proposal (Codex 0 Chapter 13). AI advises; people decide.
7. Audit and record
- Events emitted (ENT-18):
- Audit records emitted (ENT-19), with actor, subject, time, and reason:
- What the affected person can later see about this action, and where.
8. Failure
| Failure | When it happens | What the person sees | What the institution does |
|---|---|---|---|
| Validation | cause, consequence, remedy | ||
| Permission | what is missing and what to do | ||
| Partial completion mid-flow | recovery or explicit rollback | ||
| Backend unavailable | degradation path | ||
| Duplicate submission | idempotency behaviour |
State explicitly what happens if the person closes the browser at each step.
9. Consent and data
- New data collected, and the minimum necessary justification for each field.
- Consent required? Purpose, wording, and how it is revoked. Consent is never bundled into this interaction if it is not needed for it.
- Retention. How long, and what deletes it.
10. Rubric self-score
| # | Dimension | Score | Evidence |
|---|---|---|---|
| 1 | Primary action clarity | ||
| 2 | Progressive disclosure | ||
| 3 | Cognitive load | ||
| 4 | Mastery-first guidance | ||
| 5 | Orientation | ||
| 6 | Register and restraint | ||
| 7 | Failure and recovery | ||
| 8 | Access and inclusion | ||
| Total / 24 |
Confirm explicitly: no manufactured urgency, no countdown, no loss framing, no bundled consent, no obstruction of cancellation or export.
Did this make the person's life better? One paragraph, honest.