📥 Stream 3 deliverable (GPT-5.5 Pro/Extended). Prompt: PROMPT-packet-3-construction-sop · context: packet-0-shared-base-context · feeds → PROMPT-packet-4-live-demo-spec. Dashboard: Dashboard · findings: RESEARCH-FINDINGS-AND-DECISIONS.

I reviewed the attached context pack and used it as the product constraint set. The practical answer is this: do not build “AI site diaries.” Build a commercial-event capture system that happens to produce a good diary. The diary is the record container. The Commercial Event is the product object.

A. Executive summary

A useful construction field-capture SOP should work like this:

Voice note + photos + files
        ↓
Transcript
        ↓
Structured daily facts
        ↓
Commercial event detection
        ↓
Missing evidence prompts
        ↓
PM / QS review
        ↓
Diary, event card, evidence pack, email/RFI/variation draft
        ↓
Export to Procore / PDF / Excel / SharePoint / email

The daily diary schema should cover normal site-record fields: project, date, weather, reporting person, labour, plant, visitors, inspections, deliveries, scheduled work, photos, delays, accidents/safety, productivity, quantities, plan revisions, and change history. Procore’s Daily Log structure is a useful market reference because it already separates weather, manpower, equipment, visitors, phone calls, inspections, deliveries, scheduled work, safety, accidents, quantities, productivity, photos, delays, and change history. It also records workers, hours, companies, cost codes, equipment usage, delivery contents, and daily photos. citeturn650330view0

For UK-style site diaries, the record should be chronological, time-stamped, factual, and commercially useful. Procore’s UK guidance frames the site diary as a real-time project record used for project management, communication, risk reduction, JCT/NEC evidence, labour/attendance, work activities, materials, equipment, inspections, safety, budget/resource impact, and next steps. citeturn650330view1

The strongest evidence design should follow the Society of Construction Law’s record-keeping logic: daily records should capture weather, manpower, key material deliveries, adverse conditions, working hours, major plant/equipment, work activities, obstruction data, inspection records, progress photos, procurement records, delivery records, labour/equipment allocation, material logs, and cost records. The SCL Protocol also says progress/resource/cost records should state facts, not opinions, and should be signed by authorised representatives where reasonably practicable. citeturn233353view2 citeturn233353view3

The product should not make contractual claims. It should say:

Possible commercial issue detected.
Evidence exists / missing evidence exists.
Human review required before RFI, notice, variation, claim, or formal correspondence.

That matters because variations and compensation events are contract-specific. A variation is broadly a change to originally contracted scope, and NEC compensation events are contractual mechanisms that may adjust price and/or completion dates, but whether a particular site event qualifies depends on the contract, facts, procedure, notices, and reviewer judgement. citeturn348762search2 citeturn382540search0

The core product rule should be:

No source → no claim.
Weak source → uncertain fact.
Conflicting source → human review.
Commercial implication → suggested action only.
Formal output → approval required.

B. Standard daily diary field schema

B1. Daily diary field schema

B2. Field-capture SOP

1. Site manager opens magic link.
2. App pre-fills project, date, reporter, weather if available.
3. Site manager records voice note.
4. Site manager uploads photos/files.
5. AI transcribes voice note.
6. AI extracts daily facts.
7. AI detects commercial events.
8. AI checks missing evidence.
9. AI asks 1–3 follow-ups only.
10. Site manager answers by voice/text/upload.
11. System creates:
    - diary draft
    - event cards
    - evidence checklist
    - PM/QS action queue
12. PM/QS reviews.
13. Approved outputs export to PDF/email/Excel/Procore/SharePoint.

Field prompt shown to site manager:

Tell us:
- What was planned today?
- What actually happened?
- Any delays, instructions, missing materials, rework, access issues, or labour standing?
- Upload photos or delivery notes if you have them.

Do not ask the site manager to fill a long form. That is how this dies.

C. Commercial event taxonomy table

Use CommercialEvent as the central object. The diary, dashboard, emails, RFIs, and evidence packs are views over events.

C1. Event taxonomy

D. Missing evidence rules table

D1. Evidence priority levels

P0 = safety / statutory / immediate hidden-works risk
P1 = high commercial risk; evidence may disappear today
P2 = commercially useful but can wait 24–48h
P3 = nice-to-have context

The system should not ask every possible question. It should ask the highest-value missing fact first.

D2. Missing evidence behaviour

If evidence exists:
    ask for upload.
If evidence does not exist:
    ask user to mark unavailable and explain why.
If evidence is expected from someone else:
    create task for owner.
If evidence conflicts:
    flag conflict; do not resolve automatically.
If event is commercially significant and evidence remains missing:
    keep event open in QS/PM review queue.

E. Follow-up question decision tree

E1. Follow-up design principles

The follow-up system should behave like a sharp assistant, not a form.

Rules:

1. Ask max 1–3 questions per round.
2. Ask only questions that change commercial usefulness.
3. Prefer one combined question over three tiny ones.
4. Let the user answer by voice, text, photo, or file upload.
5. Do not ask for fields already present in source evidence.
6. Do not ask legal/entitlement questions to site managers.
7. Escalate PM/QS questions to PM/QS, not site.
8. Stop once the event is reviewable, not perfect.

E2. Decision tree

START
  ↓
Parse voice/photos/files
  ↓
Any P0 safety or hidden-works issue?
  ├── Yes → ask immediate evidence/escalation question
  │        "Upload photo before close-up" / "Record incident details"
  │
  └── No
       ↓
Detect commercial event?
  ├── No → create diary draft only
  │
  └── Yes
       ↓
Does event have minimum commercial facts?
       Minimum = what + where + when + affected activity + evidence
       ↓
  Missing "what/where/when"?
  ├── Yes → ask factual clarification first
  │
  └── No
       ↓
  Missing volatile evidence?
  ├── Yes → ask upload question
  │        delivery note / photo / instruction / markup / pre-close photo
  │
  └── No
       ↓
  Missing impact data?
  ├── Yes → ask labour/programme/quantity question
  │
  └── No
       ↓
  Human review needed?
  ├── PM → coordination/programme/action
  ├── QS → cost/change/evidence
  ├── Commercial manager → notice/claim/high-risk
  └── Estimator → tender assumption/original scope basis

E3. Example follow-up bundles

Late delivery:

1. What time was the partition track expected or needed on site?
2. Were the dryliners idle, reassigned, or working on other tasks before it arrived?
3. Can you upload the delivery note, or confirm it is missing?

Verbal instruction:

1. Who gave the instruction, and what is their company/role?
2. What exactly changed from the current drawing/spec/scope?
3. Is there any written confirmation? Upload it if yes.

Drawing/spec conflict:

1. Which drawing and spec references conflict?
2. What work is blocked or at risk because of the conflict?
3. Upload a photo/markup showing the issue.

Hidden works:

1. Upload a photo before this is closed up.
2. Which location/room/grid does it show?
3. Has inspection/sign-off happened yet?

E4. Output structures

A. Daily diary draft

Header
Site conditions
Labour and plant
Planned work
Completed work
Incomplete work and reasons
Deliveries/materials
Instructions/RFIs/variations
Quality/safety/inspections
Commercial events detected
Missing evidence
PM/QS follow-up actions
Evidence attachments
Approval/export status

B. Commercial event card

Event title
Event type
Severity
Location
Date/time
Confirmed facts
Inferred facts
Missing facts
Conflicting facts
Evidence panel
Affected activity/package
Possible commercial relevance
Suggested actions
Review owner
Status

C. Missing evidence checklist

Missing item
Why it matters
Linked event
Owner
Priority
Due date
Accepted alternatives
Status

D. PM/QS review queue

Event ID
Project
Date
Type
Severity
Owner
Missing evidence count
Suggested action
Review state
Age
Export status

E. Evidence pack

Event summary
Timeline
Source transcript excerpts
Photo/file table
Delivery notes / emails / programme extracts
Missing evidence log
Review decisions
Exported PDF bundle

F. Draft confirmation email

To / CC
Subject
Factual summary only
Requested confirmation
Attachments
No entitlement language unless approved
Reviewer approval block

G. Draft RFI / variation note skeleton

Title
Location
Background facts
Question / change description
Relevant document references
Required response date
Programme/cost impact: TBC unless reviewed
Attachments
Prepared by
Requires PM/QS/commercial approval

H. Weekly commercial risk digest

Open commercial events by project/package
High-severity events
Missing evidence ageing
Potential RFIs
Potential variations
Potential notice review items
Overdue owner actions
Evidence captured this week
Events closed/exported

E5. Confidence and uncertainty rules

F. Example end-to-end scenario output

F1. Project metadata

Project: Commercial office fit-out
Package: Drylining / partitions
Area: Level 2 Zone B
Date: 2026-06-16
Reporter: Tom Harris, Site Manager
Planned activity: DRY-L2-ZB-014 — install partition track, Level 2 Zone B
Planned start: 08:00
Material: Partition track
Expected delivery: not stated in first voice note
Actual delivery: 13:32, per site manager voice note
Labour: 6 dryliners on site
Reassignment: 2 operatives reassigned
Delivery note: missing
Photos: 6 uploaded

F2. Example voice note transcript

“Quick update for Level 2 Zone B. Drylining was meant to start first thing at eight, but the partition track wasn’t here. We had six dryliners in. The track eventually turned up at 13:32. I moved two of the lads onto Level 1 snagging around quarter past eleven because they were just waiting around. The other four stayed on Level 2 doing what they could, but they couldn’t start the track install properly until the delivery came in. I’ve taken photos of the delivery and the Zone B area. I don’t have the delivery note — driver said it was with the office, but I haven’t got a copy. We need QS to know because this has knocked today’s drylining plan.”

F3. Structured extraction

F4. Follow-up questions

Round 1 — ask only three:

1. What time was the partition track expected or required on site?
2. Who was the supplier, and can you upload the delivery note or confirm it is unavailable?
3. Were the remaining four dryliners idle, doing useful alternative work, or only partial prep before the track arrived?

Example site manager answers:

1. Needed by 08:00 for planned start. Supplier was told morning delivery, but I don’t have the supplier email.
2. Supplier was BuildLine Interiors. Delivery note is unavailable at the moment; I’ll ask the office.
3. The four on Level 2 did setting out and tidying, but no track install until after the delivery.

F5. Completed daily diary draft

DAILY DIARY — DRAFT

Project: Commercial office fit-out
Date: 2026-06-16
Reporter: Tom Harris, Site Manager
Area: Level 2 Zone B
Package: Drylining / partitions

Weather:
No weather impact reported.

Planned work:
Drylining team planned to start partition track installation in Level 2 Zone B at 08:00 under activity DRY-L2-ZB-014.

Labour:
6 dryliners on site for Level 2 Zone B.
At approx. 11:15, 2 dryliners were reassigned to Level 1 snagging.
4 dryliners remained on Level 2 and carried out setting out/tidying only. Track installation could not start properly until partition track arrived.

Deliveries:
Partition track delivery arrived at 13:32.
Supplier reported by site manager as BuildLine Interiors.
Delivery note not uploaded. Site manager to request copy from office/supplier.
Photos of delivery and Level 2 Zone B uploaded.

Work completed:
Limited setting out/tidying carried out before delivery.
Partition track installation started after delivery at 13:32. Quantity installed not confirmed.

Incomplete work / blockers:
Planned 08:00 drylining start in Level 2 Zone B was blocked by absence of partition track.
Expected/required delivery time recorded as 08:00 based on planned start. Supplier confirmation not uploaded.

Commercial events detected:
CE-001 Late delivery — partition track arrived 13:32.
CE-002 Reassigned / potentially idle labour — 6 dryliners affected; 2 reassigned at approx. 11:15; 4 remained on Level 2 on limited prep.
CE-003 Missing evidence — delivery note missing; supplier confirmation missing.

PM/QS follow-up:
QS to review possible labour/productivity impact.
PM to confirm whether activity DRY-L2-ZB-014 programme completion was affected.
Site manager/procurement to obtain delivery note and supplier delivery confirmation.

F6. Commercial event card

Commercial Event CE-001

Title:
Partition track late delivery affected Level 2 Zone B drylining start.

Type:
Late delivery + labour disruption + missing delivery note.

Severity:
Medium-high for demo.
Commercial significance: uncertain until QS/PM review.

Date/time:
2026-06-16.
Planned drylining start: 08:00.
Delivery arrival: 13:32.

Location:
Level 2 Zone B.

Confirmed facts:
- Drylining planned to start at 08:00.
- Six dryliners were on site.
- Partition track arrived at 13:32.
- Two dryliners were reassigned to Level 1 snagging at approx. 11:15.
- Four dryliners remained on Level 2 but could not start track installation properly before delivery.
- Delivery note is missing/not uploaded.
- Photos uploaded.

Inferred facts:
- Planned drylining start was delayed by 5h32m from 08:00 to 13:32.
- Potential affected planned drylining time:
  - 6 operatives from 08:00–11:15 = 19.5 operative-hours.
  - 4 operatives from 11:15–13:32 = 9.1 operative-hours.
  - Total potential affected planned drylining time = 28.6 operative-hours.
- This is not the same as recoverable cost. QS review required.

Missing facts:
- Supplier delivery note.
- Supplier promised/confirmed delivery window.
- Quantity delivered.
- Quantity installed after delivery.
- Whether programme activity DRY-L2-ZB-014 completion date moved.
- Cost code / subcontractor labour rate.

Suggested actions:
1. Site manager/procurement: obtain delivery note.
2. PM: confirm programme impact against lookahead/programme.
3. QS: review labour impact and whether any contractual/commercial action is required.
4. Draft confirmation email available for PM/QS approval.

Review state:
Needs QS review.
Needs PM programme review.
Evidence incomplete.

F7. Missing evidence checklist

F8. Suggested PM/QS actions

PM action:
Confirm whether activity DRY-L2-ZB-014 was delayed, resequenced, or recovered same day.
Attach relevant lookahead/programme extract.

QS action:
Review potential affected planned drylining hours.
Do not treat 28.6 operative-hours as a claim value. It is an inferred exposure requiring labour records, subcontract terms, mitigation review, and contract review.

Procurement action:
Request delivery note and supplier delivery confirmation from BuildLine Interiors.

Site manager action:
Label uploaded photos:
- delivery arrival
- partition track
- Level 2 Zone B workface
- drylining area before start

F9. Draft confirmation email

Subject: Project record — partition track delivery to Level 2 Zone B on 16 June

To: [PM / Supplier / Procurement — to be selected]
CC: [QS], [Site Manager]
Status: Draft — PM/QS approval required before sending

Hi [Name],

For the project record, please confirm the following regarding the partition track delivery for Level 2 Zone B on 16 June:

- Drylining / partition track installation was planned to start in Level 2 Zone B at 08:00.
- Six dryliners were on site for the planned works.
- The partition track delivery arrived on site at 13:32.
- Two dryliners were reassigned to Level 1 snagging at approximately 11:15.
- The delivery note has not yet been received/uploaded.

Please confirm:
1. the delivery note number and a copy of the delivery note;
2. the supplier’s planned/confirmed delivery window;
3. the quantity of partition track delivered.

Photos from site are attached for reference.

Regards,  
[Sender]

Attachments:
- Photo P001 — Level 2 Zone B workface
- Photo P002 — partition track delivery
- Photo P003 — material label/pallet

No entitlement language. No “claim.” No “you caused delay.” Just facts and confirmation.

F10. Evidence pack table

F11. Bad output examples and factual rewrites

G. JSON-style schemas

These are intentionally product schemas, not legal schemas.

{
  "DailyDiary": {
    "type": "object",
    "required": ["diary_id", "project_id", "date", "reporter", "review_state"],
    "properties": {
      "diary_id": "string",
      "project_id": "string",
      "project_name": "string",
      "contract_or_package": "string",
      "date": "YYYY-MM-DD",
      "timezone": "string",
      "reporter": {
        "user_id": "string",
        "name": "string",
        "role": "string",
        "company": "string"
      },
      "working_hours": {
        "planned_start": "HH:mm",
        "planned_finish": "HH:mm",
        "actual_start": "HH:mm",
        "actual_finish": "HH:mm"
      },
      "weather": {
        "source": "manual|api|unknown",
        "conditions": "string",
        "temperature_c": "number|null",
        "rainfall_mm": "number|null",
        "wind_speed_mph": "number|null",
        "impact_reported": "boolean",
        "impact_notes": "string|null"
      },
      "locations": [
        {
          "building": "string",
          "level": "string",
          "zone": "string",
          "room": "string|null",
          "gridline": "string|null"
        }
      ],
      "labour": [
        {
          "company": "string",
          "trade": "string",
          "headcount": "integer",
          "start_time": "HH:mm|null",
          "end_time": "HH:mm|null",
          "hours": "number|null",
          "status": "working|idle|reassigned|stood_down|unknown",
          "activity": "string|null",
          "cost_code": "string|null",
          "notes": "string|null"
        }
      ],
      "plant_equipment": [
        {
          "item": "string",
          "company": "string|null",
          "hours_used": "number|null",
          "inactive_hours": "number|null",
          "downtime_reason": "string|null",
          "inspection_status": "passed|failed|not_applicable|unknown"
        }
      ],
      "planned_work": [
        {
          "activity_id": "string|null",
          "description": "string",
          "location": "string",
          "planned_start": "HH:mm|null",
          "planned_finish": "HH:mm|null",
          "planned_resource": "string|null"
        }
      ],
      "completed_work": [
        {
          "description": "string",
          "location": "string",
          "quantity": "number|null",
          "unit": "string|null",
          "evidence_ids": ["string"]
        }
      ],
      "incomplete_work": [
        {
          "description": "string",
          "location": "string",
          "reason": "string",
          "linked_event_id": "string|null"
        }
      ],
      "deliveries": [
        {
          "supplier": "string|null",
          "material": "string",
          "expected_time": "HH:mm|null",
          "actual_time": "HH:mm|null",
          "quantity": "number|null",
          "unit": "string|null",
          "delivery_note_id": "string|null",
          "condition": "ok|damaged|incomplete|unknown",
          "evidence_ids": ["string"]
        }
      ],
      "instructions": [
        {
          "instruction_type": "verbal|email|formal_instruction|meeting|unknown",
          "given_by": "string|null",
          "company": "string|null",
          "role": "string|null",
          "time": "HH:mm|null",
          "description": "string",
          "written_confirmation_status": "attached|missing|not_required|unknown",
          "linked_event_id": "string|null"
        }
      ],
      "rfis": [
        {
          "rfi_id": "string|null",
          "status": "potential|draft|submitted|answered|closed|unknown",
          "question": "string",
          "drawing_refs": ["string"],
          "spec_refs": ["string"],
          "due_date": "YYYY-MM-DD|null",
          "linked_event_id": "string|null"
        }
      ],
      "quality_safety": [
        {
          "type": "inspection|defect|hold_point|incident|near_miss|permit",
          "description": "string",
          "location": "string|null",
          "severity": "low|medium|high|critical|unknown",
          "evidence_ids": ["string"],
          "escalation_required": "boolean"
        }
      ],
      "commercial_event_ids": ["string"],
      "evidence_item_ids": ["string"],
      "missing_evidence_request_ids": ["string"],
      "suggested_action_ids": ["string"],
      "review_state": "ReviewState",
      "exports": [
        {
          "export_type": "pdf|email|excel|procore|sharepoint",
          "exported_at": "datetime",
          "exported_by": "string",
          "destination": "string"
        }
      ],
      "audit_log": [
        {
          "timestamp": "datetime",
          "actor": "string",
          "action": "created|edited|approved|rejected|exported",
          "details": "string"
        }
      ]
    }
  },

  "CommercialEvent": {
    "type": "object",
    "required": ["event_id", "project_id", "event_type", "title", "date", "review_state"],
    "properties": {
      "event_id": "string",
      "project_id": "string",
      "diary_id": "string",
      "event_type": "late_delivery|missing_material|damaged_material|access_blocked|design_info_missing|drawing_spec_conflict|verbal_instruction|client_consultant_instruction|scope_change|abortive_labour|idle_labour|reassigned_labour|out_of_sequence|rework|quality_hold|hidden_works|inspection_result|weather_delay|subcontractor_delay|supplier_delay|programme_slippage|potential_rfi|potential_variation|potential_notice|missing_evidence|claim_supporting_evidence",
      "title": "string",
      "date": "YYYY-MM-DD",
      "time_start": "HH:mm|null",
      "time_end": "HH:mm|null",
      "location": {
        "building": "string|null",
        "level": "string|null",
        "zone": "string|null",
        "room": "string|null",
        "gridline": "string|null"
      },
      "source_summary": "string",
      "confirmed_facts": [
        {
          "fact": "string",
          "source_evidence_ids": ["string"],
          "confidence": "high|medium|low"
        }
      ],
      "inferred_facts": [
        {
          "inference": "string",
          "basis_evidence_ids": ["string"],
          "formula_or_reasoning": "string|null",
          "confidence": "high|medium|low"
        }
      ],
      "missing_facts": [
        {
          "field": "string",
          "why_needed": "string",
          "priority": "P0|P1|P2|P3"
        }
      ],
      "conflicting_facts": [
        {
          "field": "string",
          "source_a": "string",
          "source_b": "string",
          "resolution_status": "unresolved|resolved_by_reviewer"
        }
      ],
      "affected_activity": {
        "programme_activity_id": "string|null",
        "description": "string|null",
        "planned_start": "datetime|null",
        "planned_finish": "datetime|null",
        "programme_impact_status": "none|possible|confirmed|unknown"
      },
      "resource_impact": {
        "labour_headcount": "integer|null",
        "trade": "string|null",
        "affected_hours_estimate": "number|null",
        "plant_impact": "string|null",
        "material_impact": "string|null"
      },
      "commercial_significance": "none|low|medium|high|unknown",
      "severity": "low|medium|high|critical",
      "human_review_required": "boolean",
      "review_roles": ["site_manager", "pm", "qs", "commercial_manager", "estimator", "design_manager", "qa"],
      "suggested_action_ids": ["string"],
      "evidence_item_ids": ["string"],
      "missing_evidence_request_ids": ["string"],
      "review_state": "ReviewState"
    }
  },

  "EvidenceItem": {
    "type": "object",
    "required": ["evidence_id", "type", "captured_at", "source_channel"],
    "properties": {
      "evidence_id": "string",
      "type": "voice_transcript|photo|video|delivery_note|email|whatsapp|programme_extract|drawing|specification|rfi_log|variation_log|timesheet|inspection_report|permit|other",
      "file_name": "string|null",
      "source_channel": "pwa|email|whatsapp|procore|sharepoint|manual_upload|api",
      "captured_at": "datetime|null",
      "uploaded_at": "datetime",
      "uploaded_by": "string",
      "created_by_original": "string|null",
      "hash": "string|null",
      "metadata": {
        "mime_type": "string|null",
        "exif_timestamp": "datetime|null",
        "gps_lat": "number|null",
        "gps_lng": "number|null",
        "page_number": "integer|null",
        "document_ref": "string|null"
      },
      "description": "string",
      "linked_project_id": "string",
      "linked_diary_id": "string|null",
      "linked_event_ids": ["string"],
      "supports_facts": ["string"],
      "evidence_status": "raw|processed|labelled|verified|rejected|missing|superseded",
      "access_control": {
        "visibility": "internal|project_team|restricted",
        "restricted_reason": "string|null"
      }
    }
  },

  "MissingEvidenceRequest": {
    "type": "object",
    "required": ["request_id", "event_id", "priority", "requested_item", "status"],
    "properties": {
      "request_id": "string",
      "event_id": "string",
      "trigger_rule_id": "string",
      "priority": "P0|P1|P2|P3",
      "requested_item": "delivery_note|photo|programme_extract|drawing_ref|spec_ref|timesheet|supplier_confirmation|written_instruction|inspection_report|quantity|time|person|location|other",
      "question_text": "string",
      "why_needed": "string",
      "acceptable_alternatives": ["string"],
      "owner_role": "site_manager|pm|qs|commercial_manager|procurement|design_manager|qa",
      "owner_user_id": "string|null",
      "due_by": "datetime|null",
      "status": "open|answered|uploaded|unavailable|waived_by_reviewer|overdue|closed",
      "response": {
        "answer_text": "string|null",
        "evidence_item_ids": ["string"],
        "responded_by": "string|null",
        "responded_at": "datetime|null"
      }
    }
  },

  "FollowUpQuestion": {
    "type": "object",
    "required": ["question_id", "prompt", "priority", "expected_answer_type"],
    "properties": {
      "question_id": "string",
      "event_id": "string|null",
      "prompt": "string",
      "reason": "string",
      "priority": "P0|P1|P2|P3",
      "expected_answer_type": "short_text|long_text|time|date|number|single_choice|multi_choice|photo_upload|file_upload|voice",
      "choices": ["string"],
      "max_questions_in_round": "integer",
      "destination_fields": ["string"],
      "linked_missing_evidence_request_id": "string|null",
      "asked_at": "datetime|null",
      "answered_at": "datetime|null",
      "status": "queued|asked|answered|skipped|expired"
    }
  },

  "SuggestedAction": {
    "type": "object",
    "required": ["action_id", "action_type", "title", "human_approval_required", "status"],
    "properties": {
      "action_id": "string",
      "event_id": "string",
      "action_type": "diary_note|pm_task|qs_review|procurement_task|draft_email|draft_rfi|draft_variation_note|draft_notice_review|evidence_pack|programme_review|qa_task|safety_escalation",
      "title": "string",
      "rationale": "string",
      "owner_role": "site_manager|pm|qs|commercial_manager|procurement|design_manager|qa|estimator",
      "owner_user_id": "string|null",
      "due_by": "datetime|null",
      "draft_text": "string|null",
      "source_evidence_ids": ["string"],
      "human_approval_required": "boolean",
      "approval_role_required": ["pm", "qs", "commercial_manager"],
      "status": "suggested|assigned|in_review|approved|rejected|sent|exported|closed",
      "review_notes": "string|null"
    }
  },

  "ReviewState": {
    "type": "object",
    "required": ["status", "version"],
    "properties": {
      "status": "new|extracted|needs_site_followup|awaiting_evidence|ready_for_pm_review|pm_reviewed|ready_for_qs_review|qs_reviewed|commercial_review_required|approved|rejected|exported|closed",
      "version": "integer",
      "current_owner_role": "site_manager|pm|qs|commercial_manager|procurement|design_manager|qa|system",
      "current_owner_user_id": "string|null",
      "reviewers": [
        {
          "user_id": "string",
          "role": "string",
          "decision": "pending|approved|rejected|needs_more_info",
          "decision_at": "datetime|null",
          "notes": "string|null"
        }
      ],
      "approval_required_before": ["email_send", "rfi_submit", "variation_submit", "notice_submit", "claim_pack_export"],
      "last_updated_at": "datetime",
      "closed_at": "datetime|null"
    }
  }
}

H. First-demo checklist

Build the demo around one event. Do not overbuild.

Include in first demo

Field PWA
- Magic-link access
- Project/date/reporter prefill
- One-button voice record
- Photo/file upload
- Manual weather field or simple auto-fill
- 1–3 follow-up questions

AI pipeline
- Speech-to-text transcript
- Structured daily extraction
- Commercial event classification
- Missing evidence detection
- Confidence labels
- Suggested actions

Outputs
- Raw transcript
- Daily diary draft
- Commercial event card
- Missing evidence checklist
- PM/QS review queue
- Draft confirmation email
- Evidence pack table
- Admin dashboard

Admin dashboard
- Event ID
- Project
- Date
- Event type
- Severity
- Missing evidence
- Owner
- Review state
- Suggested action
- Export button mocked or real PDF/email

Do not include in first demo

- Full Procore write-back
- WhatsApp integration unless already trivial
- Contract-specific notice automation
- BIM/drawing measurement
- Automated programme delay analysis
- Cost valuation
- Final account intelligence
- Reality capture / OpenCV progress verification
- Multi-project analytics
- Complex permissions

The demo should make one point: a messy voice note becomes a reviewable commercial evidence workflow.

I. Later-product checklist

Build later only after the first workflow proves adoption.

1. Procore / Autodesk / SharePoint integrations.
2. WhatsApp/email ingestion for messy real-world records.
3. Contract-specific rule packs: JCT, NEC, subcontract variants.
4. RFI and variation tracker sync.
5. Programme import and activity matching.
6. Labour allocation/timesheet integration.
7. Procurement/delivery note integration.
8. Commercial manager approval workflows.
9. Evidence pack PDF with audit trail.
10. Weekly commercial risk digest across projects.
11. Historical event search.
12. Historical cost memory:
    - similar event lookup
    - labour/resource impacts
    - recovered/unrecovered values
    - tender assumption feedback
13. Estimator feedback loop:
    - “This package usually suffers from late materials/access/design ambiguity.”
14. Advanced photo handling:
    - EXIF validation
    - location tagging
    - duplicate detection
    - manual annotation
15. Long-term cost intelligence:
    - final account movement
    - variation outcomes
    - package-level productivity history

J. Risks and domain questions to validate with the construction partner

Product risks

Domain questions for partner meeting

1. What contract forms do you normally use: JCT, NEC, bespoke, subcontract variants?
2. Who can issue valid instructions on your projects?
3. How are verbal instructions handled today?
4. What is your current site diary template?
5. Who writes it, when, and who reviews it?
6. What fields are usually missing?
7. Which events have cost you money in the last 12 months?
8. How do site teams currently send photos?
9. Are photos labelled by project/location/date, or just dumped in folders/WhatsApp?
10. Where do delivery notes live?
11. Do you have a delivery tracker?
12. How do QSs find evidence for variations today?
13. What is the current RFI workflow?
14. What is the current variation/change workflow?
15. How are programme activities communicated to site?
16. Do site managers use lookaheads, full programmes, or verbal plans?
17. How do you record labour allocation and idle time?
18. Who signs off daily records?
19. What would count as a commercially useful event card?
20. What output format would your PM/QS actually use: PDF, Excel, email, Procore item, SharePoint folder?
21. What should never be sent without commercial manager approval?
22. Can you give us one painful real event and the messy records around it?

The hard ask after the demo should be:

Give us one real commercially painful event.
Give us the messy evidence.
Let us reconstruct:
- what happened
- what evidence existed
- what evidence was missing
- what should have been flagged
- what action should have happened
- what money/entitlement may have been exposed
- how the workflow would catch it next time

That is the real test. A polished demo proves build capability. A cold reconstruction proves whether this product matters.