Skip to content

inspect.md

Latest commit

 

History

History
25 lines (14 loc) · 2.62 KB

inspect.md

File metadata and controls

25 lines (14 loc) · 2.62 KB
Raw

/inspect — survey an existing project and carve out its features

No argument, or a directory to focus on. For adopting PDD on a codebase that predates it: the agent finds the features itself, drafts them itself, and the author reviews finished drafts instead of writing from scratch.

Phase 1 — inventory (autonomous)

  1. Sweep the project's consumption surfaces: existing specs (SPECS/FEATURES, SPECS/TASKS, READMEs, docs), config schema (keys a user can set), CLI/API/RPC surface, build flags, and the code's package structure. Use subagents for parallel sweeps on large repos.
  2. Carve the surface into candidate features — aspects a consumer experiences as one capability. Guides: one feature = one narrative of "what you can do here"; a feature of one promise is suspicious (granularity doc); process work (CI, sync, audits) forms process features.
  3. Produce the map as a table: candidate name, consumer, one-line purpose, consumption surface (keys/endpoints/flags), size estimate in promises, existing docs to distill from. Flag overlaps and orphans (surface that fits no candidate) — those become questions, not guesses.

Phase 2 — the author's cut

Show the map. The author merges/splits/renames/drops candidates and picks what gets drafted now. Do not proceed past this gate silently.

Phase 3 — drafting (autonomous, per approved candidate)

For each approved feature run the /backfill drafting flow: a full FEATURE.md draft — purpose, promises (P1…) with "the one where …" witnesses, assumptions, non-goals — written into SPECS/FEATURES/NNN-NAME/FEATURE.md with a backfill mode mark and a DRAFT — pending author review line in the header. Unillustratable promises become recorded questions, never guesses.

Phase 4 — review gate

Deliver the drafts with a per-feature summary: promise count, open questions, weakest promises (no witness / no conceivable mutation). Promises are authorial: a draft loses its DRAFT mark only after the author reads it and says so. Only then do tasks start declaring Touches against it and uphold passes judge by it.

Phase 5 — marking (after the DRAFT mark comes off)

Per approved feature, place the // PROMISE FNNN-PN markers in the existing code — the /backfill step 7 flow: find what actually fulfils each promise today, propose the placements to the author, then mark. On a large codebase this is the expensive half of adoption; it is also what turns the promises from a document into something the courts can check. Verify with sh .pdd/scripts/check-promises.sh <feature-path>; until a feature is marked, use --no-code so the check still guards IDs and witnesses.