Routed from a downstream Act review (getwyrd/wyrd-pdca, 2026-07-07).
Principle
When a change introduces a dependency a human must install or provide — a build tool, a system lib, a runtime service, a required capability — the system must register it: list it in pdca doctor (with an install hint) and prompt the human, rather than letting it surface mid-cycle as a cryptic build/runtime failure. Registration should be a forcing function, not best-effort.
Evidence — the reactive-registration gap
The brief template already softly directs this — the External dependencies field says "enumerated at Plan so they preflight (seed the render's [[doctor.checks]] where you can)" — but "where you can" is not a forcing function, so registration kept happening reactively.
Proposed scope (implementation later)
- Brief template (
templates/brief.md.tpl, External dependencies): make doctor registration mandatory — every declared external dependency a human installs/provides MUST have a matching [[doctor.checks]] row (a cmd that detects it + an install hint); a declared dep with no row is a Plan-exit gap.
- Builder skill (
agents/builder.md): when Do discovers/introduces a dependency, it must also propose its [[doctor.checks]] row (id / detect-cmd / hint / level) in build-notes.md, alongside the existing NEEDS-HUMAN external dependency marker.
- Reviewer skill (
agents/reviewer.md): raise NEEDS-HUMAN when a build/runtime dependency the bundle relies on — a brief External dependencies entry, a newly-enabled Cargo feature/dep, or a Do-discovered prereq — has no matching [[doctor.checks]] row ("register before accept").
- (Stretch — mechanism):
pdca doctor / the driver reconciles declared External dependencies (and/or added Cargo deps) against the registered doctor rows and warns on any unregistered one; optionally surface the install hint as an actionable prompt.
Downstream instance follow-up (getwyrd/wyrd-pdca)
Once the convention lands, register the concrete already-known deps: protoc (etcd feature build, WARN — parallel to the existing docker/openssl rows) and audit that docker/openssl coverage is complete.
Related (this project): the doctor rows live in pdca.toml (instance data, getwyrd/wyrd-pdca#96 added docker+openssl); this issue is the generic template + skills + mechanism side.
Routed from a downstream Act review (getwyrd/wyrd-pdca, 2026-07-07).
Principle
When a change introduces a dependency a human must install or provide — a build tool, a system lib, a runtime service, a required capability — the system must register it: list it in
pdca doctor(with an installhint) and prompt the human, rather than letting it surface mid-cycle as a cryptic build/runtime failure. Registration should be a forcing function, not best-effort.Evidence — the reactive-registration gap
docker+pkg-config/libssl-devwere added to[[doctor.checks]]only after they false-failed gates (Act 2026-07-04, config: pdca doctor should preflight the M4 TiKV leg prerequisites (docker + pkg-config/libssl-dev) getwyrd/wyrd-pdca#96). The operator hit an OpenSSL build failure the runner even mis-retried 5× as "TiKV may still be bootstrapping."etcd-clientregenerates protobufs at build time and needs a systemprotoc(Cargo.toml:110,crates/coordination-etcd/Cargo.toml:13), butprotocwas never registered in doctor.cargo xtask etcd-conformancetherefore hits a cryptic protobuf build failure instead of apdca doctorprompt.The brief template already softly directs this — the
External dependenciesfield says "enumerated at Plan so they preflight (seed the render's[[doctor.checks]]where you can)" — but "where you can" is not a forcing function, so registration kept happening reactively.Proposed scope (implementation later)
templates/brief.md.tpl,External dependencies): make doctor registration mandatory — every declared external dependency a human installs/provides MUST have a matching[[doctor.checks]]row (acmdthat detects it + an installhint); a declared dep with no row is a Plan-exit gap.agents/builder.md): when Do discovers/introduces a dependency, it must also propose its[[doctor.checks]]row (id / detect-cmd / hint / level) inbuild-notes.md, alongside the existingNEEDS-HUMAN external dependencymarker.agents/reviewer.md): raise NEEDS-HUMAN when a build/runtime dependency the bundle relies on — a briefExternal dependenciesentry, a newly-enabled Cargo feature/dep, or a Do-discovered prereq — has no matching[[doctor.checks]]row ("register before accept").pdca doctor/ the driver reconciles declaredExternal dependencies(and/or added Cargo deps) against the registered doctor rows and warns on any unregistered one; optionally surface the installhintas an actionable prompt.Downstream instance follow-up (getwyrd/wyrd-pdca)
Once the convention lands, register the concrete already-known deps:
protoc(etcd feature build, WARN — parallel to the existing docker/openssl rows) and audit that docker/openssl coverage is complete.Related (this project): the doctor rows live in
pdca.toml(instance data, getwyrd/wyrd-pdca#96 added docker+openssl); this issue is the generic template + skills + mechanism side.