institutional-knowledge

# /institutional-knowledge — Executive Knowledge Preservation **Intent.** Build a comprehensive, structured knowledge archive of a senior leader's tenure by mining their Microsoft 365 signals (emails, Teams chats, meetings, OneDrive/SharePoint contributions), distilling decisions/rationale/relationships, and producing a multi-phase document a successor or AI assistant can ground on. Designed for **long-tenure senior leaders** (3+ years) whose departure would otherwise lose significant decision history and tribal knowledge. This skill is **resumable**. Each invocation reads `manifest.md` and continues where the last session stopped. Plan for a 1-week sprint across multiple sessions. --- ## 0. Core operating principles 1. **The leader curates; you produce.** The user (the departing leader, or a delegate working with them) answers clarifying questions and validates. You write everything. 2. **Decision archaeology is the highest-value output.** Bias toward capturing *why* decisions were made over *what* projects exist. Successors can read project trackers; they can't recover lost rationale. 3. **Multi-phase, gated progression.** Phase 1 (discovery) → Phase 2 (deep extraction) → Phase 3 (cross-cutting themes) → Phase 4 (gap questionnaire) → Phase 5 (final assembly). Confirm with the user before advancing phases. 4. **Idempotent ingest.** Every signal is keyed by `(source_id, item_id)` or `(source_id, date)`. Re-running merges, never duplicates. 5. **Capture before polish.** Get raw signals down across all phases before refining. If time runs short, raw breadth beats polished narrowness. 6. **Privacy.** The archive is built from private signals and lives on the user's machine inside their M365 trust boundary. HR / compensation / performance / health content is automatically out of scope. The leader alone decides what to share with the org or successor. --- ## 1. First-run bootstrap Default archive path: `$env:USERPROFILE\Documents\institutional-knowledge` on Windows/PowerShell hosts, `~/Documents/institutional-knowledge` elsewhere. Some Cowork/Scout sandboxes expose a different writable root and may not set `$env:USERPROFILE` — if the default path can't be resolved or written, discover a writable `Documents/`-equivalent folder from the host and confirm it with the user before scaffolding. Detection: an `AGENTS.md` containing the marker `institutional-knowledge-schema-v1` in its first 200 chars (written during scaffold — see §1.4). **If no archive exists, run bootstrap.** ### 1.1 Confirm parameters (one at a time — never silently default) - **a) Archive location.** Default as above; allow override. - **b) Leader's name, title, tenure dates.** "Doug Smith — VP of Platform Engineering — Jan 2020 to present, last day June 30 2026." - **c) Tenure horizon.** Default: full tenure. Confirm start year. Senior leaders' early-tenure decisions often anchor current state — do not truncate without reason. - **d) Audience for the archive.** Successor (named, if known) / leadership team / future AI assistant grounding / all of the above. Affects tone of final document. - **e) Explicit out-of-scope.** Any project, vendor, or topic the leader does not want captured. Always-excluded: HR matters, compensation, performance reviews, health. - **f) Sessions available.** How many work sessions before the last day. Calibrates Section 1.5 plan. - **g) Delegate?** Is the user the leader themselves, or a delegate (chief of staff, EA, successor) operating on their behalf? Affects how clarifying questions are framed. ### 1.2 Gather identity & relationships In parallel (retry transient failures once before marking blocked): - `m365_get_my_profile` *(required — abort if it fails twice)* - `m365_get_my_manager` - `m365_get_my_direct_reports` - `m365_get_relevant_people` *(limit 25, used to seed the relationship map)* ### 1.3 Discover sources → write `manifest.md` Best-effort; record any failures in `log.md` under "Discovery limitations" and continue. - **Mail folders** — `m365_list_mail_folders(limit: 20)`. **Always pass `limit` explicitly.** Note custom folders (`Leadership`, `Board`, `Strategy`, `Decisions`, project-named folders). Skip personal folders (`H1B*`, `Immig*`, `PTO*`, `Personal`, `H1Renewal`). - **Active Teams chats** — `m365_list_chats(limit: 50)`. Do not pass `orderBy`. Tag each `1:1` / `group` / `meeting`. - **Teams memberships** — `m365_list_teams` + `m365_list_channels`. Often fails on `teams_auth_required` — mark blocked and continue; `m365_list_chats` already covers most active conversation. - **Recurring meetings** — `m365_list_events` over the last 180-365 days; cluster by subject prefix to detect recurrence. - **Authored documents** — `m365_get_recent_files(limit: 50)` first; fall back to `m365_list_files(limit: 50)` if it fails. Do not rely on `m365_search_files(query: '*')` — unreliable. - **Targeted email scoping** — `m365_search_emails` works for specific names/keywords but fails on broad queries. Use only during per-project deep dives in Phase 2. Each source becomes a row in `manifest.md` with status `pending` / `in_progress` / `done` / `skipped` / `blocked`. ### 1.4 Scaffold the archive Create the layout (Section 2) and seed files: `AGENTS.md`, `index.md`, `log.md`, `manifest.md`, `phase-1-inventory.md`, `relationships.md`, `decisions.md`. Other files are created on first need. **`AGENTS.md` must begin with the detection marker so future sessions can recognize this archive (see §1).** Write the literal string `institutional-knowledge-schema-v1` within the first 200 characters of `AGENTS.md` — the recommended first line is an HTML comment so it renders invisibly: ```markdown <!-- institutional-knowledge-schema-v1 --> # Institutional Knowledge Archive — <Leader name> <!-- schema + conventions for this archive; do not delete the marker above --> ``` Do not scaffold `AGENTS.md` without this marker: resumability (§11 "continue") depends on it. ### 1.5 Propose phase plan Map phases to remaining sessions: | Session | Phase focus | |---|---| | 1 | Bootstrap + Phase 1 discovery (full project/initiative inventory) | | 2–3 | Phase 2 deep-dive on High-significance projects | | 4 | Phase 2 continues + Phase 3 cross-cutting themes | | 5 | Phase 4 gap questionnaire → leader answers offline | | 6 | Phase 5 final assembly + review | Adjust to actual available sessions. Compress by dropping Medium/Low-significance Phase 2 deep-dives first. --- ## 2. Directory layout ``` institutional-knowledge/ ├── AGENTS.md # schema, customized for this leader ├── index.md # catalog: every page, one-line summary, last-updated ├── log.md # append-only timeline ├── manifest.md # discovered sources + ingest status ├── phase-1-inventory.md # project & initiative catalog (Phase 1 output) ├── projects/ # one page per significant project (Phase 2) │ └── <slug>.md ├── decisions.md # cross-project decision log ├── relationships.md # people, stakeholders, engagement guidance ├── themes.md # cross-cutting principles, operating style (Phase 3) ├── domain-knowledge.md # technical/industry/regulatory knowledge ├── org-navigation.md # "how to get things done here" ├── historical-context.md # origin stories, past failures, unwritten rules ├── gap-questionnaire.md # Phase 4 questions for the leader ├── gap-answers.md # leader's responses (input by user) ├── final-archive.md # Phase 5 assembled document └── raw/ # immutable per-source extracts ├── email-<folder>/YYYY-MM.md ├── chat-<slug>/YYYY-MM.md ├── meeting-<series-slug>/YYYY-MM-DD.md └── sharepoint-<site-slug>/index.md ``` Naming: lowercase kebab-case. Dates: `YYYY-MM-DD` or `YYYY-MM`. --- ## 3. Phase 1 — Project & Initiative Discovery **Objective.** Build a comprehensive catalog of every significant project, initiative, recurring forum, or workstream the leader owned or materially shaped. ### 3.1 Search strategy Across all M365 sources, identify: - Projects where the leader was owner / lead / primary decision-maker - Recurring meeting series they organized or regularly attended as required - Email threads with significant decision content (length > 5 messages, leadership participants) - Documents they authored or were primary contributor to - Channels / chats they created or are most active in ### 3.2 Time slicing Break the tenure into eras and analyze each: - **Early tenure** (Year 1–2): foundational work, what they inherited, first initiatives - **Growth period** (Year 3–4): major initiatives, scope expansion, key hires - **Recent / current** (last 2 years): current state, in-flight work, near-term commitments ### 3.3 Categorization For each project, tag with one or more: - Product / Engineering - Strategic Planning / OKRs - Team / Org Leadership (hiring, reorgs, performance culture) - Cross-functional Initiatives - Technical / Architecture Decisions - Vendor / Partner Relationships - Business Development / Customer - Regulatory / Compliance ### 3.4 Output → `phase-1-inventory.md` ```markdown # Phase 1 — Project & Initiative Inventory ## <Project name> - **Period:** <start> – <end or "active"> - **Category:** <one or more from §3.3> - **Role:** owner / lead / key contributor / advisor - **Key collaborators:** [[relationships.md#name]], ... - **Data sources found:** N emails, M Teams threads, K meetings, J documents - **Significance:** High / Medium / Low - **Why this rating:** one sentence ``` After Phase 1 is complete, **present the full inventory to the user, ask them to validate significance ratings and flag anything missing, then confirm before starting Phase 2.** --- ## 4. Phase 2 — Deep Knowledge Extraction (per project) For each High-significance project (then Medium if time allows), produce `projects/<slug>.md`. ### 4.1 Decision archaeology Search for signal phrases in emails/chats/meeting notes: - "We decided to…" / "After discussing, we're going with…" - "The recommendation is…" / "Leadership approved…" - "We're not going to pursue X because…" - "The tradeoff is…" / "The risk is…" - "<Leader's first name> recommended…" / "Based on <leader>'s input…" - "Reversing course…" / "We tried X and it didn't work…" For each decision, capture: **what was decided, when, by whom, why, what alternatives were rejected and why, reversibility (easy / hard / one-way door), and source link.** ### 4.2 Problem-solution mapping - Obstacles encountered → approach taken → outcome → lesson - Failed approaches and why they failed (these are *especially* valuable — successors will be tempted to retry) - Workarounds still in place ### 4.3 Relationships & context - Stakeholders who had to be aligned - Cross-team dependencies - External factors (market, regulatory, vendor situations, org changes) that shaped the work ### 4.4 Lessons & insights - What worked well (replicate) - What the leader would do differently with hindsight - Tribal knowledge — "everyone knows but nothing is written down" - Advice for the person taking this over ### 4.5 Artifacts - Key documents (specs, designs, proposals, decks) — with SharePoint/OneDrive links - Reference email threads (subject, date range, participants) - Meeting recordings/transcripts where critical - Tools and systems where the work lives ### 4.6 Output template → `projects/<slug>.md` ```markdown --- slug: <slug> title: <project name> period: <start> – <end> category: <tags> role: <owner | lead | contributor | advisor> significance: high | medium | low status: active | wrapping-up | dormant | done | handed-off last_activity: YYYY-MM-DD source_count: N --- # <Project name> ## Executive summary 2–3 sentences: what this was, why it mattered, current state. ## Key decisions | Decision | Date | Rationale | Alternatives rejected | Participants | Reversibility | Source | |---|---|---|---|---|---|---| ## Problems and solutions ### Problem: <description> - **Context:** what was happening - **Approach:** what was done - **Outcome:** result - **Lesson:** takeaway - **Source:** raw/<source>/<date>.md ## Key relationships - **<Stakeholder>:** nature of relationship, how to work with them effectively ## Critical insights 1. … 2. … ## Successor guidance What the leader would tell the person taking this over. Direct quote where possible; paraphrase otherwise and mark `[paraphrased]`. ## Reference artifacts - <Doc title>: <webUrl> — what it contains - Email thread "<subject>": <date range> — <participants> ``` ### 4.7 Clarifying-question loop After each project deep-dive, **stop and ask the user 2–3 clarifying questions** to fill gaps the raw signals can't: - "Project X went quiet in March. Was it (a) dormant, (b) finished, (c) handed off, (d) still active but slow?" - "You and <name> exchanged 40 emails about <topic> but never reached a decision in writing. What did you ultimately decide and why?" - "I see <vendor> in 20 threads but can't tell if the relationship is healthy. How would you characterize it?" Write answers into the project page immediately, marking quotes vs. paraphrase. This is the highest-leverage step in the whole skill. ### 4.8 Budget guards - ~500 emails per session pass before checkpoint - ~5 chats per pass - One project deep-dive per session typically; two if signals are concentrated If a lane has more to ingest, mark `in_progress` in `manifest.md` with a next-offset note and stop. Tell the user "this project has N more sources; continue or switch?" --- ## 5. Phase 3 — Cross-Cutting Themes After enough High-significance Phase 2 deep-dives, run synthesis across them. ### 5.1 Leadership principles & operating style → `themes.md` - How does the leader approach decision-making? (consensus, decisive, data-driven, intuition, etc.) - What frameworks/mental models recur in their writing? (e.g., "reversible vs. one-way doors", "disagree and commit", named frameworks they cite) - How do they prioritize competing demands? - How do they handle disagreement? - Communication style across audiences (board, peers, reports, customers) ### 5.2 Organizational navigation → `org-navigation.md` - Go-to people for specific needs ("for budget questions → X; for legal → Y") - Political dynamics navigated - How alignment gets built across teams here - Watch-outs ("don't go to X before Y has heard it first") ### 5.3 Domain expertise → `domain-knowledge.md` - Technical/industry knowledge uniquely held by the leader - Critical vendor/partner relationships and their history - Regulatory/compliance knowledge - Customer/market context ### 5.4 Historical context → `historical-context.md` - Origin stories of current processes, systems, team structures - Past failures whose lessons inform current approaches - "Unwritten rules" of the organization - Founders'/predecessors' decisions still in force --- ## 6. Phase 4 — Gap Analysis & Questionnaire Review all extracted content for: - Topics mentioned but not fully explained - Decisions captured without clear *why* - Projects without documented outcomes - Implicit knowledge — things hinted at but never stated - Forward-looking items (upcoming decisions, planned changes, roadmap) ### 6.1 Output → `gap-questionnaire.md` Structure for the leader to answer offline: ```markdown # Gap Questionnaire for <Leader> > Please answer in as much detail as you can. These are gaps only you can fill. This is your last chance to capture context that will otherwise be lost. ## Project-specific ### <Project name> 1. <question> 2. <question> ## Strategic & leadership 1. What are the top 3 things your successor absolutely must know? 2. What mistakes did you make that others should avoid? 3. What relationships are most critical to maintain, and why? 4. What is the biggest risk or opportunity the team should be aware of? 5. What would you do differently if starting over? 6. What unfinished business matters most? 7. What decisions are pending that someone will need to make soon? 8. What context would be lost if you walked out today without documenting it? ## Domain & technical 1. <gap> 2. <gap> ## Organizational & cultural 1. <gap> 2. <gap> ``` Present the questionnaire and **pause**. The leader fills in `gap-answers.md` (the user pastes their responses or types them in a session). Do not advance to Phase 5 until answers are in. ---