joseluisamado 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.
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. Read it when
the skill is invoked. The short version:
- Extract an investigation spec from the current conversation.
- Print it; ask the user to confirm or correct.
- Ask explicitly: license, artifact-provenance policy, gates add-on.
- Write the scaffold using
templates/. Skip files that already exist. - Generate
BOOTSTRAP-MANIFEST.mdand.bootstrap-meta.yaml(mode: investigation). - 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 narrativeSUBJECT.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.
See CHANGELOG.md for version history.