DaveCBeck/worth-sharing.md

## worth-sharing.md

      
    Raw
  

              worth-sharing.md
            
          
    name
    workflows:worth-sharing
  
  
    description
    Evaluate solutions/patterns for novelty and create shareable content (Gist + Quartz article)
  
  
    argument-hint
    [optional: solution doc path, pattern doc path, or 'latest']
  
  
/workflows:worth-sharing

Evaluate documented solutions/patterns for novelty and shareability. If innovative or contextually unique, generate shareable content in two formats: GitHub Gist (concise code) and Quartz markdown article (full write-up).
Purpose

After documenting a solution or pattern with /workflows:compound, this command evaluates whether it's worth sharing publicly. It searches for similar solutions online, determines novelty, and if worth sharing, creates:

GitHub Gist: Concise, self-documenting code snippets (key examples only)
Quartz Markdown: Full article for website publication

Why "worth-sharing"? Not every solution needs to be shared. This command filters for genuinely innovative approaches or solutions in unique contexts that would benefit the broader community.
Usage

/workflows:worth-sharing                    # Evaluate latest solution/pattern
/workflows:worth-sharing docs/solutions/...  # Evaluate specific doc
/workflows:worth-sharing latest             # Evaluate most recent
Workflow Phases

Agent Usage Summary

This command leverages existing agents for efficiency, running them in parallel where possible:
Phase 2 (Parallel Search) - Both run simultaneously:

best-practices-researcher(problem_statement, domain) - External best practices, web search, and GitHub code search
learnings-researcher(problem_statement, tags, module) - Internal docs/solutions/, docs/patterns/, and thala-dev content search

Phase 3 (Novelty Analysis):

pattern-recognition-specialist(code_examples) - Optional, identifies if pattern is novel

Phase 4 (Parallel Code Review) - All applicable agents run simultaneously:

Always:

code-simplicity-reviewer(code_snippets) - Ensures minimal, clean code
kieran-python-reviewer(code_snippets) - General-purpose Python code review (type hints, Pythonic patterns, maintainability)


Conditional (based on tags/frontmatter):

langgraph-workflow-reviewer(code_snippets) - If LangGraph-related
async-python-reviewer(code_snippets) - If async/concurrency
llm-interaction-specialist(code_snippets) - If LLM/prompts
data-integrity-guardian(code_snippets) - If stores/data
architecture-strategist(code_snippets) - If architecture-related


Phase 5b (Quartz Document):

thala-style-reviewer agent - Reviews and edits document for style guide compliance

Phase 1: Input Detection & Context Extraction

Input Sources (in priority order):

Explicit argument: File path to solution/pattern doc (docs/solutions/**/*.md or docs/patterns/**/*.md)
"latest" argument: Most recently created solution/pattern doc (by modification time)
Conversation context: If invoked after /workflows:compound, extract from recent conversation
Prompt user: If no clear input, ask which doc to evaluate

Context Extraction:
Read the solution/pattern document and extract all necessary information directly from the document itself:

Problem statement / Pattern intent (from document content)
Solution approach / Implementation details (from document content)
Code examples (all code blocks in the document)
Domain/context (LangGraph, async Python, stores, etc. - from frontmatter or content)
Innovation points (what makes this different? - inferred from content)

Note: All context comes from reading the document. No conversation history is required for post-hoc evaluation. The document should contain:

YAML frontmatter with metadata (problem_type, tags, etc.)
Problem statement section
Solution/implementation details
Code examples (if applicable)

Output: Structured context object with problem, solution, code, and domain info
Implementation:

Use read_file to read the document
Parse YAML frontmatter if present (extract tags, problem_type, module, date, etc.)
Extract date field from frontmatter - this will be used for the Quartz article
Extract code blocks (python, bash, etc.)
Identify domain keywords (LangGraph, async, Elasticsearch, etc.) from frontmatter tags or content
Extract problem statement from "Problem" or "Problem Statement" section
Extract solution from "Solution" or "Working Solution" section

Phase 2: Parallel Search for Similar Solutions

<parallel_execution>
1. best-practices-researcher (Parallel)

Launch best-practices-researcher agent with expanded scope to search for ALL external solutions:
Agent tasks:

Research external best practices and examples for the problem/domain
Web search using WebSearch tool for:

"[problem statement]" solution [domain]
"[approach/method]" implementation [technology]


GitHub Code Search using gh search code via Bash:

Problem keywords + language (Python)
Solution approach keywords
Technology stack keywords
Filter: Public repos, recent activity preferred
Rate limit: 10 requests/minute for code search


Returns:

List of external solutions found (web + GitHub)
URL/link for each
Similarity score (high/medium/low)
Key differences noted
"Easy to find" flag (yes/no)

2. learnings-researcher (Parallel)

Launch learnings-researcher agent with expanded scope to search ALL internal sources:
Agent tasks:

Search docs/solutions/ for similar issues by frontmatter metadata:

Filter by tags, category, module, symptoms
Search titles and content for keywords


Search docs/patterns/ for related patterns:

Similar code structures
Same components
Related techniques


Search .context/libs/thala-dev/content/ (if exists):

Similar problems/solutions in existing Quartz articles
Frontmatter tags and titles for relevance


Returns:

List of internal solutions/patterns found
File paths
Similarity score (high/medium/low)
Whether this problem is already documented internally

</parallel_execution>
Synthesize Search Results

Wait for both agents to complete, then consolidate findings:

 Collect results from both parallel agents
 Categorize by source: external (web/GitHub) / internal (docs/thala-dev)
 Extract URLs/links from each source
 Assess similarity score (high/medium/low) for each result
 Note key differences between found solutions and our approach
 Identify "easy to find" solutions (top 3-5 results, well-indexed)

Output: Consolidated list of similar solutions found with:

Source (external-web/external-github/internal-docs/internal-thala-dev)
URL/link or file path
Similarity score (high/medium/low)
Key differences noted
"Easy to find" flag (yes/no)

Phase 3: Novelty Analysis

Key Criteria: If there's an existing solution that's "easy to find" & high-quality, then STOP (do NOT proceed). Otherwise, consider further.
"Easy to Find" means:

Appears in top 10 search results
Clear title/description matches the problem or intended implementation

"High-Quality" means:

Recent (within last 2-3 years preferred)
Well-documented with code examples
Similar domain/technology stack
Actively maintained or from reputable source

Proceed Criteria (continue if ALL are true):

No easy-to-find, high-quality solution exists
OR solution exists but in significantly different context/domain
OR our approach is novel even if problem is common

Stop Criteria (do NOT proceed if):

Found 1+ easy-to-find, high-quality solution(s) in same domain
Our solution is essentially identical to existing ones
Problem or implementation is trivial/common using well-established patterns

Optional Agent: Task pattern-recognition-specialist(code_examples) - Can help identify if the pattern/approach is novel or already exists in common patterns
Step 3: Synthesize Novelty Analysis

After search results are synthesized and optional pattern analysis completes:

 Review all search results from Phase 2
 Identify "easy to find" solutions (top 3-5 results, well-indexed)
 Assess "high-quality" criteria for each found solution:

Recent (within last 2-3 years preferred)
Well-documented with code examples
Similar domain/technology stack
Actively maintained or from reputable source


 Compare our approach to found solutions
 Determine if our solution is essentially identical or has unique differentiators

Analysis Output:

Novelty verdict: worth_sharing | not_worth_sharing
Reasoning: Why it's worth sharing (or not), including what similar solutions were found
Key differentiators: What makes our approach unique (if proceeding)
Found solutions summary: List of easy-to-find, high-quality solutions (if any)

If not_worth_sharing: Display reasoning and stop. Do not proceed to Phase 4.
Phase 4: Deep Review (if worth sharing)

If novelty analysis determines it's worth sharing:
4a. Extract Code Snippets


Extract all relevant code snippets from source document
Identify the core solution pattern (key examples in context)
Prepare code snippets for agent review

4b. Parallel Code Review Agents

<parallel_execution>
Run code review agents IN PARALLEL based on domain detected from frontmatter/tags:
Always run:

Task code-simplicity-reviewer(code_snippets) - Ensures code is minimal and follows YAGNI principles
Task kieran-python-reviewer(code_snippets) - General-purpose Python code review with high quality bar (type hints, Pythonic patterns, maintainability)

Conditional agents (run if applicable based on tags/frontmatter):
If document contains LangGraph-related tags (langgraph, workflow, state, reducer):
3. Task langgraph-workflow-reviewer(code_snippets) - Check state management, reducer patterns, parallel execution
If document contains async/concurrency tags (async, concurrent, semaphore, rate_limit):
4. Task async-python-reviewer(code_snippets) - Check async/await patterns, rate limiting, concurrency
If document contains LLM/prompt tags (llm, prompt, structured_output, anthropic):
5. Task llm-interaction-specialist(code_snippets) - Review structured output schemas, prompt quality
If document contains store/data tags (elasticsearch, chroma, zotero, store, storage):
6. Task data-integrity-guardian(code_snippets) - Review store/data access patterns, error handling
If document contains architecture tags (architecture, design, pattern):
7. Task architecture-strategist(code_snippets) - Review architectural patterns and design
When to run conditional agents:

Check frontmatter tags array for matching keywords
Check problem_type field (e.g., langgraph_issue, async_issue, llm_issue)
Check component field (e.g., langgraph_node, llm_call, elasticsearch)

</parallel_execution>
4c. Synthesize Code Review Results

Wait for all code review agents to complete, then:

 Collect recommendations from all agents
 Apply code simplifications from code-simplicity-reviewer
 Apply general Python improvements from kieran-python-reviewer (type hints, Pythonic patterns, maintainability)
 Apply domain-specific recommendations (LangGraph, async, LLM, etc.)
 Refine code snippets based on agent feedback
 Ensure code is clean, well-commented, with docstrings
 Verify code examples are complete and runnable
 Focus on key examples - identify the core solution pattern for Gist

4d. Content Enhancement


Expand problem context
Explain why this solution is valuable
Add before/after comparisons if applicable
Include usage examples
Add links to related resources
If adding or preserving flow/process diagrams: use Mermaid, not ASCII art

Phase 5: Generate Shareable Content

5a. GitHub Gist Creation

Format: Concise, self-documenting code snippets with docstrings and comments
Key Principle: Include only the key examples that show how the solution works, not everything-that's-relevant. Keep it focused and minimal.
Structure:

1-3 files maximum (keep it concise)
Filenames: solution.py, example_usage.py (if needed)
Code should be self-documenting with docstrings
Focus on the core solution pattern, not all edge cases

Creation Method: Use GitHub CLI
# Create temporary files with code snippets
# Then create gist
gh gist create solution.py example_usage.py --desc "Brief description" --public

# Returns: https://gist.github.com/[username]/[gist_id]
Output: Gist URL
Error Handling: If gh CLI fails or not authenticated:

Save code snippets to temporary files
Provide manual creation instructions
Display gist content for copy-paste

5b. Quartz Markdown Document

Location: .context/libs/thala-dev/content/[filename].md
Format: Can be longer/more detailed than the Gist. Full article format.
Frontmatter (Quartz format):
---
title: "[Article Title]"
description: "[Brief description for link previews]"
date: YYYY-MM-DD  # Use the date from the SOURCE document's frontmatter
tags:
  - [relevant-tag-1]
  - [relevant-tag-2]
draft: false
---
Date Handling: Use the date field from the source document's frontmatter. If the source document has date: 2026-01-02, the Quartz article should also use date: 2026-01-02. Only fall back to today's date if the source document has no date field.
Content Structure:

Introduction: Problem statement and why it matters
Context: Domain/technology stack
The Solution: Detailed explanation with code examples
Why This Approach: What makes it innovative/different
Usage Examples: Practical examples
Related Resources: Links to docs, gist, etc.

Diagrams: If the document includes flow or process diagrams, use Mermaid rather than ASCII art. Quartz renders Mermaid; use a fenced code block with language mermaid for each diagram.
Filename: YYYY-MM-DD-[kebab-case-title].md (where YYYY-MM-DD matches the source document's date)
Style Review:
After writing the document, use the thala-style-reviewer agent to review and edit for style guide compliance:
Task thala-style-reviewer: Review and edit [file_path] for thala style guide compliance

The agent will:

Read the style guide from .claude/skills/thala-style-editor/references/THALA_WRITE_STYLE.md
Review the document systematically
Make direct edits to fix style issues
Return a summary of corrections made

Implementation:

Create directory if it doesn't exist: .context/libs/thala-dev/content/
Generate filename from title (kebab-case, date-prefixed)
Write markdown file with frontmatter and content
Task thala-style-reviewer agent to review and edit the content
Continue to Phase 6 after agent completes.

Phase 6: Post-Creation Actions

After creating both outputs:


Update Source Document:

Add cross-reference to gist and article in the original solution/pattern doc
Add frontmatter field: shared: true with gist_url and article_path
If frontmatter doesn't exist, add it


Display Summary:
✓ Worth-sharing evaluation complete

Novelty Analysis:
- [Reasoning for why it's worth sharing]
- Key differentiators: [list]

Created:
- GitHub Gist: [URL]
- Quartz Article: .context/libs/thala-dev/content/[filename].md

Similar solutions found: [count]


Done - Command completes after summary display.
Integration with Compound Command

Auto-invoke Option: After /workflows:compound completes successfully, offer:
✓ Solution documented

Would you like to evaluate this for sharing?
1. Yes, check if worth sharing
2. Skip

Manual Invocation:
/workflows:worth-sharing                    # Evaluate latest solution/pattern
/workflows:worth-sharing docs/solutions/...  # Evaluate specific doc
/workflows:worth-sharing latest             # Evaluate most recent
Technical Implementation Details

GitHub API Usage

Search Code Endpoint:
# Pseudo-code
async def search_github_code(query: str) -> list[dict]:
    url = "https://api.github.com/search/code"
    params = {
        "q": f"{query} language:python",
        "sort": "updated",
        "order": "desc"
    }
    # Handle rate limiting (10 req/min for code search)
    # Parse results, extract repo/file info
Alternative: Use gh search code CLI command if available.
GitHub CLI Gist Creation

# Create gist with multiple files
gh gist create file1.py file2.py --desc "Description" --public

# Returns: https://gist.github.com/[username]/[gist_id]
Check authentication: gh auth status before attempting gist creation.
Web Search Integration

Use existing tools:

web_search tool for general web search
Perplexity via langchain_tools.perplexity if available

Finding Latest Document

# Find most recently modified solution/pattern doc
find docs/solutions docs/patterns -name "*.md" -type f -printf '%T@ %p\n' | sort -n | tail -1
Error Handling


No input found: Prompt user for doc path, list available docs
Document not found: List available docs, let user choose
Search failures: Continue with partial results, note limitations in analysis
Gist creation failure: Save content locally, provide manual creation instructions
Quartz path missing: Create directory structure (.context/libs/thala-dev/content/)
GitHub CLI not authenticated: Provide manual gist creation instructions
No similar solutions found: Proceed with novelty analysis (may indicate worth sharing)

Success Criteria

Command succeeds when:

✅ Novelty analysis completed
✅ If worth sharing: Both Gist and Quartz doc created
✅ Source document updated with cross-references
✅ Summary displayed

Related Commands


/workflows:compound - Creates the source documentation
/workflows:review - May identify interesting patterns worth sharing
/workflows:plan - May reference shared solutions

Future Enhancements


Semantic similarity detection using embeddings
Automatic tagging based on content analysis
Social media post generation
Analytics tracking for shared content
name	workflows:worth-sharing
description	Evaluate solutions/patterns for novelty and create shareable content (Gist + Quartz article)
argument-hint	[optional: solution doc path, pattern doc path, or 'latest']
No results found