Reconstruct

Reconstruct: any repo — or any idea — → a buildable PRD suite

For engine evidence and coverage limits, read engine-evidence.

A dependency-free Node script does the deterministic scaffold (facts + candidate hints); you supply the framework-aware understanding — the interface surface, the data model, the real features — for any stack. The output is a folder of PRDs an agent can rebuild the project from, with no access to the original and no access to this conversation.

The markdown is the program. The engine never reasons; every judgement in this skill is yours.

Route the request

Use the absolute path to scripts/analyze.mjs inside the installed skill folder. --help lists every flag. Skip the skill for tiny single-file scripts, or when the user wants a running app now rather than a plan.

Inputs to confirm (code path): target repo · output dir · mode preserve (keep the architecture) or redesign (same features, fresh architecture) · level light (faithful) or complex (also suggest improvements) · fidelity mirror/embed/describe, derived from mode+level if unset.

The pipeline — four phases

# 1. SCAFFOLD — deterministic, no API key
node scripts/analyze.mjs --repo <REPO> --out <OUT> --mode <MODE> --level <LEVEL>

# 2. ORIENT — SUMMARY.md (~3 KB, written every run), NOT inventory.json (grows with the repo)
#    slice the inventory:  jq '.features[] | {slug, files: (.files|length)}' <OUT>/inventory.json
#    identify the stack → references/stack-guides/INDEX.md maps the label to its guide

# 3. ENRICH — fill INTERFACES.md, DATA-MODEL.md, ARCHITECTURE.md (+ DESIGN-SYSTEM.md for a UI),
#    then every features/<slug>/PRD.md to full spine depth. At scale, fan out:
node scripts/analyze.mjs --orchestrate --out <OUT> --phase enrich-map

# 4. CONVERGE — run to the fixpoint, autonomously, in one go
node scripts/analyze.mjs --check   --out <OUT>              # layer 1: structure
node scripts/analyze.mjs --review  --out <OUT>              # layer 2: worklist (changed units only)
#   → findings.json → --review --apply findings.json --out <OUT>
node scripts/analyze.mjs --verify  --out <OUT>              # faithfulness: requirement↔evidence
#   → verdicts.json → --verify --apply verdicts.json --out <OUT>
node scripts/analyze.mjs --check --semantic --out <OUT>     # the final, fail-closed gate

Phase 4 is a loop, not a checklist: enrich → check → review → fix → verify → gate, until --check --semantic exits 0. Its rules, ledger fields and stopping conditions are defined once, in convergence-loop.md. Do not improvise stopping rules.

Non-negotiables

• hints, routes and i18n are candidates to verify, never truth. Open the source and confirm. Resolve every entry in inventory.unknowns. If inventory.warnings is present, detection degraded there — check those areas by hand.
• Every > 🧠 callout gets resolved and deleted. One left in place means the unit is not done, and --check fails.
• Be exhaustive, never illustrative. No "etc.", no "and so on", no happy-path-only. If a behaviour, role, validation rule or error state exists, it gets its own line.
• Capture the contract, not the name. A rate limit without numbers, an enum without its member list, a service without its request shape — none of these are buildable. The ten categories: buildability-checklist.md.
• Many small PRDs beat a few broad ones. More than ~5–7 stories or ~3 entities in one unit → split it. Every distinct capability earns its own PRD.
• Never re-run the analyzer over an enriched tree — it re-renders every document. The CLI refuses it; to continue an existing tree use --check/--review/--verify, and to re-scaffold point --out at a new directory.
• Ground every claim in source//data/ (code mode) or CONTEXT.md/ADRs (scratch mode). An invented fix just trades one finding for another.
• Never let a cap stay silent. --verify bounds its worklist (60 pairs by default) and a large fan-out bounds its agent count. Read coverage, report what you actually covered.
• Own the loop end-to-end. Run it yourself to the fixpoint — do not hand rounds back, do not ask "should I continue?", do not stop at the first pass. Report once, at the end.
• The self-check: could a fresh agent rebuild this unit correctly — contracts right, not just the gist — from its PRD + the architecture docs alone? If not, dig further. worked-example.md is the depth bar.

Orchestration — route by harness

The judgment phases fan out over independent per-unit worklists. --orchestrate emits the fan-out from <OUT>'s current worklists, with absolute paths and real unit ids baked in:

node scripts/analyze.mjs --orchestrate --out <OUT> [--phase enrich-map|review-find|review-verify|adjudicate] [--eco] [--list]

Fan-out is an optimization, never a requirement — the gates are harness-independent and every phase has a sequential fallback with identical artifacts. Subagents never write: the reduce (every doc merge, every --apply fold) always stays with you. Never fan out the greenfield interview, --brainstorm, a reduce step, or the scratch build. --phase <p> before its worklist exists exits 2 and names the command that produces it. Protocol: orchestration.md; sizing: scale-and-context.md.

Reference map

Start here

Method

Gates

Greenfield & ideation

Output shape

Safety

The analyzer only reads the target repo and copies files into the output. It never executes the analyzed project's code during analysis. The separate opt-in --compare <cases.json> --original <dir> --rebuilt <dir> --run-tests mode executes fixture commands with local user privileges. Read every command and obtain explicit authorization before using --run-tests; without it, cases remain not-tested and the gate fails. Report only the exercised cases and exact stdout/stderr/exit equality, never global equivalence. The source-faithfulness and buildability ledgers remain independent gates. Review scripts/ before running on untrusted repos.