Source and version
- Repository path
.agents/skills/evidence-grounded-research-spike/SKILL.md- Source revision
341bceb719a28be760775b6322021d78abaa919b- Source SHA-256
844fc0c6b0b956b81984a2c2d47d9252abadeb0a6554c5ef4734d0f1e5f4b531- Publication standing
- Public ready
Included source files
This skill has no additional files in its public source package.
Complete skill source
The Markdown below matches the exact source text. The format link above opens the file on its own.
---
name: evidence-grounded-research-spike
description: Converts current expert writing, official documentation, standards, and practiced experience into a bounded repository decision. Applies when contemporary evidence should change a plan, instruction, architecture boundary, or collaboration method.
---
# Evidence-grounded research spike
## Contract
- **What:** A decision-oriented synthesis with direct evidence routes, claim classes, transfer limits, and instruction delta.
- **When:** A technical or collaboration decision depends on contemporary external evidence.
- **Boundaries:** Primary and official sources ground factual technical claims. External workspaces supply research input while the repository retains durable operating guidance.
- **Result:** Supported or bounded decision, remaining uncertainty, and a clear receiving surface.
## Rules
### Rule: The receiving decision leads
The spike begins with the decision, repository surface, claims requiring current evidence, and stopping condition.
### Rule: Evidence retains source class
The working hierarchy is:
1. primary research, standards, and specifications;
2. official product or platform documentation;
3. replicated practitioner guidance with concrete artifacts;
4. named field observations and lived experience;
5. secondary synthesis for discovery and vocabulary.
Material claims remain classified as verified fact, supported inference, practitioner observation, or open hypothesis. System, version or date, task conditions, limitations, and transfer boundary accompany applicability-sensitive findings.
Within a decision, evidence can **support**, **qualify**, **challenge**, or **bound** a claim. Citation count and derivative restatement remain separate from independent support.
### Rule: Mechanism crosses a design bridge
A mechanistic or descriptive finding becomes repository guidance only after the spike names the receiving goal, material design consequence, relevant boundary, and observable effect. Source authority and local instruction authority remain distinct.
### Rule: Findings change the receiving work
Each retained finding changes an instruction, source boundary, implementation route, observation, loop exit, recovery move, or purposeful deferral.
### Rule: Useful uncertainty remains reachable
An unknown or disagreement receives enough research to establish its utility and consequence. Generative uncertainty can remain open; harmful or coordination-blocking uncertainty receives the smallest evidence move that supports a responsible route.
## Operating sequence
1. **Frame:** The spike states the decision, receiving surface, evidence-sensitive claims, and stopping condition.
2. **Retrieve:** Primary, official, replicated practitioner, and named field evidence enter in descending authority.
3. **Classify:** Each material claim receives a claim class, evidence relation, and transfer boundary.
4. **Challenge:** One counterexample, disconfirming condition, or transfer limit tests the selected route.
5. **Precipitate:** The result carries a synthesis, evidence map, research-to-design bridge, instruction delta, remaining uncertainty, and direct citations.
6. **Stop:** Retrieval ends when additional examples cease to change the next move.
## Representative scenarios
### Scenario: Contemporary practice extends an official convention
- Given official documentation establishes metadata routing and progressive disclosure
- And named practitioner work demonstrates a useful scenario-based authoring pattern
- When repository guidance is formed
- Then official behavior remains a verified fact
- And the practitioner pattern remains a scoped observation
- And local use determines transfer into a standing instruction
### Scenario: External workspace context is unavailable later
- Given a Notion payload supplies useful research and vocabulary
- When the repository decision settles
- Then direct source routes remain in the evidence map
- And the durable instruction is carried in repository source
- And runtime collaboration remains independent of Notion availability
## Completion
The spike completes when the decision is supported or bounded, important transfer limits remain visible, and further reading would add examples without changing the next move.