1. Overview

Phase 1 (Firestore form) is retired. The live roadmap at /dept/engineering?tab=itsc reads and writes Ticket__c Initiative records in Salesforce directly. Use the audit banner above (loaded from the org) to see which V2 optional fields are still missing.

User edits inline on /dept/engineering ──► services/itsc_sf.py ──► Salesforce Ticket__c (Initiative RT)
Reports / Power BI / SF users ← SOQL ──► same records

Both sides see the same data. Either side can edit. Conflicts are resolved by LastModifiedDate.

2. Architecture

Use the existing Ticket__c object with a new Strategic Initiative record type. This decision (carried forward from v1) avoids a duplicate object hierarchy, inherits ticket lifecycle / ownership / sharing for free, and keeps reporting in one universe.

Three things that are different in v2:

• Dual-write contract (§13) — the DataOS form remains the operational UI; the Firestore document is a cache, not the system of record.
• Three additional brief fields (§4) — the workbook's per-project one-pager has 4 panels, not 1, and v1 only mapped one of them.
• Total score + executive sponsor + intake metadata (§4) — preserves the upstream nomination/scoring artifacts the steering committee uses.

3. Record Type Configuration

New Record Type: Strategic Initiative

Represents strategic roadmap initiatives, cross-functional programs, and operational improvement efforts. Does not replace standard development / Salesforce-ops tickets, bug tracking, or support workflows — those keep their existing record types.

• Profile assignment: Initial access to Engineering Leadership, IT, and Strategy users; broader once the workflow is validated.
• Page layout: see §7.
• Default record-type behavior: new Ticket created from /dept/engineering always carries this record type ID.

4. Field Additions on Ticket__c

20 new fields. Bold = additions beyond the v1 spec. Italic = clarifications.

4a. Strategic context

4b. Alignment flags (5 booleans, unchanged from v1)

4c. Brief one-pager new in v2 (four panels)

The workbook stores a four-panel one-pager per project. v1 mapped only the first panel to the existing Description field. v2 adds the missing three.

4d. Intake / scoring new in v2

4e. Hierarchy + identity

4f. Audit (preserve original attribution through migration)

5. Existing Fields to Reuse

6. Parent / Child Initiative Structure

Parent_Initiative__c is a self-lookup on Ticket__c filtered to the Strategic Initiative record type. Validated needs from the 50 imported records:

• 🧩 Feedback Platform (v1) ↔ (v2)
• 🌐 Event Segmentation (v1) ↔ (v2)
• 📱 Event App : PWA – In-House (v1) ↔ (v2)
• ⚡ BidSpeed (cloverleaf) ↔ ⚡ BidSpeed (euna) (siblings under a new "BidSpeed" parent record)
• 📊 Sponsor Portal Automation (Pre-Event) ↔ (Post-Event)
• 3 × 🤖 Agent Phase 2 (Tell Me When Alerts / Proposal Generator / Personal Document Library) under a new "Agent Phase 2" parent
• 3 × GTZenda items (Process Optimization / Full Autonomy / Grants Data API Integration) under a new "GTZenda" parent

Backfill creates the umbrella parent records where one doesn't already exist; assigns Parent_Initiative__c for each child during the same migration pass.

7. Page Layout

Sections, in order:

1. Initiative Details — Title, Record Type, Status, Priority, Sort Order, Owner, IT Lead, Launch Target Raw, Launch Target Date (formula), Department, Strategic Group
2. Strategic Context — Strategic Value, Level of Effort, Dev T-Shirt, Dev Readiness, Total Score, Primary System
3. Goal Alignment — Alignment, High Impact Work, Retention Focus, Thought Leadership, AI Ways of Working (5 checkboxes inline)
4. Brief — Description ("What It Does"), Why It Matters, Business Impact, Punchline
5. Intake — Submitted By, Executive Sponsor, Intake Document URL, Reviewer Comments
6. Hierarchy — Parent Initiative, Related list: Child Initiatives (filtered self-lookup)
7. System — DataOS Project Id, Imported Created/Updated By, standard audit fields (collapsed by default)

8. Voter Scoring — Decision and Future Path

Rationale: the per-voter scoring exercise is upstream of becoming a real Ticket__c — six voters per nominee, scores 1-5, the committee tallies and picks. The total is what leadership reads; the per-voter detail is committee-internal. Putting per-voter rows in SF today would require a child object that only DataOS writes to.

Future path (additive, no migration of Total_Score__c): if SF needs per-voter history later, add an ITSC_Voter_Score__c master-detail child with Voter_Name__c / Voter_User__c / Score__c / Recorded_At__c, and convert Total_Score__c to a Roll-Up Summary. The DataOS sync then writes child rows instead of just the rolled-up total. Zero impact on existing reports.

9. Picklist Expansions

Validated against the 50 records currently in Firestore.

9a. Status

9b. Priority

9c. Level of Effort

Plain High / Medium / Low. Emoji stripped at migration; no data loss (clean 50-of-50 map).

10. Department vs. Strategic Group — Two-Field Model

These are different concepts and stay in different fields:

• Department (existing, free-text or picklist) = operational owner. The 50 records have 32 distinct values like "Product / Events / Sales Ops" or "Marketing / Demand Gen". Preserved as-is.
• Strategic_Group__c (new picklist, §4a) = strategic lens. One project can be in dept "Marketing / Demand Gen" AND strategic group "Retention & Intelligence".

This avoids the lossy force-fit of 32 free-text departments into 9 strategic-group picklist values.

11. List Views

• All Strategic Initiatives — RecordType = Strategic Initiative, sort by Priority ASC, Sort_Order__c ASC, Launch_Target__c ASC NULLS LAST
• P1 Active — Priority = P1 AND Status NOT IN (Completed, N/A)
• P2 Pipeline — Priority = P2 AND Status NOT IN (Completed, N/A)
• Not Yet Prioritized — Priority IN (TBD, Not yet Prioritized)
• Needs Attention — Status IN (Paused, Unknown) OR (Launch_Target__c < TODAY AND Status NOT IN (Completed, N/A))
• Upcoming 90d — Launch_Target__c BETWEEN TODAY AND TODAY+90, Status NOT IN (Completed, N/A)

12. Validation Rules

• Launch_Target_Raw_Valid — Launch_Target_Raw__c is blank OR matches ^\d{4}-\d{2}-\d{2}$ OR ∈ {?, TBD, N/A}
• Dev_Readiness_Range — 0 ≤ Dev_Readiness__c ≤ 100
• Total_Score_NonNeg — Total_Score__c ≥ 0
• Parent_Cannot_Be_Self — Parent_Initiative__c ≠ Id

13. Dual-Write Contract (DataOS ⇄ Salesforce)

This is the v2-specific addition. The DataOS form remains the system of entry; Salesforce is the system of record. Both stay consistent through a deterministic dual-write keyed on DataOS_Project_Id__c.

13a. Write path (DataOS form → SF)

User submits the form at /dept/engineering
   │
   ▼
services/itsc_roadmap.py::create_project / update_project / delete_project
   │   (existing: validates + persists to Firestore)
   ▼
services/itsc_sf_sync.py::push_to_sf(project_id)        ← NEW MODULE
   │   - simple-salesforce upsert against Ticket__c using
   │     DataOS_Project_Id__c as the external ID
   │   - field map lives in one dict (mirrors §4)
   │   - on success: stores SF Id back on the Firestore doc
   │   - on failure: logged + queued for retry, does NOT fail the user request
   ▼
SF Ticket__c (Strategic Initiative record type) — system of record

• Idempotent: upsert by external ID, safe to replay.
• Fail-open from the user's perspective: a transient SF outage doesn't block the form save. The retry worker (scheduled every 15 min via the existing ETL scheduler) drains the queue.
• Voter scores: when the form submits, the recomputed total_score is what gets pushed. Per-voter rows are NOT pushed (see §8).

13b. Read path (today: Firestore; tomorrow: SF)

Phase 1 (immediate after backfill): reads continue from Firestore for sub-50ms latency in the /dept/engineering tab. SF is shadow-of-truth.

Phase 2 (once SF UI exists and is in steady use): a nightly reconciliation job pulls every Ticket__c with RecordType = Strategic Initiative, diffs against Firestore by DataOS_Project_Id__c, and applies SF-side edits back into Firestore. Conflict resolution: LastModifiedDate wins.

Phase 3 (optional, future): cut over reads to SOQL directly, decommission the Firestore collection. Service signature doesn't change, only the loader behind services/itsc_roadmap.py::list_projects does.

13c. Reverse path (SF → DataOS, Phase 2 onward)

• Triggered by either:
  • A scheduled reconciliation (15-min cadence), OR
  • A SF Outbound Message / Platform Event on Ticket__c update (if SF ops is comfortable adding it)
• For each SF record where LastModifiedDate > Firestore.updated_at, write the SF state back to Firestore.
• Skips records where DataOS write happened in the last 60 seconds (debounce so a DataOS write doesn't immediately echo back as a SF→DataOS overwrite).

13d. Source of truth for each field

14. Data Migration

Migration target: the 50 records currently in itsc_projects Firestore.

Steps:

1. Export Firestore → flat CSV via a one-shot scripts/export_itsc_to_sf_csv.py (writes itsc_to_sf.csv with columns = SF API names per §4 + §5; emojis stripped from Priority and LOE; status remapped per §9a).
2. Identify the 7 parent-record umbrellas from §6 — create them in SF first (manually or as separate CSV rows), capture their SF Ids.
3. Backfill parent_id column in itsc_to_sf.csv using the umbrella SF Ids.
4. Bulk upsert into Ticket__c keyed on DataOS_Project_Id__c. Validate row count = 50 + umbrella count.
5. Spot-check the 5 emoji-heavy records (Custom Communication, Health Dashboard, both Feedback Platforms, GTZenda variants) to confirm round-trip.
6. Turn on dual-write in DataOS (env flag ITSC_SF_SYNC_ENABLED=1). From that moment, all DataOS writes also push to SF.
7. Run a one-time reconciliation read (SF → Firestore) to confirm parity.

Rollback: disable ITSC_SF_SYNC_ENABLED. DataOS reverts to Firestore-only operation. SF records remain but go stale until re-enabled.

15. Phasing / Rollout

16. Benefits of This Approach

• No duplicate object hierarchy — uses existing Ticket__c lifecycle, ownership, sharing, audit.
• Single source of truth in Salesforce — Power BI, SF reports, and the rest of the company's data universe see initiatives in the same place they see tickets.
• DataOS form remains the operational UI — the steering committee keeps the fast, purpose-built /dept/engineering tab they're already using.
• Zero data loss from the current workbook — every field that today has a non-trivial value (brief panels, voter total, exec sponsor, intake metadata) has a home.
• Additive future path for voter detail — when/if SF needs per-voter rows, it's an additive child object, not a migration.
• Fail-soft on SF outage — user writes never block on SF availability.

17. Open Questions for Steering / SF Ops

1. In Progress vs. In Development — are these two genuinely different statuses, or did the workbook accidentally accumulate both? Currently 5 records use In Progress and 6 use In Development. Recommend keeping both (committee call).
2. Submitted_By__c vs. ownership — is the submitter the same as the eventual owner in 90% of cases? If yes, we can default Submitted_By__c to OwnerId on insert and skip the extra picker in the form.
3. Intake docs — keep Intake_Document_URL__c as a URL field, or move to native SF Files (ContentDocument)? Files give versioning and access control; URL is simpler for the SharePoint links the committee already uses.
4. Reviewer comments — Reviewer_Comments__c field, or Chatter? Chatter gives threading and notifications but is harder to migrate from the workbook's free-text field.
5. Strategic_Group picklist values — the 9 listed are from v1. Should the committee add / rename / drop any before deployment, while picklist changes are still cheap?

18. Changes from V1

For anyone who's already read v1: