Scope technical experiments

Defines a small time-bounded experiment when an important decision depends on a genuinely unknown technical fact.

technical-spike-scoping

See how it helps

When is it useful?

Use when code and documentation cannot resolve an assumption whose failure would cause costly rework.

What does it help you do?

States one falsifiable question and the smallest necessary prototype.
Sets decision thresholds before running measurements.
Records the result and a clear disposition for prototype code.

Try asking this

Scope an experiment comparing local search latency at our expected document volume, with thresholds that decide whether another index is needed. Run representative queries at the expected volume within the timebox. Keep or reject the alternative using the predefined threshold, and record what happens to prototype code.

Detailed documentation

Read the skill’s original instructions, examples and checks in their authored language.

Details…Show less

Technical Spike Scoping

Use this skill when a design decision is blocked by genuine technical uncertainty (e.g., third-party API behavior, library compatibility, or a performance hypothesis) so the team runs a fast, bounded experiment instead of debating in the abstract or over-building on assumptions.

When to Propose a Spike

Propose a spike when: An important architectural or scope choice depends on an unknown fact that cannot be answered by reading existing code or documentation in 15 minutes, and guessing wrong would cause a costly rework.
Do NOT propose a spike when: The behavior is already known in the codebase, or the decision is a reversible two-way door where building the simple version directly is faster than running a separate experiment.

Spike Design Contract

Every technical spike must define four elements upfront:

Single falsifiable question:
- State the exact question the spike must answer (e.g., "Can SQLite FTS5 index and query 200k project documents under 30 ms p95 on a local disk without an external search server?").
Strict boundary and minimal setup:
- Specify the smallest script, test, or isolated prototype needed to answer the question.
- Do not build production UI, full CRUD layers, or polished abstractions inside a spike.
Pass / Fail decision threshold:
- Define before running the spike what measurement or result selects Path A (Simple) vs. Path B (Alternative):
  - If p95 < 30 ms and index size < 250 MB -> use built-in SQLite FTS5.
  - If p95 >= 30 ms -> evaluate dedicated search index.
Cleanup & disposition rule:
- Record the measured finding in the work item or decision note, delete throwaway prototype code (or extract only the verified core with proper tests), and immediately proceed with the chosen path.

Anti-Patterns to Avoid

Open-ended "research tasks" with no exit criteria: Spikes without a concrete question and pass/fail threshold turn into multi-day wandering.
Merging unverified spike hacks directly into production: A spike proves feasibility; production commits still require clean boundaries, error handling, and tests.
Running a spike to delay a straightforward decision: Never use a spike as a polite way to avoid cutting unnecessary scope.

Included files 1

SKILL.md