Generating spikes

Generating a spike is the core of SpikeMe. You provide a project manifest, a topic (a real technical decision), how many options to compare, the language of the document, and the depth. SpikeMe collects live facts about the candidate packages and writes a full decision document you can read, download, and share.

Choosing a topic

A spike answers exactly one technical decision, so a good topic is concrete and comparative, not a broad theme. Think "state management library", "asyncpg vs psycopg", or "which end-to-end testing tool". The narrower the topic, the sharper the recommendation.

You do not have to invent topics from scratch. When SpikeMe analyzes your manifest it categorizes your dependencies and detects gaps (categories your stack has no package for), and it turns those gaps into suggested topics. Pick one of those, or type your own.

Along with the topic you set:

• Options to compare: how many candidates SpikeMe should analyze side by side (for example, two or three libraries).
• Language: the language the document is written in.
• Depth: quick or full, described below.

Depth: quick vs full

Depth controls which model writes the document and how detailed it is. It is the main lever on cost and time.

quick

quick uses a cheaper, faster model and produces a concise document (about 600-900 words). It keeps snippets minimal and stays focused on the comparison and the recommendation. Use it to triage a decision fast or when the choice is low-stakes.

full

full uses the strongest model and produces a detailed document (about 1500-2200 words), with realistic code snippets for each option and a detailed proof-of-concept plan. Use it for decisions you will actually commit to and want to defend later.

Options and language

The number of options sets how many candidates land in the comparison table and get their own subsection. Two or three is the sweet spot: enough to see a real trade-off, few enough that the document stays decisive.

The language setting controls the prose (headings, analysis, recommendation). Code snippets and package names stay as they are.

The evidence engine

This is what separates a SpikeMe document from a plain chat answer. Before writing, SpikeMe collects live facts for the candidate packages and injects a dated facts block into the prompt, so the document cites real numbers and names the source and date instead of guessing from stale training data.

Sources depend on the ecosystem:

• npm: the npm registry (version, license), npm downloads (weekly downloads), and bundlephobia (gzipped bundle size).
• Python: PyPI (version, license) and pypistats (weekly downloads).
• Go: deps.dev (version, license). Go has no public weekly-download count, so those numbers are omitted — as expected.

The injected block looks roughly like this:

<facts date="2026-07-14">
zustand: v5.0.2, MIT, 4.8M downloads/week, 1.1 kB gzipped (npm registry, npm downloads, bundlephobia)
jotai:   v2.10.3, MIT, 1.6M downloads/week, 3.4 kB gzipped (npm registry, npm downloads, bundlephobia)
</facts>

Collection is best-effort: if a fact cannot be gathered in time, generation still proceeds without it and never blocks. This determinism and freshness is the product's differentiator: the same topic produces a document anchored in today's real numbers, not a model's recollection.

What's in the document

Every generated spike follows the same structure, so decisions are easy to compare across your team:

• A title and context paragraph citing the project and its stack.
• ## Objective and decision criteria: measurable bullets you will judge the options against.
• ## Options analyzed: one subsection per option, with pros and cons and a short, real code snippet.
• ## Comparison: a table scoring the options by criteria.
• ## Recommendation: the choice, why it wins, and when to reconsider it.
• ## Proof-of-concept plan: numbered, timeboxed steps plus the exact install command for your project's package manager.
• ## Risks and mitigation: what could go wrong and how to contain it.
• ## Spike acceptance criteria: a checklist to know when the spike is done.

Exporting and sharing

Once the document streams in, you can:

• Read it live as it is written.
• Download it as a .md file.
• Export as ADR in MADR format, to drop straight into your architecture decision records.
• Keep it in My spikes: every document is saved to your account.
• Share a public link at /s/<slug>, complete with a generated preview image.
• Export a Team kit: a shareable onboarding kit that packages the decision for the rest of the team.

Where to generate

You can generate a spike from three places, all backed by the same engine:

• Web wizard at spikeme.io/app: upload a manifest, pick a topic and depth, read and share the result.
• CLI with spikeme gen: generate from the terminal, where your code already lives. See CLI.
• MCP server: expose generation to your coding agent (Claude Code, Cursor), so the agent produces the artifact directly. See MCP.