Contract review vs approval email recipient triage

When to use / not use

• Use when the complaint is about who is on TO/CC for review- or approval-related contract emails, not whether the message arrived.
• Do not use as the only skill if the issue is purely signing/OTP/counterparty delivery—route to email-delivery-triage.

Step-by-step investigation

Step 1 — Classify the email (do this first)

From email audit (Django admin), customer forward, or subject/body:

Known example (Fractal, 2026-03): An approval was named “Contract Review Approval” and assigned to Contracts Review Team, while review was assigned to Admin. Screenshots showed review request emails; those correctly targeted Admin-side recipients. Customer expected approval-team-only mail. Resolution: clarify product behavior + naming; treat as WAI for recipient choice if the email type matches review, not approval.

If Step 1 already explains all recipients, stop or close with CS messaging—do not chase EmailConfig.

Step 2 — Confirm product state

• Review task / assignment: Metabase or admin—manual review task for {contract_id}, assigned role/team vs email TO line.
• Approval chain: Admin or BQ (if available)—approval step name, assignee team, order.
• Email audit row: Note email_type (or equivalent) and raw TO/CC.

Placeholders: {contract_id}, {wsid}, {workspace_id}, {cluster}, {wfid}.

Step 3 — If it is creator-party review mail and CC still looks wrong

If the audit shows CONTRACT_REVIEW_REQUIRED (or you have confirmed the send is from SendContractReviewRequiredEmailUseCase) and CC lists include addresses that are not explained by Step 1–2:

1. Admin → Email configs for {workspace_id} and the contract’s contract type:
   • Rows with config_for in creator-party / ALL_EMAILS scope.
   • email_type = CONTRACT_REVIEW_REQUIRED or NULL (broad match).
2. Clear or narrow CC/BCC on unintended rows; re-trigger review and re-check audit.

Why config applies (code): FilterEmailCcBccAuditForContractEmailsUseCase._get_linked_to_entity_id_and_type only sets entity linkage for CONTRACT_EXECUTED; other types return empty audit → BaseSendEmailUseCase._get_final_cc_bcc_lists uses if not send_request.is_email_to_creator_party or email_cc_bcc_audit is None and then _get_custom_email_config merges configured CC/BCC.

Key files:

• contracts_v3/services/contract_communication_service.py — communication_on_workflow_status_update_to_review
• contracts_v3/contract/domain/use_cases/send_contract_review_required_email_use_case.py — email_type → CONTRACT_REVIEW_REQUIRED
• emails/email/domain/use_cases/base_send_email_use_case.py — _get_final_cc_bcc_lists
• contracts_v3/contract/domain/use_cases/filter_email_cc_bcc_audit_for_contract_emails_use_case.py — audit entity linking (today effectively executed-only)

Step 4 — Logging

GCP / Groundcover around the send time for {contract_id} on the prod Django app for the cluster; correlate with email audit UUID / Postmark if needed.

Known patterns

Pattern A — Naming / workflow confusion (WAI after verification)

• Symptom: “Why did the Contracts Review Team / approval POC not get the only email?”
• Cause: Email was review assignment, not approval request.
• Mitigation: Explain review vs approval; suggest renaming the approval step if it misleads users.

Pattern B — EmailConfig CC on review-required

• Symptom: Extra CCs on review emails; audit shows type consistent with review-required; not explained by team membership alone.
• Cause: Workspace EmailConfig + audit gap for non-CONTRACT_EXECUTED types (see Step 3).
• Mitigation: Adjust config; long-term product/engineering options discussed in internal incident threads (e.g. override _get_custom_email_config in SendContractReviewRequiredEmailUseCase to return None, or extend CC/BCC audit to CONTRACT_REVIEW_REQUIRED with clear re-trigger semantics).

Escalation triggers

• Need product decision on whether any workspace CC should apply to review-required mail.
• Suspected regression in ContractCommunicationService or template routing—engage contracts/workflow owners with request IDs and audit IDs.

Related incidents / links

• Example incident channel: #incident-20260331-medium-fractal-auto-triggered-review-emails-sent-to-additional — Fractal, {workspace_id} 391689, {contract_id} 1857940, WFID 2714; Rootly 3060; Jira SPD-43065. Final CS stance: review vs approval confusion (WAI); parallel engineering analysis documented EmailConfig + audit behavior for true CC inflation cases.

Connections to other skills

• email-delivery-triage — delivery failures, suppression, OTP.
• resume-approvals-not-visible — approval state / UI, not email recipients.