# Assumption Excavation

> Surface hidden assumptions in plans, specs, AGENTS.md, SKILL.md, SET bundles, and workflow contracts before implementation or handoff. Use when an artifact looks plausible but may rely on unstated environment, dependency, behavioral, temporal, or success assumptions.

- Skill: `markoblogo/assumption-excavation` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add markoblogo/assumption-excavation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/markoblogo/assumption-excavation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- License: MIT
- Author: markoblogo (https://skillmd.com/u/markoblogo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/markoblogo/assumption-excavation

---


# Assumption Excavation

Find what the artifact takes for granted before those assumptions become implementation bugs.

## Use When

- reviewing PRDs, specs, plans, or issue slices before work starts;
- reviewing `AGENTS.md`, `SKILL.md`, SET bundles, proof-loop contracts, or workflow docs;
- a proposal sounds confident but depends on unclear prerequisites;
- you need a lightweight pre-implementation review lens.

## Workflow

1. Identify the artifact and its intended consumer.
2. Read for implicit assumptions, not prose quality.
3. Classify assumptions:
   - environment: tools, services, files, auth, OS, network;
   - dependency: upstream state, input shape, prior checks;
   - behavioral: what humans, agents, or systems are expected to do;
   - temporal: what must remain stable over time;
   - success: what the artifact counts as done or safe.
4. Rank the assumptions by fragility:
   - high: likely to break or expensive if wrong;
   - medium: plausible risk with manageable fallout;
   - low: visible but not blocking.
5. Mark partially surfaced assumptions as `PARTIAL`.
6. Recommend what must be clarified, tested, or accepted before implementation.

## Output Shape

Use:

- verdict: `EXAMINED` or `UNEXAMINED`;
- top assumptions, ranked;
- fragility score or severity per item;
- missing evidence;
- smallest clarification or verification step.

## Guardrails

- Do not rewrite the artifact unless asked.
- Do not treat assumptions as errors by default; some are deliberate.
- Do not block on low-risk assumptions.
- State uncertainty as text-based inference, not mind reading.

## Provenance

Adapted from the `assumption-excavator` pattern in `aself101/agents-and-pipelines`, compressed for ABVX skill use and broader repo-contract review.