# Bootstrap Investigation

> Crystallize an investigation-design conversation into a complete investigation/documentation project scaffold. For projects whose deliverable is *understanding and a record* — recoveries, reverse-engineering efforts, forensics, research write-ups, post-mortems — NOT software built from source. Reads the current session for project name, subject, principles, phases, and audience; writes the docs quintet (PROJECT, FOUNDATION, SUBJECT, WRITEUP, PRIVACY), the plan under docs/plan/ (PROCEDURE, ROADMAP), a dated append-only logbook/, an evidence/ directory, CLAUDE.md, LICENSE, CHANGELOG, and supporting files. Asks an artifact-provenance policy (private-archive / public-writeup / none) and offers optional add-ons: a go/no-go GATES decision-log, a docs/COMPONENTS.md flat inventory, and an evidence/netlist/ structure map. Use this when the user says "bootstrap this investigation", "scaffold this recovery/research project", "set up the documentation project", or invokes /bootstrap-investigation. The skill is a finalize

- Skill: `joseluisamado/bootstrap-investigation` (Agent Skill, multi-file: 31 files)
- Install (CLI): `npx skillmds@latest add joseluisamado/bootstrap-investigation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/joseluisamado/bootstrap-investigation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: joseluisamado (https://skillmd.com/u/joseluisamado)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/joseluisamado/bootstrap-investigation

---


# bootstrap-investigation

This skill produces a scaffold for an **investigation / documentation project**:
one whose output is understanding plus a durable, auditable record — not a built
software artifact. Its shape is distilled from a real firmware-recovery project
(phased plan, go/no-go gates, an append-only dated logbook, evidence and source
archives, and per-artifact provenance manifests).

It is the investigation sibling of [`bootstrap-project`](../bootstrap-project/).
Where `bootstrap-project` asks "what stack, what deploy model" and writes a
Makefile/CI/PROGRESS for code, this skill asks "what subject, what artifact
policy" and writes a FOUNDATION/PROCEDURE/logbook for an inquiry.

The full playbook lives in [`INSTRUCTIONS.md`](./INSTRUCTIONS.md). Read it when
the skill is invoked. The short version:

1. Extract an investigation spec from the current conversation.
2. Print it; ask the user to confirm or correct.
3. Ask explicitly: license, artifact-provenance policy, gates add-on.
4. Write the scaffold using `templates/`. Skip files that already exist.
5. Generate `BOOTSTRAP-MANIFEST.md` and `.bootstrap-meta.yaml` (mode: investigation).
6. Print the "next 30 minutes" punch list.

The skill is **same-session only**. If invoked cold (no prior design
conversation in this session), refuse and ask the user to have the
investigation-design conversation first or paste a summary.

The skill **never writes outside the project root** and **never clobbers
existing files**.

## Artifact-provenance policy

Investigations vary in how they handle the evidence and tooling they gather.
The skill asks which posture applies:

- `private-archive` — the repo is the durable backup; it **commits** scarce or
  proprietary artifacts (leaked tools, firmware, licenses, photos) with a
  per-artifact manifest (sha256 + provenance), and carries "keep this repo
  private" warnings. Only reproducible blobs (disk images) are git-ignored.
- `public-writeup` — no proprietary blobs committed; artifacts are referenced,
  not stored. Manifests optional. Suitable for a publishable write-up.
- `none` — no artifact machinery; just the docs, logbook, and evidence.

## Optional gates add-on

Risk-laden investigations (a step can brick the subject or terminate the
project) benefit from an explicit **go/no-go decision log**. With the gates
add-on, the skill writes `docs/plan/GATES.md` (OPEN / BLOCKED / PASSED / FAILED
per gate, with condition / status / evidence / history) and shapes
`docs/plan/ROADMAP.md` so each phase ends in a gate. Without it, the ROADMAP is a
plain phased plan.

## Optional inventory & structure-map add-ons

Two further opt-in add-ons, distilled from what real hardware/reverse-engineering
runs converged on:

- **components-inventory** → `docs/COMPONENTS.md`, a flat current-state parts/
  elements list that is the itemized companion to the narrative `SUBJECT.md`.
- **structure-map** → `evidence/netlist/` (README + NETLIST stub), the recovered
  internal structure map (a circuit netlist, or the equivalent relational map)
  the reconstruction is built against.

Both default ON for a physical device under reverse-engineering, OFF for a purely
documentary inquiry.

## Layout note (v0.3.0)

No **`sources/`** directory. Source and reference tracking folds into
`evidence/` (references cited from the logbook) and, for scarce or proprietary
material, the per-artifact manifests. A large single-bucket `artifacts/` can be
promoted into **typed stores** (`datasheets/`, `learning/`, …) at the repo root
as it grows — see the artifacts README. Both changes came from what the R4700
ISA-card investigation converged on.

## Layout note (v0.2.0)

The plan lives under **`docs/plan/`** — `PROCEDURE.md`, `ROADMAP.md`, and (if
gated) `GATES.md` are siblings there. There is no top-level `plan/` directory.
Earlier v0.1.0 scaffolds used a top-level `plan/` with `PROCEDURE.md` in `docs/`;
both real projects relocated to `docs/plan/`, and v0.2.0 makes that the default.

For background on why the scaffold has this shape, see
[`patterns/investigation-shape.md`](./patterns/investigation-shape.md).

See [`CHANGELOG.md`](./CHANGELOG.md) for version history.