# Customer Knowledge
Maintain durable customer facts without turning recollection into certainty. The skill owns a living knowledge base and an append-only source ledger for each named customer. Every substantive fact in the knowledge base must trace to a stable source ID and either an archived source document or an explicit archive-pending provider/local pointer.
Load First
Read these shared references before writing:
- `./references/dependencies/conversint-current/references/skill-operating-standards.md`
- `./references/dependencies/conversint-current/references/output-paths.md`
- `./references/dependencies/conversint-current/references/google-workspace-access.md` when Gmail or Drive is involved
- `./references/dependencies/conversint-current/references/client-deliverable-standards.md` section 4 for citation rules
- This skill's `./references/artifact-schema.md`
Use the repo-local Google Workspace tooling. Read Gmail through `/gmail` and perform Drive operations through `/gdrive` or `lib/gdrive.py`; do not implement parallel Gmail or Drive clients inside this skill.
Owned Records
For customer display name `<Customer>`, this skill owns:
- `customers/<Customer>/<Customer> - Knowledge Base.md`
- `customers/<Customer>/<Customer> - Knowledge Source Ledger.md`
Whenever a run captures information Patrick supplies directly in chat, create or update this supporting source document; it is mandatory, not optional:
- `customers/<Customer>/<Customer> - Firsthand Notes.md`
The knowledge base is a current synthesis. The source ledger and firsthand note are append-only evidence records. Git history versions the files; do not create dated copies of the knowledge base or ledger.
Modes
Infer the mode from the request. If the request combines modes, use the order `archive -> capture -> refresh -> report -> audit`.
`init`
Create the three customer artifacts as needed, inventory available primary sources, assign source IDs, archive approved source documents, and populate the first cited knowledge base.
`capture`
Add one or more new sources or firsthand statements. Update the source ledger before changing the knowledge base. Preserve the user's wording in the firsthand note and separate it from any interpretation.
`refresh`
Reconcile new source material against the current ledger and knowledge base. Add new source IDs, mark contradicted facts in the knowledge base, and regenerate affected sections without erasing history. Change a source's status to `Disputed` only when the source itself is questionable and to `Superseded` only when a later source replaces it; ordinary disagreement does not invalidate either source.
`report`
Answer a customer question from the current knowledge base. Cite source IDs in the answer and state gaps or conflicts plainly. Do not mutate files unless the request also supplies new durable information.
`archive`
Save source documentation to the existing customer folder in the Conversint Shared drive. Reuse an existing Drive file ID when a source is already present; do not create duplicates. Preserve raw evidence such as `.eml`, images, and office files with `/gdrive --no-convert`. Maintained knowledge-base and ledger Markdown may be converted to native Google Docs for review.
Drive upload remains user-driven and permission is object-specific:
- Explicit language such as `archive`, `upload these sources`, or `save these sources in Drive` authorizes only the named raw source archives. - Uploading or refreshing the maintained knowledge base, source ledger, or firsthand-notes file requires separate language such as `sync the knowledge artifacts to Drive`, `publish the knowledge base`, or `create Google Docs`. A synchronized firsthand-notes file is a convenience artifact only, never the archived source for an individual firsthand entry. - `init`, `capture`, `refresh`, `set up`, and `reconcile` alone authorize local artifact changes only.
When the required upload intent is absent, capture locally and ask before that Drive write. When a maintained Google Doc already exists, update it in place by file ID.
`audit`
Run the validator, check Drive links and source status, and report stale, uncited, disputed, or archive-pending items. Do not change substantive facts in audit mode.
Evidence Rules
Assign source IDs monotonically as `SRC-001`, `SRC-002`, and so on. Never reuse an ID, including after a source is superseded.
Classify each source and claim using the schema reference:
- `Customer-confirmed`
- `Attributed transcript`
- `Patrick firsthand`
- `Public source`
- `Derived analysis`
- `Inference`
- `Unknown`
Treat customer-authored emails, customer-provided documents, and attributed transcripts as stronger evidence than a proposal or analysis that summarizes them. Treat machine transcripts as attributed but fallible; avoid relying on a single garbled phrase for names or exact numbers.
Firsthand Chat Capture
When Patrick explicitly asks to preserve firsthand customer information:
1. Identify the customer and the exact factual statement. 2. Append a dated note with the speaker, verbatim statement, conversation context, and any interpretation kept on a separate line. If the firsthand-notes file does not exist, create it before adding the source-ledger entry. A quotation copied only into the ledger does not satisfy this requirement. 3. Do not record credentials, access tokens, payment-card data, health data, or other unnecessary secrets. Redact them and record that redaction occurred. 4. When the invocation specifically authorizes archival of the firsthand source, save a new, raw Markdown snapshot containing exactly that `FH-...` entry, using `--no-convert`. Give every firsthand entry its own Drive file; do not update or reuse a prior snapshot. Permission to archive another raw source does not authorize this upload. 5. Add a ledger entry with source type `Patrick firsthand` and a Drive pointer only when that immutable entry snapshot was authorized and archived. Otherwise set its `Archive status` to `Archive pending` and use the local firsthand-note entry as the canonical pointer. The maintained firsthand-notes file may be synchronized separately, but it cannot fill this source-archive role. Assign exactly one `SRC-###` record to each `FH-YYYYMMDD-NN` entry and record it in the ledger's `Firsthand entry` field. No two firsthand entries may share a Drive snapshot or source ID. One firsthand entry may group tightly related statements supplied together in the same conversation context. 6. Add or update the knowledge-base fact with that source ID and evidence label.
Do not complete a firsthand capture unless the verbatim statement exists in the firsthand-notes file and the ledger's `Local path` points to that file.
A firsthand assertion is evidence that Patrick said it, not independent proof that the customer confirmed it. If it conflicts with customer-authored evidence, preserve both sources and mark the fact `Disputed` until Patrick resolves it.
Workflow
1. Resolve The Customer
Use the CRM display name and existing `customers/<Customer>/` folder. If two folders could match, stop and ask which customer record is canonical.
2. Read Current State
Read the existing knowledge base, source ledger, firsthand note, and any source files or Drive links named by the user. Check `git status` before editing and preserve unrelated or user-authored changes.
Before changing an existing ledger or firsthand note, copy each current file to a temporary baseline path. Use those baselines during validation so a removed or rewritten historical entry cannot pass unnoticed.
3. Inventory Sources
Prefer primary sources in this order:
- Customer-authored email or document
- Attributed meeting transcript or note
- Patrick's documented firsthand statement
- Official customer or vendor page
- Conversint analysis that clearly cites its primary evidence
For Gmail, use a narrow sender/date/subject search through `/gmail`. If a useful email is not archived, prepare a customer-folder email export containing its headers, message ID, and relevant body, then archive it through `/gdrive` when authorized. Do not paste private email into web tools.
For Drive, list the existing customer folder before uploading. Record each file's name, file ID, URL, MIME type, source date, immutable origin fingerprint, and Drive archive fingerprint where available. Use the Drive version plus modified time for a native Google file and the provider revision or checksum for an uploaded blob. Keep source-origin identity separate through a provider ID or content hash.
Before assigning a new source ID, look for the source's stable external identity: Gmail message ID, Drive file ID plus revision/modified time, transcript path plus content hash, or another immutable provider identifier. When a caller supplies a reconciliation operation key, also check the reconciliation journal and commit history as described by the caller. Reuse the existing source record when the same provider identity is already represented; do not append a second `SRC-###` entry.
During `refresh` and `audit`, re-read Drive metadata for every active archived source and compare it with the recorded `Drive fingerprint`. Treat a changed version, modified time, or checksum as source drift requiring review; never silently bless the changed content under the old source ID.
4. Reconcile Before Writing
For every proposed fact, determine whether it is new, corroborating, contradictory, or a correction. Do not select a winner silently when sources disagree. Prefer a concise `Open Questions and Conflicts` entry over false resolution.
5. Update The Ledger First
Append a complete source entry using the schema reference. Include what the source supports and any reliability limits. Mark old entries rather than deleting them.
6. Update The Knowledge Base
Maintain these sections:
- `Tech Stack and Environment`
- `Organizational Structure`
- `Known Processes`
- `Stakeholders and Known Goals`
- `Open Questions and Conflicts`
Use concise tables. Put one factual proposition per row and include its evidence label plus linked source IDs. Do not copy long quotations into the knowledge base; keep verbatim material in the source document or ledger.
7. Archive And Link
When source archival is authorized, archive missing source documents first and add their Drive URLs to the ledger and knowledge base. For `Patrick firsthand`, archive one immutable raw snapshot per `FH-...` entry rather than linking the maintained notes file. Upload the maintained knowledge base, source ledger, or firsthand notes only when maintained-artifact synchronization is separately authorized. If archival fails, retain `Archive status: Archive pending` in the ledger and do not claim the record is fully synchronized.
8. Validate And Commit
Run:
```bash scripts/python .claude/skills/customer-knowledge/scripts/validate.py \ --customer "<Customer>" --require-archived ```
When refreshing existing records, also pass `--baseline-ledger` and `--baseline-firsthand-notes` using the temporary snapshots created before the edit. Omit `--require-archived` when Drive upload was not authorized; explain any archive-pending warnings.
Resolve every error. Warnings must be explained in the final response.
Commit the source ledger before or together with the refreshed knowledge base using `./references/dependencies/conversint-current/scripts/commit-md-to-main.sh`. Include the firsthand note when it changed. Do not include unrelated dirty files in the commit. When `/operator reconcile` supplies an operation key and expected path list, follow its stricter atomic commit and recovery instructions instead of creating one commit per artifact.
Ownership And Handoffs
- Customer facts and provenance: `/customer-knowledge`
- Opportunity stage, contacts, sales activity, and forecast fields: `/crm`
- Customer delivery tasks, owners, blockers, and completion: `/project-manager`
- Meeting discovery and `Meeting Notes/` archival: `/drive-watch`
- Reusable quotable customer language: `/voice-of-customer`
- Gmail reads and exports: `/gmail`
- Drive reads and writes: `/gdrive`
Offer the appropriate handoff when a source creates a task, CRM change, or reusable quote. Never silently write another skill's system of record.
Completion Report
Report:
- Customer and mode
- Knowledge-base and ledger paths
- Source IDs added or changed
- Source documents archived, reused, or still pending
- Conflicts and open questions surfaced
- Validation result
- GitHub and Drive links for maintained artifacts when available