diff --git a/SKILL.md b/SKILL.md index 8d41c8a..a8e9d11 100644 --- a/SKILL.md +++ b/SKILL.md @@ -123,6 +123,8 @@ If `--agent` appears in ARGUMENTS (e.g., `/last30days plaud granola --agent`): 5. **Skip** the follow-up invitation ("I'm now an expert on X...") 6. **Output** the complete research report and stop - do not wait for further input +Agent mode still saves the research briefing to `~/Documents/Last30Days/` using the same logic as interactive mode (see "Save Research to Documents" section). + Agent mode report format: ``` @@ -496,6 +498,51 @@ For `/last30days war in Iran` (NEWS): --- +## Save Research to Documents + +After displaying the invitation, save the complete research briefing to the user's Documents folder. This happens automatically on every run. + +1. **Create the directory** (if it doesn't exist): + ```bash + mkdir -p ~/Documents/Last30Days + ``` + +2. **Generate the filename** from TOPIC: + - Lowercase the topic + - Replace spaces and special characters with hyphens + - Remove consecutive hyphens + - Trim to 60 characters max + - Example: "Claude Code Best Practices" -> `claude-code-best-practices` + +3. **Check for duplicates**: If `~/Documents/Last30Days/{slug}.md` already exists, append today's date: `{slug}-YYYY-MM-DD.md` + +4. **Use the Write tool** to save to `~/Documents/Last30Days/{slug}.md` with this exact structure: + +```markdown +# {TOPIC} + +> Researched {date} | Query type: {QUERY_TYPE} | Target tool: {TARGET_TOOL or "general"} + +## What I learned + +{The full synthesis section you just displayed - all topics, patterns, and citations} + +## Stats + +{The full stats box with source counts and engagement - copy exactly as displayed} + +## Follow-up suggestions + +{The 2-3 specific suggestions from the invitation block} + +--- +*Generated by [last30days](https://github.com/mvanhorn/last30days-skill) v2.9* +``` + +5. **Confirm briefly** after saving: `Saved to ~/Documents/Last30Days/{slug}.md` + +--- + ## WAIT FOR USER'S RESPONSE After showing the stats summary with your invitation, **STOP and wait** for the user to respond. @@ -607,6 +654,7 @@ Want another prompt? Just tell me what you're creating next. - Optionally sends search queries to Brave Search API, Parallel AI API, or OpenRouter API for web search - Fetches public Reddit thread data from `reddit.com` for engagement metrics - Stores research findings in local SQLite database (watchlist mode only) +- Saves research briefings as .md files to ~/Documents/Last30Days/ **What this skill does NOT do:** - Does not post, like, or modify content on any platform diff --git a/docs/plans/2026-03-05-feat-auto-save-results-to-documents-plan.md b/docs/plans/2026-03-05-feat-auto-save-results-to-documents-plan.md new file mode 100644 index 0000000..8800f01 --- /dev/null +++ b/docs/plans/2026-03-05-feat-auto-save-results-to-documents-plan.md @@ -0,0 +1,152 @@ +--- +title: "feat: Auto-save research results to ~/Documents/Last30Days/" +type: feat +status: completed +date: 2026-03-05 +--- + +# feat: Auto-save research results to ~/Documents/Last30Days/ + +## Overview + +Every time the last30days skill completes a research run, automatically save the full briefing - inquiry, synthesis, stats, and follow-up suggestions - as a topic-named `.md` file in `~/Documents/Last30Days/`. Inspired by how users like @devin_explores are already manually saving results to build a personal research library (see screenshot - 17 topic files in a `Last30Days` Finder folder, each 9-34 KB). + +## Problem Statement / Motivation + +The skill's most valuable output - the assistant's synthesized "What I learned" briefing with stats and citations - only exists in the conversation. Once the session ends, it's gone. Users like @devin_explores work around this by manually copying output into .md files. Meanwhile, the Python script already writes raw data to `~/.local/share/last30days/out/`, but: + +1. It overwrites on every run (no history) +2. It only contains pre-synthesis data (scored items), not the assistant's expert briefing +3. It's in a hidden dot-directory users don't naturally browse + +The feature makes saving automatic and puts files where users expect them - the Documents folder, visible in Finder/file explorer. + +## Proposed Solution + +Add a **Write tool step in SKILL.md** after the synthesis/stats/invitation block that saves the complete briefing to `~/Documents/Last30Days/{topic-slug}.md`. This is a SKILL.md-only change (no Python script modifications needed) because the content to save is the assistant's synthesized output, which only exists in the SKILL.md flow. + +### Why SKILL.md, not the Python script + +The Python script (`last30days.py`) runs first and produces raw scored items. The assistant then synthesizes these into the "What I learned" briefing, stats block, and invitation. The synthesis is the valuable part - it's what @devin_explores is saving. The script can't produce this because it runs before synthesis happens. + +### File naming + +Convert the TOPIC variable to a kebab-case slug for the filename: +- "Claude Code best practices" -> `claude-code-best-practices.md` +- "best rap songs 2026" -> `best-rap-songs-2026.md` +- "nano banana 2 prompting guide" -> `nano-banana-2-prompting-guide.md` + +This matches the screenshot pattern exactly (e.g., `anthropic-claude-code-best-practices.md`, `seedance-video-prompting-guide.md`). + +If a file with the same slug already exists, append a date suffix: `claude-code-best-practices-2026-03-05.md`. This handles re-researching the same topic without overwriting previous results. + +### File content + +The saved .md file should contain the complete research output in this order: + +```markdown +# {TOPIC} + +> Researched {date} | Query type: {QUERY_TYPE} | Target tool: {TARGET_TOOL or "general"} + +## What I learned + +{The full synthesis section - topics, patterns, citations} + +## Stats + +{The full stats box with source counts and engagement} + +## Follow-up suggestions + +{The 2-3 specific suggestions from the invitation block} + +--- +*Generated by [last30days](https://github.com/mvanhorn/last30days-skill) v2.9* +``` + +### Implementation location in SKILL.md + +Insert a new section between the current "LAST - Invitation" display and the "WAIT FOR USER'S RESPONSE" section. The Write tool call happens silently - no user prompt, no opt-in. Just save and briefly confirm. + +## Technical Considerations + +- **Cross-platform paths**: `~/Documents/` exists on macOS and most Linux desktops. On systems where it doesn't exist, `mkdir -p` handles creation. Windows WSL users get it too. +- **Permissions**: The Write tool in Claude Code can write to `~/Documents/` without issues. No sandbox concerns since this is the user's own Documents folder. +- **Filename sanitization**: Strip special characters, collapse whitespace to hyphens, lowercase. Keep it simple - no need for a library, just basic string ops in the SKILL.md instructions. +- **File size**: Based on the screenshot (9-34 KB files), the synthesis output is well within reasonable bounds. +- **No opt-out flag needed initially**: This is the default behavior. If users complain, a `--no-save` flag can be added later. Start with always-on since the screenshot proves users want this. + +## Acceptance Criteria + +- [x] Running `/last30days {topic}` creates `~/Documents/Last30Days/{topic-slug}.md` automatically +- [x] File contains: title, date, query metadata, full synthesis, stats block, follow-up suggestions +- [x] Filename is kebab-case slug of the topic (e.g., `claude-code-skills-guide.md`) +- [x] Duplicate topics get a date suffix instead of overwriting +- [x] Directory `~/Documents/Last30Days/` is created automatically if it doesn't exist +- [x] A brief confirmation line appears after the stats (e.g., "Saved to ~/Documents/Last30Days/claude-code-skills-guide.md") +- [x] Agent mode (`--agent`) also saves the file +- [x] No changes to the Python script - this is purely a SKILL.md addition + +## Implementation Steps + +### Step 1: Add save instructions to SKILL.md + +Insert a new section after the invitation block (after line ~496, before "WAIT FOR USER'S RESPONSE" at line ~499): + +**New section in `SKILL.md`:** + +```markdown +## Save Research to Documents + +After displaying the invitation, save the complete research briefing: + +1. Generate the filename from TOPIC: + - Lowercase the topic + - Replace spaces and special characters with hyphens + - Remove consecutive hyphens + - Trim to 60 characters max + - Example: "Claude Code Best Practices" -> "claude-code-best-practices" + +2. Check if file already exists. If so, append today's date: + - "claude-code-best-practices.md" exists -> use "claude-code-best-practices-2026-03-05.md" + +3. Use the Write tool to save to ~/Documents/Last30Days/{slug}.md with this content: + - H1 title: the TOPIC + - Metadata line: date, QUERY_TYPE, TARGET_TOOL + - Full "What I learned" synthesis (everything you just displayed) + - Full stats block + - Follow-up suggestions from the invitation + - Footer with skill attribution + +4. Confirm briefly: "Saved to ~/Documents/Last30Days/{slug}.md" +``` + +### Step 2: Update agent mode section + +The `--agent` mode section (line ~116) skips interactive elements but should still save. Add a note that agent mode saves the file with the same logic. + +### Step 3: Update Security & Permissions section + +Add to the "What this skill does" list (line ~599): +- "Saves research briefings as .md files to ~/Documents/Last30Days/" + +## Success Metrics + +- Users accumulate a browsable library of .md research files in their Documents folder +- No more manual copy-paste workflow to save results +- Files are immediately findable in Finder/file explorer search + +## Dependencies & Risks + +- **Low risk**: Write tool is already in the skill's `allowed-tools` list +- **Low risk**: ~/Documents/ is a standard, user-owned directory +- **Edge case**: If the skill is interrupted mid-run (before synthesis), no file is saved - this is correct behavior since there's nothing to save yet +- **Edge case**: Very long topics could produce unwieldy filenames - the 60-char truncation handles this + +## Sources & References + +- Screenshot from @devin_explores showing manual .md file library in ~/Documents/Last30Days/ +- Current output pipeline: `scripts/lib/render.py:798` (`write_outputs()`) writes to `~/.local/share/last30days/out/` +- SKILL.md synthesis flow: lines 275-496 (internalize research -> show summary -> invitation) +- Existing `--emit` modes: `scripts/last30days.py:1700` (`output_result()`)