Build-Evidence-Map

# Build Evidence Map

Turn one contested question into a portable decision artifact that shows what

supports the current position, what pushes against it, and what remains unknown.

Do not use a graph to decorate an answer that has not been sourced.

For a simple factual claim or a general fact-checking request, use a verification

workflow such as `doublecheck` instead. Use this skill when the relationships

between evidence, intermediate claims, trade-offs, and missing facts matter.

Workflow

1. **Frame one decision.** Write one falsifiable question and one provisional

position. Narrow the question until a reader can identify what action or

belief the map is testing.

2. **Collect bounded source regions.** Prefer direct observations and primary

sources. Record the URL or absolute local path, publisher, publication date,

retrieval date, section/page/line/timestamp locator, and a short checkable

excerpt. Read [references/evidence-ladder.md](references/evidence-ladder.md)

when source quality is disputed.

3. **Atomize the reasoning.** Create only four node types:

- `position`: the single current verdict;

- `claim`: an intermediate proposition;

- `evidence`: a faithful statement of one source region;

- `unknown`: a specific missing fact that could change the verdict.

4. **Type every edge.** Use `supports`, `contradicts`, `qualifies`, or

`missing`. Add a plain-language note explaining why the source node bears on

the target. Topical similarity is not support. Different scope, date, or

population is not automatically a contradiction.

5. **Preserve counterevidence.** Do not delete contrary evidence because the

provisional verdict survives it. Represent scope differences with

`qualifies` edges.

6. **Express uncertainty structurally.** Do not invent confidence percentages.

Add an `unknown`, narrow the position, or qualify a claim.

7. **Write UTF-8 JSON** with a `.doubt.json` suffix. Follow

[references/map-schema.md](references/map-schema.md). Keep IDs short,

stable, and semantic.

8. **Validate fail-closed.** Resolve

`scripts/validate.mjs` relative to this `SKILL.md`, then run it with Node.js

18 or newer:

```bash

node <skill-directory>/scripts/validate.mjs decision.doubt.json

```

The bundled validator uses only Node.js built-ins and does not require npm or

network access. Fix every finding before reporting success. Only say the map

is valid when the command exits `0` and prints `VALID` followed by a

64-character receipt. A file hash, node count, JSON parse, or manual schema

review is not a Doubt receipt. If deterministic validation cannot run, report

that block instead of inventing success.

Render the validated map only when the user has already installed

`doubt-ai@0.8.0`; do not install or execute a remote package implicitly:

```bash

doubt map decision.doubt.json --out decision.html

```

9. **Verify source snapshots only with explicit network permission.** The

following command retrieves each recorded HTTP(S) source and fails closed if

an excerpt cannot be matched:

```bash

doubt verify decision.doubt.json \

--out decision.verified.doubt.json

```

Never run this command implicitly. Local file verification does not use the

network. Do not write a `verification` object by hand or hide a mismatch.

10. **Inspect the deliverable.** Confirm that the question, verdict,

counterevidence, unknowns, edge notes, and exact source regions remain

readable. Treat JSON as the canonical editable artifact; HTML is a

shareable view.

Quality gates

A finished map must satisfy all of these:

- exactly one `position` has incoming reasoning;

- every evidence node names one source and participates in an edge;

- every source is used and has dates, a bounded locator, and a substantive

excerpt;

- every non-position node has a directed path to the position;

- the reasoning graph has no duplicate edges or directed cyc