Build Evidence Map

GitHubOfficialFirst committed by alsoleg89Distributed by GitHub

Skill
Workflow
Agent tooling
MIT
Low risk
Has scripts

From the author

Build an auditable evidence map for a contested technical choice, research synthesis, proposal review, or consequential decision. Use when Copilot must preserve supporting, contradicting, qualifying, and missing evidence with exact source regions instead of collapsing disagreement into prose.

— the description by alsoleg89

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured workflow for building an evidence map to support complex decision-making. Instead of prose, it uses a graph-based approach to link positions, claims, evidence, and unknowns. It emphasizes traceability by requiring exact source regions, explicit edge types, and deterministic validation to ensure the integrity of the reasoning graph.

What it does

Frames a single falsifiable question and a provisional position.
Atomizes reasoning into position, claim, evidence, and unknown nodes.
Defines relationships between nodes using supports, contradicts, qualifies, or missing edges.
Validates the structural integrity of the reasoning graph.
Verifies source snapshots against recorded excerpts.
Produces a portable JSON artifact representing the decision map.

When to use it

When a technical choice or proposal is contested.
When you need to preserve counterevidence rather than collapsing it into prose.
When the relationship between evidence, trade-offs, and missing facts is critical.
When you need to maintain an auditable trail for a consequential decision.

Advantages

Prevents the loss of nuance by explicitly representing contrary evidence.
Ensures traceability through bounded source regions and explicit locators.
Provides a deterministic method to validate graph integrity.
Clearly identifies gaps in knowledge via unknown nodes.

Usage examples

“Build an evidence map for the decision to migrate our backend to a microservices architecture.”: The agent will guide you through framing the question, collecting primary sources, and structuring the reasoning graph to identify supporting evidence, contradictions, and missing data.
“Validate my current evidence map for the database selection project.”: The agent will run the validation script to check for cycles, missing edges, or unreferenced sources, ensuring the map meets all structural requirements.

Install

Download the skill as a ZIP:
https://autogineer.com/agent-skills/github/build-evidence-map/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip build-evidence-map.zip -d .agents/skills

Documentation by alsoleg89

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

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.
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 when source quality is disputed.
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.
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.
Preserve counterevidence. Do not delete contrary evidence because the provisional verdict survives it. Represent scope differences with qualifies edges.
Express uncertainty structurally. Do not invent confidence percentages. Add an unknown, narrow the position, or qualify a claim.
Write UTF-8 JSON with a .doubt.json suffix. Follow references/map-schema.md. Keep IDs short, stable, and semantic.
Validate fail-closed. Resolve scripts/validate.mjs relative to this SKILL.md, then run it with Node.js 18 or newer:
```
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 [email protected]; do not install or execute a remote package implicitly:
```
doubt map decision.doubt.json --out decision.html
```
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:
```
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.
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 cycles;
contrary or qualifying evidence is present when the source set contains it;
each decision-changing gap is an explicit unknown node;
every edge note explains support, contradiction, qualification, or absence;
the verdict is no broader than the evidence.

Deliver the result

Report:

the current position in one sentence;
the strongest counterevidence or qualification;
the most important unresolved unknown;
paths to the canonical JSON and any rendered HTML;
whether deterministic validation and explicit source verification ran.

Never describe a structurally valid map as proven true. Validation establishes traceability and graph integrity; source quality and inference quality still require human review.

Files

ATTRIBUTION.mdAdded by AutoGineer871 B
LICENSELicence file added by AutoGineer1.0 KiB
SKILL.md5.0 KiB
references/evidence-ladder.md1.8 KiB
references/map-schema.md3.2 KiB
scripts/contract.mjsScript17.8 KiB
scripts/validate.mjsScript2.8 KiB

scripts/validate.mjs

#!/usr/bin/env node

import { createHash } from "node:crypto";
import { readFile } from "node:fs/promises";
import { resolve } from "node:path";
import { fileURLToPath } from "node:url";
import {
  canonicalJson,
  inspectMapContract,
  receiptPayload,
} from "./contract.mjs";

function receiptFor(map) {
  const sourceSnapshots = map.sources.map((source) => ({
    id: source.id,
    retrievedAt: source.retrievedAt,
    excerptSha256: createHash("sha256").update(source.excerpt).digest("hex"),
  }));
  return createHash("sha256")
    .update(canonicalJson(receiptPayload(map, sourceSnapshots)))
    .digest("hex");
}

export function inspectOfflineMap(map) {
  const result = inspectMapContract(map);
  return {
    ...result,
    receipt: result.valid ? receiptFor(map) : null,
  };
}

export async function validateMapFile(file) {
  let map;
  try {
    const input = file instanceof URL ? file : resolve(file);
    map = JSON.parse(await readFile(input, "utf8"));
  } catch (error) {
    return {
      findings: [{
        path: "$",
        rule: "invalid-json",
        message: `Could not parse JSON: ${error.message}`,
      }],
      metrics: { claims: 0, contradictions: 0, evidence: 0, sources: 0, unknowns: 0 },
      receipt: null,
      valid: false,
    };
  }
  return inspectOfflineMap(map);
}

function plural(count, singular, pluralForm = `${singular}s`) {
  return count === 1 ? singular : pluralForm;
}

function printHuman(result) {
  if (!result.valid) {
    console.error(`INVALID ${result.findings.length} ${plural(result.findings.length, "finding")}`);
    for (const finding of result.findings) {
      console.error(`  - ${finding.path} [${finding.rule}] ${finding.message}`);
    }
    return;
  }
  console.log(`VALID ${result.receipt}`);
  console.log(
    `  ✓ ${result.metrics.claims} ${plural(result.metrics.claims, "claim")} · ${result.metrics.evidence} evidence · ${result.metrics.sources} ${plural(result.metrics.sources, "source")}`,
  );
  console.log(
    `  ↯ ${result.metrics.contradictions} ${plural(result.metrics.contradictions, "contradiction")} · ${result.metrics.unknowns} explicit ${plural(result.metrics.unknowns, "unknown")}`,
  );
}

async function main(argv) {
  if (argv.includes("--help") || argv.includes("-h")) {
    console.log("Usage: node <skill-dir>/scripts/validate.mjs <map.doubt.json> [--json]");
    return;
  }
  const file = argv.find((value) => !value.startsWith("-"));
  if (!file) throw new Error("Pass a .doubt.json evidence map.");
  const result = await validateMapFile(file);
  if (argv.includes("--json")) console.log(JSON.stringify(result, null, 2));
  else printHuman(result);
  if (!result.valid) process.exitCode = 1;
}

if (process.argv[1] === fileURLToPath(import.meta.url)) {
  main(process.argv.slice(2)).catch((error) => {
    console.error(error.message);
    process.exitCode = 1;
  });
}

Requirements and compatibility

Written for: GitHub Copilot

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Node.js