# Workshop Handover Log — Draft

A proposed single-device handover log, conditional on validating a structured paper process first.

**Kind:** software · **Investigation:** Workshop handover, reviewed by an orchestrator · **Composed:** 2026-10-01T19:54:43.304Z · **Model:** openai gpt-6-sol

## 1. Problem space

**Who:** Staff and supervisor in the fictional two-shift workshop.

**Pain:** The synthetic notes illustrate ambiguity about ownership, next action and closure; they do not establish real-world demand or impact.

**Context:** Investigate the paper process before building software. Operational and safety decisions remain with the supervisor outside the app.

Evidence: `handover-question` What should the next shift know?; `sample-handover` Three sample handover notes; `handover-concept` A single-device handover log

## 2. Solution idea

If the paper-process gate passes, prototype a local browser log on one shared device. Capture six core fields, show unresolved items first, record receipt acknowledgements and export JSON and CSV.

**Differentiators**

- One device and a fixed local application origin.
- Acknowledgement records receipt without changing ownership.

**Non-goals**

- No backend, cloud, accounts, sync, notifications, integrations, AI features, machine control, diagnosis or safety sign-off.
- No telemetry, in-app paper-comparison view or JSON import/restore.

## 3. Concept

**User journey**

1. Before a software build, a supervisor evaluates whether a structured six-field paper checklist produces usable handovers.
2. If that gate passes, staff create or edit local items; the next shift sees unresolved items first and can acknowledge receipt.
3. A supervisor exports records for external review. A later evaluation compares the prototype with the paper baseline before any broader commitment.

**Success criteria**

- The paper gate has pre-agreed checks for field completeness and owner/next-action clarity; no outcome is assumed.
- The proposed prototype passes persistence, ordering, acknowledgement and export checks on a selected device and browser.
- A later, separately defined software-versus-paper comparison establishes whether software adds value.

## 4. Data

**Entities**

| Entity | Fields | Source |
| --- | --- | --- |
| handover_item | item_id: generated identifier, equipment_label: required text, issue_short: required text, current_owner: required text, next_action: required text, status: open \| awaiting_review \| closed, timestamp: creation time, updated_at: last edit time, acknowledged_by: optional entered initials, acknowledged_at: optional receipt time | Six core fields proposed in handover-concept; status and ownership ambiguity illustrated by synthetic sample-handover. Identifiers and metadata are design choices. |

**Evidence used as data**

| Evidence | Use |
| --- | --- |
| `handover-question` What should the next shift know? | Goal and validation question. |
| `sample-handover` Three sample handover notes | Synthetic examples of handover ambiguity, not field research. |
| `handover-concept` A single-device handover log | Candidate scope, fields, acknowledgement and exports. |

## 5. Architecture

Proposed vanilla JavaScript UI and direct IndexedDB, with bundled static assets served on the shared device at http://localhost:4173. No external requests or backend.

**Components**

| Component | Responsibility | Technology |
| --- | --- | --- |
| Staff UI | Create, edit, list and acknowledge items. | HTML, CSS, vanilla JavaScript |
| Local store | Persist records under the fixed origin. | Direct IndexedDB API |
| Exporter | Download outbound-only JSON and CSV. | Browser Blob and download link |
| Local static server | Serve bundled assets at the fixed origin. | Device-local static HTTP server |

**Interfaces**

| From | To | Protocol | Purpose |
| --- | --- | --- | --- |
| Staff UI | Local store | In-browser IndexedDB calls | Read and write items. |
| Staff UI | Exporter | In-browser function call | Produce local downloads. |
| Local static server | Staff UI | Loopback HTTP | Serve bundled assets. |

**Deployment:** Proposed fixed origin http://localhost:4173 on one shared device; choose the device, browser and local server before persistence testing. Initial loopback asset loads are expected; normal use makes no external requests.

## 6. Modules

| Id | Module | Purpose | Depends on |
| --- | --- | --- | --- |
| m1 | Local records | Schema, validation, persistence and unresolved-first query. | — |
| m2 | Handover UI | Create, edit, list and acknowledge receipt. | m1 |
| m3 | Outbound export | Download complete JSON and readable CSV without import. | m1, m2 |

## 7. Build waves

### Wave 1 · Wave 1 — Records and UI (sequential)

After the paper gate, implement and check m1, then m2.

Modules: m1, m2

### Wave 2 · Wave 2 — Export (sequential)

After Wave 1, implement m3 and check the integrated prototype.

Modules: m3

## 8. PRDs

### m1

**S1 · Save a six-field item**

- A valid item is saved at the fixed origin with generated item_id and timestamp.
- Missing equipment label, issue, owner or next action is rejected.

**S2 · Retrieve unresolved items first**

- Open and awaiting_review items appear before closed items; within each status, updated_at descending determines order.
- Saved items remain available after browser restart at the same origin.

### m2

**S3 · Create and edit from the tablet UI**

- The form exposes equipment label, issue, owner, next action and status; timestamp is set by the app.
- Editing an item updates updated_at and displays the saved values.

**S4 · Acknowledge receipt**

- Acknowledging stores entered initials and acknowledged_at and displays both.
- Comparing the stored record before and after acknowledgement shows current_owner and status unchanged.

### m3

**S5 · Export JSON**

- The downloaded JSON parses and contains every stored item and its metadata.
- The UI offers no import or restore action; export is not presented as in-app recovery.

**S6 · Export readable CSV**

- The CSV has one row per item and headers for item_id, the six core fields, updated_at, acknowledged_by and acknowledged_at.
- A proposed check opens the download and verifies that commas, quotes and line breaks in entered text remain within their CSV fields.

## Design system

- Show unresolved work first.
- Label owner and next action explicitly.
- Keep receipt acknowledgement distinct from issue ownership.

**Tone:** Plain and non-authoritative about safety. · **Colors:** High-contrast dark text on a light backg · **Typography:** System font; tablet legibility requires prototype review.

## Agent concurrency

Up to 1 builder(s) in parallel.

**Shared files (serialize edits)**

- src/store.js
- src/app.js
- src/export.js

**Rules**

- One builder at a time.
- Complete Wave 1 before Wave 2.
- Review changes to the record contract before dependent UI or export changes.

## Controls and tests

| Area | Check | Method |
| --- | --- | --- |
| Paper gate | Determine whether the structured paper checklist yields complete fields and unambiguous owners and next actions. | Proposed supervised paper pilot; agree measures, duration and pass criteria before collecting outcomes. |
| Later value comparison | Determine whether software improves on the validated paper baseline. | After the paper gate and prototype, pre-agree comparable measures and evaluate both processes separately. |
| Persistence and origin | Items survive browser restart and device power cycle at http://localhost:4173. | Proposed manual check on the selected device and browser; record origin and compare stored items before and after. |
| Ordering and receipt | Unresolved items lead; acknowledgement changes receipt metadata only. | Proposed mixed-status UI check and before/after IndexedDB record comparison. |
| Export and network | JSON parses, CSV columns and escaping are correct, and normal use makes no external requests. | Proposed fixture checks and browser network inspection; allow initial loopback asset requests. |

## Dependencies

| Dependency | Kind | Reason |
| --- | --- | --- |
| IndexedDB | standard | Local persistence at the fixed browser origin. |
| Device-local static HTTP server | service | Provides a stable localhost application origin. |

## Risks

| Risk | Mitigation |
| --- | --- |
| Synthetic notes do not establish user demand or ergonomic suitability. | Run the paper gate and review the prototype before adoption. |
| Changing origin or losing the single device may make records inaccessible; export cannot restore them in-app. | Fix the origin, test on the chosen device and agree an external retention and recovery policy. |
| Shared-device acknowledgements may not reliably identify a person. | Agree an initials and supervision policy outside the app. |
| Privacy and physical suitability of the tablet or paper checklist materials are unknown. | Resolve handling, access, retention and physical-use questions before any supervised pilot. |

## Open questions

- Which tablet, browser and local-server arrangement will be used?
- Who enters acknowledgement initials, and how is ambiguity handled?
- What are the device-unavailability, export-retention and recovery procedures?
- What privacy rules govern names, issue descriptions and exported files?
- What paper-checklist material and tablet placement are suitable?
- What pre-agreed paper-gate criteria and later comparison method are acceptable?

## Evidence

- `handover-question` What should the next shift know?
- `sample-handover` Three sample handover notes
- `handover-concept` A single-device handover log

## Recorded investigation basis

**Frozen scope:** my canvas revision 1

No linked decision is inferred; review the retained records before treating this draft as a commitment.

### Selected concept

_No selected named concept was present in the frozen package scope._

### Human decision records

_No selected human concept decision record._

### Exact selected material

- `handover-question` What should the next shift know? (content 1)
- `sample-handover` Three sample handover notes (content 1)
- `handover-concept` A single-device handover log (content 1)

## Frozen specification

**Export state:** Needs review · **Specification revision:** 1

**Specification digest:** `da945df18ef33c486d5a8016dfe1d97b066bcfae2cbaac190a180a66e41a432c`

No human approval for handoff is recorded for this exact specification revision. Downloading or copying this export does not approve it.

### R-001 · revision 1 · Needs review

Before software work, define and run a supervised structured-paper gate; assess software against paper only in a later, separate comparison.

**Acceptance**

- Document the paper measures and pass criteria before the paper pilot.
- Document a separate, pre-agreed software-versus-paper comparison before drawing a software value conclusion.

**Decision records**

_No exact human decision record._

**Evidence versions**

- canvas=my, nodeId=handover-question, contentRevision=1

**Assumptions**

- No real pilot results are supplied.

**Unresolved**

- Pilot duration, sample size and decision thresholds.

### R-002 · revision 1 · Needs review

Store the six-field handover item locally on one device at the fixed application origin, without an external service.

**Acceptance**

- Create an item and verify its six core fields in IndexedDB.
- At the same origin, verify it remains after browser restart; inspect normal use for external requests.

**Decision records**

_No exact human decision record._

**Evidence versions**

- canvas=my, nodeId=handover-concept, contentRevision=1

**Assumptions**

- The selected device can run a local static server and supports IndexedDB.

**Unresolved**

- Target device and browser.

### R-003 · revision 1 · Needs review

Present unresolved items first and allow creation, editing and receipt acknowledgement without transferring ownership.

**Acceptance**

- A mixed-status fixture displays open and awaiting_review before closed.
- Before/after record comparison confirms acknowledgement writes initials and time but leaves current_owner and status unchanged.

**Decision records**

_No exact human decision record._

**Evidence versions**

- canvas=my, nodeId=sample-handover, contentRevision=1
- canvas=my, nodeId=handover-concept, contentRevision=1

**Assumptions**

- Entered initials can be interpreted under an agreed workshop policy.

**Unresolved**

- Acknowledgement identity policy.

### R-004 · revision 1 · Needs review

Provide outbound JSON and readable CSV export; exclude JSON import and in-app restore.

**Acceptance**

- Parse a downloaded JSON file and compare its records with the stored set.
- Check CSV headers, row count and escaping against the same set.
- Confirm there is no import or restore control or claim.

**Decision records**

_No exact human decision record._

**Evidence versions**

- canvas=my, nodeId=handover-concept, contentRevision=1

**Assumptions**

- Supervisors can retain exports outside the app.

**Unresolved**

- Export retention and recovery policy.

### R-005 · revision 1 · Needs review

Keep the draft build to three modules, two sequential waves and one builder; exclude telemetry and an in-app paper-comparison view.

**Acceptance**

- Review the plan for exactly three modules, six stories, two sequential waves and one builder.
- Inspect proposed UI and checks for the absence of telemetry and a paper-comparison view.

**Decision records**

_No exact human decision record._

**Evidence versions**

- canvas=my, nodeId=handover-question, contentRevision=1

**Assumptions**

_None._

**Unresolved**

_None._

### Exact reference availability

- canvas=my, nodeId=handover-question, contentRevision=1 — **current**
- canvas=my, nodeId=handover-concept, contentRevision=1 — **current**
- canvas=my, nodeId=sample-handover, contentRevision=1 — **current**

### Honest unresolved context

**Contradictions, risks and missing evidence**

- Synthetic notes do not establish user demand or ergonomic suitability. — Run the paper gate and review the prototype before adoption.
- Changing origin or losing the single device may make records inaccessible; export cannot restore them in-app. — Fix the origin, test on the chosen device and agree an external retention and recovery policy.
- Shared-device acknowledgements may not reliably identify a person. — Agree an initials and supervision policy outside the app.
- Privacy and physical suitability of the tablet or paper checklist materials are unknown. — Resolve handling, access, retention and physical-use questions before any supervised pilot.

**Risks accepted for this exact handoff**

_None. This revision has no handoff approval._

**Unanswered questions**

- Which tablet, browser and local-server arrangement will be used?
- Who enters acknowledgement initials, and how is ambiguity handled?
- What are the device-unavailability, export-retention and recovery procedures?
- What privacy rules govern names, issue descriptions and exported files?
- What paper-checklist material and tablet placement are suitable?
- What pre-agreed paper-gate criteria and later comparison method are acceptable?
- Pilot duration, sample size and decision thresholds.
- Target device and browser.
- Acknowledgement identity policy.
- Export retention and recovery policy.

**Assumptions**

- No real pilot results are supplied.
- The selected device can run a local static server and supports IndexedDB.
- Entered initials can be interpreted under an agreed workshop policy.
- Supervisors can retain exports outside the app.

**Requirements without an exact decision record**

- R-001
- R-002
- R-003
- R-004
- R-005

**Pending claims / requirements awaiting human review**

- R-001
- R-002
- R-003
- R-004
- R-005

Some retained historical material is unavailable. Its frozen identifiers remain visible, but this export does not restore or disclose the unavailable private content.