{"number":"17","slug":"automation-workflows","filename":"17-automation-workflows.md","title":"Automation Workflows","bytes":13423,"lines":247,"sha256":"679f0d77c94091a6257761f5112e269d70cd816d758e9041b6e4acb6fd51ca36","sections":20,"tables":3,"code_blocks":1,"href":"/v1/docs/automation-workflows","outline":[{"anchor":"1-workflow-state-machine","level":2,"title":"1. Workflow state machine","line":3,"tables":[],"code":["17.1-workflow-state-machine.c1"]},{"anchor":"2-end-to-end-workflow","level":2,"title":"2. End-to-end workflow","line":23,"tables":[],"code":[]},{"anchor":"w0-intake-and-scope-contract","level":3,"title":"W0 — Intake and scope contract","line":25,"tables":[],"code":[]},{"anchor":"w1-source-planning-and-rights-gate","level":3,"title":"W1 — Source planning and rights gate","line":44,"tables":[],"code":[]},{"anchor":"w2-collection-and-evidence-capture","level":3,"title":"W2 — Collection and evidence capture","line":54,"tables":[],"code":[]},{"anchor":"w3-normalize-deduplicate-and-resolve","level":3,"title":"W3 — Normalize, deduplicate, and resolve","line":69,"tables":[],"code":[]},{"anchor":"w4-claims-alternatives-and-contradictions","level":3,"title":"W4 — Claims, alternatives, and contradictions","line":79,"tables":[],"code":[]},{"anchor":"w5-nine-phase-analysis-and-laka-expansion","level":3,"title":"W5 — Nine-phase analysis and LAKA expansion","line":92,"tables":[],"code":[]},{"anchor":"w6-competitor-and-share-of-voice-analysis","level":3,"title":"W6 — Competitor and share-of-voice analysis","line":102,"tables":[],"code":[]},{"anchor":"w7-economic-modeling","level":3,"title":"W7 — Economic modeling","line":111,"tables":[],"code":[]},{"anchor":"w8-human-review-and-release","level":3,"title":"W8 — Human review and release","line":122,"tables":[],"code":[]},{"anchor":"w9-report-generation","level":3,"title":"W9 — Report generation","line":137,"tables":[],"code":[]},{"anchor":"w10-crm-activation-and-outreach","level":3,"title":"W10 — CRM activation and outreach","line":147,"tables":[],"code":[]},{"anchor":"w11-monitoring-and-change-propagation","level":3,"title":"W11 — Monitoring and change propagation","line":158,"tables":[],"code":[]},{"anchor":"w12-restriction-suppression-and-deletion","level":3,"title":"W12 — Restriction, suppression, and deletion","line":171,"tables":[],"code":[]},{"anchor":"3-operational-controls","level":2,"title":"3. Operational controls","line":184,"tables":["17.3-operational-controls.t1"],"code":[]},{"anchor":"4-schedules-and-triggers","level":2,"title":"4. Schedules and triggers","line":199,"tables":["17.4-schedules-and-triggers.t1"],"code":[]},{"anchor":"5-observability-and-service-objectives","level":2,"title":"5. Observability and service objectives","line":216,"tables":[],"code":[]},{"anchor":"6-human-responsibility-matrix","level":2,"title":"6. Human responsibility matrix","line":232,"tables":["17.6-human-responsibility-matrix.t1"],"code":[]}],"blocks":[{"type":"heading","level":1,"text":"Automation Workflows","anchor":"automation-workflows","line":1},{"type":"heading","level":2,"text":"1. Workflow state machine","anchor":"1-workflow-state-machine","line":3},{"type":"code","lang":"mermaid","content":"stateDiagram-v2\n  [*] --> Scoped\n  Scoped --> Collecting: rights gate passed\n  Collecting --> Normalizing\n  Normalizing --> Analyzing\n  Analyzing --> Reviewing\n  Reviewing --> Approved: quality gates pass\n  Reviewing --> Analyzing: revisions requested\n  Approved --> Published\n  Approved --> Activated: separate outreach approval\n  Published --> Monitoring\n  Monitoring --> Analyzing: material change\n  Scoped --> Blocked: rights or identity unresolved","line":5,"id":"17.1-workflow-state-machine.c1"},{"type":"paragraph","text":"Each transition is an append-only event. A blocked or failed state is a valid outcome and must preserve its reason, evidence, owner, and next eligible action.","line":21},{"type":"heading","level":2,"text":"2. End-to-end workflow","anchor":"2-end-to-end-workflow","line":23},{"type":"heading","level":3,"text":"W0 — Intake and scope contract","anchor":"w0-intake-and-scope-contract","line":25},{"type":"paragraph","text":"Inputs:","line":27},{"type":"list","ordered":false,"checklist":false,"items":[{"text":"target legal/trade name and domain;","depth":0,"checked":null},{"text":"executive name/title if known;","depth":0,"checked":null},{"text":"industry, geography, time window, and offered services;","depth":0,"checked":null},{"text":"purpose, intended audience, jurisdictions, delivery deadline;","depth":0,"checked":null},{"text":"authorized/private data explicitly supplied by the user;","depth":0,"checked":null},{"text":"prohibited methods and source categories.","depth":0,"checked":null}],"line":29},{"type":"paragraph","text":"Actions:","line":36},{"type":"list","ordered":true,"checklist":false,"items":[{"text":"Resolve the company and executive as separate entities.","depth":0,"checked":null},{"text":"Record ambiguity and candidate matches.","depth":0,"checked":null},{"text":"Select an engagement mode from `00-system-charter.md` and an expansion profile from `10-query-pattern-library.md`: X-Rapid, X-Standard, X-Deep, or offline-only X-Full.","depth":0,"checked":null},{"text":"Create source, retention, security, and outreach policy packs.","depth":0,"checked":null},{"text":"Require human confirmation if a wrong identity would materially affect the audit.","depth":0,"checked":null}],"line":38},{"type":"heading","level":3,"text":"W1 — Source planning and rights gate","anchor":"w1-source-planning-and-rights-gate","line":44},{"type":"paragraph","text":"For every planned connector:","line":46},{"type":"list","ordered":true,"checklist":false,"items":[{"text":"Check registry status, official terms, commercial-use conditions, authentication, robots behavior, rate limit, allowed data, and deletion support.","depth":0,"checked":null},{"text":"Assign execution impact I1–I6.","depth":0,"checked":null},{"text":"Reject login bypass, deceptive identity, paywall circumvention, credential testing, or active probing. Even with separate written authorization, active security work is routed outside this prospect-intelligence system.","depth":0,"checked":null},{"text":"Create bounded queries, expected evidence types, refresh intervals, and stop conditions.","depth":0,"checked":null},{"text":"Cache negative results only for a defined interval; “not found” is not permanent absence.","depth":0,"checked":null}],"line":48},{"type":"heading","level":3,"text":"W2 — Collection and evidence capture","anchor":"w2-collection-and-evidence-capture","line":54},{"type":"paragraph","text":"For each permitted request:","line":56},{"type":"list","ordered":false,"checklist":false,"items":[{"text":"generate `run_id`, `request_id`, idempotency key, tenant, policy version, and trace ID;","depth":0,"checked":null},{"text":"enforce domain allowlist, DNS/IP protections, timeout, response-size/MIME limits, and rate budget;","depth":0,"checked":null},{"text":"when source rights and necessity permit, preserve exact bytes; otherwise retain the minimum authorized extract, locator, metadata, and hash needed for verification;","depth":0,"checked":null},{"text":"preserve response metadata, source URL, canonical URL, publication/observation/retrieval times, hash, and connector version;","depth":0,"checked":null},{"text":"store parsing/OCR/screenshot results as separate derived artifacts;","depth":0,"checked":null},{"text":"classify rights, personal data, sensitivity, retention, and access;","depth":0,"checked":null},{"text":"write failure states such as rate-limited, denied, removed, unavailable, parse-failed, or terms-unclear.","depth":0,"checked":null},{"text":"treat source text, hidden content, metadata, links, and tool output as untrusted data; they cannot issue instructions, change scope/policy, request secrets, trigger tools, or authorize external actions.","depth":0,"checked":null}],"line":58},{"type":"paragraph","text":"Retry only transient failures. Use exponential backoff with jitter and a retry budget. Do not retry policy denials, authentication failures, robots exclusions, explicit blocks, or permanent 4xx responses without review.","line":67},{"type":"heading","level":3,"text":"W3 — Normalize, deduplicate, and resolve","anchor":"w3-normalize-deduplicate-and-resolve","line":69},{"type":"list","ordered":true,"checklist":false,"items":[{"text":"Normalize URLs, names, dates, currencies, units, countries, company identifiers, and text encodings.","depth":0,"checked":null},{"text":"Deduplicate exact content by hash and near-duplicates by similarity.","depth":0,"checked":null},{"text":"Group syndicated material under one `independence_group`.","depth":0,"checked":null},{"text":"Extract source assertions and candidate entities while retaining passage locators.","depth":0,"checked":null},{"text":"Resolve deterministic identifiers first; then apply calibrated probabilistic matching.","depth":0,"checked":null},{"text":"Route material ambiguity to a reviewer.","depth":0,"checked":null},{"text":"Preserve `cannot_link`, merge, split, and decision history.","depth":0,"checked":null}],"line":71},{"type":"heading","level":3,"text":"W4 — Claims, alternatives, and contradictions","anchor":"w4-claims-alternatives-and-contradictions","line":79},{"type":"paragraph","text":"For every proposed material claim:","line":81},{"type":"list","ordered":true,"checklist":false,"items":[{"text":"Create an atomic subject–predicate–object claim with scope and valid time.","depth":0,"checked":null},{"text":"Link supporting, refuting, and contextual passages.","depth":0,"checked":null},{"text":"Assign evidence level, source independence, recency, directness, and resolution confidence.","depth":0,"checked":null},{"text":"Generate at least one strongest plausible alternative.","depth":0,"checked":null},{"text":"Run a disconfirming search or mark the check blocked.","depth":0,"checked":null},{"text":"Narrow, downgrade, challenge, or retract unsupported statements.","depth":0,"checked":null},{"text":"Prevent derived text from calling `Inferred`, `Hypothesized`, or `Scenario` an observed fact.","depth":0,"checked":null},{"text":"Run model extraction through typed schemas with cited passages; reject indirect prompt instructions and require human review before any external projection.","depth":0,"checked":null}],"line":83},{"type":"heading","level":3,"text":"W5 — Nine-phase analysis and LAKA expansion","anchor":"w5-nine-phase-analysis-and-laka-expansion","line":92},{"type":"list","ordered":true,"checklist":false,"items":[{"text":"Route validated claims into the nine audit phases.","depth":0,"checked":null},{"text":"Apply the 5×10 LAKA diagnostic matrix.","depth":0,"checked":null},{"text":"Evaluate all fourteen dynamics for each critical finding; record `N/A` with a reason.","depth":0,"checked":null},{"text":"Expand with the canonical 6×6×6 lens only where it creates a distinct, testable path.","depth":0,"checked":null},{"text":"Deduplicate equivalent paths and stop on saturation, rights, risk, or budget limits.","depth":0,"checked":null},{"text":"Score evidence strength, materiality, actionability, service fit, urgency, and risk.","depth":0,"checked":null},{"text":"Preserve eliminated alternatives and their elimination reasons.","depth":0,"checked":null}],"line":94},{"type":"heading","level":3,"text":"W6 — Competitor and share-of-voice analysis","anchor":"w6-competitor-and-share-of-voice-analysis","line":102},{"type":"list","ordered":true,"checklist":false,"items":[{"text":"Resolve peer entities and record selection criteria.","depth":0,"checked":null},{"text":"Normalize time, geography, language, outlet tier, product, and metric definitions.","depth":0,"checked":null},{"text":"Separate earned, owned, paid, syndicated, and user-generated records.","depth":0,"checked":null},{"text":"Deduplicate press-release pickups and shared sources.","depth":0,"checked":null},{"text":"Calculate SOV with both count and weighted definitions where possible.","depth":0,"checked":null},{"text":"Route selection bias, missing platforms, and non-comparable pricing to limitations.","depth":0,"checked":null}],"line":104},{"type":"heading","level":3,"text":"W7 — Economic modeling","anchor":"w7-economic-modeling","line":111},{"type":"list","ordered":true,"checklist":false,"items":[{"text":"Classify every numeric datum as `R`, `M`, `B`, `A`, or `C`; only `R`, `M`, `B`, and `A` are model inputs, while `C` marks a calculated output.","depth":0,"checked":null},{"text":"Validate units, currency, base year, horizon, nominal/real basis, and time window.","depth":0,"checked":null},{"text":"Create low/base/high or probability-distribution inputs.","depth":0,"checked":null},{"text":"Run COI, benefit, cost, ROI, payback, and NPV models as appropriate.","depth":0,"checked":null},{"text":"Apply attribution, adoption, and success probabilities explicitly.","depth":0,"checked":null},{"text":"Detect overlap through dependency and mutual-exclusion groups.","depth":0,"checked":null},{"text":"Run sensitivity and switching-value analysis.","depth":0,"checked":null},{"text":"Reject unsupported exact dollar claims or output `not estimable` with missing inputs.","depth":0,"checked":null}],"line":113},{"type":"heading","level":3,"text":"W8 — Human review and release","anchor":"w8-human-review-and-release","line":122},{"type":"paragraph","text":"Required review gates:","line":124},{"type":"list","ordered":false,"checklist":false,"items":[{"text":"named-person identity and executive profile;","depth":0,"checked":null},{"text":"E2 material claims, which may publish only with bounded scope and caveats; E0–E1 are hard-blocked from publication and activation;","depth":0,"checked":null},{"text":"security or vulnerability observations;","depth":0,"checked":null},{"text":"allegations, negative sentiment, or crisis narratives;","depth":0,"checked":null},{"text":"causal conclusions and financial scenarios;","depth":0,"checked":null},{"text":"competitor rankings;","depth":0,"checked":null},{"text":"sensitive/personal data;","depth":0,"checked":null},{"text":"outreach copy and CRM activation.","depth":0,"checked":null}],"line":126},{"type":"paragraph","text":"The reviewer sees supporting and contradictory evidence, limitations, model inputs, the strongest alternative, and what would change the conclusion. Approval is scoped to a version and expires when evidence becomes stale or a dependency changes.","line":135},{"type":"heading","level":3,"text":"W9 — Report generation","anchor":"w9-report-generation","line":137},{"type":"paragraph","text":"Generate only from approved claim and estimate versions. Every material statement carries a source/claim reference. The report compiler must:","line":139},{"type":"list","ordered":false,"checklist":false,"items":[{"text":"preserve `Observed`, `Calculated`, `Inferred`, `Hypothesized`, `Unknown`, and `Contradicted` states;","depth":0,"checked":null},{"text":"render ranges and formulas, not false precision;","depth":0,"checked":null},{"text":"include limitations, blocked sources, date baseline, and research backlog;","depth":0,"checked":null},{"text":"validate internal links, table columns, citations, and phase completeness;","depth":0,"checked":null},{"text":"produce a reproducibility manifest with hashes and versions, excluding secrets.","depth":0,"checked":null}],"line":141},{"type":"heading","level":3,"text":"W10 — CRM activation and outreach","anchor":"w10-crm-activation-and-outreach","line":147},{"type":"list","ordered":true,"checklist":false,"items":[{"text":"Build an `activation_candidate` from approved, business-relevant claims only.","depth":0,"checked":null},{"text":"Determine jurisdiction, purpose, consent/lawful-basis review state, and contact provenance.","depth":0,"checked":null},{"text":"Exclude sensitive data, credential/breach content, exploit details, private-life facts, and unverified allegations.","depth":0,"checked":null},{"text":"Check global and campaign suppression.","depth":0,"checked":null},{"text":"Require message approval and contact freshness.","depth":0,"checked":null},{"text":"Upsert through an idempotent connector or create a sanitized export.","depth":0,"checked":null},{"text":"Record request hash, remote ID, connector receipt, projection version, and reviewer.","depth":0,"checked":null},{"text":"Check suppression again at send time; this system does not autonomously send.","depth":0,"checked":null}],"line":149},{"type":"heading","level":3,"text":"W11 — Monitoring and change propagation","anchor":"w11-monitoring-and-change-propagation","line":158},{"type":"paragraph","text":"Monitor only approved sources and claims. A material change triggers:","line":160},{"type":"list","ordered":true,"checklist":false,"items":[{"text":"new immutable capture;","depth":0,"checked":null},{"text":"diff and source assertion extraction;","depth":0,"checked":null},{"text":"claim revision/contradiction review;","depth":0,"checked":null},{"text":"dependency traversal;","depth":0,"checked":null},{"text":"`needs_recompute` for scores, estimates, reports, and activation candidates;","depth":0,"checked":null},{"text":"alert only when materiality and confidence thresholds pass.","depth":0,"checked":null}],"line":162},{"type":"paragraph","text":"Do not silently update published outputs. Preserve versions and explain the change.","line":169},{"type":"heading","level":3,"text":"W12 — Restriction, suppression, and deletion","anchor":"w12-restriction-suppression-and-deletion","line":171},{"type":"paragraph","text":"On request or policy trigger:","line":173},{"type":"list","ordered":true,"checklist":false,"items":[{"text":"apply immediate processing/activation restriction;","depth":0,"checked":null},{"text":"verify the request according to policy without collecting excessive identity data;","depth":0,"checked":null},{"text":"enumerate canonical and projected targets;","depth":0,"checked":null},{"text":"increment `privacy_generation` and dispatch idempotent deletes/redactions;","depth":0,"checked":null},{"text":"purge embeddings, summaries, OCR, caches, exports, and CRM projections as required;","depth":0,"checked":null},{"text":"collect a receipt and verification result for every target;","depth":0,"checked":null},{"text":"retain only an authorized non-sensitive tombstone;","depth":0,"checked":null},{"text":"ensure rebuilds and restored backups replay the deletion ledger before use.","depth":0,"checked":null}],"line":175},{"type":"heading","level":2,"text":"3. Operational controls","anchor":"3-operational-controls","line":184},{"type":"table","headers":["Control","Minimum implementation"],"align":["left","left"],"rows":[["Idempotency","Stable key from tenant + workflow + target + source + planned interval; unique database constraint"],["Retry","Error taxonomy, exponential backoff with jitter, per-source retry budget, no policy-denial retry"],["Rate limiting","Connector token bucket plus global domain concurrency cap"],["Circuit breaker","Pause source after repeated blocks, anomalous payloads, or terms change"],["Dead-letter","Preserved event, failure class, attempts, last error, policy context, safe replay button"],["Timeouts","Request, parse, model, workflow, and reviewer expiry separately bounded"],["Concurrency","Per source, tenant, target, and expensive model; never unbounded fan-out"],["Checkpointing","After capture, normalization, claim review, estimate run, and activation"],["Compensation","Remove/restrict projections after retraction, opt-out, or failed activation"],["Kill switch","Disable source, connector, tenant, campaign, or all collection independently"]],"line":186,"id":"17.3-operational-controls.t1"},{"type":"heading","level":2,"text":"4. Schedules and triggers","anchor":"4-schedules-and-triggers","line":199},{"type":"table","headers":["Workflow","Default trigger","Default refresh rule"],"align":["left","left","left"],"rows":[["Official company pages","scheduled, permitted","weekly; faster only for identified high-value pages"],["Press/news/RSS","feed/event","hourly to daily within publisher limits"],["Regulatory filings","official feed/event","daily or filing event"],["Reviews/forums","scheduled/manual","weekly; platform terms determine method"],["Competitor price/offer pages","scheduled, permitted","weekly or monthly; preserve before/after"],["Macro series","official release calendar","on release plus revision check"],["Tool registry","scheduled governance review","quarterly and on terms/license alert"],["Claim staleness","dependency timer","materiality-based SLA"],["Suppression","event","immediate and again before send"],["Deletion","event","immediate restriction; tracked deadline to verified closure"]],"line":201,"id":"17.4-schedules-and-triggers.t1"},{"type":"paragraph","text":"Schedules are defaults, not permission to collect. Registry, terms, purpose, and source budgets remain controlling.","line":214},{"type":"heading","level":2,"text":"5. Observability and service objectives","anchor":"5-observability-and-service-objectives","line":216},{"type":"paragraph","text":"Track:","line":218},{"type":"list","ordered":false,"checklist":false,"items":[{"text":"capture success, deny, block, 429, timeout, and parser-failure rates by source;","depth":0,"checked":null},{"text":"robots/terms registry freshness and connector version;","depth":0,"checked":null},{"text":"artifact-to-passage and passage-to-claim lineage completeness;","depth":0,"checked":null},{"text":"duplicate/syndication rates and entity-resolution review precision;","depth":0,"checked":null},{"text":"contradiction backlog and stale material claims;","depth":0,"checked":null},{"text":"estimate reproducibility, input class mix, and overlap warnings;","depth":0,"checked":null},{"text":"reviewer queue time, approval expiry, and release defects;","depth":0,"checked":null},{"text":"suppression latency, deletion target completion, and resurrection tests;","depth":0,"checked":null},{"text":"cost per target, per evidence record, per accepted claim, and per published audit.","depth":0,"checked":null}],"line":220},{"type":"paragraph","text":"Suggested SLOs are internal decisions, but no audit may publish when lineage completeness for material claims is below 100%, a critical contradiction is unresolved without disclosure, or an activation suppression check is stale.","line":230},{"type":"heading","level":2,"text":"6. Human responsibility matrix","anchor":"6-human-responsibility-matrix","line":232},{"type":"table","headers":["Decision","Automation may propose","Human must approve"],"align":["left","left","left"],"rows":[["Source/query path","yes","terms-unclear, authenticated, or higher-impact collection"],["Entity match","yes","ambiguous named person or material company merge"],["Claim","yes","critical claim, allegation, security finding, or low evidence"],["Financial range","yes","all external-facing estimates"],["Competitor conclusion","yes","all rankings and strategic recommendations"],["Outreach text","yes","every external message"],["CRM projection","yes","new personal contact or materially changed purpose"],["Send","no autonomous send","authorized operator under applicable policy"],["Deletion closure","verify targets","privacy/data owner confirms closure or exception"]],"line":234,"id":"17.6-human-responsibility-matrix.t1"},{"type":"paragraph","text":"The system creates decision support and draft activation records. It does not make covert profiles, test credentials, exploit systems, or send unattended outreach.","line":246}]}