{"slug":"architecture/TWIN_BEHAVIOR","title":"IntegrateWise — Twin Behavior Model","section":"architecture","sectionLabel":"Architecture","status":"unclassified","type":"document","path":"architecture/TWIN_BEHAVIOR.mdx","bytes":7082,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n**Status**: FROZEN\n**Date**: July 17, 2026\n\n---\n\n# Product Model\n\n```text\nOnboarding\n    ↓\nUser Workbench\n    ├── user works in departmental modules\n    ├── pipeline executes\n    └── Twin silently observes\n             ↓ (only when explicitly engaged or material value exists)\n        ORIENT → THINK → RECOMMEND\n             ↓\n        approved outcome returns through Pipeline → Spine\n```\n\nThe user experience has three concepts only:\n\n1. **Onboarding** — establishes role, connected systems, permissions, and initial Spine context.\n2. **User Workbench** — the primary operational surface.\n3. **Twin** — a silent context-aware partner, not another workspace, permanent panel, or sidebar destination.\n\n---\n\n# Twin Modes\n\n## 1. Passive Mode — Always Observe, Stay Lightweight\n\nThe Twin is continuously aware without continuously performing expensive reasoning.\n\n```text\nPipeline events\nSpine changes\nCurrent Workbench surface\nCurrent entity\nUser actions\nOODA state\nApprovals and outcomes\nContext changes\n        ↓\nLightweight observation\n        ↓\nOnly material signal → small, contextual surfacing\n```\n\nExamples of permitted lightweight surfacing:\n\n- “Renewal risk detected.”\n- “Meeting starts in 10 minutes.”\n- “Three approvals pending.”\n- “Connector sync failed; account data may be stale.”\n\nPassive mode does not open a Twin panel, generate a long analysis, or compete with the user's work.\n\n## 2. Active Mode — Ask your Twin → Orient\n\nWhen the user needs detail or clicks **Ask your Twin**, the Twin escalates from observation to grounded reasoning.\n\n```text\nAsk your Twin\n    ↓\nORIENT\n    ├── Current Workbench surface\n    ├── Current entity and related entities\n    ├── Adaptive Spine projection, timeline, relationships, and provenance\n    ├── Pipeline state, freshness, and ingestion status\n    ├── OODA state\n    ├── Evidence and connected-system context\n    └── Organizational memory\n    ↓\nTHINK\n    ↓\nEvidence-backed recommendation\n    ↓\nUser decides\n```\n\nThe Twin only performs comprehensive analysis after explicit engagement or a material pipeline event that justifies proactive assistance.\n\n---\n\n# Grounded Twin Inputs\n\nEvery Twin response is grounded in the same bounded context:\n\n```text\nCurrent Surface\n    + Current Entity\n    + Pipeline State\n    + OODA State\n    + Adaptive Spine\n    + Evidence\n    + Connected Systems\n    + Organizational Memory\n    ↓\nTwin Reasoning\n```\n\nThe Twin must distinguish facts, evidence, freshness, uncertainty, and recommendations. It never invents missing operational truth.\n\n---\n\n# OODA Grammar — Four Buttons\n\nThe four buttons are the explicit human-to-platform control grammar. They do not replace normal operational interactions such as navigating modules, editing a record, or logging activity.\n\n| Button                    | OODA phase | User intent                               | Platform behavior                                                                                                                                     |\n| ------------------------- | ---------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Store in Spine**        | Observe    | Capture a durable observation or decision | Workbench submits a governed write through the Pipeline; Spine records entity, timeline, provenance, and links. The Twin does **not** write directly. |\n| **Ask your Twin**         | Orient     | Request understanding of current work     | Twin reads the current surface and bounded context, then reasons over Pipeline, Spine, OODA, evidence, connected systems, and memory.                 |\n| **Assign your Twin**      | Decide     | Delegate a bounded task                   | Twin creates a draft, analysis, or proposed action from grounded context; it does not externally execute.                                             |\n| **Approve Twin's Action** | Act        | Authorize a proposal                      | Governance validates approval; the Pipeline invokes the authorized capability; external result is reconciled back to Spine.                           |\n\n## Example: Customer Success Account\n\n```text\nUser opens FinanceFlow account\n    ↓\nPassive Twin notices: renewal in 18 days + health decline + two unresolved P1 tickets\n    ↓\nSmall inline signal: “Renewal risk detected.” [Review] [Ignore]\n    ↓\nUser needs detail → [Ask your Twin]\n    ↓\nTwin ORIENTS over account Entity 360, signal evidence, sync freshness,\nmeeting history, OODA state, and related contacts\n    ↓\nTwin RECOMMENDS: “Prepare an intervention plan; evidence: …”\n    ↓\nUser → [Assign your Twin]: “Draft the intervention email and QBR recovery plan.”\n    ↓\nTwin returns a proposal and evidence; no external action occurred\n    ↓\nUser → [Approve Twin's Action]\n    ↓\nGovernance gate → authorized Pipeline capability → connected system\n    ↓\nOutcome is re-ingested and reconciled to Spine\n```\n\n---\n\n# Pipeline Relationship\n\n```text\nLOAD → NORMALIZE → STORE → THINK → RECOMMEND → APPROVE → ACT → REPEAT\n                          ↑                   ↑\n                   Twin reasons here    Human authority here\n```\n\n- **Pipeline** owns ingestion, normalization, durable writes, authorized execution, and reconciliation.\n- **Spine** owns canonical truth, timelines, provenance, relationships, and projections.\n- **Twin** observes the pipeline and OODA state; when engaged, it orients and thinks over grounded context.\n- **Governance** is a hard gate: no approval token, no external mutation.\n\nThe Twin never directly writes truth to Spine and never directly mutates a connected system.\n\n---\n\n# Surfacing Rules\n\n1. **Silent by default.** No permanent Twin pane or sidebar item across surfaces.\n2. **Contextual by exception.** A material signal may appear inline, as a small notification, or as a proposal card.\n3. **Deep only on demand.** `Ask your Twin` starts Orient; the Twin reads the current surface rather than requiring the user to restate context.\n4. **Evidence before recommendation.** Every recommendation identifies its supporting evidence and data freshness.\n5. **Human authority is final.** A proposed action is inert until explicitly approved.\n6. **Pipeline is the execution boundary.** Approved outcomes return through the Pipeline and are reconciled to Spine.\n\n---\n\n# UI Placement\n\nThe Twin is invoked **where work is happening**, not housed as a universal destination:\n\n- An inline risk signal on an Account view.\n- A contextual **Ask your Twin** affordance in a module header or entity detail.\n- A proposal card after an assignment or material detection.\n- A contextual **Approve Twin's Action** control only when a governed proposal exists.\n\nThe Workbench remains primary. The Twin appears only as much as the current work and user request require.\n"}