data-persistence

Fires on any operation that reads or writes deal, company, contact, call note, or task data. Provides: file schemas, write protocol (entity + index + cross-references + ops.log), account name resoluti

SKILL.md

GitHub

Data Persistence Skill

Purpose

Central reference for all data operations. The primary data layer is local workspace files with structured headers. Follow the write protocol in the Project CLAUDE.md (.claude/CLAUDE.md).

If a connected database service is available, data can also be synced to structured databases using the schemas below. Local files are always canonical.

When Referenced

  • Any interaction reading or writing data — local file operations, schema validation, account resolution
  • Deep personalization sessions — creates local data structure and optionally syncs to connected databases
  • Adding accounts and deals — record creation in local files
  • Processing calls — writes to multiple local files simultaneously (call note, deal, contacts, tasks, index)

Core Framework

Database Schemas

Companies (13 fields)

# Field Type Options/Notes
1 Company Name Title —
2 Territory Status Select Active, Prospect, Inactive, Former Customer
3 Industry Select Options populated during deep personalization per user's market
4 Account Size Select Enterprise, Mid-Market, SMB
5 Hell Yes/Hell No Select Hell Yes, Evaluating, Hell No
6 Primary Contact Relation →Contacts
7 Tech Stack Multi-select Populated per account
8 Current Products Multi-select User's product line, set during deep personalization
9 Annual Revenue Number —
10 Last Activity Date Auto-updated on any interaction
11 Notes Text Research briefs, general context
12 Website URL —
13 Evidence Sources List Provenance: what sources informed key fields (grade, source, date per field). See Project CLAUDE.md for format.

Contacts (9 fields)

# Field Type Options/Notes
1 Name Title —
2 Company Relation →Companies
3 Title Text Job title
4 MEDDPICC Role Multi-select Champion, Economic Buyer, Technical Buyer, Influencer, Blocker, User
5 Email Email —
6 LinkedIn URL —
7 Sentiment Select Champion, Supportive, Neutral, Skeptical, Blocker
8 Last Contacted Date —
9 Notes Text —

Deals (22 fields)

# Field Type Options/Notes
1 Deal Name Title —
2 Company Relation →Companies
3 Contacts Relation →Contacts (linked during add deal)
4 Stage Select Prospecting, Discovery, Qualification, Proposal, Negotiation, Closed Won, Closed Lost
5 Deal Value Number —
6 Close Date Date —
7 Forecast Category Select Commit, Best Case, Pipeline, Omitted
8 Primary Competitor Select Options populated during deep personalization Phase 3
9 Next Step Text —
10 Deal Risk Select High, Medium, Low
11 MEDDPICC Confidence Select High, Medium, Low
12 M-Metrics Select Red, Yellow, Green
13 E-Economic Buyer Select Red, Yellow, Green
14 D-Decision Criteria Select Red, Yellow, Green
15 D-Decision Process Select Red, Yellow, Green
16 P-Paper Process Select Red, Yellow, Green
17 I-Identify Pain Select Red, Yellow, Green
18 C-Champion Select Red, Yellow, Green
19 C-Competition Select Red, Yellow, Green
20 Created Date Date Set on creation
21 Last Activity Date Auto-updated on any interaction
22 Notes Text —

Default Stage Probability Weights (used by forecast update):

Stage Default Probability
Prospecting 10%
Discovery 20%
Qualification 40%
Proposal 60%
Negotiation 80%
Closed Won 100%
Closed Lost 0%

These are defaults. Deep personalization asks if the user's org uses different stage names or probabilities, and stores customized values in {{DEAL_STAGES}}.

Tasks (9 fields)

# Field Type Options/Notes
1 Task Title —
2 Company Relation →Companies
3 Deal Relation →Deals
4 Owner Select AE, Prospect, Internal
5 Priority Select High, Medium, Low
6 Due Date Date —
7 Status Select Not Started, In Progress, Done, Blocked
8 Source Select Call, Strategy, Manual
9 Notes Text —

Call Notes (10 fields)

# Field Type Options/Notes
1 Call Title Title —
2 Company Relation →Companies
3 Deal Relation →Deals
4 Call Date Date —
5 Summary Text AI-generated summary
6 Action Items Text Extracted tasks (also written to Tasks DB)
7 Risk Level Select High, Medium, Low
8 Competitive Intel Text Competitor mentions and analysis
9 Coaching Score Number 1-5 (average of 5 coaching dimensions)
10 MEDDPICC Changes Text Elements that changed R/Y/G this call

LinkedIn Posts (8 fields)

# Field Type Options/Notes
1 Post Title Title —
2 Post Type Select Personal, Business, Educational
3 Status Select Idea, Draft, Ready, Scheduled, Posted
4 Scheduled/Posted Date Date —
5 Hook Text First 2 lines (scroll-stopper)
6 Content Text Full post body
7 Related Company Relation →Companies
8 Notes Text —

Total: 6 databases, 70 fields.

Account Resolution Logic

When a user references a company by name, resolve using this priority order:

  1. Exact match on Company Name field (case-insensitive)
  2. Starts-with match if no exact match (e.g., "Acme" matches "Acme Corporation")
  3. Contains match as fallback (e.g., "Acme" matches "The Acme Group")
  4. Multiple matches → ask user to clarify: "I found multiple matches: [list]. Which one?"
  5. No match → "I don't have [Company] in my records. Want me to add [Company] to your pipeline?"

When resolving for deal-specific capabilities (deal strategy, competitive analysis, meeting prep):

  • After finding the company, look for active deals (Stage ≠ Closed Won, Closed Lost)
  • If multiple active deals → ask: "You have [X] active deals at [Company]: [list]. Which one?"
  • If one active deal → use it automatically
  • If no active deals → "No active deal at [Company]. Want to add a deal for [Company]?"

Read/Write Patterns by Command

Capability Reads Writes
Morning Briefing Tasks (due/overdue), Deals (needing attention) —
Evening Wrap Tasks (today's), Deals (movement) —
Weekly Summary Deals (all active), Tasks (week), Call Notes (week) —
Call Processing Companies, Contacts, Deals, Call Notes (history) Call Notes (new), Tasks (new), Deals (MEDDPICC update), Companies (Last Activity)
Meeting Prep Companies, Contacts, Deals, Call Notes (recent), Tasks —
Deal Strategy Companies, Deals, Contacts, Call Notes, Tasks —
Competitive Analysis Companies, Deals, Call Notes, Contacts —
Business Case Companies, Deals, Call Notes —
Pipeline Review Deals (all active), Companies —
Whitespace Analysis Companies, Deals —
Forecast Update Deals (by period) —
Account Research Companies (if exists), Deals, Call Notes Companies (Notes, Tech Stack, Industry, Account Size)
Outreach Companies, Contacts, Deals —
Contextual Email Companies, Contacts, Deals, Call Notes —
LinkedIn Post LinkedIn Posts (recent) LinkedIn Posts (new draft, on confirm)
Presentation Companies, Deals, Contacts, Call Notes —
Add Company Companies (duplicate check) Companies (new record)
Add Deal Companies, Contacts, Deals (duplicate check) Deals (new record)
Call Coaching Call Notes, Deals —
Passive capture (all conversations) Trail (recent), entity files Trail (new entry), entity notes (updated). See CLAUDE.md Section 10.5.

Intelligence Trail

Trail files (data/trail/) are written passively during substantive conversations. They capture: what was discussed, which entities were referenced, what decisions were made, and what intelligence was filed. One file per conversation per day. The trail is the safety net that catches intelligence the structured commands miss.

Use the Section 10.5 capture decision policy before writing: NOOP, TRAIL_ONLY, TRAIL_PLUS_ENTITY_UPDATE, or ASK_USER. Default to trail-only when uncertain. Entity notes are updated only for explicit, high-confidence facts tied to existing records; casual or inferred remarks stay in the trail.

Write Failure Handling

When a database write fails:

  1. Never silently drop data. Always inform the user what failed to save.
  2. Present the data that would have been written in a formatted block the user can manually enter.
  3. Diagnose the likely cause:
    • "Database not found" → Database ID may be wrong. Suggest: "Check that your databases are set up. Try a deep personalization session to reconfigure."
    • "Permission denied" → API key may lack write access. Suggest: "Check your integration permissions — it needs read AND write access."
    • "Validation error" → Field type mismatch. Suggest: "The [field] in your [database] may have different options than expected."
    • "Rate limited" → Too many requests. Suggest: "The service is rate-limiting requests. I'll try again in a moment."
  4. Retry once on transient errors (rate limit, timeout). If retry fails, fall back to manual mode.
  5. Log the failure context so self-audit can check for patterns.

V4 Persistence Architecture

SalesSidekick uses a three-tier persistence model. No external services required for the core experience.

Tier Where What lives here When it's read API calls
Slow lane Global CLAUDE.md (/mnt/.claude/CLAUDE.md) Stable identity and operating guardrails: name, company, product, ICP, competitors, selling style, quality rules, cascading context rules, and memory/setup protection. Written automatically during onboarding from templates/global-identity.md within <!-- SALESSIDEKICK-IDENTITY-START/END --> markers. Automatically by Cowork before any plugin fires Zero
Fast lane Local workspace files (data/ in Project folder) All operational data: deals, contacts, companies, call notes, tasks. Stored as structured markdown with YAML frontmatter. data/index.md is the flattened read cache. On demand when capabilities need data Zero
Optional Connected databases (if available) Structured database views of the same data. Cross-device access. Only when user explicitly requests database features Per operation

Data operations use the write protocol defined in the Project CLAUDE.md (.claude/CLAUDE.md in the workspace). The full schemas, cross-reference rules, ops.log format, and write-verification step are there.

Local files are always canonical. If local files and connected databases disagree, local files win.

Write verification: Every write operation completes with a read-back verification step. After writing the entity file, updating the index, updating cross-references, and logging to ops.log, the system reads back the index row for the primary entity and confirms key fields match. If they don't match, the index update is retried once. If retry fails, VERIFY_FAIL is logged and the user is informed. This catches partial writes immediately.

Database Creation (optional — deep personalization Phase 6)

Only if the user has a database connector and wants structured views:

  1. Search by name before creating — never duplicate
  2. Create in dependency order: Companies → Contacts → Deals → Tasks → Call Notes → LinkedIn Posts
  3. Set up cross-relations after all databases exist
  4. Store database IDs in the Project CLAUDE.md
  5. Verify by reading back each database

Structured Database Schemas (for optional database sync)

The schemas below define the structured database format. They are used ONLY when a database connector is active and the user has opted into database sync. The primary data model uses the local file schemas defined in the Project CLAUDE.md template.

Personalization Notes

  • Select field options for Industry, Primary Competitor, and Current Products are customized during deep personalization
  • Stage names and probability weights may be customized
  • Account resolution logic is universal — no personalization needed
  • Identity and personalization variables live in Global CLAUDE.md — not in external databases