Context kit ingest

Prior Session Ingestion

Take work that happened before this kit was in place -- an old chat export, prior engagement notes, exported scripts/policies, or another engineer's session -- and fold it into the kit cleanly: pull the material, distill it to signal, store reusable assets under docs/sessions/, record completed changes in docs/history.md, update the affected entity's file (see Step 0), capture lessons in the matching runbook companion file, and verify the result.

The hard rule that shapes everything below: never store a verbatim transcript. A full chat log is noise, context-bloat, and a likely secret leak. You are extracting signal -- what changed, what was found, what assets were produced, what was learned -- not archiving a conversation.

Conventions (governed by context-kit-steward)

--- GOVERNED CONVENTIONS (source: context-kit-steward charter v1.0) --- Do not edit here. Change the charter in context-kit-steward and re-run it to re-sync; local edits to this block will be overwritten on the next sync.

This skill honors these shared Context Kit conventions (full text + rationale in the context-kit-steward charter):

• Encodes C1 (dating): date entries to when the work was DONE (the session/ conversation start), YYYY-MM-DD, never future.
• Encodes C2 (ordering): interleave history.md chronologically and the status.md table newest-first -- by the work date, not at the top.
• Encodes C3 (concurrency): re-read shared index files before editing; minimal targeted inserts; Version = on-disk + 1; one writer-of-record.
• Encodes C4 (session folders): assets under docs/sessions/<work-date>-<slug>/notes.md.
• Encodes C5 (entity vocabulary): discover the kit's entity term and directory (Step 0); never assume "tenant"; skip the entity layer if the kit has none.
• Encodes C7 (hygiene): never store verbatim transcripts or secrets; no absolute mount/session paths; real IDs only in the entity file.
• Follows C6/C8/C10: reference global kit skills rather than embedding; treat leading-underscore dirs as read-only; never rm -- move to Trash.

Terminology: this skill adapts to the kit it runs in

Kits organize durable work around a recurring subject -- the "in-circle entity." Different kits name it differently: a customer, a client, an account, a stakeholder, a vendor, a project, a property, or (in an MSP/M365 kit) a tenant. This skill does not assume "tenant." Step 0 discovers what this kit calls its entity and which directory holds the per-entity files; everywhere below, "the entity file" means that discovered file (for example docs/customers/acme.md, docs/clients/acme.md, or docs/tenants/acme.md). The MSP examples that appear throughout (a ticketing-system ticket, M365/Intune/Defender objects, a tenants/ directory) are one instantiation, not a requirement -- substitute the kit's own terms.

When to use

• The engineer has notes or a transcript from work done before this kit existed.
• A prior engagement produced scripts, policy exports, or baselines worth preserving as session assets.
• A shared or on-call session produced durable findings that belong in history.md or an entity's per-subject file.
• Onboarding a new customer / client / stakeholder whose prior work was done outside this kit.

Before you start

• Have the source in hand: a file path, a chat share link, a pasted transcript, or exported files.
• Complete Step 0 so you know the kit's entity vocabulary before writing.
• Confirm write access to docs/sessions/, docs/history.md, docs/status.md, and the relevant entity file.
• Know the ticket or reference for the original work (a Jira/ticket ID, a PR, or a description of the prior engagement).
• Run the context-kit-check skill first so you know the kit's starting state before writing anything. You will run it again at the end.

The copy-paste templates referenced throughout (session notes.md, the history.md entry, the lessons entry, and the read-only sub-agent brief) live in references/templates.md. Read that file when you reach the step that uses each one.

---

Procedure

Step 0 -- Identify the kit's entity layer

Before ingesting anything, determine what this kit calls its in-circle entity and where per-entity files live. Do not assume "tenant."

1. Find the per-entity directory. Look under docs/ for a directory of per-subject files. Common names: tenants/, customers/, clients/, accounts/, stakeholders/, vendors/, projects/, properties/. Whichever exists is the entity directory.
2. If several exist, pick the one whose files match the subject of the source material (e.g. ingest customer work into customers/, vendor work into vendors/).
3. Learn the kit's term. Read CLAUDE.md and an existing entity file for the word the kit uses for the subject (customer, client, account, stakeholder, tenant, etc.) and the per-entity file shape. Mirror that exact term and shape in everything you write -- do not introduce "tenant" if the kit says "customer."
4. If the kit has no per-entity directory, there is no entity layer here. Skip Step 5 and record the work in history.md only. Propose creating an entity directory only if the user asks for one; do not invent the convention unilaterally.

Record the resolved entity term and directory for use in Steps 2, 4, 5, and 7.

Step 1 -- Pull the source material

Retrieve the source with the method that matches its form:

• Chat / assistant export or share link. Use the available session or browser tools to read the transcript in memory. Do not paste the whole transcript into a file -- that creates the verbatim transcript the skill prohibits. Read it and go straight to Step 2.
• Prior notes / ticket export / handover doc. Read the file(s) directly. Pull the actionable signal -- what changed, what was found, what was learned -- and ignore conversational filler.
• Exported assets (scripts, policy JSON, config backups, config files). List and categorize them; they go to docs/sessions/ in Step 3. Do not move them yet.

Step 2 -- Distill: extract signal before writing anything

Answer these four questions from the source. Nothing lands on disk until you have:

• 2a. What was done? List each discrete change (one change = one candidate history.md entry). For each: entity affected (the kit's subject from Step 0), date (best estimate if not recorded), what changed (specific object/policy/setting/system), why, outcome (verified / partial / failed), and any restore point or backup taken.
• 2b. What was found but not changed? Audit findings, misconfigurations, risks. These become "Open Items" in the entity file or a file under docs/reviews/.
• 2c. What reusable assets were produced? Scripts, policy JSON, config/baseline exports, infrastructure backups, modules. These go to docs/sessions/.
• 2d. What lessons were learned? Surprises, gotchas, gaps the runbook did not warn about, procedures that needed adapting. These go to the matching runbook's -lessons.md companion.

Do not write verbatim transcript content anywhere. Distill to the signal.

Step 3 -- Store generated assets in docs/sessions/

For each reusable asset from 2c:

1. Create the session directory if needed: docs/sessions/<YYYY-MM-DD>-<slug>/. The date is when the work was done, not today; the slug is a 2-4 word kebab-case description (e.g. docs/sessions/2026-05-12-acme-ca-baseline/).
2. Copy the asset files in. Never store secrets -- placeholders only; real values stay in a secret store or a 0600 file outside the repo.
3. Create or update a notes.md manifest using the template in references/templates.md.

If the session produced no reusable assets (a read-only audit, a health check), skip the directory -- a history.md entry alone is enough.

Step 4 -- Interleave a history.md entry

For each completed change from 2a, add an entry to docs/history.md. Re-read the live docs/history.md first and match the entry shape it actually uses on disk -- read the "Entry shape" block at the top of the file and copy the most recent real entry's structure. Do not blindly paste a template from elsewhere: a change-management runbook and this skill's references/templates.md show the general shape, but the live file's fields can be richer or have drifted (for example a ### heading with Type, Entity / host, What shipped, Rollback points, and New risks / follow-ups). The live file is the source of truth for format; the template is a fallback only when the file has no existing entry to mirror.

Whatever shape you mirror, add the "Ingested from" line so the entry is marked as backfilled rather than written live. Where the source did not record a restore point or verification, write "none recorded" / "not recorded" rather than inventing one.

Interleave chronologically by the date the work was done -- do not just prepend. history.md is newest-first, so an entry for work done weeks ago belongs in its correct date position (often well below the top), not at the head of the file. Find the entries that bracket the work date and insert between them.

Then add a one-line summary row to the recent-changes table in docs/status.md, placed in the same chronological position (that table is newest-first too, so an older ingested session slots below the more recent rows, not at the top).

Step 5 -- Update the entity file

(Skip this step if Step 0 found no per-entity directory; the history.md entry stands on its own.)

For each entity touched in 2a or 2b, open the kit's entity file for that subject (e.g. docs/customers/<name>.md, docs/clients/<name>.md, or docs/tenants/<name>.md -- whatever Step 0 resolved) and refresh the now-stale sections: stack/baseline state, configuration/hardening state, Open Items (add findings from 2b; close anything resolved), and the last-updated date.

Re-read the file from disk first and use targeted edits -- do not rewrite it from memory, or you will clobber edits made by the current session.

Step 6 -- Capture lessons

For each lesson from 2d, open the matching docs/runbooks/<name>-lessons.md and prepend a new entry (newest-first) using the lessons template in references/templates.md. If a lesson does not clearly belong to one runbook, add it to the closest one and note the cross-cutting relevance.

Mark any lesson you could not personally validate as "Ingested -- unverified" (see Safety and gotchas).

Step 7 -- Verify with a read-only sub-agent

Spawn a read-only sub-agent and brief it with the verification template in references/templates.md. It confirms the session notes.md, the history.md entry, the entity file state, and the prepended lessons all exist and cohere.

A sub-agent's output is a proposal, not truth. If it reports a pass on a check you know should have failed, investigate before continuing.

Step 8 -- Run the context integrity check

Run the context-kit-check skill again to confirm the kit is coherent. Resolve any new FAILs the ingestion introduced before closing the task.

---

Rollback

Ingestion is additive and reversible. To undo one that introduced errors:

1. Remove the session directory. On a Mac, move it to the Trash per the file-deletion rule -- never rm. On a remote host with no Trash, remove it only after confirming a backup exists.
2. Remove the appended history.md entry and its status.md row.
3. Revert the entity file edits (re-read, then remove the ingested changes).
4. Remove the prepended lessons entries.
5. Re-run context-kit-check to confirm the kit is back to its pre-ingestion state.

---

Safety and gotchas

• Never store verbatim transcripts. Distill to signal -- what changed, what was learned, what assets were produced. A full transcript is context-bloat and a likely secret leak.
• Use the kit's own entity vocabulary (Step 0). Writing "tenant" into a kit that organizes work by "customer" or "stakeholder" creates orphaned, confusing docs and has tripped up later agents. Mirror the term the kit actually uses.
• Date the session to when the work was done, not today. The sessions/ directory name is the date the work occurred, so provenance stays accurate when ingesting work from weeks or months ago.
• Secrets may be in prior session material. A password, app secret, or API key in a code block must never be copied into docs/. Treat it as a rotation trigger: if the secret touched an uncontrolled channel (a shared transcript), it is burned -- rotate before ingesting the rest.
• "Not recorded" restore points are a gap, not a detail to hide. If a prior destructive change took no restore point, record "none recorded" in history.md and add an open item to validate current state against a known baseline.
• Do not backfill lessons you have not personally validated. Mark unconfirmed procedures "Ingested -- unverified". An unvalidated lesson that looks authoritative will mislead the next engineer.
• Real domain identifiers from prior sessions are real. Unlike the kit's placeholder convention for IDs (e.g. an ID token), prior material may carry real values -- an M365 tenant GUID, an account number, a customer ID. They may go into the entity file (the right place) but must never appear in runbooks, CLAUDE.md, or shared templates.