diff --git a/plugins/learning/.claude-plugin/plugin.json b/plugins/learning/.claude-plugin/plugin.json new file mode 100644 index 0000000..216140b --- /dev/null +++ b/plugins/learning/.claude-plugin/plugin.json @@ -0,0 +1,5 @@ +{ + "name": "arevlo:learning", + "description": "Personal learning tools — vocabulary lookup and grammar/punctuation rules, in English and Spanish.", + "version": "2.0.0" +} diff --git a/plugins/learning/README.md b/plugins/learning/README.md new file mode 100644 index 0000000..d2fcc84 --- /dev/null +++ b/plugins/learning/README.md @@ -0,0 +1,63 @@ +# Learning Plugin + +Personal learning tools for vocabulary lookup and grammar/punctuation rules. Supports English and Spanish. + +## Commands + +### `/arevlo:learning:vocab` + +Look up a word — definition, pronunciation, and a simple example. + +**Usage:** +``` +/arevlo:learning:vocab +/arevlo:learning:vocab es +``` + +- Default language is English +- Prefix with `es` for Spanish lookups +- Uses web search to find definitions from authoritative dictionaries + +### `/arevlo:learning:grammar` + +Look up a grammar or punctuation rule — usage, examples, and common mistakes. + +**Usage:** +``` +/arevlo:learning:grammar +/arevlo:learning:grammar es +``` + +- Default language is English +- Prefix with `es` for Spanish lookups +- Covers grammar rules, punctuation marks, commonly confused words + +## Installation + +This plugin is part of the `claude-code-workflows` marketplace. + +1. Add the marketplace to `~/.claude.json`: +```json +{ + "extraKnownMarketplaces": { + "claude-code-workflows": { + "source": { + "source": "github", + "owner": "arevlo", + "repo": "claude-code-workflows" + } + } + } +} +``` + +2. Enable the plugin in `~/.claude/settings.json`: +```json +{ + "enabledPlugins": { + "arevlo:learning@claude-code-workflows": true + } +} +``` + +3. Restart Claude Code or run `/plugins refresh` diff --git a/plugins/learning/commands/grammar.md b/plugins/learning/commands/grammar.md new file mode 100644 index 0000000..06e91a6 --- /dev/null +++ b/plugins/learning/commands/grammar.md @@ -0,0 +1,84 @@ +--- +description: Look up a grammar or punctuation rule — usage, examples, and common mistakes (English/Spanish) +argument-hint: "[es] " +allowed-tools: WebSearch,WebFetch +model: haiku +--- + +# Grammar & Punctuation Lookup + +Look up a grammar or punctuation rule and display practical guidance with real-world examples. Supports English (default) and Spanish. + +## Process + +1. Extract the arguments. If no arguments were provided, ask the user what grammar rule or punctuation mark they want to look up. Suggest a few examples: + - English: semicolons, em dashes, oxford comma, who vs whom, affect vs effect + - Spanish: punto y coma, tilde, signos de interrogacion, por que vs porque, ser vs estar + +2. **Detect language:** Check if the first token is `es` (case-insensitive). If so, the language is **Spanish** and the topic is everything after `es`. Otherwise, the language is **English** and the entire argument is the topic. + +3. **Search for the rule:** + + **English:** Use WebSearch to search for: ` grammar rule usage examples site:grammarly.com OR site:owl.purdue.edu OR site:chicagomanualofstyle.org` + Then use WebFetch on the most relevant result to get the full explanation. + + **Spanish:** Use WebSearch to search for: ` regla gramatical uso ejemplos site:dle.rae.es OR site:fundeu.es OR site:wikilengua.org` + Then use WebFetch on the most relevant result to get the full explanation. + +4. **Format the output:** + + **English format:** + + ``` + ## + + **What it is:** + + **When to use it:** + - + - + - + + **Examples:** + - — + - — + + **Common mistakes:** + - -> + - -> + + **Quick tip:** + ``` + + **Spanish format:** + + ``` + ## + + **Que es:** + + **Cuando se usa:** + - + - + - + + **Ejemplos:** + - — + - — + + **Errores comunes:** + - -> + - -> + + **Consejo rapido:** + ``` + +## Rules + +- Be practical over exhaustive — focus on the 2-3 most useful things to know +- Use real-world examples, not textbook-sounding ones +- Always highlight common mistakes — that's where the most value is +- Keep the quick tip memorable and actionable +- **English lookups:** all output in English +- **Spanish lookups:** all output entirely in Spanish (labels, explanations, examples — everything) +- Do NOT save anything to a file — just display the result in the terminal diff --git a/plugins/learning/commands/vocab.md b/plugins/learning/commands/vocab.md new file mode 100644 index 0000000..f2d5c98 --- /dev/null +++ b/plugins/learning/commands/vocab.md @@ -0,0 +1,64 @@ +--- +description: Look up a word — definition, pronunciation, and simple example (English/Spanish) +argument-hint: "[es] " +allowed-tools: WebSearch,WebFetch +model: haiku +--- + +# Vocabulary Lookup + +Look up a word and display its definition, pronunciation, and a simple example. Supports English (default) and Spanish. + +## Process + +1. Extract the arguments. If no arguments were provided, ask the user what word they want to look up. + +2. **Detect language:** Check if the first token is `es` (case-insensitive). If so, the language is **Spanish** and the word is everything after `es`. Otherwise, the language is **English** and the entire argument is the word. + +3. **Search for the word:** + + **English:** Use WebSearch to search for: `"" definition pronunciation dictionary` + Then use WebFetch on the most relevant dictionary result (prefer Merriam-Webster, Dictionary.com, or Oxford) to get the full entry. + + **Spanish:** Use WebSearch to search for: `"" definicion pronunciacion diccionario site:dle.rae.es OR site:spanishdict.com OR site:wordreference.com` + Then use WebFetch on the most relevant result (prefer RAE, SpanishDict, or WordReference) to get the full entry. + +4. **Format the output:** + + **English format:** + + ``` + ## + + **Pronunciation:** // + + **Part of speech:** + + **Definition:** + + **Example:** + ``` + + **Spanish format:** + + ``` + ## + + **Pronunciacion:** // + + **Categoria gramatical:** + + **Definicion:** + + **Ejemplo:** + ``` + +## Rules + +- Keep it short — one primary definition, one example +- If the word has multiple parts of speech, show the most common one +- The example sentence should be straightforward and relatable for a ~12 year old +- If the word is not found, say so clearly +- **English lookups:** all output in English +- **Spanish lookups:** all output entirely in Spanish (labels, definition, example — everything) +- Do NOT save anything to a file — just display the result in the terminal diff --git a/plugins/obsidian/.claude-plugin/plugin.json b/plugins/obsidian/.claude-plugin/plugin.json index bb9be07..efc48d4 100644 --- a/plugins/obsidian/.claude-plugin/plugin.json +++ b/plugins/obsidian/.claude-plugin/plugin.json @@ -1,5 +1,5 @@ { "name": "arevlo:obsidian", - "description": "Capture screenshots and context to Obsidian Zettelkasten vault as fragment notes. Save external links to note tables.", - "version": "1.2.1" + "description": "Capture screenshots and context to Obsidian Zettelkasten vault as fragment notes. Save external links to note tables. Interactively study complex documents with Q&A. Add Confluence document summaries to project files.", + "version": "1.6.0" } diff --git a/plugins/obsidian/README.md b/plugins/obsidian/README.md index 364dfba..fa62383 100644 --- a/plugins/obsidian/README.md +++ b/plugins/obsidian/README.md @@ -1,6 +1,6 @@ -# Obsidian Capture Plugin +# Obsidian Plugin -Capture screenshots and context directly to your Obsidian Zettelkasten vault as fragment notes. +Capture screenshots and context to your Obsidian Zettelkasten vault as fragment notes. Save external links to note tables. Interactively study complex documents with Q&A. Add Confluence document summaries to project files. ## Commands @@ -13,32 +13,18 @@ Capture a screenshot with context and create a fragment note in your Obsidian va /arevlo:obsidian:capture [category] # Example: -/arevlo:obsidian:capture flow +/arevlo:obsidian:capture ai ``` **What it does:** 1. Analyzes any screenshot you've shared in the conversation -2. Prompts for category (flow, ai, personal, etc.) if not provided +2. Prompts for category if not provided 3. Asks for a topic-based title 4. Creates a `{category}/fragments/` subfolder if it doesn't exist 5. Copies the screenshot to `{category}/fragments/_attachments/{topic}.png` 6. Creates a fragment note with the screenshot embedded, your analysis, and any external links 7. Returns the path to the created note -**Example workflow:** -``` -User: [Pastes screenshot from Slack] - https://life-in-flow.slack.com/archives/C123/p456 - -/arevlo:obsidian:capture flow - -Claude: What topic should I use for the filename? -User: property-filters-discussion - -Claude: ✓ Fragment note created: flow/fragments/property-filters-discussion.md - ✓ Screenshot saved: flow/fragments/_attachments/property-filters-discussion.png -``` - ### `/arevlo:obsidian:save-link` Save external links to an Obsidian note's external links table. Creates the note if it doesn't exist. @@ -61,58 +47,62 @@ Save external links to an Obsidian note's external links table. Creates the note 6. Creates the note if it doesn't exist 7. Auto-generates a source tag from the URL domain (e.g., "source/anthropic") -**Example workflow:** -``` -User: /arevlo:obsidian:save-link https://anthropic.com/research/constitutional-ai - -Claude: What title/description should I use for this link? -User: Constitutional AI Research Paper +### `/arevlo:obsidian:study` -Claude: Where should I save this link? -User: ai/outlinks +Interactively break down and study complex documents (TDDs, specs, architecture docs) with Q&A, saving session notes to your Obsidian vault. -Claude: Any tags to add? (optional) -User: research, alignment +**Usage:** +``` +/arevlo:obsidian:study [confluence-url or file-path] +``` -Claude: Any notes or context? (optional) -User: Foundational paper on RLHF with AI feedback +**What it does:** +1. Fetches the document content (Confluence or local file) +2. Parses it into logical sections and presents an outline +3. Walks through each section interactively with summaries and Q&A +4. Tracks all questions and answers from the session +5. Generates a study session note with summaries, key points, Q&A, and takeaways +6. Saves the note to your Obsidian vault -Claude: ✓ Link saved to ai/outlinks - Title: Constitutional AI Research Paper - Tags: research, alignment, source/anthropic -``` +### `/arevlo:obsidian:project-doc` -**External Links Table Format:** -The command creates/updates a table in your note with this structure: -```markdown -## External Links +Add a Confluence document summary (TDD, PRD, Design Doc, RFC, Spec) to a project file. -| Title | Tags | Link | Notes | -|-------|------|------|-------| -| Constitutional AI Research Paper | #research #alignment #source/anthropic | [Constitutional AI Research Paper](https://anthropic.com/research/constitutional-ai) | Foundational paper on RLHF with AI feedback | +**Usage:** ``` +/arevlo:obsidian:project-doc [confluence-url] [optional:project-name] +``` + +**What it does:** +1. Fetches the Confluence page content and metadata +2. Auto-detects the document type (TDD, PRD, Design, RFC, Spec) from the title +3. Asks which platform section (Web/Mobile) and document status +4. Generates a one-line description, author attribution, and dense 3-6 sentence summary +5. Creates a new project file with the full template, or appends the section to an existing one ## Configuration -The plugin expects your Obsidian vault at: -``` -/Users/arevlo/Library/Mobile Documents/com~apple~CloudDocs/zk -``` +Configuration is stored in `~/.claude/obsidian-plugin.json`. On first use, any command will prompt you to set up your vault path. -To change this, edit the `VAULT_PATH` in `commands/capture.md`. +| Field | Used By | Description | +|-------|---------|-------------| +| `vault_path` | All commands | Absolute path to your Obsidian vault | + +To reconfigure, edit `~/.claude/obsidian-plugin.json` directly. ## Installation This plugin is part of the `claude-code-workflows` marketplace. -1. Make sure your `~/.claude.json` includes this marketplace: +1. Add the marketplace to `~/.claude.json`: ```json { "extraKnownMarketplaces": { "claude-code-workflows": { "source": { - "source": "directory", - "path": "/Users/arevlo/Desktop/personal-repos/claude-code-workflows" + "source": "github", + "owner": "arevlo", + "repo": "claude-code-workflows" } } } @@ -132,9 +122,9 @@ This plugin is part of the `claude-code-workflows` marketplace. ## Requirements -- **Obsidian MCP server** must be configured and running - Screenshots must be pasted into Claude Code (they're auto-cached in `~/.claude/image-cache/`) - Your Obsidian vault must be accessible at the configured path +- For `/study` and `/project-doc`: Atlassian MCP server for Confluence access ## Fragment Workflow @@ -143,9 +133,8 @@ Fragments are temporary captures in the Zettelkasten method: 2. **Process** - Review and convert to atomic primitives 3. **Connect** - Link primitives to build knowledge graph -Use `mcp__obsidian-zettelkasten__process_fragment` to convert fragments to primitives later. - ## Version History +- **1.6.0** - Added `/arevlo:obsidian:study` and `/arevlo:obsidian:project-doc` commands - **1.2.0** - Added `/arevlo:obsidian:save-link` command for saving external links to notes - **1.0.0** - Initial release with screenshot capture to fragment notes diff --git a/plugins/obsidian/commands/project-doc.md b/plugins/obsidian/commands/project-doc.md new file mode 100644 index 0000000..bb453aa --- /dev/null +++ b/plugins/obsidian/commands/project-doc.md @@ -0,0 +1,256 @@ +--- +description: Add a Confluence document summary to an Obsidian project file (TDD, PRD, Design, etc.) +argument-hint: [confluence-url] [optional:project-name] +allowed-tools: mcp__claude_ai_Atlassian__getConfluencePage,Read,Write,Bash,AskUserQuestion,Glob +--- + +Add a Confluence document summary (TDD, PRD, Design Doc, RFC, Spec) to a project file in your local projects directory. Fetches the Confluence page, generates a dense summary, and creates or appends to the project file. + +## What this does + +When you provide a Confluence URL and project name: +1. Fetches the Confluence page content and metadata +2. Detects the document type (TDD, PRD, Design, RFC, Spec) +3. Asks which platform section (Web/Mobile) and document status +4. Generates a one-line description, author attribution, and 3-6 sentence summary +5. Creates a new project file with the full template, or appends the document block to an existing one + +## Configuration + +Configuration is stored in `~/.claude/obsidian-plugin.json`. The `vault_path` field is used to locate the `projects/` directory. + +## Steps + +### 0. Load Configuration + +Before doing anything else, read the configuration file: + +1. Use the `Read` tool to read `~/.claude/obsidian-plugin.json` +2. **If the file does not exist:** + - Inform the user: "No Obsidian plugin configuration found. Let's set it up." + - Use `AskUserQuestion` to ask for their Obsidian vault path (absolute path, no `~`) + - Use `Bash` to create the config file: + ```bash + mkdir -p ~/.claude && cat > ~/.claude/obsidian-plugin.json << 'ENDCONFIG' + { + "vault_path": "{user's vault path}" + } + ENDCONFIG + ``` + - Continue with the values provided +3. **If the file exists:** Parse the JSON and extract `vault_path` for use in subsequent steps + +The projects directory is `{vault_path}/projects/`. + +### 1. Fetch the Confluence Page + +Parse the user's input for a Confluence URL: + +- **URL provided as argument:** Extract the page ID from the URL (the numeric segment after `/pages/`). Use `mcp__claude_ai_Atlassian__getConfluencePage` with `bodyFormat: "storage"` to get the full HTML content and metadata. Parse the HTML into readable text. +- **No URL provided:** Use `AskUserQuestion` to ask: + - Question: "What Confluence page would you like to add?" + - Options: + - "I'll paste a URL" + - "Search by title" + - Then follow up to get the URL + +Extract from the Confluence response: +- **Page title** (from the API response) +- **Page URL** (reconstruct from the Confluence URL or `_links` in response) +- **Authors** (from `version.by.displayName` or page history/metadata — look for creator and any co-authors mentioned in the content) +- **Full content** for summary generation + +### 2. Resolve the Project File + +Determine which project file to use: + +1. **If project name was provided as argument:** Convert to kebab-case filename: `{vault_path}/projects/{project-name}.md` +2. **If not provided:** Use `Glob` to list existing files in `{vault_path}/projects/*.md`, then use `AskUserQuestion`: + - Question: "Which project should I add this document to?" + - Options: List up to 3 existing project files (by filename without extension), plus a "Create new project" option + - If "Create new project": ask for the project name + +3. **Check if the file exists** using `Read`: + - **File exists with full template** (has `## Web` or `## Mobile` headings): Will append to it in Step 7 + - **File exists but minimal** (just an H1 title, like `# Unit Availability`): Will rebuild with full template, preserving the existing H1 + - **File does not exist:** Will create new file with full template in Step 7 + +### 3. Ask for Platform + +Use `AskUserQuestion`: +- Question: "Which platform section should this document go under?" +- Options: + - "Web" + - "Mobile" + +### 4. Detect Document Type + +Auto-detect the document type from the Confluence page title by looking for these keywords (case-insensitive): +- **TDD** — title contains "TDD" or "Technical Design" +- **PRD** — title contains "PRD" or "Product Requirements" +- **Design** — title contains "Design Doc" or "Design Document" or "HLD" or "LLD" +- **RFC** — title contains "RFC" or "Request for Comments" +- **Spec** — title contains "Spec" or "Specification" + +If auto-detected, confirm with the user via `AskUserQuestion`: +- Question: "I detected this as a **{type}**. Is that correct?" +- Options: + - "{type} (Recommended)" + - "TDD" + - "PRD" + - "Design" + - "RFC" + +If not auto-detected, ask the user: +- Question: "What type of document is this?" +- Options: + - "TDD" + - "PRD" + - "Design" + - "RFC" + +### 5. Ask for Status + +Use `AskUserQuestion`: +- Question: "What is the current status of this document?" +- Options: + - "DRAFT" + - "IN REVIEW" + - "APPROVED" + - "FINAL" + +### 6. Generate Content + +Using the Confluence page content, generate: + +1. **One-line description** — A single sentence describing what this document covers in the context of the project. Example: "Technical design for the user authentication workflows feature." + +2. **Author line** — Extract author names from the Confluence page metadata (`version.by.displayName`, creator info). If multiple authors are apparent from the document content (e.g., listed contributors), include them separated by `&`. If author information is unavailable, use `AskUserQuestion` to ask: "Who are the authors of this document?" + +3. **Summary** — A dense 3-6 sentence summary that covers: + - What the document defines/proposes + - Key architectural or product decisions + - Important technical details or scope + - Timeline or milestones if mentioned + - Any notable constraints or tradeoffs + +The summary should be information-dense and reference specific details from the document (names of services, specific numbers, dates, etc.) rather than being generic. + +### 7. Write Output + +Compose the document block: + +```markdown +### {DOC_TYPE} + +{One-line description.} + +[{Page Title}]({url}) — {Author Names} | Status: {STATUS} + +**Summary:** {3-6 sentence dense summary.} + +### Notes +- +``` + +Now write the file based on the project file state determined in Step 2: + +#### New file (does not exist) + +Create a new file at `{vault_path}/projects/{project-name}.md` with: + +```markdown +# {Project Name} + +{time-estimate}... +## Web + +{document block here if platform is Web, otherwise leave empty} + +## Mobile + +{document block here if platform is Mobile, otherwise leave empty} + +``` + +Use `Bash` to create the projects directory if it doesn't exist: +```bash +mkdir -p "{vault_path}/projects" +``` + +Then use `Write` to create the file. + +#### Minimal existing file (just an H1, no platform headings) + +Read the existing H1 title from the file. Rebuild with the full template structure, preserving the original H1: + +```markdown +# {Existing H1 Title} + +{time-estimate}... +## Web + +{document block here if platform is Web, otherwise leave empty} + +## Mobile + +{document block here if platform is Mobile, otherwise leave empty} + +``` + +Use `Write` to overwrite the file. + +#### Existing file with full template + +Read the file content. Find the `## {Platform}` heading (e.g., `## Web`). + +**Check for duplicate doc type:** Search for `### {DOC_TYPE}` under the target platform section (between `## {Platform}` and the next `## ` heading or end of file). If found: +- Use `AskUserQuestion`: + - Question: "A **{DOC_TYPE}** section already exists under **{Platform}**. What should I do?" + - Options: + - "Add anyway (keep both)" + - "Replace existing" + - "Cancel" +- If "Cancel": Stop and inform the user. +- If "Replace existing": Remove the existing doc type block (from `### {DOC_TYPE}` to the next `### ` heading or `## ` heading or end of file) before inserting. + +**Insert the document block:** +- Find the insertion point: the line before the next `## ` heading after `## {Platform}`, or end of file if it's the last section. +- If the platform section is empty, insert directly after the `## {Platform}` line (with a blank line). +- If the platform section already has content, insert after the last content block in that section (before the next `## ` heading). + +**If the platform heading doesn't exist:** Append the platform section with the document block at the end of the file: + +```markdown + +## {Platform} + +{document block} + +``` + +Use `Write` to save the updated file. + +### 8. Confirm + +Show the user a confirmation: + +``` +Project doc updated: projects/{project-name}.md + +Section: ## {Platform} → ### {DOC_TYPE} +Status: {STATUS} +Authors: {Author Names} + +Summary preview: +{First ~100 characters of the summary}... +``` + +## Notes + +- **Direct file writes only** — This command writes directly to the filesystem using the `Write` tool. It does NOT use the obsidian-zettelkasten MCP server. +- **Projects directory** — All project files live in `{vault_path}/projects/`. The directory is created if it doesn't exist. +- **Template consistency** — New and minimal files always get the full template with both `## Web` and `## Mobile` sections and the `{time-estimate}...` placeholder. +- **Summary quality** — Summaries should be information-dense with specific details (service names, endpoint counts, dates, task types) rather than generic descriptions. +- **Author extraction** — Primary source is Confluence metadata. Fall back to asking the user only if metadata is unavailable. +- **Confluence URL format** — URLs look like `https://{domain}.atlassian.net/wiki/spaces/{SPACE}/pages/{pageId}/{Page+Title}`. The page ID is the numeric segment. diff --git a/plugins/obsidian/commands/study.md b/plugins/obsidian/commands/study.md new file mode 100644 index 0000000..f32339b --- /dev/null +++ b/plugins/obsidian/commands/study.md @@ -0,0 +1,276 @@ +--- +description: Interactively break down and study complex documents (TDDs, specs, architecture docs) with Q&A, saving session notes to Obsidian vault +allowed-tools: mcp__claude_ai_Atlassian__getConfluencePage,mcp__claude_ai_Atlassian__search,Read,Write,Bash,AskUserQuestion +--- + +Interactively break down and study a complex document (TDD, spec, architecture doc) section-by-section with Q&A, then save the study session as a fragment note in your Obsidian vault. + +## What this does + +When you provide a Confluence URL or local file path: +1. Fetches the document content +2. Parses it into logical sections and presents an outline +3. Walks through each section interactively with summaries and Q&A +4. Tracks all questions and answers from the session +5. Generates a study session note with summaries, key points, Q&A, and takeaways +6. Saves the note to your Obsidian vault + +## Configuration + +Configuration is stored in `~/.claude/obsidian-plugin.json`. The `vault_path` field is used for saving study notes. + +## Steps + +### 0. Load Configuration + +Before doing anything else, read the configuration file: + +1. Use the `Read` tool to read `~/.claude/obsidian-plugin.json` +2. **If the file does not exist:** + - Inform the user: "No Obsidian plugin configuration found. Let's set it up." + - Use `AskUserQuestion` to ask for their Obsidian vault path (absolute path, no `~`) + - Use `Bash` to create the config file: + ```bash + mkdir -p ~/.claude && cat > ~/.claude/obsidian-plugin.json << 'ENDCONFIG' + { + "vault_path": "{user's vault path}" + } + ENDCONFIG + ``` + - Continue with the values provided +3. **If the file exists:** Parse the JSON and extract `vault_path` for use in subsequent steps + +### 1. Identify the Source Document + +Parse the user's input for a source document: + +- **Confluence URL:** If the user provided a Confluence URL (contains `atlassian.net/wiki`), use `mcp__claude_ai_Atlassian__getConfluencePage` to fetch the full page content. Extract the page ID from the URL. Use `bodyFormat: "storage"` to get the full HTML content, then parse it into readable text. +- **Local file path:** If the user provided a file path, use `Read` to read the file content. +- **Neither provided:** Use `AskUserQuestion` to ask: + - Question: "What document would you like to study?" + - Options: + - "Confluence page (I'll paste a URL)" + - "Local file (I'll provide a path)" + - Then follow up to get the specific URL or path + +Once the document content is loaded, extract: +- **Document title** (from Confluence page title or filename) +- **Source reference** (URL or file path) +- **Full content** for section parsing + +### 2. Analyze and Present Outline + +Parse the document into logical sections based on headings and major topics: + +1. Identify all top-level and second-level sections (H1, H2, or equivalent structural boundaries) +2. For each section, generate a brief 1-line description of what it covers +3. Present the outline to the user: + +``` +Study Session: {Document Title} +Source: {URL or file path} + +Sections: +1. {Section 1 title} — {1-line description} +2. {Section 2 title} — {1-line description} +3. {Section 3 title} — {1-line description} +... + +I'll walk through each section with summaries and Q&A. Ask questions anytime. +``` + +4. Use `AskUserQuestion` to ask where to start: + - Question: "Where would you like to start?" + - Options: + - "Start from the beginning" + - "Jump to a specific section" + - If "Jump to a specific section": ask which section number to start from + +### 3. Interactive Section-by-Section Walkthrough + +**Initialize tracking:** +- Create an internal list to track all Q&A pairs per section +- Track which sections have been covered +- Track the current section index + +**For each section**, repeat this loop: + +#### 3a. Present Section Summary + +Present a clear summary (200-300 words) that explains: +- **What this section covers** — the main topic and purpose +- **Key decisions or tradeoffs** — any architectural choices, design decisions, or tradeoffs discussed +- **Connection to previous sections** — how this builds on or relates to what came before +- **Important technical details** — simplified explanation of any complex technical content + +Format the summary clearly with the section number and title as a header. + +#### 3b. Ask for Questions + +Use `AskUserQuestion`: +- Question: "Questions about **{Section Title}**?" +- Options: + - "No questions, next section" + - "I have a question" + - "Go deeper on this section" + - "Skip to a specific section" + +#### 3c. Handle Response + +- **"No questions, next section"**: Move to the next section. If this was the last section, proceed to Step 4. +- **"I have a question"**: The user will type their question. Answer it thoroughly, then record the Q&A pair. After answering, ask again (repeat 3b) to check for more questions. +- **"Go deeper on this section"**: Provide a more detailed breakdown covering implementation details, edge cases, implications, and any nuances. Then ask again (repeat 3b). +- **"Skip to a specific section"**: Ask which section number, then jump to that section. + +**Important:** The user may also type free-form questions or comments instead of selecting an option. Always treat free-form text as a question and answer it, then loop back to ask if they have more questions. + +#### 3d. Record Q&A + +For every question asked (whether via option selection or free-form), record: +- The question text +- Your answer text +- Which section it belongs to + +These will be included in the final output note. + +### 4. Generate Session Summary + +After completing all sections (or when the user indicates they're done): + +1. **Compile takeaways** — Identify the 3-5 most important points from the entire document. These should be actionable or conceptually significant insights. + +2. **List open questions** — Any questions that came up during the session that couldn't be fully answered, or areas that need further investigation. + +3. **Note action items** — Any follow-ups, tasks, or next steps identified during the discussion. + +Present the summary to the user before saving: + +``` +Session Summary + +Sections covered: {n}/{total} +Questions answered: {count} + +Key Takeaways: +1. {Takeaway 1} +2. {Takeaway 2} +3. {Takeaway 3} + +Open Questions: +- {Question 1} +- {Question 2} + +Action Items: +- {Action 1} +- {Action 2} +``` + +### 5. Save to Obsidian + +Ask the user for save details using `AskUserQuestion`: +- Question: "What category folder should this be saved to? (Type the folder name, e.g., 'ai', 'work', 'projects')" +- Let the user type their category folder name directly + +Then ask for the topic slug: +- Question: "What topic slug should I use for the filename?" +- Suggest a default based on the document title (e.g., `api-architecture-spec`, `auth-service-tdd`) +- Options: + - "{suggested-slug} (Recommended)" + - "Let me type a custom slug" + +**Create the output directory if needed:** + +```bash +VAULT_PATH="{vault_path from config}" +CATEGORY="{selected category}" +mkdir -p "$VAULT_PATH/$CATEGORY/fragments" +``` + +**Write the study note** using the `Write` tool to save to `{vault_path}/{category}/fragments/{topic}.md`: + +```markdown +--- +date: YYYY-MM-DD +type: study-session +source: "{URL or file path}" +--- + +# Study: {Document Title} + +> Source: [{title}]({url or path}) +> Date: {Mon DD, YYYY} +> Sections covered: {n}/{total} + +## Overview +{2-3 sentence summary of the entire document — what it is, what it defines, and its scope} + +## {Section 1 Title} + +### Summary +{The summary presented during the walkthrough for this section} + +### Key Points +- {Key point 1} +- {Key point 2} +- {Key point 3} + +### Q&A +**Q: {User's question}** +A: {Your answer} + +**Q: {Another question}** +A: {Answer} + +## {Section 2 Title} + +### Summary +{Summary} + +### Key Points +- {Points} + +### Q&A +{Q&A pairs, or omit this subsection if no questions were asked for this section} + +... + +## Takeaways +- {Key takeaway 1} +- {Key takeaway 2} +- {Key takeaway 3} +- {Key takeaway 4} +- {Key takeaway 5} + +## Open Questions +- {Any unresolved questions from the session} + +## Action Items +- {Any follow-ups identified during the session} +``` + +**Rules for the output note:** +- Only include the Q&A subsection for sections where questions were actually asked +- Only include "Open Questions" and "Action Items" sections if there are items to list +- Use the actual date of the session +- For Confluence sources, make the source a clickable link +- Keep section summaries concise (the note is a reference, not a reproduction of the walkthrough) + +### 6. Confirm + +Show the user a final confirmation: + +``` +Study session saved: {category}/fragments/{topic}.md + +Sections covered: {n}/{total} +Questions answered: {count} +Takeaways captured: {count} +``` + +## Notes + +- **Session flexibility:** Users can stop at any point and the note will be generated with whatever sections were covered. Track "Sections covered: X/Y" to reflect this. +- **Long documents:** For very long documents (20+ sections), suggest grouping related sections or focusing on specific areas rather than walking through everything. +- **Confluence formatting:** Confluence pages may have complex HTML (tables, macros, panels). Parse these into readable plain text/markdown for the summaries. +- **Fragment lifecycle:** Like other fragment notes, study sessions are captures meant to be referenced later or processed into atomic knowledge. +- **Re-studying:** Users may want to re-study a document. Each session creates a new fragment, so previous sessions are preserved.