# Workshop Handover: Single-Device Local Log (Draft)

A single-browser, single-device handover log (IndexedDB) capturing equipment, issue, owner, next action, status, timestamp, acknowledge and JSON/CSV export—draft for pilot validation.

**Kind:** software · **Investigation:** A clearer workshop handover · **Composed:** 2026-10-01T17:34:26.505Z · **Model:** openai gpt-5-mini

## 1. Problem space

**Who:** Two-shift small workshop staff and supervising manager responsible for safe, unambiguous maintenance handovers.

**Pain:** Ambiguous ownership, next action and closure at shift handover causes delays and unclear responsibilities (sample synthetic notes show this ambiguity).

**Context:** A teaching-case proposal: single shared tablet in the workshop capturing a 6-field minimal record to reduce handover ambiguity; no cloud, auth, notifications or integrations. Software justified only after a paper-checklist pilot.

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

A minimal local-browser app on one shared tablet that stores handover items in IndexedDB, presents unresolved items first, supports an acknowledge action, and exports data as JSON and human-readable CSV for supervisor review and archival.

**Differentiators**

- Single-device, local-only IndexedDB persistence to match workshop constraints and privacy.
- Strict six-field minimal model (equipment_label, issue_short, current_owner, next_action, status, timestamp) derived from the idea node.
- Designed as a lightweight follow-up to a validated paper checklist; no integrations, auth, notifications or automated decisions.

**Non-goals**

- No backend, cloud, authentication, sync, notifications, AI, machine control or integrations (explicit exclusion).
- Does not include safety sign-off, automated fault diagnosis, or supervisor authority within the app.

## 3. Concept

**User journey**

1. Shift-end operator opens the shared tablet app, creates or updates an item with required fields, app stores item to IndexedDB with system timestamp.
2. Next-shift opens app; the UI sorts unresolved items first; operator can 'acknowledge' an item (records acknowledge timestamp and initials) or edit next_action and owner.
3. Supervisor periodically exports JSON/CSV from the device and reviews externally; closure decisions are made outside the app.

**Success criteria**

- App runs entirely in a modern Chromium-based mobile/desktop browser on a single shared device with local storage only.
- IndexedDB persists entries across browser restarts and device power cycles on the same device and origin.
- Exports produce a JSON file with full records and a readable CSV mapping the six fields plus acknowledge metadata.
- UI orders unresolved items first and exposes an acknowledge action that records user-entered initials and timestamp.

## 4. Data

**Entities**

| Entity | Fields | Source |
| --- | --- | --- |
| handover_item | item_id: uuid (system-generated), equipment_label: string (required), issue_short: string (<=140 chars, required), current_owner: string (initials or name, required), next_action: string (required), status: enum [open, awaiting_review, closed] (required), created_at: ISO8601 timestamp (system), updated_at: ISO8601 timestamp (system), acknowledged_by: string (optional initials), acknowledged_at: ISO8601 timestamp (optional) | Derived from handover-concept and sample-handover |

**Evidence used as data**

| Evidence | Use |
| --- | --- |
| `handover-question` What should the next shift know? | Defines problem scope and validation goal |
| `sample-handover` Three sample handover notes | Illustrates ambiguity and minimal fields needed |
| `handover-concept` A single-device handover log | Specifies single-device constraint and required fields |

## 5. Architecture

Single-page web app (PWA-lite not installed) running in-browser on a single shared device/origin, using IndexedDB (via Dexie.js) for persistence, vanilla JS or a compact framework (Svelte/Preact) for UI, CSV/JSON export to file, no network calls.

**Components**

| Component | Responsibility | Technology |
| --- | --- | --- |
| UI Shell | Render list, item create/edit form, acknowledge action and export buttons; sort unresolved first | Svelte or Preact, plain CSS |
| Local Storage Layer | IndexedDB schema, CRUD, migrations, export serialization | Dexie.js (or direct IndexedDB API) |
| Export/Serialization | Produce JSON and human-readable CSV and trigger file download | JSON.stringify, Blob, FileSaver.js or native anchor download |

**Interfaces**

| From | To | Protocol | Purpose |
| --- | --- | --- | --- |
| UI Shell | Local Storage Layer | in-browser JS function calls / Promise API | CRUD operations and queries (unresolved-first sort) |
| UI Shell | Export/Serialization | in-memory data serialization | Export current dataset to JSON/CSV file |

**Deployment:** Serve static HTML/CSS/JS files on the shared device filesystem or local file server; open index.html in a modern Chromium-based browser that supports IndexedDB.

## 6. Modules

| Id | Module | Purpose | Depends on |
| --- | --- | --- | --- |
| m1 | Core data model & storage | Implement IndexedDB schema, migrations, and API for CRUD and queries (unresolved-first). | — |
| m2 | UI and acknowledgement flow | List view sorted unresolved-first, create/edit form, acknowledge action recording initials and timestamp. | m1 |
| m3 | Export & pilot tooling | JSON and CSV export, simple pilot-mode telemetry (local only), and paper-checklist comparison view for supervisors. | m1, m2 |

## 7. Build waves

### Wave 1 · Wave 1 — Core storage and basic UI (parallel)

Deliver M1 and minimal M2 list/create/acknowledge UI; verify persistence and unresolved-first ordering.

Modules: m1, m2

### Wave 2 · Wave 2 — Export and pilot support (sequential)

Deliver M3 export features, pilot view and finalize acceptance checks for supervised trial.

Modules: m3

## 8. PRDs

### m1

**S1 · IndexedDB schema and CRUD**

- IndexedDB schema implements handover_item with required fields; records persist after browser restart.
- Automated test: write 3 items, reload page, query unresolved items and receive same 3 items.

**S2 · Unresolved-first query and migration**

- Query API returns items sorted: open and awaiting_review before closed; stable sorting by updated_at desc within status.
- Migration test: simulate older record without acknowledged_at; app upgrades schema without data loss.

### m2

**S3 · Create / Edit / Acknowledge UI**

- User can create an item with all required fields; create sets created_at and updated_at automatically.
- Acknowledge action records acknowledged_by and acknowledged_at; UI shows acknowledge metadata.
- Manual checklist comparison: map a paper checklist entry to a saved item in-app and verify fields align.

**S4 · Local usage ergonomics**

- On-screen form uses compact inputs suitable for tablet; required fields validated client-side.
- List view shows clear indicators for status and owner initials.

### m3

**S5 · JSON export**

- Export produces a single JSON file containing all handover_item records including metadata (created_at, updated_at, acknowledged_*).
- Downloaded JSON loads back into the app when re-imported (file-based import optional for recovery).

**S6 · CSV export and pilot view**

- Export produces a readable CSV mapping six core fields plus acknowledge metadata; column headers are human-readable.
- Pilot view shows side-by-side mapping with the one-page paper checklist fields for supervisor comparison.

## Design system

- Minimal: show only required fields and unresolved items up-front.
- Robust: work offline and tolerate abrupt app/browser restarts.
- Transparent: exports are human-readable and directly comparable to the paper checklist.

**Tone:** Plain, high-contrast, legible for workshop lighting · **Colors:** High-contrast text (dark on light), stat · **Typography:** System UI fonts, large touch targets for tablet use

## Agent concurrency

Up to 1 builder(s) in parallel.

**Shared files (serialize edits)**

- schema/indexeddb-schema.json
- data-model/handover_item.json
- storage/migrations.js

**Rules**

- Only one builder agent works at a time (serial).
- All edits to sharedFiles must be done serially and reviewed by a human before committing.
- Feature branches are allowed but merges touching sharedFiles require explicit human merge and sanity check on migration tests.

## Controls and tests

| Area | Check | Method |
| --- | --- | --- |
| Persistence | Records persist across browser restart and device power cycle on the same origin | Manual test: create items, close browser, restart, verify items present |
| Export | JSON and CSV exports contain all fields and are syntactically valid | Automated unit test for JSON validity and CSV header/row counts; manual open of CSV in spreadsheet |
| Ordering and ACK | UI lists unresolved items first and acknowledge records initials+timestamp | End-to-end manual verification with sample dataset (three items) and UI observation |
| Paper comparison | App fields map 1:1 to the laminated paper checklist | Supervisor-led mapping session: take 5 recent paper checklist entries and confirm mapping to in-app items |

## Dependencies

| Dependency | Kind | Reason |
| --- | --- | --- |
| Dexie.js | library | Simplifies IndexedDB schema/migrations and is lightweight for single-device apps |
| FileSaver.js or native Blob download | library | Triggering reliable client-side file downloads for JSON/CSV |

## Risks

| Risk | Mitigation |
| --- | --- |
| No real users interviewed; app may not match real ergonomic needs. | Run short supervised pilot using paper checklist mapping before software pilot; keep UI minimal and iterate. |
| Single-device usage can fail if tablet is unavailable or browser origin changes. | Provide clear device usage policy and local backup via manual JSON export; test recovery via import. |

## Open questions

- What exact tablet model and browser will be used in pilot (affects touch layout and IndexedDB behavior)?
- Who will enter initials for acknowledge action and how will identity ambiguity be handled (initials vs full name)?
- What duration/size of supervised pilot is considered sufficient by stakeholders to decide for a software build?

## 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 2

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:** `5aeb57870ef9f453f68a5acc3b21d64a8aab07a0981f76d2c37dd0a2f5ac2058`

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

Implement a local-only handover_item schema in IndexedDB with the six fields (equipment_label, issue_short, current_owner, next_action, status, timestamp) plus acknowledge metadata; no network calls.

**Acceptance**

- IndexedDB contains handover_item records with required fields and acknowledge metadata.
- No outbound network/XHR/fetch calls are made during normal CRUD operations (validated via devtools network tab).

**Decision records**

_No exact human decision record._

**Evidence versions**

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

**Assumptions**

_None._

**Unresolved**

_None._

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

App UI must display unresolved items first and allow create/edit of the six-field model and an acknowledge action that records initials and timestamp.

**Acceptance**

- List view sorts unresolved statuses (open, awaiting_review) above closed and shows updated_at ordering within each status.
- Acknowledge action prompts for initials and stores acknowledged_by and acknowledged_at.

**Decision records**

_No exact human decision record._

**Evidence versions**

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

**Assumptions**

_None._

**Unresolved**

_None._

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

Provide JSON and human-readable CSV export of the full dataset, downloadable from the device without network usage.

**Acceptance**

- Exported JSON is a valid JSON file containing all handover_item records.
- Exported CSV has headers mapping to core fields and can be opened in a spreadsheet application.

**Decision records**

_No exact human decision record._

**Evidence versions**

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

**Assumptions**

_None._

**Unresolved**

_None._

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

The system must be single-device and local-origin only: deploy as static files to the device and require no backend or cloud services.

**Acceptance**

- All functionality works with files served from local filesystem or static server and without network connectivity.
- Devtools network panel shows zero network requests during normal use (except optional manual export/import file reads).

**Decision records**

_No exact human decision record._

**Evidence versions**

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

**Assumptions**

_None._

**Unresolved**

_None._

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

The build must include a supervisor-facing paper-checklist comparison view and instructions to run a supervised pilot before committing to broader software development.

**Acceptance**

- UI exposes a pilot view that maps in-app fields to the one-page laminated checklist format.
- Documentation includes clear pilot instructions: how to run the paper-checklist mapping session and record outcomes locally.

**Decision records**

_No exact human decision record._

**Evidence versions**

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

**Assumptions**

_None._

**Unresolved**

_None._

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

Provide developer controls and tests proving persistence, export correctness, unresolved-first ordering and acknowledge behavior before pilot start.

**Acceptance**

- Automated and manual tests cover persistence, export validity, ordering and acknowledge metadata; report produced before pilot.
- AgentConcurrency rules enforced: single-builder merge for shared schema/storage files.

**Decision records**

_No exact human decision record._

**Evidence versions**

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

**Assumptions**

_None._

**Unresolved**

_None._

### Exact reference availability

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

### Honest unresolved context

**Contradictions, risks and missing evidence**

- No real users interviewed; app may not match real ergonomic needs. — Run short supervised pilot using paper checklist mapping before software pilot; keep UI minimal and iterate.
- Single-device usage can fail if tablet is unavailable or browser origin changes. — Provide clear device usage policy and local backup via manual JSON export; test recovery via import.

**Risks accepted for this exact handoff**

_None. This revision has no handoff approval._

**Unanswered questions**

- What exact tablet model and browser will be used in pilot (affects touch layout and IndexedDB behavior)?
- Who will enter initials for acknowledge action and how will identity ambiguity be handled (initials vs full name)?
- What duration/size of supervised pilot is considered sufficient by stakeholders to decide for a software build?

**Assumptions**

_None._

**Requirements without an exact decision record**

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

**Pending claims / requirements awaiting human review**

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