contextualize

name	contextualize
description	Use when the user wants to generate a companion-specific reference file from existing org library notes. Processes library notes chapter-by-chapter, filtering and reframing concepts for the current companion's needs. Requires a book with complete or in-progress library notes.
disable-model-invocation	true
argument-hint	[book-search-term] [client/companion]

/contextualize — Generate Companion-Specific Reference from Library Notes

Take existing companion-neutral library notes and generate a reference file tailored to a specific companion — without re-reading the book.

Usage:

• /contextualize [book-search-term] — Search org library, use current companion
• /contextualize [book-search-term] [client/companion] — Override companion

Examples:

/contextualize king                                   # Finds king-on-writing in library
/contextualize story-structure                        # Matches by subject tag
/contextualize king consortium.team/writing-companion # Override companion

---

Step 0: Determine Companion and Organization

1. Parse $ARGUMENTS:
   • Last argument may be a companion path (contains /) — if so, use it as the companion
   • Remaining arguments are the book search term
2. If no companion path in arguments, read tracking/current-companion.md for the current companion
3. If no companion is set:

   No companion set. Use /companion to set or create one first.
   

4. Derive the organization from the client portion of the companion path (e.g., consortium.team from consortium.team/writing-companion)
5. Set library_dir = companion-kits/private-kits/[org]-companion-kit/library/
6. Set companion_dir = companions/[client]/[companion]/

Declare collected values:

Step 0 Complete. Collected values:
- Companion: [client/companion]
- Companion dir: [absolute path]
- Organization: [org]
- Library dir: [absolute path]
- Search term: [book-search-term]

---

Step 1: Find the Library Book

1. Scan all metadata.yaml files in [library_dir]/**/metadata.yaml
2. For each metadata file, match the search term against:
   • Directory name (e.g., king-on-writing)
   • title field
   • author field
   • subjects array entries
3. Matching is case-insensitive and partial (e.g., "king" matches "Stephen King")

Handle results:

• No matches:

  No books matching "[search-term]" found in the [org] library.
  
  Available books:
  - [title] by [author] ([directory-name]) — [status]
  - ...
  
  Try a different search term.
  

• Multiple matches:

  Multiple books match "[search-term]":
  
  1. [title] by [author] — [status]
  2. [title] by [author] — [status]
  
  Which one?
  

  Wait for user to choose.

• Single match: Proceed to Step 2.

Declare collected values:

Step 1 Complete. Found book:
- Title: [title]
- Author: [author]
- Directory: [path]
- Status: [status]
- Subjects: [subjects]

---

Step 2: Validate Book Status

Read the metadata.yaml for the matched book and check the status field:

• complete — Proceed to Step 3
• in-progress — Warn the user, then proceed:

  Note: This book's library notes are still in progress. Contextualizing what's available so far.
  

• needs-decontextualization — Block:

  This book's notes.md needs to be populated first. The library entry exists but
  the notes haven't been written yet.
  
  Use /read-book --library [org] to read and annotate this book first.
  

• not-yet-read — Block:

  This book hasn't been read yet.
  
  Use /read-book --library [org] [kindle-url] to read it first.
  

Also verify notes.md exists in the book's library directory and has substantive content (more than just a header/placeholder). If notes.md is missing or empty:

The library entry for this book exists but notes.md is missing or empty.
Use /read-book --library [org] to populate it first.

---

Compliance Checkpoint 1

Before proceeding to contextualization, confirm book and companion are correct:

Ready to contextualize.

Book: [title] by [author]
Status: [status]
Companion: [client/companion]
Purpose: [companion purpose from context]

This will create a companion-specific reference file filtered for [companion]'s needs.
Proceed?

STOP and wait for user confirmation.

---

Step 3: Load Companion Context

Read the following files from the companion directory:

1. [companion_dir]/context/requirements.md
2. [companion_dir]/context/decisions.md
3. [companion_dir]/context/constraints.md
4. [companion_dir]/CLAUDE.md

Extract and summarize:

• Companion purpose — What is this companion for?
• Persona — What persona does it use? What's its voice?
• User profile — Who uses this companion?
• Key themes — What topics/frameworks matter most?

Report what was loaded:

Step 3 Complete. Companion context loaded:
- Purpose: [brief summary]
- Persona: [persona name and key traits]
- User: [who the companion serves]
- Key themes: [list of themes/frameworks]
- Files read: [list of files successfully read]
- Files missing: [any context files not found]

---

Step 4: Check for Existing Reference File

1. Search [companion_dir]/reference/ for any file that appears to be a contextualization of this book
   • Match by author name, book title, or presence of the book's metadata in the file header
2. If found with progress marker (contains "Contextualization paused"):
   • Read the file to find where it left off
   • Report: "Found existing contextualization, paused at [chapter]. Resuming from there."
   • Skip to Step 6, starting from the next unprocessed chapter
3. If found with completion marker (contains "Contextualization complete"):

   A contextualized reference for this book already exists:
   [file path]
   
   Options:
   1. View the existing file
   2. Re-contextualize (overwrite)
   3. Cancel
   
   What would you like to do?
   

   Wait for user response.
4. If not found — Proceed to Step 5

---

Step 5: Create the Reference File

1. Suggest filename: [author-lastname]-[short-title]-companion-notes.md
   • Confirm with user or let them override
2. Create the file in [companion_dir]/reference/ with this header:

# [Book Title] — Companion Reference

**Source:** [Author], *[Book Title]* (from [org] library)
**Library location:** [relative path to library book directory]
**Companion:** [companion name/purpose from Step 3]
**Purpose:** Concepts from this book filtered and reframed for this companion's specific needs
**Method:** Chapter-by-chapter contextualization from library notes.md

---

3. Create the [companion_dir]/reference/ directory if it doesn't exist

---

Step 6: Contextualize Chapter by Chapter

This is the core loop. Process one chapter at a time.

Read the library notes.md and identify all chapters.

For each chapter:

1. Read the chapter's notes from the library notes.md
2. Filter: For each concept/framework in the chapter, evaluate:
   • Is this relevant to this companion's purpose?
   • Is this relevant to this companion's users?
   • Does this connect to any of the companion's key themes?
3. Rewrite relevant concepts with companion-specific applicability:
   • How does this concept apply to what this companion does?
   • When would this companion invoke this concept?
   • What specific guidance does this give?
4. Write the chapter section to the reference file in this format:

## Chapter [N] | [Chapter Title]

### Key Insights for [Companion Name]

1. **[Concept/Framework name]** — [Rewritten description focused on this companion's needs]

   **Application:** [Specific guidance for how/when this companion should use this concept]

2. **[Concept/Framework name]** — [Description]

   **Application:** [Guidance]

### Not Applicable from This Chapter

- **[Concept name]** — [Brief note on why it was filtered out for this companion]
- **[Concept name]** — [Why not applicable]

---

5. Update progress marker at the bottom of the reference file:

   *Contextualization paused after Chapter [N]: [Chapter Title]. [M] of [total] chapters complete.*
   

6. Report to user:

   Chapter [N]: [Title] — contextualized.
   - [X] concepts applied, [Y] filtered out
   
   Say **next** when ready for the next chapter.
   

7. STOP and wait for the user to say "next" — Do not continue without user confirmation

Compliance Checkpoint 2

After each chapter, this is a mandatory pause point. Do not proceed to the next chapter until the user explicitly says "next" or equivalent. This gives the user review and pacing control.

---

Step 7: Companion Synthesis

After all chapters are processed, write a master synthesis section at the end of the reference file:

## Companion Synthesis

### Priority Frameworks

*Ranked by relevance to this companion's core purpose.*

1. **[Framework name]** (from Chapter [N])
   - **When to invoke:** [Specific trigger/situation]
   - **How to apply:** [Concrete guidance]

2. **[Framework name]** (from Chapter [N])
   - **When to invoke:** [Trigger]
   - **How to apply:** [Guidance]

3. **[Framework name]** (from Chapter [N])
   - **When to invoke:** [Trigger]
   - **How to apply:** [Guidance]

[3-5 frameworks total]

### What This Book Doesn't Cover

- [Gap 1 relative to this companion's needs]
- [Gap 2]

### Integration Notes

- [How these frameworks connect to other reference material in the companion]
- [Potential tensions or complementary relationships with existing guidance]

Replace the progress marker with a completion marker:

*Contextualization complete. [N] chapters processed, [X] concepts applied, [Y] filtered.*

---

Compliance Checkpoint 3

After writing the synthesis, present it to the user for review:

Contextualization complete.

**Top frameworks extracted:**
1. [Framework 1]
2. [Framework 2]
3. [Framework 3]

**Gaps identified:**
- [Gap 1]
- [Gap 2]

Does the synthesis look accurate? Any frameworks to add or re-prioritize?

STOP and wait for user confirmation before recording.

---

Step 8: Record the Contextualization

1. Add a row to [companion_dir]/context/decisions.md:

   | Contextualized [Book Title] for companion | [Top 3 frameworks extracted]; [N] concepts filtered as not applicable | [date] |
   

   Create the decisions table if it doesn't exist.

2. Report to user:

   ## Contextualization Complete
   
   **File:** [relative path to reference file]
   **Chapters processed:** [N]
   **Concepts applied:** [X]
   **Concepts filtered:** [Y]
   
   **Top frameworks:**
   1. [Framework 1]
   2. [Framework 2]
   3. [Framework 3]
   
   The reference file is ready for use by the companion.
   

---

Design Rationale

• notes.md, not synthesis.md — Full signal, not lossy summary. synthesis.md is for /intake discovery; notes.md has the detail needed for companion-specific filtering.
• Chapter-by-chapter with writes — Same resilience pattern as /read-book. If context compaction hits, at most one chapter's work is lost.
• User says "next" — Pacing control and natural breakpoints. User can review each chapter's contextualization.
• Filter, don't copy — The value is in deciding what matters for THIS companion, not in reproducing the library notes.
• Record skipped content — "Not Applicable" sections enable reviewability and future re-contextualization with different criteria.
• Status gating — Only complete or in-progress books are eligible, preventing contextualization of empty stubs.
• Progress markers — Enable resume after interruption, matching the /read-book resilience pattern.