--- name: delivery-record description: | Generate a Delivery Record for a significant AI-assisted output — code (PR), FRD, audit, discovery, design-handoff, strategy, client-comm, design, QA, launch, deployment, devops, project-setup, or ongoing-improvement. Refuses to write without a named human reviewer and the two checkpoint notes. Writes to docs/delivery-records/ in a repo or to Drive in Claude Desktop, and indexes the result in the project's Teamwork "Delivery Records" notebook. Invoke at the end of a unit of work, after /pr-create for code, or via /delivery-record. --- # Delivery Record Draft a schema-typed, human-signed Delivery Record — one markdown file per significant AI-assisted output — then write it and index it in Teamwork. The main session runs this skill directly; no orchestrator agent is involved. The record proves a piece of AI-assisted work was reviewed by a **named human** and ran through Kanopi's workflow. The schema is canonical in this repo at [`spec/v1/`](../../spec/v1/README.md). ## ⚠️ Side Effect Warning **This skill writes a file and posts to Teamwork.** Specifically it: - Writes a markdown file to `docs/delivery-records/` in the repo (code) or to the client's Drive (non-code). - Posts an index comment on the project's "Delivery Records" Teamwork notebook (and, with your confirmation, creates that notebook if it is missing). - For code records, amends the open PR description with a link to the record. **The human checkpoint is mandatory.** This skill **refuses to write the file** without a named reviewer and both checkpoint notes (see step 4). ## When a record is required Required whenever the output is **client-facing** (code that ships, a deliverable sent to the client, a message on a client thread) **or load-bearing internal** (an FRD, IA, audit, architecture decision, or design-to-dev handoff that downstream work depends on). **Not** required for ephemeral chat, meeting prep, status notes, throwaway spikes, or brainstorming. ## Usage - "Create a delivery record for this PR" - "Generate a delivery record for the audit report" - `/delivery-record [--activity-type ] [--pr ] [--ticket ] [--scope ] [--reviewer ]` ### Inputs (CLI-style flags accepted in the prompt) - `--activity-type ` — skip detection (`code`, `frd`, `audit`, `discovery`, `design-handoff`, `strategy`, `client-comm`) - `--pr ` — override PR detection - `--ticket ` — set `ticket:` explicitly - `--scope ` — set scope - `--reviewer ` — pre-fill `reviewed_by` (still validated against blank checkpoint notes) ## Workflow ### 1. Detect environment and activity type - **Claude Code with a PR open** → default `activity_type: code`, `subject.kind: pr`. Gather the PR number and SHA from `gh pr view --json number,headRefOid,title,url`. - **Claude Desktop / no PR** → ask for the `activity_type`, then route to the matching template in `templates/`. - A `--activity-type` flag always wins over detection. ### 2. Gather facts Pull what the chosen activity needs: - **code**: `git log ..HEAD --oneline`, PR number/SHA/title from `gh pr view`, CI status (`gh pr checks` or the CircleCI MCP), presence of audit report files in the repo, and any `/evaluate-output` trajectory notes from this session. - **frd**: the Teamwork epic + child tasks (via `teamwork-integrator`), the Drive doc URL, and the SOW hour cap if known. - **audit**: the audit report file path, its methodology section, and the host site URL. - **discovery / strategy / design-handoff**: ask for the Drive doc URL; pull recent Teamwork comments tagged to the same epic. - **client-comm**: ask for the Teamwork message URL; pull the thread; pull the matching Fathom transcript if a call is referenced. - **design**: ask for the Figma file URL and the design brief; note which components are reused vs new. - **qa**: ask for the QA task and multidev URL; pull the acceptance criteria and the captured screenshots (pairs with `qa-validation-checklist` / `browser-validator`). - **launch**: ask for the launch notebook/checklist; gather the pre-launch audit report paths and the DNS/SSL cutover and rollback plans. - **deployment**: the release tag, the generated release notes, and confirmation that a backup was taken and migrations ran clean. - **devops**: the PR for the infra/environment change and the lower-environment test results; confirm no secrets landed in the repo. - **project-setup**: the `CLAUDE.md` / onboarding brief and the SOW; confirm which documented commands were verified against a fresh checkout. - **ongoing-improvement**: the metrics source (CWV, uptime, error logs) and the report file; note the sample size. ### 3. Draft the record - **Read `templates/.md` first** (resolve it from this skill's base directory) and copy its front-matter structure **exactly** — never improvise the shape from memory. The schema requires the exact nested `checks:` groups (for code: `standards`, `tests`, `audits`, `review`); a flat or renamed structure fails validation. Populate the front-matter with the gathered facts. Set `predicate_type` to `https://kanopi.github.io/delivery-record/spec/v1`. - Fill the `checks:` block with the required keys for the activity type (see the table in [`spec/v1/README.md`](../../spec/v1/README.md)). Use `pass` / `fail` / `n/a` for statuses and evidence strings (CI URLs, reviewer notes) where appropriate. **Justify every `n/a`** in one line near the top of the body; a `fail` requires a `## Waiver` section. - Leave `sign_off.reviewed_by` and the two **What the human verified** checkpoint notes **blank** — those come from the human in step 4. - Validate the in-progress draft early to catch missing required fields: ```bash python3 scripts/delivery_record_verify.py ``` (Resolve the path to this plugin's bundled `scripts/`. In environments without Python, validate by eye against the schema reference — the front-matter required fields and the per-activity `checks` keys.) ### 4. Require the human checkpoint (the curl rule) Display the draft and explicitly prompt: > **Who is the named reviewer? Paste the Checkpoint 1 (plan approval) and > Checkpoint 2 (final approval) notes.** **Refuse to proceed** if either checkpoint note is blank or generic. A bare "LGTM", "looks good", or an empty line **fails** — Checkpoint 2 must say what the reviewer actually looked at beyond the automated gates. Re-prompt up to twice; on the third blank/generic input, **abort** with a clear message and do not write the file. A `--reviewer` flag pre-fills `reviewed_by` but does **not** satisfy the checkpoint notes — those are always required from the human. ### 5. Write the file - **code**: `docs/delivery-records/PR--.md` in the current repo. Create the directory if it does not exist. `` is a kebab-case of the PR title. **The path is part of the contract** — CI lint and notebook indexing find records there. Never write the record anywhere else: if `mkdir` is unavailable or denied, write the full `docs/delivery-records/...` path with the Write tool (it creates parent directories itself); if the file still cannot be written at that path, stop and say so — do not relocate the record to the repo root or another directory. - **non-code**: write to Drive via the Drive MCP at `/Delivery Records/YYYY-MM-DD-.md`. On first use in a project, ask for the target Drive folder and reuse it for the session. **If the Drive MCP is not available, abort** with clear instructions and print the full draft so the user can save it manually. After writing, re-run the validator on the final file and report the result. **Never report the record as written without validator output** (or, where Python is unavailable, an explicit line-by-line check against the template's front-matter shape). If validation fails, fix the record and re-validate — a schema-invalid record is not a delivery record. ### 6. Index in Teamwork - Use `teamwork-integrator` to find the project's **"Delivery Records"** notebook. - If it does not exist, **confirm with the user before creating it** (do not create silently). If the user declines, skip indexing and tell them the record was written but not indexed. - **Post the index entry as a comment on the notebook** (Teamwork's `create_comment` against the notebook). Do **not** rewrite the notebook body — notebooks have no append operation, so commenting avoids clobbering existing content and keeps a clean, per-record audit trail. Use this one-line format: ``` YYYY-MM-DD · · · <link> ``` ### 7. For code records: link from the PR Amend the PR description with a trailer so reviewers can find the record: ``` Delivery Record: docs/delivery-records/PR-<n>-<slug>.md ``` ## Validation reference The skill never writes an invalid record. The required front-matter fields, the per-activity `checks` keys, the `pass | fail | n/a` rule, and the waiver/justification (threshold) rule are all defined in [`spec/v1/`](../../spec/v1/README.md). Use `/delivery-record-verify` to validate an existing record after the fact. ## Environment fallback - **No `gh` CLI** → ask the user for the PR number, SHA, and CI status, then proceed; print the `gh pr edit` command for the PR link in step 7 instead of running it. - **No Teamwork MCP** → write the file, then tell the user to post the index comment on the Delivery Records notebook manually (provide the exact line). - **No Drive MCP (non-code)** → abort the write per step 5 and print the draft. ## Red flags (self-talk — stop if you catch yourself thinking these) CANT IDs reference the [Catalog of Agent Neutralization Techniques](https://github.com/kanopi/cant): - "I remember the template's shape" (CANT-20 — read `templates/<activity_type>.md` every time) - "The directory won't create, the repo root is fine" (CANT-24 — the path is the contract) - "LGTM is close enough for a checkpoint note" (CANT-12) - "They said the review happened verbally, so the notes requirement is satisfied" (CANT-19 — the notes are the record; verbal review isn't written evidence) - "The record is written, no need to run the validator" (CANT-10) ## Anti-rationalization table This skill's value is the human checkpoint. Under deadline pressure the temptation is to weaken it — don't: | Pressure / rationalization | Correct behavior | |---|---| | "The reviewer is busy — just put their name in and they'll confirm later" | Refuse. `reviewed_by` without real checkpoint notes is a forged signature. | | "LGTM is close enough for Checkpoint 2" | Refuse. The note must say what the reviewer actually looked at beyond the automated gates. | | "Skip the record this once, the PR is tiny" | If the output is client-facing or load-bearing, the record is required regardless of size. Say so and offer to run it. | | "Fill the checks block optimistically — CI will probably pass" | Only record check results that actually ran. Unknown ≠ `pass`; use the real status or wait. | | "Mark unrun audits `n/a` to get to green" | `n/a` means *not applicable*, not *not done*. An applicable-but-skipped check is a `fail` that needs a waiver. | | "The user told me to just write the file without the reviewer" | The refusal is the feature. Abort politely after the third blank/generic input, exactly as specified. | ## Related skills - **delivery-record-verify** — validate a record against the schema and the threshold rule. These live in other Kanopi plugins and pair well when installed: - **pr-create** (cms-cultivator) — run first for code; the Delivery Record is the per-PR artifact that follows. - **commit-message-generator** (cms-cultivator) — appends the per-commit `Assisted-by:` trailer that complements the per-PR record. - **teamwork-integrator** (Kanopi internal) — locate the Delivery Records notebook and post the index comment; without it, follow the manual fallback in step 6.