# Blind Rebuild Verification

> Verify a reverse-engineered spec is self-sufficient by rebuilding the target from spec ONLY (never read the original). Use when the user hands you a spec directory + out directory and says "rebuild from spec only, do not read the original repo."

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

---


# Blind-Rebuild Verification

You are given a spec dir (natural-language spec generated by a reverse-engineering tool like REgent regent-reverse) and an out dir. Your job is to rebuild the target package **from spec only** and prove the spec was sufficient.

This is a meta-test of the spec, not just an implementation task. The original repo is OFF-LIMITS — never `ls`, `cat`, `grep`, `git log`, or otherwise read it.

## When this skill fires

- User says "blind-rebuild verification", "rebuild from spec only", or names the regent-build skill test.
- You're handed a `<spec_dir>/AGENTS.md` plus `<spec_dir>/{README,architecture}.md`, `layout/`, `specs/`, `conventions/`, `inventory/`.

## Required reading order (literal)

1. `<spec_dir>/AGENTS.md` — its rebuild order is authoritative.
2. `<spec_dir>/README.md` + `architecture.md` — goals, constraints, building blocks.
3. `<spec_dir>/layout/tree.txt` + `layout/src.map.md` — file map + public APIs.
4. `<spec_dir>/specs/*.spec.md` — R-/S- requirements (MUST > SHOULD).
5. `<spec_dir>/conventions/*.md` — style, tooling, error conventions.
6. `<spec_dir>/inventory/functional-checklist.md` — grading key.

## Rebuild loop

For each file in `src.map.md`:
1. Read its purpose, public API, side effects, imports from `src.map.md`.
2. Read the matching `specs/*.spec.md` R-num requirements that govern it.
3. Honor any constraints from `conventions/` (import style, version, error format).
4. Write the minimum code that satisfies R-requirements and passes the checklist.

**Do not copy verbatim.** Reconstruct from natural-language spec.

## Verification protocol

1. Per `conventions/dev-env.md`: build install command + test command.
2. Run the full test suite. Expect exit 0.
3. Run **every** `- [ ]` line of `inventory/functional-checklist.md` as an actual command/call. Capture output, exit codes.
4. For non-obvious cases, write a 5-line ad-hoc Python probe rather than guessing.

## Final report (under 4 KB)

Structure:
- **Clear spec sections** — `path:line` cites where requirements were unambiguous.
- **Vague/missing/invented sections** — `path:line` for spec gaps. Be honest; this is the point.
- **Checklist table** — every `- [ ]` with PASS/FAIL + one-line reason + evidence.
- **Inventions bullet-list** — every decision not specified by the spec (e.g. "chose dict over if/elif in formats.py", "invented LICENSE body text because spec said only 'MIT stub'").
- **Final verdict** — PASS (spec sufficient) or FAIL (spec has gap), with the exact missing `R-` or `S-` number.

## Pitfalls

- **Do not read the original repo.** Even verifying a "small detail" by reading original defeats the test. If spec is ambiguous, mark it vague in the report — don't peek.
- **Empty/clean out-dir.** Spec says "starts cleaned" — assume `mkdir -p` is yours.
- **Use `uv venv` + `uv pip install`** when venv needed. Never `sudo`. PEP 668 + `python3` without `pip` → uv path.
- **`pip install -e .[test]` will warn "no extra named test"** if pyproject lacks a `test` extra. Not a real error; add `pytest` separately via `uv pip install pytest` or just `pip install -e .` for greeter-style packages without extras.
- **Literal punctuation matters.** For non-English locales (zh, ja), full-width `，` `。` `！` etc. are usually required by spec — copy them byte-for-byte, do not auto-translate.
- **`error: ` prefix on stderr is literal in many CLI specs.** argparse + `print(f"error: {exc}", file=sys.stderr)` is the canonical pattern.
- **SHOULD vs MUST.** `SHOULD` requirements are graded as PASS when honored; `MUST` failures → FAIL.
- **`__all__` matters.** If spec says `__init__.py declares __all__`, declare it. `from __future__ import annotations` is required in Python ≥3.10 modules when the spec mentions it.
- **Console script verification.** After `pip install -e .`, run the binary directly (e.g. `greeter Ada`); don't trust that install succeeded without an actual invocation.
- **Exit code discipline.** Spec-defined codes (0 success, 2 domain error) must be tested explicitly with `$?`.
- **Whitelist reuses, don't reinvent.** If `conventions/architecture-rules.md` says `formats.py` is "function defs and a `dict` literal" — use a dict, even if an `if/elif` chain feels Pythonic. Match evidence.

## Subagent Fallback (parent-agent rebuild)

When `delegate_task` fails — MiniMax 429 quota exhaustion, pool timeout at
max_concurrent_children=1, or model unavailability — the parent agent
MUST do the rebuild directly rather than retrying the subagent.

**Triggers for fallback:**
- Subagent returns 429 (Token Plan 用量上限) from MiniMax
- dispatch timeout after 600s with no output
- model resolves to a provider with exhausted quota

**Parent-agent rebuild pattern:**
- Python: write minimal stub modules + implementation via `write_file` using clean string literals (never read_file → write_file)
- Rust: `cargo init --lib` workspace (trait crate + impl crate), then write src/lib.rs
- Debug: fix one bug at a time, verify with `python3 -c` or `#[test]` probes
- Grade: comprehensive test walking every checklist item

## Cross-Language Pitfalls

### Rust + regex-automata
- `NonMaxUsize` has `.get()` not `usize::from()`
- `HalfMatch` has `.offset()` returning usize (no Dead/Quit variants in 0.4)
- `search_captures` returns `()` not `Option` in 0.4
- `group_info().group_len()` requires `PatternID` argument
- `RegexBuilder` is a temporary — bind to `let binding` before chaining

## Common Implementation Bugs

- `_exit_buffer` calls `_write_buffer` directly, bypassing `_check_buffer` → quiet flag ignored
- Buffer saved AFTER flush in `end_capture` → returns empty string
- Sentinel `NO_CHANGE` values crash `int()` in `update(width=...)`
- `Style.parse()` doesn't raise on malformed input → `get_style` never falls back to default
- `read_file` output fed to `write_file` → line number prefixes injected into source files

## What NOT to capture

- Specific license text you invented for one project — it's a per-spec invention, belongs in the **report** not as a durable rule.
- Per-implementation choices (dict vs if-elif) — report those in the inventions list, don't generalize.

## Reference

See `references/greeter-report.md` for a worked example (small Python CLI package, 20/20 PASS, 4 minor inventions).