Dhpk Execution Checklist

---
name: dhpk-execution-checklist
description: "End-of-task self-check for substantive repository changes. Use after the final Edit/Write before replying or smart-commit, especially for source, SQL/repository/migration, auth/crypto/money/upload, high-volume-table, frontend/template-script, harness, policy, or documentation changes. Not for trivial typo-only edits or research/planning with no pending commit. Output: a gated wrap-up reply with changed files, verification, and risks/open questions."
metadata:
  dhpk-invocation-class: "implicit-eligible"
---

# Execution checklist

Use this gate at the wrap-up boundary for substantive edits or a pending commit.
It has three stages: Per-reply, Conditional, and Task-end. Record skips and
blockers in the wrap-up reply; a quiet hook does not prove that a reviewer ran.

> Source: the project's execution policy — project
> `.claude/rules/execution-policy.md` if present, else
> `${CLAUDE_PLUGIN_ROOT}/rules/execution-policy.md`. This skill carries the
> long-form checklist so the policy rule itself stays index-sized.

## When NOT to Use

- Trivial typo-only edits with no triggered safety surface.
- Pure research / planning turns with no Edit/Write and no pending commit.

## Usage

- **Load it at wrap-up** — after the final Edit/Write, before emitting the
  Conclusion, or before `smart-commit` when the change is already staged.
- **Honour the reviewer dispatch model** — triage false positives, dispatch every
  surviving configured reviewer slot in one parallel batch, and record any
  triage-drop or self-accountable skip.

## Per-reply (check after a substantive Edit/Write or before a pending commit)

Four boxes must clear:

1. **TDD pre-run** — Bug fix / feature that touches business logic: did
   `tdd-guide` (or the configured first agent in `review_agents`) run in
   the RED phase, writing the failing test first? Skip for pure docs /
   harness / hook edits.
2. **Final gate ran** — After the Edit/Write, every matching configured reviewer
   slot (the 7-slot default is defined by `review_agents`) either ran, or has an
   explicit "self-accountable skip" reason recorded (e.g. all sentinels clean
   already, session-local agent dispatch unavailable, pure review-feedback fixup).
3. **Output structure complete** —
   `Conclusion → Changed files → Verification → Risks/Open questions`.
   When blocked: `Blocker → Tried → Next viable option`.
4. **Edit-before-Read enforced** — every file_path that was Edit/Write'd
   this turn has been Read in **this session** first. Mass refactor
   (same string across N files) MUST Read each file independently.
   Successive Edits on the same file with linter / parallel-edit risk
   in between: re-Read first. Matching error messages:
   `File has not been read yet` / `File has been modified since read`.

### Mass refactor preference order (avoid N-deep Edit failure chains)

When mechanically replacing across multiple files, **pick the tool
before reaching for Edit**:

- Same string, across many files, mechanical replace (e.g. `array()` → `[]`)
  → **first choice**: `Bash sed -i` or a formatter rule
  (e.g. `php-cs-fixer fix --rules='{array_syntax:{syntax:short}}'`,
  `prettier --write`, `ruff format`).
- Same file, multiple places, needs semantic context preserved →
  `Edit replace_all: true` + Read the file **once** first.
- Across files but each spot has different semantic context → only then
  fall back to multiple Edits (**Read each file independently**).

> Anti-pattern: chain N Edits across N files without Read → 100%
> failure rate × N, wasting tokens and reviewer trigger cost.

## Conditional (only when the trigger fires)

| Trigger | Required check |
|---|---|
| Modifying an existing symbol's body / signature / docblock | `gitnexus_impact({ target, direction:"upstream" })` ran. The append-only exemption is defined solely in `${CLAUDE_PLUGIN_ROOT}/rules/execution-policy.md` Glossary; record its required skip label when applicable. |
| New / modified SQL or repository code | The database-reviewer slot (sentinel `.pending-db-review`) cleared, or a self-accountable skip is recorded. |
| New / modified migration code | The database-reviewer and applicable migration-reviewer slots (sentinels `.pending-db-review` and `.pending-migration-review`) cleared, or each has a self-accountable skip recorded. |
| Auth / crypto / money / file-upload code paths | The security-reviewer slot (sentinel `.pending-security-review`) cleared, or a self-accountable skip is recorded. |
| Repository methods on a high-volume table (the project's hottest tables — typical examples: an event log, an orders / sales table, an inventory table) | `performance-analyzer` (no hook, AI-judgment trigger) ran or skipped with reason. |
| `*.{js,ts,jsx,tsx,vue,svelte}` edit or template-embedded `<script>` change | The frontend-reviewer slot (sentinel `.pending-frontend-review`) cleared, or backfill ran when the hook missed (template-embedded scripts cannot be detected by file-extension hooks — AI judgment must backfill). |
| Pure `.claude/{agents,rules,commands,skills,manifests}/**/*.md` edit | The doc-reviewer slot (sentinel `.pending-doc-review`) cleared. Code-reviewer is not required for pure-doc edits; mixed diffs run both. |
| PHP edit with a runtime-version guard | The applicable polyfill-reviewer slot (sentinel `.pending-polyfill-review`) cleared, or a self-accountable skip is recorded. This slot is module-owned and may be unavailable. |
| Controller / HTTP-entry-point edits | Security-reviewer and code-reviewer both dispatch (in parallel per reviewer dispatch); code-reviewer merges the findings. |
| Edits to a shared `_lib/` hook helper | Run contract tests for ALL hooks that source the helper (e.g. `_lib/js-tier-detect.sh` is consumed by both `post-edit-js-lint.sh` and `pre-commit-js-validation.sh` — verify both still pass). |
| Bash uses bare glob expansion (`ls .pending-*` / `for f in .pending-*`) in a shell **without** `nullglob` (zsh default, dash, BusyBox) | Switch to `find <dir> -maxdepth N -name '<pattern>' -print 2>/dev/null` or append `2>/dev/null \|\| true`. Bare glob with zero matches becomes a literal token in those shells, then often errors as "no such file". Common in sentinel-existence checks. |
| Hand-constructing `clear-sentinel.sh` path | Use the dhpk SSOT: `${CLAUDE_PLUGIN_ROOT}/scripts/hooks/clear-sentinel.sh` (NOT `${CLAUDE_PROJECT_DIR}/.claude/scripts/...`). Reviewer agent bodies shipped in dhpk already use the correct path — compare against them before constructing your own. A subagent must never paste the literal `${CLAUDE_PLUGIN_ROOT}/...` token into a Bash command (it is a markdown-interpolation token, unset in the subagent shell); full caveat SSOT: `@skills/dhpk-execution-policy/references/review-gate-mechanics.md`. |

## Task-end (book-keeping at the very end)

- **Newly discovered trap** → if the project tracks `MEMORY.md` and its policy
  permits updates, decide whether the trap belongs there; do not update
  user-level memory without explicit authorization.
- **Retrospective entry** → if the project tracks a
  `skill-retrospective.md`, append one entry. Refresh aggregate stats
  every ~5 entries.
- **Backlog open items** → any `Risks / Open questions` item that should
  become a `/dhpk:dhpk-create-request` ticket?

## Reviewer dispatch (quick reference)

Triage out false positives → dispatch the surviving configured reviewer slots
**in parallel** (one message, multiple Agent calls) → `code-reviewer` merges / dedups:

```
{ code-reviewer | database-reviewer | security-reviewer | frontend-reviewer | doc-reviewer | polyfill-reviewer | migration-reviewer }   ← parallel
```

- The default is seven slots; `polyfill-reviewer` and `migration-reviewer` are
  module/project-triggered and may be unavailable. Follow `review_agents` and
  the execution-policy SSOT rather than inventing a replacement slot.
- code-reviewer and doc-reviewer are **not mutually exclusive** — a mixed
  diff dispatches both.
- Any reviewer returning CRITICAL blocks the merge/commit; `code-reviewer`
  dedups overlapping findings across the parallel results.
- Pure research / planning (no Edit/Write) skips all reviewers.

The slot-to-agent mapping is `review_agents` userConfig (7-slot default
since v0.10.0; see `agents/INDEX.md`). Re-order or substitute agents per
project via that knob.

## Append-only exemption

Definition and required label live in `${CLAUDE_PLUGIN_ROOT}/rules/execution-policy.md`
Glossary — do not restate here. Checklist-specific reminder: if the change
modifies an existing method signature / class hierarchy / interface
contract, the exemption does not apply — run impact analysis.

## Output

This skill produces no artifact of its own — it shapes the **wrap-up reply**.
At wrap-up the reply MUST follow:

`Conclusion → Changed files → Verification → Risks / Open questions`

When blocked, switch to: `Blocker → Tried → Next viable option`. Any
self-accountable reviewer skip is recorded inline (with its reason) in the
Verification section.

## Verification

- [ ] Per-reply four boxes cleared (TDD pre-run, final gate, output structure, Edit-before-Read).
- [ ] Every conditional trigger that fired has its required check run, or a recorded skip reason.
- [ ] Surviving reviewers dispatched in parallel; any CRITICAL resolved before commit.
- [ ] Task-end book-keeping considered (MEMORY.md / retrospective / backlog tickets).