escribano 0.1.0

package/prompts/action-items.md

@@ -0,0 +1,55 @@
+# Action Items
+You are a project manager extracting action items from a work session. Your goal is to create clear, specific, and actionable tasks that can be executed without ambiguity.
+
+## Context
+Metadata: {{METADATA}}
+Visual Log: {{VISUAL_LOG}}
+Detected Language: {{LANGUAGE}}
+
+## Instructions
+1. **Language Rule**: Use English for the document structure and headings. The task descriptions, names of responsible parties, and specific technical details must remain in the original language ({{LANGUAGE}}).
+
+2. **Extraction Scope**: Identify all tasks, assignments, decisions, and follow-ups mentioned in the transcript. Look for both explicit and implicit action items.
+
+3. **Action Item Standards**: Each action item must be:
+   - **Specific**: Clear enough that someone not in the meeting understands what to do
+   - **Action-oriented**: Begin with a strong verb (e.g., "Create," "Submit," "Review," "Fix," "Research")
+   - **Complete**: Include all necessary context, documents, or reference materials mentioned
+   - **Measurable**: Include a success criteria or deliverable that indicates completion
+
+4. **Handling Ambiguity**:
+   - If an item is vague or abstract, break it down into 2-3 concrete sub-tasks
+   - If no owner is explicitly stated, infer from context based on who raised the item, who has relevant expertise, or the role discussed
+   - Mark items with inferred assignments as [Inferred] and note reasoning
+
+5. **Deadlines and Priority**:
+   - Extract specific deadlines mentioned. If none mentioned, mark as "Deadline not specified"
+   - Identify priority levels from context:
+     - **High/Urgent**: Blocks other work, mentioned as critical, or has firm deadline
+     - **Medium**: Important but not blocking
+     - **Low**: Nice-to-have or can be deferred
+   - If priority is unclear, mark as "Priority not specified"
+
+6. **Format**:
+   Use a numbered list format for each action item with the following structure:
+
+   ```
+   [ID]. [Action verb] [Specific task description]
+   
+      • Owner: [Name/Role] [Mark [Inferred] if not explicit]
+      • Deadline: [Specific date/time OR "Not specified"]
+      • Priority: [High/Medium/Low OR "Not specified"]
+      • Success Criteria: [How completion will be verified OR "Not specified"]
+      • Context/Notes: [Relevant details, dependencies, reference materials]
+   ```
+
+   Group related items together under logical headers if helpful.
+
+7. **Quality Checks**:
+   - Ensure every item starts with an action verb
+   - Verify each item has at least one owner (explicit or inferred)
+   - Confirm no item is so vague it would require follow-up clarification
+   - If an item cannot be made specific from the transcript, mark it as [Requires Clarification] and include a brief note
+
+## Transcript
+{{TRANSCRIPT_ALL}}

package/prompts/blog-draft.md

@@ -0,0 +1,54 @@
+# Blog Narrative Draft
+
+You are a creative writer transforming a technical or business session into a narrative-driven blog post or article.
+
+## Context
+Metadata: {{METADATA}}
+Detected Language: {{LANGUAGE}}
+
+## Instructions
+
+1. **Language Rule**: Use English for headings and structural elements. The actual narrative content, quotes, and creative storytelling must remain in the original language ({{LANGUAGE}}).
+
+2. **Adopt a Proven Narrative Structure** (choose one based on session content):
+   - **Problem-Solution Arc**: Start with a relatable problem → Show struggle/attempted solutions → Describe the breakthrough or key insight → Explain the resolution → Share lessons learned
+   - **Hero's Journey**: Introduce a protagonist (could be the speaker, team, or customer) → Present the challenge they face → Describe the guide/mentor or discovery → Show the transformation → Reflect on the journey
+   - **Case Study Format**: Set the context/background → Define the challenge → Detail the approach/process → Reveal results → Extract key takeaways
+
+3. **Engagement Techniques**:
+   - **Hook your reader immediately** with one of these opening techniques:
+     * A compelling anecdote from the session
+     * A startling statistic or counterintuitive fact
+     * A provocative question that addresses the reader's pain point
+     * A "what if" scenario
+   - **Create tension early** by establishing the stakes — what's at risk? What problem needs solving?
+   - **"Show, don't tell"** throughout — use specific details, examples, and vivid descriptions rather than abstract statements
+   - **Build characters** — make the people in the session relatable with specific details, motivations, and perspectives
+
+4. **Scannability for Web Readers**:
+   - Use **short paragraphs** (2-3 sentences maximum)
+   - Insert **subheadings** every 3-4 paragraphs to guide readers through the narrative
+   - Use **bulleted lists** for key points, lessons, or examples
+   - Include **a pull quote** or highlighted insight from the transcript that captures the essence
+   - Start each paragraph with a **topic sentence** that hints at what follows (Google Developers)
+
+5. **Structure Required**:
+   - **Compelling Hook** (opening technique as above)
+   - **The Narrative Arc** — logically flowing from beginning to middle to end, with rising action
+   - **Key Takeaways** — 3-5 concrete lessons or insights, presented as a bulleted list
+   - **Call-to-Action** — give the reader a purposeful next step: "Try this approach," "Apply this insight," "Share your experience," or "Join the conversation"
+   - **Conclusion** — reflect on the session's broader impact or future outlook
+
+6. **Tone and Style**:
+   - Use **active voice** throughout for clarity and impact
+   - Make content **relatable** — connect technical concepts to everyday experiences
+   - Balance **authenticity** with polish — preserve genuine moments from the transcript while ensuring flow
+   - Aim for **memorable** through surprising insights, emotional resonance, or practical value
+
+7. **Avoid**:
+   - Chronological transcript dumps (this is not a transcript)
+   - Overly jargon-heavy explanations without context
+   - Abstract generalities — ground every point in specific examples from the session
+
+## Transcript
+{{TRANSCRIPT_ALL}}

package/prompts/blog-research.md

@@ -0,0 +1,87 @@
+# Blog Research Synthesis
+
+You are a content researcher synthesizing a deep-dive learning or research session into a structured knowledge base following systematic qualitative analysis methods.
+
+## Context
+Metadata: {{METADATA}}
+Detected Language: {{LANGUAGE}}
+
+## Instructions
+
+### 1. Language Rule
+- **Structural elements**: Use English for all headings, section labels, bullet points, and organizational markers.
+- **Research content**: Preserve the original language ({{LANGUAGE}}) for all research findings, quotes, examples, and conceptual explanations.
+
+### 2. Analysis Methodology
+Follow this systematic process before writing your output:
+
+**Step 1: Coding**
+- Identify and label key concepts, claims, and arguments in the transcript
+- Look for recurring terminology and ideas
+- Note direct quotes that capture essential insights
+
+**Step 2: Pattern Recognition**
+- Group related codes into clusters
+- Identify relationships between concepts (causality, comparison, contrast)
+- Detect contradictions or tensions in the reasoning
+
+**Step 3: Theme Development**
+- Name each theme clearly and descriptively
+- Define the scope of each theme
+- Validate that themes accurately reflect the transcript content
+
+**Step 4: Synthesis**
+- Connect themes to higher-level insights
+- Identify the overarching narrative or framework
+- Distinguish between what was explored, what was concluded, and what remains uncertain
+
+### 3. Output Structure
+
+#### A. Research Overview
+- **Research Goal**: What specific question, problem, or topic was being explored?
+- **Research Context**: Why this topic matters (background, motivation, stakes)
+- **Research Scope**: What was in-scope vs. out-of-scope for this session
+
+#### B. Thematic Breakdown
+For each major theme, provide:
+- **Theme Name**: Clear, descriptive label
+- **Theme Definition**: What this theme encompasses
+- **Key Insights**: 3-5 core findings related to this theme
+- **Supporting Evidence**: Direct quotes or paraphrased evidence (preserve original language)
+- **Connections**: How this theme relates to other themes
+
+#### C. Comparative Analysis (if applicable)
+When multiple options, approaches, or perspectives were discussed:
+- **Options Compared**: List each option/approach
+- **Criteria for Comparison**: What dimensions were evaluated
+- **Pros and Cons**: Evidence-based advantages and disadvantages for each
+- **Trade-offs**: What had to be given up for each choice
+
+#### D. Key Findings
+Synthesize the most important takeaways:
+- **Primary Insights**: The central conclusions or discoveries
+- **Evidence Base**: What evidence supports these insights (cite transcript segments)
+- **Implications**: What these findings mean for the broader topic
+- **Confidence Level**: How certain is this finding (High/Medium/Low) and why
+
+#### E. Knowledge Graph
+Create a network view of the session's concepts:
+- **Core Concepts**: The fundamental ideas discussed
+- **Relationships**: How concepts connect (e.g., "depends on", "contradicts", "builds on")
+- **Hierarchy**: Which concepts are foundational vs. derived
+
+#### F. Open Questions & Future Research
+- **Unresolved Issues**: Questions that emerged but weren't answered
+- **Knowledge Gaps**: Areas where more research is needed
+- **Next Steps**: Concrete follow-up actions or investigations suggested
+
+### 4. Quality Standards
+Your synthesis must:
+- **Ground claims in evidence**: Every insight should reference transcript content
+- **Preserve nuance**: Don't oversimplify complex or ambiguous discussions
+- **Attribute sources**: When possible, indicate where claims came from (e.g., "according to the transcript at [topic/section]")
+- **Distinguish evidence from interpretation**: Clearly separate what was said vs. what you infer
+- **Maintain traceability**: Keep the output verifiable against the original transcript
+
+### 5. Transcript Data
+{{TRANSCRIPT_ALL}}

package/prompts/card.md

@@ -0,0 +1,54 @@
+# Card Format - Structured Per-Subject Output
+
+You are generating a structured card summary of a work session. The session has been grouped into SUBJECTS (coherent work threads).
+
+## Session Metadata
+- **Duration:** {{SESSION_DURATION}}
+- **Date:** {{SESSION_DATE}}
+- **Subjects:** {{SUBJECT_COUNT}}
+
+## Subjects
+
+{{SUBJECTS_DATA}}
+
+---
+
+## Instructions
+
+Generate a structured card summary with:
+
+1. **Per-subject sections** with:
+   - Subject label as header (## Subject Name)
+   - Duration and activity breakdown in bold: `**3h 12m** | coding 1h 45m, debugging 52m`
+   - 2-4 bullet points of key accomplishments/activities (extracted from the descriptions)
+
+2. **Personal subjects** should be shown as a single line at the end: `*Personal time: 47m (WhatsApp, Instagram)*`
+
+3. **Format example:**
+
+```markdown
+# Session Card - Feb 25, 2026
+
+## Escribano Pipeline Optimization
+**3h 12m** | coding 1h 45m, debugging 52m, terminal 35m
+
+- Achieved 20.6x speedup in scene detection with skip-frame nokey strategy
+- Resolved LLM truncation errors via raw response logging
+- Benchmarked MLX vs Ollama VLM performance
+
+## Research & Exploration
+**32m** | research 22m, other 10m
+
+- Explored Screenpipe repository architecture for comparison
+- Reviewed HuggingFace model options for VLM inference
+
+---
+*Personal time: 47m (filtered)*
+```
+
+**Rules:**
+- Be concise - each subject gets 2-4 bullets max
+- Extract specifics from descriptions (metrics, file names, error types)
+- Use present tense, first person
+- Total output should be 200-500 words
+- DO NOT include raw descriptions or transcripts - synthesize into bullets

package/prompts/classify-segment.md

@@ -0,0 +1,38 @@
+# Segment Classification Prompt
+
+You are an expert session analyst. Your task is to classify a specific segment of a work session based on visual evidence and available audio.
+
+## Input Context
+
+- **Time Range**: {{TIME_RANGE}}
+- **Visual Context**: {{VISUAL_CONTEXT}}
+- **OCR Evidence**: {{OCR_CONTEXT}}
+- **Transcript Content**: {{TRANSCRIPT_CONTENT}}
+- **Vision Model Analysis**: {{VLM_DESCRIPTION}}
+
+## Classification Types
+
+1. **meeting**: Conversations, interviews, or group discussions. Multiple speakers or Q&A.
+2. **debugging**: Troubleshooting errors, fixing bugs, investigating log outputs.
+3. **tutorial**: Teaching or demonstrating a process step-by-step.
+4. **learning**: Researching, studying documentation, reading articles, watching educational videos.
+5. **working**: Active building, coding (not debugging), writing documents, designing.
+
+## Task
+
+Analyze the evidence and provide a multi-label classification score (0-100) for each type. The scores represent your confidence/degree of matching for that specific segment.
+
+If the segment contains background music or is purely transitional/noise (e.g., browsing a music player), assign low scores to all categories or focus on the primary intent if visible.
+
+## Output Format
+
+Return ONLY a JSON object with this structure:
+```json
+{
+  "meeting": number,
+  "debugging": number,
+  "tutorial": number,
+  "learning": number,
+  "working": number
+}
+```

package/prompts/classify.md

@@ -0,0 +1,37 @@
+# Session Classification
+
+Output ONLY JSON scores (0-100) for each session type.
+
+## Session Types:
+
+**meeting** - Conversations, interviews, discussions
+Examples: Team meetings, client calls, 1-on-1s, planning sessions
+Look for: Multiple speakers, Q&A format, decisions being made
+
+**debugging** - Fixing errors and troubleshooting  
+Examples: Finding bugs, fixing tests, resolving crashes
+Look for: Error messages, "not working", investigation steps
+
+**tutorial** - Teaching or demonstrating
+Examples: How-to guides, walkthroughs, step-by-step explanations
+Look for: Instructions, "first do this, then...", teaching tone
+
+**learning** - Researching or studying
+Examples: Reading docs, exploring frameworks, comparing options
+Look for: "Let me understand", research, exploration
+
+**working** - Building or creating (not fixing)
+Examples: Writing features, refactoring, implementing new code
+Look for: Creating files, "let's implement", productive coding
+
+## Input Context:
+
+### Visual Log (Screen Activity)
+{{VISUAL_LOG}}
+
+### Transcript
+{{TRANSCRIPT_ALL}}
+
+## Output Format:
+Output ONLY JSON scores (0-100) for each session type.
+{"meeting": 85, "debugging": 10, "tutorial": 0, "learning": 45, "working": 20}

package/prompts/code-snippets.md

@@ -0,0 +1,163 @@
+# Code Snippets & Implementation Details
+
+You are a developer documenting code changes and implementation details from a working session. Your goal is to create **literate documentation**: an explanatory narrative that embeds code as part of the story of how and why the solution was built.
+
+## Context
+Metadata: {{METADATA}}
+Visual Log: {{VISUAL_LOG}}
+Detected Language: {{LANGUAGE}}
+
+## Visual Integration Rule
+If a code snippet is demonstrated on screen but not fully captured in text, you can request a screenshot of the editor using `[SCREENSHOT: timestamp]`.
+
+## Core Principles
+1. **Literate Programming**: Organize code by human logic, not file order. Tell the story of implementation decisions.
+2. **Why Over How**: Focus on motivations, trade-offs, and reasoning. Let the code speak for itself when possible.
+3. **Complete Yet Concise**: Include necessary context, imports, and error handling, but avoid obvious explanations.
+
+## Language Rule
+Use English for:
+- Section headings
+- Structure markers (e.g., "##", "**", lists)
+- Technical terminology (e.g., "function", "class", "exception")
+
+Use {{LANGUAGE}} for:
+- Code content and variable names
+- Descriptions of implementation logic
+- Explanations of what code does in original language
+
+## Output Structure
+
+### 1. Implementation Overview
+**Purpose**: Summarize what was built and why it matters.
+
+Include:
+- Problem statement (what challenge did this solve?)
+- High-level approach (what pattern/architecture?)
+- Key components (modules, classes, major functions)
+- Dependencies (external libraries, APIs, services)
+- Known limitations or TODOs
+
+**Format**: 3-5 paragraphs, maximum.
+
+---
+
+### 2. Refined Code Snippets
+**Purpose**: Present clean, documented, ready-to-use code.
+
+Organize **hierarchically** by logical flow:
+- By component/module (if multiple)
+- By class or major function group
+- By implementation phase (setup → core → helpers)
+
+**For each snippet**:
+1. **Context** (2-3 sentences): What does this code do? Where does it fit?
+2. **Code block**:
+   - Include necessary imports
+   - Follow language conventions (PEP 8 for Python, Google Style for JS/TS, etc.)
+   - Add **docstrings** for all functions/classes with:
+     - Summary line (imperative: "Do X", not "Does X")
+     - Parameters (name, type, description)
+     - Return value (type, description)
+     - Exceptions raised (if any)
+   - Mark incomplete/placeholder code with `[TODO]` or `[FIXME]`
+3. **Notes** (if needed): Edge cases, assumptions, or important details
+
+**Improvement Guidelines**:
+- Fix formatting (indentation, line length < 80 chars where possible)
+- Add missing imports
+- Complete partial code where intent is clear from transcript
+- Remove commented-out dead code
+- Standardize naming (snake_case for Python/other, camelCase for JS/TS)
+- Add type hints (Python) or JSDoc (JavaScript/TypeScript) if clear from context
+
+**Example format**:
+```python
+# Helper function for processing user input
+
+def validate_email(email: str) -> bool:
+    """Validate an email address using regex pattern.
+    
+    Args:
+        email: The email string to validate.
+        
+    Returns:
+        bool: True if valid, False otherwise.
+        
+    Raises:
+        ValueError: If email is None or empty string.
+    """
+    import re
+    # Implementation...
+```
+
+---
+
+### 3. Technical Decisions
+**Purpose**: Document the reasoning behind key choices.
+
+For each significant decision (pattern, library, architecture choice):
+1. **Decision**: What was chosen?
+2. **Alternatives Considered**: What other options existed?
+3. **Rationale**: Why was this chosen? (trade-offs, requirements, constraints)
+4. **Implications**: What does this decision affect? (performance, maintainability, future work)
+
+**Prioritize**: Architecture choices, algorithm selection, library dependencies, data structures.
+
+**Format**: Bullet points or short table.
+
+---
+
+### 4. Usage Examples
+**Purpose**: Show how to use the implemented code.
+
+Provide 1-3 **runnable examples** covering:
+- Basic use case (primary functionality)
+- Edge case or advanced use (if applicable)
+- Integration with other components (if relevant)
+
+**Each example should**:
+- Be self-contained (setup, execution, expected output)
+- Include comments explaining each step
+- Show both success and error paths (if applicable)
+
+**Format**: Code block with explanatory text before/after.
+
+---
+
+### 5. Testing & Validation (Optional but Recommended)
+**Purpose**: Verify the implementation works as intended.
+
+Include if mentioned in transcript or implied by complexity:
+- Test cases for critical functions
+- Example inputs and expected outputs
+- Known bugs or areas needing more testing
+
+---
+
+## Source Material
+Use the following as input, prioritizing completeness and clarity:
+
+- **Transcript**: {{TRANSCRIPT_ALL}}
+- **Pre-extracted snippets**: {{CODE_SNIPPETS}}
+
+When transcript and snippets conflict:
+- Use transcript for context and intent
+- Use snippets for code structure
+- Reconcile by favoring code that makes logical sense
+
+---
+
+## Quality Checklist
+Before finalizing:
+- [ ] All code blocks compile/syntactically valid (in target language)
+- [ ] Every function/class has a docstring
+- [ ] All imports are included at top of relevant blocks
+- [ ] Decisions include alternatives and rationale
+- [ ] Usage examples are runnable (or clearly marked as pseudocode)
+- [ ] Incomplete code is marked with [TODO] or similar
+- [ ] English used for structure only, {{LANGUAGE}} for content
+- [ ] No obvious code is explained (let code speak for itself)
+
+## Transcript
+{{TRANSCRIPT_ALL}}

package/prompts/extract-metadata.md

@@ -0,0 +1,149 @@
+# Transcript Metadata Extraction
+
+Extract structured metadata from this session.
+
+## Visual Log (Significant Screen Changes)
+{{VISUAL_LOG}}
+
+## Session Classification
+{{CLASSIFICATION_SUMMARY}}
+
+Example: "meeting: 85%, learning: 45%"
+
+## Metadata Types to Extract
+
+### 1. Speakers (extract if meeting/tutorial)
+List all participants mentioned in the conversation with their roles if provided.
+
+**Fields:**
+- `name`: Participant's name
+- `role`: Their role/title if mentioned (e.g., "Engineering Lead", "Product Manager")
+
+**Example Output:**
+```json
+{
+  "speakers": [
+    {"name": "Alice", "role": "Engineering Lead"},
+    {"name": "Bob", "role": "Product Manager"},
+    {"name": "Carol", "role": "Designer"}
+  ]
+}
+```
+
+### 2. Key Moments (extract always)
+Important timestamps with descriptions of significant events, decisions, or insights.
+
+**CRITICAL:** If the transcript is silent, use the **Visual Log** to identify steps. A scene change at a specific timestamp usually indicates a new action or state.
+
+**Fields:**
+- `timestamp`: Time in seconds
+- `description`: What happened
+- `importance`: "high", "medium", or "low"
+
+**Importance Guidelines:**
+- **high**: Major decisions, critical issues, breakthrough insights
+- **medium**: Important discussions, technical findings
+- **low**: Minor details, background information
+
+**Example Output:**
+```json
+{
+  "keyMoments": [
+    {"timestamp": 120, "description": "Decided on Q1 priorities", "importance": "high"},
+    {"timestamp": 450, "description": "Identified root cause of authentication bug", "importance": "high"},
+    {"timestamp": 600, "description": "Reviewed database schema", "importance": "medium"}
+  ]
+}
+```
+
+### 3. Action Items (extract if meeting/working)
+Specific tasks that need to be completed, with owners and priorities.
+
+**Fields:**
+- `description`: What needs to be done
+- `owner`: Who is responsible (use "Unknown" if unclear)
+- `priority`: "high", "medium", or "low"
+
+**Example Output:**
+```json
+{
+  "actionItems": [
+    {"description": "Create technical spec for auth feature", "owner": "Alice", "priority": "high"},
+    {"description": "Schedule user research sessions", "owner": "Bob", "priority": "medium"},
+    {"description": "Update documentation", "owner": "Carol", "priority": "low"}
+  ]
+}
+```
+
+### 4. Technical Terms (extract if debugging/working/learning)
+Error messages, file paths, function names, variables, or other technical concepts mentioned.
+
+**Fields:**
+- `term`: The technical term
+- `context`: Where it was mentioned or what it means
+- `type`: One of: "error", "file", "function", "variable", "other"
+
+**Type Guidelines:**
+- **error**: Error messages, stack traces, exception names
+- **file**: File paths, document names, configuration files
+- **function**: Function/method names, API calls
+- **variable**: Variable names, constants, configuration keys
+- **other**: Other technical terms not fitting above categories
+
+**Example Output:**
+```json
+{
+  "technicalTerms": [
+    {"term": "NullPointerException", "context": "User login flow error", "type": "error"},
+    {"term": "/api/auth/validate", "context": "Endpoint for validating JWT tokens", "type": "function"},
+    {"term": "config.yaml", "context": "Configuration file for auth service", "type": "file"},
+    {"term": "MAX_RETRIES", "context": "Environment variable for retry logic", "type": "variable"}
+  ]
+}
+```
+
+### 5. Code Snippets (extract if working/tutorial/learning)
+Code examples, commands, or technical explanations with code.
+
+**Fields:**
+- `language`: Programming language or command type (e.g., "typescript", "python", "bash")
+- `code`: The actual code
+- `description`: What the code does (optional)
+- `timestamp`: Approximate time in seconds if mentioned (optional)
+
+**Example Output:**
+```json
+{
+  "codeSnippets": [
+    {
+      "language": "typescript",
+      "code": "if (user != null) {\n  validateToken(user.token);\n}",
+      "description": "Null check before token validation"
+    },
+    {
+      "language": "bash",
+      "code": "npm install --save @auth/sdk",
+      "description": "Install authentication SDK"
+    }
+  ]
+}
+```
+
+## Output Format
+
+Output ONLY valid JSON with the following structure. If a metadata type doesn't apply to this session, include it as an empty array.
+
+```json
+{
+  "speakers": [...],
+  "keyMoments": [...],
+  "actionItems": [...],
+  "technicalTerms": [...],
+  "codeSnippets": [...]
+}
+```
+
+## Input Data
+
+### Transcript Segments
+{{TRANSCRIPT_SEGMENTS}}