delivery-record

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/.

⚠️ 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 <type>] [--pr <n>] [--ticket <key>] [--scope <scope>] [--reviewer <handle>]

Inputs (CLI-style flags accepted in the prompt)

• --activity-type <type> — skip detection (code, frd, audit, discovery, design-handoff, strategy, client-comm)
• --pr <n> — override PR detection
• --ticket <key> — set ticket: explicitly
• --scope <feature|fix|chore|milestone|launch|deliverable> — set scope
• --reviewer <handle> — 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 <base>..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/<activity_type>.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). 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:

  python3 scripts/delivery_record_verify.py <draft-path>
  

  (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-<n>-<slug>.md in the current repo. Create the directory if it does not exist. <slug> 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-<slug>.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 · <activity_type> · <title> · <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/. 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:

• "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.