t0ddc3by/claude-for-customer-success/csql-tracking

[VALIDATED]

Overview

rev-ops:csql-tracking manages the full lifecycle of Customer Success Qualified Leads (CSQLs) — the handoff artifact produced by csm:expansion-business-case [mode=csql] — from CS handoff through closed/won or terminal pipeline states. It provides RevOps with a persistent, queryable portfolio of active and closed CSQLs within the CS plugin's filesystem control plane.

This skill is the downstream consumer in a two-skill inter-skill contract:

csm:expansion-business-case [mode=csql]
        ↓  emits CSQL Qualification Package
rev-ops:csql-tracking [operation=create]
        ↓  persists to context/csql-*.md

Four operations are supported: create, update, close, query.

Pre-flight

Read ~/.claude/plugins/config/claude-for-customer-success/rev-ops/CLAUDE.md and ~/.claude/plugins/config/claude-for-customer-success/company-profile.md.

If either is missing or contains [PLACEHOLDER] markers, stop and prompt for /rev-ops:cold-start-interview.

Note from config: cs_platform_connected

G-code dependency: All G-code guardrails referenced in this skill (G1–G9) are defined in the CLAUDE.md config loaded above. If Pre-flight halts or config is missing, G-codes are undefined — do not proceed with partial config.

Use When

• A CSM has completed a CSQL Qualification Package via csm:expansion-business-case [mode=csql] and needs to register it in the CSQL pipeline
• RevOps or an AE needs to update a CSQL status, assign an AE, or append notes to an existing record
• A deal reaches a terminal state (won, lost, or stalled) and needs to be formally closed in the tracker
• RevOps wants a portfolio view of active or closed CSQLs, with filtering by status, CSM, AE, or account, and sorting by creation date or close date

Do NOT Use For

• Generating CSQL Qualification Packages — use csm:expansion-business-case [mode=csql] for that
• CRM integration or external data writes of any kind
• Revenue forecasting or pipeline analytics
• Notification or alerting workflows

Typical Activation

• "Register this CSQL for Acme Corp"
• "Update CSQL-ACME-20260516-001 status to qualified"
• "Close CSQL-WIDG-20260510-002 — won at $42,000"
• "Show me all active CSQLs assigned to Jane"
• "Log a CSQL for Thorngate Partners — here's the qualification package"

Reasoning Protocol

Before generating output, apply these primers:

1. CLASSIFY: What type of CSQL operation is this?

• Create (ingest a new CSQL Qualification Package and persist a new record)
• Update (modify mutable fields on an existing CSQL record)
• Close (set a CSQL to a terminal state — won, lost, or stalled)
• Query (retrieve, filter, and surface one or more CSQL records)

1. CONSTRAINTS: What limits the solution space?
2. Confirm activation — user requesting CSQL lifecycle management or retrieval
3. Resolve the target CSQL record(s) from filesystem; declare file path and data-as-of context
4. Apply G9 — all filesystem write operations (create, update, close) require explicit user confirmation before execution; surface as draft and await approval
5. Enforce immutable field lock — csql_id, created_at, csm_owner, and source_skill fields cannot be modified after record creation under any circumstance
6. Enforce terminal state immutability — records in won, lost, or stalled status cannot be reopened, updated, or re-staged; surface the block explicitly if attempted
7. Validate status transitions against the state machine before proposing any update; reject invalid transitions with a clear explanation
8. Confirm output destination before delivering — inline summary vs. formatted table vs. full record dump

1. EXPERT CHECK: What would a veteran RevOps CSQL lifecycle analyst verify before executing?

• Is the CSQL ID being referenced one that actually exists in the filesystem? Fabricating or inferring a CSQL ID from partial context before confirming the record exists produces phantom operations. Read the record first, then act.
• Is the requested status transition valid per the state machine? The lifecycle is create → qualified → in_negotiation → won/lost/stalled. Skipping stages (create → won) or reversing direction (won → in_negotiation) are not supported — the analyst flags and blocks, not silently accepts.
• Is the close operation being performed with sufficient terminal-state data? A won close requires ACV; a lost close requires lost_reason. Attempting to close without required fields is a partial write — surface the missing data requirement before writing anything.
• Is the query filter producing the intended scope? Filters default to active records (exclude_closed=true); a query that silently omits closed records when the user asked "all CSQLs" is a silent data gap. Confirm include_closed intent before executing.

1. ANTI-PATTERNS: Common mistakes to avoid:

• Attempting to modify csql_id, created_at, csm_owner, or source_skill after record creation — these are immutable and the operation must be blocked, not silently ignored
• Attempting to update or close a record already in won, lost, or stalled status — terminal states are locked; surface the block with the current terminal state and explain why the operation cannot proceed
• Executing filesystem writes (create, update, close) without surfacing the draft for G9 confirmation first — this is a write-tier protocol violation
• Silently rejecting an invalid status transition without explaining what transitions are valid from the current state — the user needs the valid path forward, not just a block
• Returning query results that omit closed records when the user's intent was a full-portfolio view — always confirm include_closed scope for broad queries

After execution, verify:

• G9 confirmation surfaced for all filesystem write operations — no writes executed autonomously
• Immutable field lock enforced — no csql_id, created_at, csm_owner, or source_skill mutations accepted
• Terminal state immutability enforced — no won/lost/stalled record updates or reopens executed
• Status transition validated against state machine before any update was proposed
• Confidence: High when CSQL record retrieved directly from filesystem and field values confirmed; Moderate when record inferred from context or CSQL ID not yet confirmed in filesystem
• Confidence: [High] when CSQL record retrieved directly from filesystem and field values confirmed / [Medium] when record inferred from context or CSQL ID not yet confirmed in filesystem / [Low] if all inputs are manual or unverified

Operations

create

Purpose: Ingest a completed CSQL Qualification Package and persist a new CSQL record to the filesystem.

Parameters:

Auto-generated fields (immutable after creation):

Behavior:

1. Sanitize account_name via safe_account() for filesystem path derivation.
2. Derive csql_id using Auto-ID generation rules (see Filesystem Architecture).
3. Write context file: context/csql-[safe_account]-[YYYY-MM-DD]-v1.md
4. Append initial transition log entry: [created]
5. Set initial status to new.

Output: Returns csql_id and the path of the created context file.

Error conditions:

• account_name empty or missing → rejected with field validation error
• csql_package empty or missing → rejected with field validation error
• csm_name empty or missing → rejected with field validation error
• expansion_product empty or missing → rejected with field validation error

update

Purpose: Partially modify a non-terminal CSQL record — status progression, AE assignment, close date update, or note append.

Parameters:

Immutable fields — rejected if included in `update` payload:

Behavior:

1. Locate the latest version file for the target csql_id.
2. Verify record is not in a terminal state (won, lost, stalled). If terminal → reject with: Update rejected: CSQL-[ID] is in terminal state [status] and cannot be modified.
3. If status is provided, validate against the transition guard. Reject invalid transitions.
4. Write new version file (v[N+1]). Prior version is preserved — never overwritten.
5. Append transition log entry if status changed.
6. Append note if notes provided.

Output: Returns updated csql_id, new version path, and transition log entry (if status changed).

Error conditions:

• csql_id not found → not-found error
• Record in terminal state → terminal-lock error
• Invalid status transition (no override) → transition guard rejection with valid next states listed
• Override on terminal state → rejected: Override rejected: terminal state [status] is immutable and cannot be overridden. Create a new CSQL to re-pursue this opportunity.

close

Purpose: Set a CSQL to a terminal state and lock the record.

Parameters:

Behavior: