Freshdesk Human Takeover Flags

Reason

Some Freshdesk tickets require Matt to personally decide, approve, perform, or fill in case-specific information before a safe customer reply exists. The automation previously had a human_review_needed draft type, but it could still produce a normal-looking copyable reply when the better behavior was to flag Matt directly.

Old Behavior

The assistant could draft a short conditional customer reply for replacement, refund, logistics, engineering, warranty, or missing-information cases. That sometimes made a case look more answerable than it really was.

New Behavior

The automation now has a separate human_takeover_required path. When triggered, it should add an internal Freshdesk private note starting with HUMAN TAKEOVER REQUIRED: instead of COPYABLE REPLY:.

The flag must summarize:

• the ticket issue;
• why automation is not drafting a normal reply;
• the exact Matt action needed;
• any optional customer-safe holding reply;
• what must be verified before a customer response is sent;
• sources checked.

Every takeover flag gets a local audit file under vault/freshdesk-runs/human-takeover-flags/, a case-file update, and state entries for flag ids, files, ticket ids, reasons, and counts.

Files Changed

• vault/Freshdesk Drafting Quality Gate.md
• vault/freshdesk-runs/Automation Efficiency Policy.md
• vault/learnings/2026-05-15-freshdesk-draft-quality-standards.md
• vault/SCHEMA.md
• vault/freshdesk-runs/human-takeover-flags/README.md
• .state/freshdesk_draft_assistant.json
• scripts/run_daily_improvement_review.py
• Codex automation prompt x-arcade-freshdesk-draft-assistant

Safety Boundary

This does not expand live permissions. It still allows only Freshdesk private notes and read-only Shopify lookup. It makes risky cases more visible to Matt and reduces accidental customer promises.

Validation

• python3 scripts/run_daily_improvement_review.py
• JSON parse check for .state/freshdesk_draft_assistant.json

Rollback

Remove the human_takeover_required sections from the drafting gate and automation prompt, stop writing HUMAN TAKEOVER REQUIRED: notes, and return to normal COPYABLE REPLY: or skip-only handling.