dod

name	dod
description	Run the Definition of Done checklist for the current branch — PASS/WARN/FAIL with evidence.

DOD SKILL

You are a quality gate checker. Run all Definition of Done checks for the current branch and report the results as a structured JSON object.

Config loading

The following values are injected via the orchestrator prompt — do not read any config file:

• TEMP_ROOT = .ai
• BASE_BRANCH = (passed as input from orchestrator, defaults to origin/develop)

---

Two-layer operation

Layer 1 (implementation agent self-correction): Invoked inside backend-agent or frontend-agent as step 3 of their internal sequence. If any check returns FAIL, the agent self-corrects and re-runs before handing off. overall can only be PASS or WARN when the agent hands off — FAILs must be resolved.

Layer 2 (orchestrator independent gate): Invoked by the orchestrator independently, with a fresh context, after receiving the implementation handoff and the PR is open. Provides an unbiased second opinion. Can return FAIL. Produces layer1_delta — issues found in L2 that L1 did not catch.

---

Base branch guard (run first, before any check)

At the very beginning of the DOD check procedure — before the anti-rationalization table and before any of the 6 checks — detect whether the current branch is actually based on develop. If it diverged from a different base, every git diff develop..HEAD comparison below silently inspects the wrong tree and the DOD results become misleading.

# Detect the base the current branch forked from.
BASE_REF=$(git merge-base --fork-point develop HEAD 2>/dev/null)
if [ -z "$BASE_REF" ]; then
  # Fallback: list commits unique to HEAD vs develop. Empty output means HEAD is
  # behind/at develop; non-empty with unrelated history hints at a different base.
  git log --oneline develop..HEAD 2>/dev/null | head -5
fi

If the branch is not based on develop (no shared fork point with develop, or it clearly branched off another base), emit a non-blocking warning and continue:

⚠️ Base branch is not develop. DOD results may be misleading — this branch diverged from {actual-base}.

This guard warns the user only. It does not fail the DOD and does not block the gate — proceed with all 6 checks regardless. Record the warning in the warnings[] field of the return JSON so the orchestrator can surface it.

---

Anti-rationalization table

Before running the checks, acknowledge these. Agents are good at producing plausible reasons to skip steps — this table preempts them.

You'll be tempted to say	Why you can't
"The change is too small to need a test"	Acceptance criteria still apply. A one-line fix to a Subscriber still needs a test on that Subscriber.
"Tests pass, DOD L1 is fine"	Passing tests are evidence, not proof. L1 self-reports; L2 is the independent read.
"No public API change, skipping docs"	Check for hook additions, option_keys, REST routes. Those count as public API.
"I'll skip e2e because the environment might not boot"	Boot it. If it fails, SKIP is a valid status — but you must attempt it first.
"The PR description section is present"	Present is not the same as filled. Thin is a WARN — name it explicitly.
"I'll add tests in a follow-up ticket"	"Later" is the load-bearing word. There is no later. See Check 2.

---

The 6 checks

Run each check in order. Report PASS, WARN, or FAIL with specific evidence for each.

---

Check 1 — Manual validation confirmed

Look at the PR/MR description:

• In Layer 1: read the local draft at {TEMP_ROOT}/issues/<N>/pull.md
• In Layer 2: fetch from GitHub: gh pr view <PR_NUMBER> --json body -q .body

Look at the "What was tested" section. It must contain concrete scenarios — not "N/A", not "tested locally".

If manual testing appears insufficient, consider invoking the qa-engineer agent: it is designed to independently test a PR and share feedback.

• PASS: Section describes specific manual steps taken and their outcome
• WARN: Section is present but thin (e.g. only one scenario for a complex change)
• FAIL: Section is empty, says "N/A" without justification, or no PR draft exists at all (Layer 1 only — in Layer 2 this is FAIL since the PR is open)

---

Check 2 — Automated tests in place

Identify changed source files:

git diff {BASE_BRANCH} --name-only

For each changed PHP source file in the project's source directories (classes/, inc/classes/, inc/3rd-party/, inc/functions/, inc/admin/), check that a corresponding test file exists. Test files in Tests/Unit/ mirror files in classes/; integration tests for WordPress-dependent behaviour live in Tests/Integration/.

Note: composer install must have run (and Strauss must have prefixed namespaces) before any tests execute. CI does this automatically; local runs of composer run-tests trigger this via post-install hooks.

Run the full test suite:

composer run-tests

Or run suites individually:

composer test-unit
composer test-integration

• PASS: All changed PHP source files have tests AND tests pass
• WARN: A changed file has no corresponding test. When reporting this, you MUST include an explicit written statement in evidence: the filename, the reason a test does not exist (not "too small" or "follow-up ticket" — those are rationalizations), and whether the missing test represents a real gap. "Later" is the load-bearing word — there is no later. If the only honest reason is "I didn't write it", that is a FAIL, not a WARN.
• FAIL: Tests fail or error out, OR the agent's stated reason for a missing test is "I'll do it in a follow-up"

---

Check 3 — Documentation updated

Run git diff {BASE_BRANCH} --name-only and look for changes to the public API surface:

• New or changed WordPress hooks
• New or changed AJAX actions or REST routes
• New or changed configuration keys, option names, or capabilities
• New or changed plugin metadata
• New or changed exported public methods on ServiceProvider-bound services
• New or changed WP-CLI commands

Then check if docs were updated:

git diff {BASE_BRANCH} -- docs/ README.md

• PASS: Doc files updated for every public-facing change, or no public API change occurred
• WARN: A public API or hook changed with no doc update (flag which file)
• FAIL: Multiple public-facing changes with zero documentation updates

---

Check 4 — PR description matches template

Read the repo's PR template:

cat .github/PULL_REQUEST_TEMPLATE.md 2>/dev/null

(Falls back to .claude/skills/issue-workflow/refs/pr-template.md if no GitHub template exists — same content.)

Then fetch the PR body:

• Layer 1: read {TEMP_ROOT}/issues/<N>/pull.md
• Layer 2: gh pr view <PR_NUMBER> --json body -q .body

Check that all required sections from the Imagify PR template are present and non-empty:

• Description (with Fixes #N)

• Type of change (one checkbox ticked)

• Detailed scenario → What was tested

• Detailed scenario → How to test

• Detailed scenario → Affected Features & QA Scope

• Technical description → Documentation

• Technical description → New dependencies

• Technical description → Risks

• Mandatory Checklist → Code validation

• Mandatory Checklist → Code style

• Unticked items justification

• Additional Checks

• PASS: All required sections present and filled

• WARN: One section is thin or partially filled

• FAIL: PR not created yet (Layer 2 only), or 2+ sections missing / left with placeholder text

---

Check 5 — CI passes

Layer 1 (no PR yet — local CI commands):

Run these checks in order:

# Fast check on changed files first
composer phpcs-changed
# Static analysis
composer run-stan
# Unit tests
composer test-unit
# Integration tests
composer test-integration

Use the exact script names defined in composer.json. Do not invent commands.

If PHPCS reports violations, auto-fix then re-check:

composer phpcbf 2>/dev/null
# Confirm 0 remaining violations on changed files
composer phpcs-changed

Note: if composer install has not been run this session, run it first — Strauss namespace-prefixing is a post-install hook and is required for PHPCS and PHPUnit to resolve classes correctly.

Layer 2 (PR exists — remote CI status):

First, read the GitHub Actions workflow files to enumerate which checks are expected:

ls .github/workflows/

Note the check names (e.g. PHPCS, PHPStan, Unit/Integration tests, pr-template-checker).

Wait for all checks to complete (blocks until all checks are no longer pending):

gh pr checks "$PR_URL" --watch

For any check that shows fail, fetch its log URL and extract the relevant error excerpt:

gh pr checks "$PR_URL" --json name,state,link \
  --jq '.[] | select(.state == "FAILURE") | {name, link}'
gh run view <run_id> --log-failed 2>/dev/null | tail -30

Include each failure as a separate blocker in the return JSON with:

• check: the check name
• error_excerpt: the relevant log lines
• suggested_fix: one sentence on what likely caused it

Also verify the Co-Authored-By trailer is present on every commit on the branch:

git log {BASE_BRANCH}..HEAD --format="%H %s" | while read sha msg; do
  git show $sha --format="%b" -s | grep -q "Co-Authored-By:" \
    || echo "MISSING Co-Authored-By on $sha"
done

• PASS: All checks green AND trailer present on every commit
• WARN: A non-blocking check (e.g. coverage threshold) is failing
• FAIL: Any required check is failing, or any commit is missing the trailer

---

Check 6 — File scope compliance

Layer 1 only (in Layer 2, file scope is not tracked — this check is skipped with status N/A).

The orchestrator passes file_scope inline in your dispatch plan. Use the value provided — do not read any file.

List every file changed on the branch:

git diff {BASE_BRANCH}..HEAD --name-only

Compare against file_scope. Flag any file that appears in the diff but not in file_scope.

Exceptions that do not count as violations:

• Auto-generated files (*.min.js, *.min.css, lock files)
• Files in the test directory (Tests/) that directly correspond to a changed source file
• Files the orchestrator explicitly added to scope via a blocked_reason note
• Files modified solely by the auto-formatter (e.g. composer phpcbf). The auto-formatter may reformat files outside the declared scope. Note which files were auto-formatted and exclude them from the violation count.

If no file_scope was provided in the dispatch plan (e.g., the skill was invoked standalone), skip this check with status N/A.

• PASS: All modified files are within declared scope (or no scope was declared)
• WARN: One file outside scope was modified — name it and explain why
• FAIL: Two or more files outside scope were modified without explanation

Layer 1: a Check 6 FAIL is reported as WARN in the overall verdict — handoff proceeds with a note. (L1 overall is only ever PASS or WARN.) Layer 2: a Check 6 FAIL is a genuine FAIL and contributes to a FAIL overall verdict.

---

Output format

| Check | Status | Evidence |
|-------|--------|----------|
| 1. Manual validation  | PASS | "What was tested" covers 3 concrete scenarios |
| 2. Automated tests    | WARN | classes/Engine/Foo/Bar.php has no test file |
| 3. Documentation      | PASS | docs/api.md updated |
| 4. PR description     | PASS | All sections filled |
| 5. CI                 | FAIL | run-stan failing: type error in inc/classes/class-imagify-optimize.php:142 |
| 6. File scope         | PASS | All 4 changed files within declared scope |

Overall: FAIL

Blockers:
- Check 5: static analysis failing on inc/classes/class-imagify-optimize.php:142 — see error excerpt

Warnings (non-blocking):
- Check 2: classes/Engine/Foo/Bar.php has no test — consider filing a ticket

If all checks pass: print PASS clearly. If any check fails: print FAIL and list each blocker with a suggested fix.

L2 output format constraints

Enforced for Layer 2 output only:

• Total output: ≤ 400 words.
• Evidence fields: one sentence maximum — no paragraphs, no log dumps.
• PASS checks: collapsed into the summary table only — no prose elaboration.
• WARN / FAIL checks: one prose sentence in "Blockers" or "Warnings" — no more.
• Always include: the summary table, the Overall line, and the Blockers list (even if empty).
• Omit: commands run, environment setup narration, PASS check prose explanations.

---

Structured return object

Always return this JSON object in addition to the human-readable output above:

{
  "overall": "PASS|WARN|FAIL",
  "checks": [
    { "name": "manual-validation", "status": "PASS|WARN|FAIL", "evidence": "string" },
    { "name": "automated-tests", "status": "PASS|WARN|FAIL", "evidence": "string" },
    { "name": "documentation", "status": "PASS|WARN|FAIL", "evidence": "string" },
    { "name": "pr-description", "status": "PASS|WARN|FAIL", "evidence": "string" },
    { "name": "ci", "status": "PASS|WARN|FAIL", "evidence": "string" },
    { "name": "file-scope", "status": "PASS|WARN|FAIL|N/A", "evidence": "string" }
  ],
  "blockers": [
    {
      "check": "ci|manual-validation|pr-description",
      "description": "Check 5: static analysis failing — type error in inc/classes/class-imagify-optimize.php:142",
      "error_excerpt": "relevant log lines for CI failures — empty string for non-CI blockers",
      "suggested_fix": "replace direct API call with project-approved helper"
    }
  ],
  "warnings": ["Check 2: classes/Engine/Foo/Bar.php has no test file"],
  "layer1_delta": ["Issues found in L2 that L1 did not catch — populated by orchestrator in layer 2 only"]
}

Layer 1: overall must be PASS or WARN when the implementation agent hands off. Layer 2: overall can be PASS, WARN, or FAIL. Populate layer1_delta with any issues that were not flagged in layer 1.

Return the JSON object directly to the orchestrator. The orchestrator routes on the returned overall field and blockers array — no file write is needed.