Sharing Solutions

Every solution you share makes the knowledge network better for every developer who comes after you. This guide covers the mechanics of sharing and best practices for writing solutions that are useful to others.

Why sharing matters

When you solve a problem — especially one that took real debugging effort — the solution typically lives in your codebase and nowhere else. Sharing it through Spark takes about 30 seconds and creates lasting value:

• Developers hitting the same error find your fix immediately instead of debugging for 30 minutes.
• AI agents across the ecosystem can recommend your solution, multiplying its reach.
• Community validation and refinement make the solution better over time.

The public knowledge network is a commons. It works because developers contribute back.

Sharing a solution from a session

After querying Spark and solving your problem, share the solution using the session ID from your original query:

spark share <session-id> \
  --title "Brief descriptive title" \
  --content "Detailed explanation of the solution" \
  --tag language:python:3.12 \
  --tag framework:django:5

Required fields

• <session-id> — The session ID from your spark query output (e.g., abc123).
• --title — A short, descriptive title. Think of it as a commit message for the solution.
• --content — The full explanation. Include the problem, the fix, and any context that would help someone else.

Optional fields

• --tag — One or more semantic tags. See Using Semantic Tags for the full guide.
• --task-index — Link your share to a specific recommendation from the session (e.g., --task-index 0 links to the first recommendation).

Quick sharing with share-task

If you want to share a solution without starting from a query session, use share-task:

spark share-task "ESM migration error in Node 20" \
  --insight "Add 'type': 'module' to package.json and use .js extensions in all relative imports. Don't forget test files and build scripts." \
  --tag language:node:20 \
  --tag task_type:bug_fix

This creates a standalone solution in the network without needing a prior session ID. It's useful when:

• You solved a problem outside of Spark and want to share the knowledge
• You found a solution in documentation and want to make it discoverable
• You want to share a general best practice or pattern

Linking to specific tasks

If your query returned multiple recommendations and your solution builds on one of them, link them together with --task-index:

spark share abc123 \
  --title "Improved ESM migration guide with __dirname fix" \
  --content "Building on the existing recommendation, also need to handle __dirname..." \
  --task-index 0 \
  --tag language:node:20

This tells the recommendation engine that your solution is related to (and potentially improves upon) recommendation 0 from session abc123.

What gets shared vs. what stays private

Shared with the network:

• The title you provide
• The content/explanation you write
• Semantic tags you add
• Your anonymous contributor ID (no personal information)
• Timestamp

NEVER shared:

• Your source code
• File paths from your project
• Environment variables or credentials
• API keys or secrets
• Any content from your local files

You have full control over what goes into the --title and --content fields. Spark shares only what you explicitly write in those fields.

Best practices for sharing

Be descriptive in your title

# Good — specific and searchable
--title "Fix ERR_MODULE_NOT_FOUND when migrating Express app to ESM"
 
# Bad — too vague
--title "ESM fix"

Include the error message in your content

If you solved a bug, include the exact error text. This is what other developers will be searching for.

--content "Error: Cannot find module './utils'
 
This happens when migrating to ESM because Node.js requires file extensions
in relative imports. Change: import { x } from './utils' to
import { x } from './utils.js'
 
Also add \"type\": \"module\" to package.json."

Explain the why, not just the what

Don't just say what to change — explain why it works. This helps developers adapt the solution to their specific situation.

# Good
--content "Node.js ESM resolution does not perform automatic extension resolution
like CommonJS. You must include .js in imports because the ESM spec requires
explicit file extensions for relative paths."
 
# Less helpful
--content "Add .js to your imports."

Add relevant tags

Tags make your solution discoverable. Include at minimum:

• The language and version
• The framework if applicable
• The task type (bug_fix, migration, integration, etc.)

--tag language:node:20 \
--tag framework:express:5 \
--tag task_type:migration \
--tag error_type:ERR_MODULE_NOT_FOUND

Next steps

• Using Semantic Tags — full guide to the tag system
• Best Practices — tips for getting the best results from Spark