# Reality First Engineering

> Establish a short, evidence-backed decision gate before architecture or broad implementation when missing facts, requirements, external behavior, or acceptance criteria could change the direction. Use only for consequential or materially uncertain work.

- Skill: `a1024053774/reality-first-engineering` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add a1024053774/reality-first-engineering`
- Raw SKILL.md: https://api.skillmd.com/api/skills/a1024053774/reality-first-engineering/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: a1024053774 (https://skillmd.com/u/a1024053774)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/a1024053774/reality-first-engineering

---


# Reality-First Engineering

Use this before architecture or broad implementation when a wrong assumption would cause
meaningful rework, data loss, security exposure, irreversible side effects, or a false
acceptance result. It is a small decision gate, not a second project manager, code review,
test suite, or reason to delay a cheap reversible probe.

Do not use it for a small change with known inputs, contracts, and environment, or for
documentation/formatting-only work.

## Gate protocol

1. **State the decision.** Write the goal, non-goals, acceptance condition, and the exact
   decision that must be made before implementation.
2. **Separate facts from guesses.** Label each relevant item `observed`, `measured`,
   `inferred`, or `unknown`. An implementation assumption is not evidence. For facts likely to
   change, record the source and verification date.
3. **Choose the smallest probe.** For each material unknown that could change the direction,
   define one falsifiable experiment with real inputs, a pass condition, a failure condition, a
   stop condition, an owner, and an evidence location. Test the highest-impact unknowns first;
   stop once the decision is determined instead of building the whole system to discover it.
4. **Gate the direction.** Return `PASS` only when the architecture or plan follows from the
   available evidence.
   - `BLOCKED`: a decisive input, authority, or probe is unavailable, or the evidence disproves
     the proposed direction; no safe direction can be chosen.
   - `INCOMPLETE`: evidence exists but is partial or ambiguous; narrow to verified work or
     report what remains, and never silently treat it as `PASS`.
   Do not cover the gap with a fallback, compatibility path, mock-only branch, or speculative
   abstraction.
5. **Keep the boundary testable.** Put external effects behind the existing boundary that
   owns them and keep deterministic domain/state logic driven by supplied inputs. A mock may
   validate pure logic, but it cannot establish an external fact it replaces. Add a layer only
   when a concrete caller or boundary needs it.

## One ledger, one epoch

If `project-to-act` is available, run its `--check` first and follow its mode. It owns goals,
scope, durable progress, versions, evidence, and acceptance. Record this gate in the existing
canonical source; never create `REALITY.md`, a second plan, or a parallel status file.

For a managed project, use the existing files (or their equivalent sections):

- overview: constraints, facts, and current unknowns;
- progress: probes, blockers, owners, and next action;
- versions: decisions changed by evidence;
- acceptance: experiment evidence, gate result, and validity.

For an unconfigured one-off project, keep the brief in the task response. Do not initialize
project management merely because this skill loaded. Read the target section again before
writing and validate through `project-to-act` after writing.

Run one gate per decision batch. Edits and test iterations under the same assumptions do not
restart it. Re-open only when new evidence invalidates an assumption, scope changes, or a new
direction is proposed.

## Required brief

```text
REALITY GATE: PASS | BLOCKED | INCOMPLETE
GOAL / NON-GOALS:
DECISION:
OBSERVED:
MEASURED:
INFERRED:
UNKNOWN (material only):
PROBE (repeat for each material unknown): input/context, method, pass/fail,
stop condition, owner, evidence location
DECISION CONSEQUENCE:
LEDGER / NEXT:
```

After `PASS`, derive the smallest implementation plan and use normal testing. At completion,
invoke `design-integrity-review` only when its structural-risk route applies; evaluation or
generation surfaces go through its single behavioral-acceptance route. Neither reviewer
replaces this gate or creates another ledger.

The honest result may be a stop. A clean `BLOCKED`/`INCOMPLETE` with a precise next probe is
better than a polished implementation of an unverified premise.