| name | target-evidence-designer |
| description | Use when adapting ShapeShift Labs Evidence Kit to a specific JS/TS project by deriving target-owned source lists, correctness contracts, corpus cases, fuzz generators, benchmark fixtures, source-pass plans, or evidence acceptance criteria from that project's own code, docs, tests, issues, or fetched sources. |
Target Evidence Designer
Use this skill after the generic evidence harness exists. The goal is to replace placeholders with evidence derived from the target project itself.
Workflow
- Inspect the repo contract:
npx evidence-kit inspect --json
npm run docs:perf:search -- contract benchmark fuzz source
npm run research:list
Read public exports, README/API docs, existing tests, issue/regression fixtures, benchmark scripts, and package boundaries. Do not invent a contract that source or docs do not support.
- Write a short target evidence map:
- public surfaces that users import or execute,
- behaviors the project documentation promises,
- existing tests that already encode contracts,
- known failures or unsupported cases,
- performance claims that maintainers actually care about,
- external sources worth fetching.
- Create a target-owned evidence plan with five concrete outputs:
research/<topic>-sources.json: primary sources to fetch.research/<topic>-sources.md: what was inspected and transferred.- corpus file: seed cases and known failures.
test/fuzz/*: generated cases plus a stable oracle derived from the target contract.benchmarks/*: fixtures tied to specific target performance claims.
- Add or update a repeatable fetcher:
npx evidence-kit add-source-fetcher --name <topic>
npm run research:fetch -- <topic>
Use git, url, npm, file, or inline source entries. Record URL, commit/hash, local path, and why each source exists.
- Convert target contracts into executable checks before writing random generators. Each check must name:
- the source of truth for the contract,
- the generated or corpus input shape,
- the expected observation,
- the failure artifact to write on mismatch.
- Promote corpus seeds deliberately from target evidence:
- documented behavior,
- existing tests,
- fetched source material,
- user-reported failures,
- reduced fuzz failures.
-
Design benchmark fixtures from claims the project will make. Each benchmark row needs a category, fixture, metric, status, and output path under benchmarks/results/*latest.json. Keep bad-result, unsupported, timeout, and over-budget rows visible.
-
Run focused verification:
npm run test:evidence
npm run fuzz
npm run bench:evidence
npm run bench:startup:check
npm run bench:package:gates
npm run docs:perf
npm run docs:perf:search -- <topic>
Rules
- Do not stop at a prose plan when a small executable fixture can be added.
- Do not use external source names as local benchmark names unless the benchmark actually measures that source.
- Do not add runtime dependencies from source mining without benchmark and boundary evidence.
- Keep generated corpora small, readable, and replayable; cache large source material under ignored paths.
- Record rejected ideas with reasons, not silence.
