👥 Tribes

Spec map

Home: All V2 Specs · Foundation: Data System (UVP) Mode(s): Relationship Mode, Campaign Mode, Petition Mode Related specs: CTAs, Contacts, Data System (UVP), Forms, Petition Mode, Polling Engine, Surveys

🎯 Goals

Cross-Mode Architecture

Establish Tribes as a horizontal, mode-agnostic segmentation primitive that all three modes can create and consume from a single Tribe object. Membership Types
Provide five membership types spanning manual, dynamic, petition-sourced, issue-stance, and AI-suggested so any audience can be defined. Issue Stance Architecture
Make issue stances first-class consolidated UVP data with confidence and provenance so audiences query a clean canonical layer. Tribe Builder
Let users build precise audiences in plain English backed by a transparent, editable, auditable structured criteria layer. Criteria Expression Language
Provide an evaluable, composable filter DSL with operators, logic, set operations, and pre-computed fields. Tribe Library
Give accounts a managed surface to browse, organize, and operate on their full Tribe inventory including curated system Tribes. Petition-to-Tribe Pipeline
Turn petition signatures into automatic Tribe membership and issue-stance signal without manual tagging. Performance Architecture
Deliver sub-second Tribe evaluation via hot/cold caching, indexing, and async recomputation within defined limits. Privacy IP and Two-Tier Boundary
Isolate customer Tribe data while mining only anonymized aggregate patterns as Politogy IP. AI-Suggested Tribes
Proactively surface clustering-derived candidate Tribes for user adoption in V2. Cross-Mode Audience Resolution
Automatically intersect cross-mode Tribe consumption against authorization and opt-in scope. Permissions
Enforce role-based access to viewing, building, using, deleting, and bulk-operating Tribes. Provenance and Audit
Provenance-track every Tribe operation to verify segmentation decisions and consent compliance. Mobile
Provide read-and-consume Tribe access on mobile in V1 with the Builder reserved for desktop.

Mode: Cross-Mode (Relationship + Campaign + Petition) Status: Conceptual Spec — V1 Scope Definition Companion specs: vrm-data-system (UVP, layers, fields), vrm-contacts (Relationship Mode workbench), vrm-polling-engine (segment consumer), vrm-forms / vrm-surveys / vrm-cta (signal generators), politogy-vrm-brand

1. What This Product Is

Tribes is the horizontal segmentation engine of Politogy VRM. It is the platform-level capability that turns a natural-language description of “what these people have in common” into a precise, dynamically-recomputed set of UVPs ready to be messaged, called, canvassed, polled, or analyzed.

A user types: “My contacts in the Portland Metro Area who support election security and 2A.” The system parses, interprets, returns a member count, shows the user what it understood, lets them refine. “And remove anyone we contacted in the last 30 days.” The list shrinks. “And only show donors from the last cycle.” The list refines further. In thirty seconds the user has a precise, persistent audience for a precise, persistent campaign action.

Tribes operates across all three modes:

Mode	What “shared” means	Audience pool
Relationship Mode	Account-claimed contacts who share attributes	Opt-in UVPs
Campaign Mode	Voter-file voters who share political/demographic/behavioral attributes	Authorized voter roll within geographic scope
Petition Mode	Signers of a specific petition (auto-created), or voters sharing inferred issue stances	Signers + eligible voters

Tribes is the architectural surface where everything else in VRM pays off. Forms capture signals. Surveys capture signals. CTAs capture signals. Petitions capture explicit issue stances. The UVP accumulates them all. Tribes is how the user slices the UVP back out into actionable audiences.

Product thesis: Highly targeted messaging is the difference between a campaign that wastes resources and one that wins. Building a precise audience today requires expert SQL, expert filter UIs, or expert consultants. Tribes makes precise audience building a thirty-second conversation in plain English. The user says what they want; the system delivers.

2. Cross-Mode Architecture

Tribes is not a Relationship Mode feature. It is a horizontal platform primitive that all three modes consume.

2.1 The Tribe Object — Mode-Agnostic Definition

A Tribe is a single object type, regardless of which mode created it:

Property	Description
`tribe_id`	System unique ID
`account_id`	Owning account
`name`	Human-readable label
`description`	Optional user-provided description
`audience_scope`	`relationship` (claimed UVPs only), `campaign` (voter roll within authorization), or `petition` (auto-system)
`membership_type`	`static`, `dynamic`, `petition_sourced`, `issue_stance`, `ai_suggested`
`criteria`	Structured filter expression (the query)
`static_members`	UVP IDs (only when `membership_type=static`)
`member_count`	Cached count, refreshed on read
`last_evaluated`	Timestamp of last membership recomputation
`tags`	User-applied labels for organizing the Tribe library
`created_by`, `created_at`, `updated_at`	Provenance

The audience_scope determines what universe the criteria evaluates against. A relationship Tribe with the criterion “lives in Portland” returns only the account’s claimed contacts who live in Portland. A campaign Tribe with the same criterion returns every voter on the roll in Portland (within the account’s authorized geography).

2.2 Cross-Mode Consumption

A Tribe created in any mode can be consumed by any mode the account has access to:

A relationship Tribe (“Active Email Subscribers in HD37”) can be the audience for a Campaign Mode Phone Bank.
A campaign Tribe (“Registered voters in HD37 who voted in 2024 primary”) can be the audience for a Relationship Mode Email blast (intersected with claimed contacts).
A petition Tribe (“IP37 Signers”) can be the audience for a Survey, a Phone Bank, an SMS blast, a Poll segment.

The same Tribe definition powers messaging, canvassing, polling, and analysis without rebuilding.

3. The Five Tribe Membership Types

3.1 Manual Static

User explicitly picks members. UVP IDs stored in static_members. Add/remove members manually. Used for: small curated lists (board members, key donors, VIP volunteers).

3.2 Filter Dynamic

A saved structured filter expression. Membership is recomputed on every access (or pushed via cache invalidation when underlying UVP data changes). The Tribe Builder’s primary output.

This is the headline membership type. Most Tribes are dynamic.

3.3 Petition-Sourced (System)

Auto-created when a petition is registered in Petition Mode. Members = anyone who signed the petition. Membership is updated as new signatures arrive in real time.

Inherits the petition’s issue stance. When a petition is created, it carries an issue_stance_meta block — what issue does this petition speak to, and what stance (supportive / opposed) does signing it indicate? Signing IP37 (a petition to end vote-by-mail) records:

Signer added to “IP37 Signers” Petition-Sourced Tribe (auto)
Signer’s UVP issue_stances.election_security set to supportive with provenance “IP37 signature”

3.4 Issue-Stance (System + User-Adopted)

System-defined Tribes for each known issue stance. Members = UVPs whose issue_stances substructure carries the stance signal, regardless of source.

A UVP can land in “Election Security Supporters” via:

Signing a petition with that stance (IP37)
Survey response indicating support
Form custom-field selection
CTA conversion on an election-security-themed CTA
Manual tag/edit by account user

The Issue-Stance Tribe accumulates members from all signal sources. One stance, many evidence types.

3.5 AI-Suggested (V2)

Politogy’s Aggregate Intelligence clustering surfaces candidate Tribes (“we noticed 247 of your contacts share these attributes”). User reviews, names, adopts. Once adopted, becomes a Filter Dynamic Tribe with the criteria the AI generated. See Section 11.

4. The Issue Stance Architecture — A New First-Class Primitive

This is the key architectural addition introduced by Tribes. Issue stances are upgraded from “custom field value” to first-class UVP data.

4.1 The `issue_stances` UVP Substructure

A new substructure on every UVP:

issue_stances: {
  election_security: {
    stance: "supportive" | "opposed" | "neutral" | "unknown",
    confidence: 0.0–1.0,
    sources: [
      { source_type: "petition_signature", source_id: "ip37", recorded_at: "2026-03-04", stance_recorded: "supportive" },
      { source_type: "survey_response", source_id: "issue_pulse_q1", question: "...", response: "Strongly Support", recorded_at: "2026-04-10" },
      { source_type: "form_field", source_id: "volunteer_signup", field: "issues_of_concern", value: "Election Integrity", recorded_at: "2026-02-15" }
    ],
    last_updated: "2026-04-10"
  },
  second_amendment: { ... },
  property_taxes: { ... },
  parental_rights: { ... },
  ... (one entry per known issue)
}

Every issue stance carries:

Current consolidated stance (supportive / opposed / neutral / unknown)
Confidence (computed from source count, recency, source reliability)
Full provenance — every signal that contributed
Last-updated timestamp

4.2 The Canonical Issue Registry

Politogy maintains a registry of known issues at the platform level. Each issue has:

Canonical name (election_security, second_amendment, etc.)
Display label (“Election Security,” “2nd Amendment”)
Description
Related-issue links (for AI clustering)
Politogy-curated semantic synonyms for natural-language matching (“election integrity,” “voter ID,” “vote-by-mail” all link to election_security)

The registry is Politogy-controlled (similar to global fields in vrm-data-system §5.2). Customer accounts cannot create custom issues, but they can request promotion of a custom-named issue if their data shows a pattern (same promotion mechanism as global fields).

4.3 Stance Consolidation Logic

When multiple signals exist for the same UVP on the same issue:

Most recent strong-signal wins as the current stance (a petition signature beats a 2-year-old survey lukewarm response).
Conflicting signals reduce confidence. If Survey A says supportive and Survey B says opposed, confidence drops; the more recent wins for consolidated stance but the lower confidence flags the contradiction for analytical filtering.
Strength tiers per source type:
- Strongest: Explicit petition signature (action speaks)
- Strong: Survey explicit-issue response (recent within 12 months)
- Medium: Form custom field selection, CTA engagement on issue-tagged content
- Weak: Aggregate inference (followed a candidate, attended a rally for the issue)
Stance can be manually overridden by the account user from a Contact Card (records as a high-confidence manual source).

4.4 Why This Matters

Without issue_stances as a first-class substructure, the user has to query across petition signatures, survey responses, form fields, custom tags, and engagement events separately to build an “Election Security Supporters” audience — and would get inconsistent results.

With issue_stances, the query is one line: WHERE issue_stances.election_security.stance = 'supportive'. The substructure consolidates the signal upstream so every downstream consumer (Tribes, Polling Engine propensity models, Aggregate Intelligence) reads from a clean canonical layer.

This is the architectural decision that turns Ben’s framing — “if a voter signed IP37 they are clearly an election security voter” — into a system-wide property rather than a one-off interpretation.

5. The Tribe Builder — Natural Language Interface

The headline feature. A conversational AI surface for constructing Tribes from plain English.

5.1 The Interaction Model

A two-panel layout:

Left panel — Conversation:

Free-text input box at the bottom
Conversation history above (user prompts + AI responses)
AI responses include: parsed interpretation, member count, structured criteria summary

Right panel — Live Result:

Member count (updates in real time)
Sample members (first 10, with avatar + name + key attributes)
“View all members” link
Structured criteria block (the underlying filter expression, editable)
Save as Tribe button + name input

5.2 The Conversation Flow

USER: My contacts in the Portland Metro Area

AI: I found 2,847 contacts in the Portland Metro Area
    (Multnomah, Clackamas, Washington counties).
    [shows criteria: audience_scope=relationship, county IN (Multnomah, Clackamas, Washington)]

USER: who support election security

AI: Refined to 1,134 contacts. I matched "election security"
    to the issue_stances.election_security = supportive signal.
    This includes 891 IP37 signers and 243 who indicated
    support through Surveys and Forms.
    [criteria updated]

USER: and 2A

AI: Refined to 612 contacts. Added issue_stances.second_amendment
    = supportive (any source).
    [criteria updated]

USER: only those who haven't been contacted in 30 days

AI: Refined to 487 contacts. Excluded any with a contact log
    entry in the last 30 days.
    [criteria updated]

USER: save this as "PDX Metro 2A and Election Security Outreach"

AI: Tribe saved. 487 members, recomputed on every access.

5.3 The AI’s Job

Behind the conversational interface, the AI performs:

Entity extraction — pull geographic references, demographic descriptors, issue topics, engagement patterns, time windows out of the user’s prose.
Semantic field matching — map “Portland Metro” → counties Multnomah/Clackamas/Washington. Map “election security” → issue_stances.election_security. Map “donated last cycle” → contact log type = donation in the prior election cycle date range.
Disambiguation — when a phrase has multiple plausible meanings, ask. “By ‘recent voters’ do you mean voted in 2024 general, voted in 2024 primary, or registered after Jan 2024?”
Confidence reporting — explicitly tell the user what was interpreted, with named criteria the user can verify and edit.
Failure surfacing — when the AI can’t interpret a phrase, say so. “I don’t recognize ‘high-engagement folks.’ Did you mean voters who opened recent emails, attended events, or something else?” Never silently drop a constraint.
Refinement chaining — interpret each new prompt as a refinement of the current state, not a fresh query (unless the user says “start over”).

5.4 The Criteria Layer — Structured, Editable, Auditable

The natural-language prompt produces a structured criteria expression under the hood — a JSON object representing the filter logic. The user can:

View it inline at any time (right panel “Structured criteria” block)
Edit it directly with a filter-builder UI (visual representation of AND/OR clauses, with field/operator/value pickers)
Export it as JSON for replication or auditing

The structured expression is the truth. The natural language is the interface. The user can build a Tribe entirely in natural language, entirely in the structured editor, or any mixture.

5.5 Manual Filter Builder (Always Available)

For users who prefer click-driven over conversational, the criteria editor doubles as a stand-alone filter builder — same UI as the All Contacts filter bar (from vrm-contacts §7.4), with AND/OR clause support. Some users will never use the AI; that’s fine. The AI is opt-in, additive to the manual path.

6. The Criteria Expression Language

The structured filter layer is a small expression DSL designed for evaluability against the UVP and the voter file. V1 supports:

6.1 Field Operators

Operator	Applies to	Example
`equals`	text, dropdown, boolean	`party_affiliation equals "REP"`
`not_equals`	text, dropdown	`party_affiliation not_equals "DEM"`
`in`	dropdown, multi_select, geo_id	`county_name in ["Multnomah", "Clackamas"]`
`not_in`	dropdown, geo_id
`contains`	text	`notes contains "donor"`
`starts_with` / `ends_with`	text
`greater_than` / `less_than` / `between`	number, date	`age between 25 and 45`
`is_set` / `is_not_set`	any	`email is_set`
`before` / `after` / `within_last`	date, datetime	`last_contacted within_last "30d"`
`confidence_gte`	score, issue_stances	`issue_stances.election_security.confidence_gte 0.7`

6.2 Logical Composition

AND and OR at any depth
Parenthesization for grouping
NOT for negation
Maximum nesting depth: 5 levels (UI guardrail)

6.3 Set Operations

A Tribe’s criteria can reference other Tribes:

member_of_tribe("PDX Donors") — true if UVP is in that Tribe
not_member_of_tribe("Do Not Contact") — exclusion lists
intersect_with_tribe("Recent Volunteers") — same as AND member_of

This is the composable layer. A “Final Outreach Audience” Tribe might be defined as member_of("PDX Donors") AND member_of("Active SMS Subscribers") AND NOT member_of("Do Not Contact"). Three reusable Tribes compose into one targeted action audience.

6.4 Pre-computed Stance/Behavioral Fields

For performance, certain frequently-queried derivations are pre-computed on the UVP:

derived_metro_area — assigned at voter file import time based on city/county
derived_age_bucket — computed from DOB, refreshed weekly
derived_engagement_tier — high/medium/low/dormant, computed nightly from contact log activity
derived_voting_propensity — placeholder for future Polling Engine output (V2+)

These derivations allow common queries to hit indexed columns instead of computed expressions.

7. The Tribe Library — Managing Tribes Across the Account

A dedicated UI surface for browsing, organizing, and operating on the account’s full Tribe inventory.

7.1 The Library View

A filterable, searchable list of all Tribes the account owns:

Type filter: Manual Static / Filter Dynamic / Petition-Sourced / Issue-Stance / AI-Suggested
Audience scope filter: Relationship / Campaign / Petition
Tag filter: User-applied organizational tags
Created-by filter: Multi-user accounts
Date range filter: Created date or last modified

Each Tribe row shows: name, type badge, scope badge, member count (real-time), tags, creator, last modified, action menu.

7.2 Pre-Built System Tribes

Every account starts with a curated set of Issue-Stance and demographic Tribes already provisioned:

Demographic (Relationship + Campaign):

“All Active Voters”
“First-Time Voters”
“High-Propensity Voters”
“Recently Registered (60 days)”

Behavioral (Relationship):

“Active Email Subscribers”
“SMS Opt-Ins”
“New This Month”
“Disengaged (no activity 90+ days)”
“Top 10% Engaged”

Issue-Stance (cross-mode):

One Tribe per registered issue in the canonical issue registry
Auto-populated from issue_stances substructure
Hidden from the library by default if member count is zero; appear once any signal lands

Petition-Sourced (Petition Mode accounts only):

One Tribe per active petition the account manages

System Tribes are read-only (cannot edit criteria) but can be cloned into a user-owned Tribe for further refinement.

7.3 Tribe Actions (per row)

View members — opens the Contact list view filtered to the Tribe
Use in… — quick-route to: Email blast, SMS blast, Phone Bank, Survey, Poll (if applicable mode), Export
Refine — opens the Tribe Builder with current criteria pre-loaded
Clone — creates a copy as a starting point
Rename / Edit description / Tag
Archive — removes from active library; data preserved
Delete — only if Tribe has never been used as an action audience (V1 safety)

7.4 Bulk Operations

Tag multiple Tribes
Merge two Tribes (union of memberships, user names the result)
Compare two Tribes (Venn diagram visualization — overlap, A-only, B-only)
Export Tribe definitions as JSON

7.5 Tribe Discovery (V1.5)

A “Suggested Tribes for You” panel surfaces Tribes that would be useful but haven’t been built yet, derived from the account’s data patterns:

“127 of your contacts share these 3 attributes — name this Tribe?”
“You ran a Form about climate; want a Tribe of respondents?”
“Your IP37 signers haven’t been contacted in 60 days — create an outreach Tribe?”

V2 expands this into the full AI-Suggested membership type (Section 11).

8. The Petition-to-Tribe Pipeline

Ben’s specific framing: “every voter that signs the same petition is automatically recorded as a tribe based on the issue they were for or against.”

8.1 Petition Registration

When a petition is registered in Petition Mode:

The petition’s issue_stance_meta is configured by the user:
- Primary issue (selected from the canonical issue registry — e.g., election_security)
- Stance signing indicates (supportive / opposed)
- Optional: secondary issue tags
The system auto-creates a Petition-Sourced Tribe: “{Petition Name} Signers”
The system auto-tags every signature event with the corresponding Issue-Stance write to the signer’s UVP.

8.2 The Write Operation on Signature

When a voter’s signature is verified (per vrm-petition-mode):

Add UVP ID to the Petition-Sourced Tribe (denormalized for performance, since these are append-only)
Write to UVP issue_stances.{primary_issue}:
- Append a source entry: { source_type: "petition_signature", source_id: <petition_id>, recorded_at: <timestamp>, stance_recorded: <stance> }
- Recompute consolidated stance (Section 4.3)
- Recompute confidence
Update UVP last_updated

This is two writes per signature — one to the Petition-Sourced Tribe membership table, one to the UVP. Both are necessary; both are cheap.

8.3 The Effect on Issue-Stance Tribes

The signer is now automatically a member of:

“{Petition Name} Signers” (Petition-Sourced)
“{Issue} Supporters” (Issue-Stance, system-defined, dynamic)

The user did nothing to make this happen. The petition signature did the work. This is the architectural payoff — petitions become continuous signal generators for issue-stance segmentation.

8.4 Cross-Petition Synergy

If a voter signs IP37 (election security supportive), IP38 (parental rights supportive), and IP39 (anti-tax supportive), they end up in:

3 Petition-Sourced Tribes (one per petition)
3 Issue-Stance Tribes (one per issue)
Plus any derived Tribe that combines these stances (“Multi-Issue Conservatives”)

The pile-up of signals across petitions creates a high-fidelity political portrait without any manual tagging.

9. Performance Architecture

A Tribe Builder that returns “612 contacts” in 200 milliseconds is the difference between a magical product and a frustrating one. This needs to be solid in V1.

9.1 Hot vs. Cold Tribes

Hot Tribes — accessed in the last 24 hours or pinned by the user. Materialized view: membership list cached, incrementally updated as UVP changes land.
Cold Tribes — not accessed recently. Membership recomputed on demand; cached for 15 minutes; evicted afterwards.

This balances storage (don’t materialize every Tribe forever) against latency (don’t recompute every time).

9.2 Indexing Strategy

B-tree indexes on common scalar fields (party, county, age_bucket, registration status)
GIN indexes on JSONB UVP substructures (issue_stances, engagement_metrics, custom_fields)
Spatial indexes on geographic data (precincts, districts, lat/long)
Partial indexes for high-cardinality enums when justified by query patterns

9.3 The Query Planner

The criteria expression compiles to a query plan that:

Resolves any member_of_tribe references first (cheapest, reuses cached materializations)
Applies indexed scalar predicates next
Applies JSONB substructure predicates
Applies un-indexed text/computed predicates last

The user sees a query that took 187 ms; the planner did the heavy lifting.

9.4 Async Recomputation

When underlying UVP data changes (a Form submission, a contact log update, a petition signature), the system:

Inspects which Tribes’ criteria reference the changed fields
Marks those Tribes as stale
Triggers async recomputation for hot Tribes
Lazy-recomputes cold Tribes on next access

For large accounts (1M+ UVPs), eventual consistency on Tribe membership is acceptable as long as it converges within seconds. The Tribe Builder UI shows a “Computing…” indicator while a recompute is in flight.

9.5 Limits

V1 caps:

Max 5,000 Tribes per account (well above realistic use; future raise as needed)
Max criteria expression depth: 5 nesting levels
Max 20 set-operation references per Tribe (to prevent recursive explosion)

10. Privacy, IP, and the Two-Tier Boundary

10.1 What the Customer Sees

The customer sees their own Tribes, with full membership detail (subject to the standard data exposure controls in vrm-data-system). They do not see other accounts’ Tribes, members, or criteria. They do not see other accounts’ issue-stance distributions.

10.2 What Politogy Sees and Uses

Politogy’s Aggregate Intelligence layer mines:

Cross-account Tribe patterns — how many accounts have a Tribe matching “election security supporters”? What criteria combinations cluster? What naming conventions emerge?
Issue-stance distributions at scale — what fraction of the platform’s UVPs carry each stance at each confidence level?
Stance-to-action correlations — do “supportive on election security” voters tend to also be donors? volunteers? high-propensity voters?

These signals refine Politogy’s propensity models — input to the Polling Engine’s four-dimensional scoring and to Enterprise-tier Aggregate Intelligence products. Customer data never leaves Politogy’s systems and is never sold; the patterns derived from aggregated, anonymized data is Politogy’s IP.

10.3 Where the Boundary Sits

Tier	Sees
Customer	Own Tribes, own members, own criteria, own issue-stance distributions
Politogy (operational)	Issue stances per UVP across all accounts, Tribe criteria across all accounts, cross-account membership data
Politogy (commercial)	Anonymized aggregate Tribe-pattern intelligence offered as Enterprise products (cross-account propensity benchmarks, issue-cluster geographic heatmaps)

This is consistent with the two-tier IP architecture in vrm-data-system §12.

11. AI-Suggested Tribes (V2 Detail)

The V2 evolution of Tribes — Politogy’s clustering AI proactively surfaces Tribe candidates.

11.1 What the AI Looks For

Statistical clusters in the account’s UVP attributes that the user has not yet named (k-means / hierarchical clustering on engagement + issue-stance + demographic vectors)
High-value subgroups identified by cross-account benchmarking (e.g., “this segment of your contacts looks like high-converting donor segments in similar accounts”)
Latent issue affinities inferred from indirect signals (e.g., Survey responses that don’t explicitly name an issue but correlate with it)
Engagement-velocity clusters (e.g., “these 78 contacts have all opened the last 5 emails AND clicked at least one — name this Tribe ‘Hot Leads’?“)

11.2 The Suggestion Surface

A “Discover” tab in the Tribe Library. Each suggestion shows:

Candidate Tribe name (AI-generated, editable)
Member count
Defining attributes (in plain English)
Sample members
Confidence and basis (“clustered on attributes A, B, C with similarity score 0.83”)
Buttons: Adopt (save as Filter Dynamic Tribe), Refine (open in Tribe Builder), Dismiss (and don’t suggest again), Save for Later

11.3 Why V2 Not V1

The clustering model needs training data — millions of UVPs with engagement history, issue stances, demographic context. V1 ships and starts accumulating that data. The model trains continuously. V2 launches the suggestion surface once the model is well-conditioned.

This is the same phasing logic used for the Polling Engine’s AI features and for Surveys’ future AI lane-flagging.

12. Cross-Mode Audience Resolution

When a Relationship Mode Tribe is consumed by Campaign Mode (or vice versa), the system resolves membership intelligently rather than naively.

12.1 Relationship → Campaign

A Relationship Mode Tribe (“My Donors in HD37”) consumed by Campaign Mode (e.g., a Phone Bank within Campaign Mode):

Members are already UVPs.
Campaign Mode’s authorization scope is checked — if the Phone Bank is authorized only for HD37, members outside HD37 are filtered out.
The Phone Bank operates on the resolved intersection.

12.2 Campaign → Relationship

A Campaign Mode Tribe (“All Registered REP in HD37”) consumed by Relationship Mode (e.g., an Email blast):

Members are voter-file UVPs.
Relationship Mode requires opt-in claim for the action — only those who are also claimed by the account (via Forms / Surveys / CTAs / Import) are messaged.
The Email blast operates on the intersection of the Campaign Tribe AND the account’s Relationship pool.

This intersection logic is automatic. The user does not have to manually filter. The system says: “247 of the 4,829 voters in this Campaign Tribe are claimed contacts — that’s the email-eligible audience.”

12.3 Petition Tribes Are Universal

Petition-Sourced Tribes (signers) and Issue-Stance Tribes are usable across all modes without scope friction — they’re already at the UVP level and the mode-appropriate filters apply at consumption time.

13. Permissions

Tribes inherits the standard role matrix from vrm-data-system §12.

Role	View Tribes	Create / Refine	Use as Audience	Delete	Bulk Operations
Account Admin	All	Yes	Yes	Yes	Yes
Account Manager	Yes (own + shared)	Yes (own)	Yes (within scope)	Own only	Yes
Field User	Assigned Tribes	No	Limited to assigned	No	No
Viewer	Read-only	No	No	No	No

System-defined Issue-Stance and Petition-Sourced Tribes are visible to all roles within an account’s role-appropriate scope.

14. Provenance & Audit

Every Tribe operation is provenance-tracked:

Tribe creation: user, timestamp, source (Tribe Builder conversation transcript / manual filter / clone / AI suggestion / system auto-create)
Criteria changes: full history of criteria expressions with timestamps
Membership changes (Static Tribes): every add/remove logged
Action history: every time the Tribe was used (Phone Bank X, Email Y, Survey Z, etc.)

This is the audit trail. For multi-user accounts, this is how managers verify how segmentation decisions were made. For compliance, it’s the evidence that targeted messaging respected consent.

15. Mobile

V1 mobile Tribe experience: read + use.

View Tribe Library, browse, search
View Tribe members
Use a Tribe as an audience for an SMS or Email (consume only)

V1 mobile does NOT include the Tribe Builder conversational UI (too constrained for the live-result + chat-history pattern). Tribe Builder is desktop V1.

V1.5: mobile Tribe Builder with a single-panel chat-first UI, results inline.

16. V1 / V1.5 / V2 Scope

V1 — Ship

The Tribe object with five membership types (Manual Static, Filter Dynamic, Petition-Sourced, Issue-Stance, placeholder for AI-Suggested)
audience_scope cross-mode resolution
The issue_stances UVP substructure with canonical issue registry
Petition-to-Tribe pipeline with auto-creation and auto-stance-write on signature
Pre-built system Tribes (demographic, behavioral, issue-stance, petition-sourced)
The Tribe Builder — conversational AI interface with structured-criteria layer, live result panel
Manual filter builder as alternative to AI
The criteria expression language (operators, logical composition, set operations, pre-computed fields)
Tribe Library with type/scope/tag/creator/date filters, search, bulk operations
Tribe actions: View, Use in (Email/SMS/Phone Bank/Survey/Poll/Export), Refine, Clone, Rename, Tag, Archive, Delete
Cross-mode audience resolution (intersection logic for Relationship ↔ Campaign)
Performance: hot/cold Tribe caching, indexed criteria evaluation, async recomputation
Full provenance and audit
Standard role-based permissions

V1.5 — Near-term Additions

Tribe Discovery panel (V1 light AI surfacing)
Tribe comparison (Venn diagram for two Tribes)
Mobile Tribe Builder
Tribe templates (Politogy-curated starter Tribes for common political workflows)
Email/SMS unified send-to-Tribe with one-click audience finalization

V2 — Defer

Full AI-Suggested Tribes with clustering and confidence-scored suggestions
Predictive Tribes (Tribes whose members are predicted-to-have-attribute, e.g., “Likely Donors”)
Cross-account benchmarked Tribes (Enterprise tier — “your supporters compared to similar campaigns”)
Real-time Tribe collaboration (multi-user concurrent refinement)
Tribe-of-Tribes (hierarchies)
Geofenced Tribes (real-time location-based membership for canvassing)

V3+ — Aspirational

Voice Tribe Builder (“Hey VRM, build me a Tribe of…“)
Auto-refining Tribes that learn from action outcomes (“the Tribe you used last week converted at 8%; here’s a refined version predicted to convert at 12%”)
Cross-platform Tribe enrichment (importing third-party segments into VRM)

17. Summary Mental Model

Tribes is how the user slices the UVP into actionable audiences. Forms, Surveys, CTAs, Petitions, Imports, and manual edits all write signals into the UVP. The UVP accumulates them. Tribes is the language and the engine that lets the user pull a precise subset back out for action.

Three modes, three audience scopes, one Tribe object. Five membership types from manual to AI-suggested. A natural-language conversational interface backed by a structured, editable, auditable criteria expression. Issue stances as a first-class UVP substructure that consolidates signals from petitions, surveys, forms, and CTAs into a clean queryable layer. Cross-mode consumption with automatic intersection logic.

The architectural payoff: every signal-generating feature in VRM (Forms, Surveys, CTAs, Petitions) becomes more valuable because Tribes can compose those signals into actionable segments. Every action feature (Phone Banking, Email, SMS, Canvassing, Polling) becomes more effective because Tribes feeds it the right audience. Tribes is the connective tissue.

The strategic payoff: highly targeted messaging is the practical edge of the platform. A campaign with VRM can build a precise outreach audience in thirty seconds. A campaign without VRM has to hire a data consultant. That gap is the product.

North Star: The user types a sentence describing who they want to reach, and within seconds has a precise, persistent, recomputed audience ready to take action against. Everything in this spec serves that promise.

Developer Open Questions

These are V1 architectural decisions that need a recommendation before engineering can scope.

The AI model choice for the Tribe Builder. Anthropic Claude (consistent with the rest of the AI surfaces in VRM), OpenAI, or local fine-tuned model? Recommend Claude — it’s consistent with the platform’s existing AI infrastructure, and the conversational refinement loop is a natural fit. Cost per Tribe Builder session needs modeling.
The structured criteria DSL — JSON vs. SQL-like text vs. visual-only. Storage and interchange format for the filter expression. Recommend JSON (machine-readable, version-friendly, easy to validate) with the visual filter builder as the primary editing UI and the natural-language AI as the primary authoring UI.
Materialization granularity. Hot Tribes materialized as full member lists, as bloom filters, or as compiled query plans? Recommend full member lists for hot Tribes (storage is cheap, sub-100ms lookup matters), compiled query plans for cold Tribes (re-run on demand).
Issue stance recomputation cadence. When a new signal lands (petition signature, survey response, etc.), do we recompute the consolidated stance synchronously or batch? Recommend synchronous for new signals (matters for real-time Tribe membership) with async batch for confidence decay and historical recomputation.
Conflict resolution UX for opposing stance signals. When a UVP has both supportive AND opposed signals on the same issue, the consolidated stance reflects the strongest most recent — but should the customer-tier UI surface the conflict to the user? Recommend yes, as a “mixed signals” indicator on the Contact Card’s Issue Stance section, with the detailed source list available for review.
Canonical issue registry initial inventory. Politogy needs to seed the registry with starter issues. What’s the right initial set? Recommend a list of ~30 covering federal-level (immigration, abortion, election integrity, 2A, taxes, climate, healthcare, etc.) and Oregon-relevant (vote-by-mail, sanctuary status, property tax limits, etc.); expanded as accounts in other states onboard.
Tribe Builder AI personality and tone. Should the AI assistant in the Tribe Builder feel like a researcher (Methodology Agent style), a marketer (peppy, suggestive), or a neutral utility? Recommend neutral utility with subtle helpfulness — closer to “professional analyst” than “marketing pal.” Matches the political-tool seriousness.
Petition issue stance — single primary issue or multiple? A petition can speak to multiple issues; recommend a primary issue (canonical, drives the auto-stance write) and optional secondary tags (for filtering but not auto-stance). Keep the auto-stance logic clean.
Tribe membership change notifications. When a Tribe the user is about to send to grew or shrank significantly since they last viewed it, should the system warn before send? Recommend yes — banner notification if membership changed >5% since last view, with an option to refresh.
Cross-mode Tribe scope conflicts. A user in Campaign Mode tries to use a Relationship Mode Tribe whose members are outside their authorized geography. Behavior? Recommend automatic filtering with a “X of Y members in your authorized scope” notice; don’t error, don’t silently include out-of-scope members.
Static Tribe upper bound on member count. Realistic upper bound for explicit Static membership lists? Recommend 100,000 hard cap; beyond that, Static doesn’t make sense — switch to Dynamic with a saved criteria expression.
The “Use in” action menu options. Which destinations should be quick-route-accessible from the Tribe row? Recommend Email, SMS, Phone Bank, Survey, Poll, Export, Add to other Tribe, Subtract from other Tribe.
Refinement vs. new query distinction. When the user types something in the Tribe Builder, the AI defaults to refining the current state. What’s the explicit user signal to start over? Recommend a “Start over” button + AI’s ability to detect intent (“forget that, instead show me…”) with confirmation.
Tribe sharing across users in an account. Are Tribes private-to-creator by default, or shared across the account by default? Recommend shared-across-account by default (campaign teams need visibility); creator can mark a Tribe as private.
Member-count update frequency for Library list view. The Library shows member counts for every Tribe. Recompute on every page load (expensive) or use the last-cached count with a staleness indicator? Recommend last-cached with staleness indicator (e.g., “247 members, as of 6 minutes ago”); click-to-refresh for live count.
Issue-Stance Tribe visibility threshold. Issue-Stance Tribes auto-exist for every issue in the registry. Should they be visible in the Library only when they have members? Recommend yes, hide empty issue-stance Tribes by default; “Show all issue-stance Tribes” toggle for the curious.
The Tribe Builder’s handling of impossible/contradictory queries. User types: “voters in Portland who live in Salem.” AI behavior? Recommend explicit error response: “These two criteria conflict (Portland is in Multnomah, Salem is in Marion). Did you mean one or the other, or both as alternatives?”
Action-history influence on Tribe Builder suggestions. Should the AI use the user’s recent action history (sent emails, ran surveys) to inform Tribe Builder suggestions (“looks like you’re building an audience for your weekly newsletter — should I include the existing newsletter exclusion list?”)? Recommend yes in V1.5, not V1; needs more behavioral telemetry before useful.
Engagement metric definitions — account vs. platform. “Highly engaged contacts” — is the threshold per-account-tuned (top 10% of this account’s contacts) or platform-defined (e.g., opened 3+ emails in the last 30 days)? Recommend platform-defined defaults with optional per-account override; consistency across accounts makes the AI’s interpretation cleaner.
Petition-Sourced Tribe membership when a petition signature is withdrawn. What if a signature is later invalidated (county elections office rejection, fraud detection, etc.)? Recommend: remove from Petition-Sourced Tribe membership immediately; demote the issue-stance source contribution (don’t delete it from history — mark as invalidated for audit); recompute consolidated stance.
Tribe Builder transcript retention. The conversational history that built a Tribe — keep it indefinitely for audit, or roll off after N days? Recommend keep indefinitely; it’s small data and high audit value.
Boolean issue stances vs. spectrum. Currently the spec uses supportive / opposed / neutral / unknown. Should we add intensity (“strongly supportive” vs “lean supportive”)? Recommend no for V1 — that’s the Polling Engine’s four-dimensional scoring’s job. Tribes uses the simpler four-state stance and leaves intensity to Polls.

End of Spec

This document is the V1 conceptual specification for VRM Tribes — the cross-mode segmentation engine that turns natural-language audience descriptions into precise, dynamically-recomputed UVP groupings.

The North Star: the user types a sentence, the system delivers an audience. Highly targeted messaging without the data consultant.

🗳️ Politogy VRM — V2 Specs

Explorer