technical-spike ยท diff
git:20260717.dc9a72d to git:20260718.f44cf0d
11 added, 20 removed. Audit A to A.
---
name: technical-spike
- description: Run a bounded technical investigation when implementation or validation depends on unknown, unfamiliar, or version-sensitive framework, library, tool, runtime, protocol, or platform behavior. Produce only conclusions that affect the current task.
+ description: Resolve one correctness-blocking external or version-specific technical uncertainty through bounded investigation. Use when cheap local inspection cannot establish framework, library, tool, runtime, protocol, or platform behavior needed by the current task.
---
# Technical Spike
- Resolve one implementation-blocking technical question without drifting into broad research.
+ Own extended technical investigation while the calling workflow retains its planning, implementation, or validation decision.
## Workflow
- 1. State the exact technical question.
- 2. Check local evidence first: manifests, lockfiles, configuration, code, tests, installed versions, and command help.
- 3. If local evidence is insufficient, consult current official documentation for the specific tool or library.
- 4. Record only conclusions that affect implementation or validation.
- 5. Convert the findings into concrete design, compatibility, or verification implications.
- 6. Stop when the current task has a safe path forward.
-
- ## Result Shape
+ 1. State the exact question, applicable versions, decision it blocks, and stopping condition.
+ 2. Check local manifests, lockfiles, configuration, code, tests, installed versions, and command help first.
+ 3. When local evidence is insufficient, use the most authoritative relevant primary source: official documentation, specifications, upstream source, release notes, or a bounded reproduction.
+ 4. Require explicit authority before network access, dependency changes, repository edits, external writes, or experiments with side effects. Keep temporary reproductions outside the repository unless the task authorizes a durable test.
+ 5. Separate observed facts from inference and record only conclusions that affect the current task.
+ 6. Translate evidence into concrete design, compatibility, implementation, or verification implications.
- ```md
- ## Technical Spike Result
+ Report the question, applicable versions, local and external source references, observed facts, inference, conclusion, task impact, remaining uncertainty, and stopping decision.
- Question: ...
- Local evidence: ...
- External evidence, if used: ...
- Conclusion: ...
- Impact: ...
- Remaining uncertainty: ...
- ```
+ Do not research adjacent features, upgrade dependencies, add abstractions to hide uncertainty, or present unresolved behavior as confirmed. Return unresolved uncertainty as a blocker or explicit risk.
- Do not research adjacent features, upgrade dependencies without authorization, add abstractions to hide uncertainty, or use unofficial sources when authoritative documentation is available.
+ Finish when the current task has a supported path forward or further evidence requires new authority or unavailable state.