Editorial models and field evolution

Read references/engineering-contract.md first. Review requests stay read-only: assess, explain and recommend without edits, schema or data changes, wp acf json sync|import, backfills, or running untrusted code. Use the implementation path only when the request authorizes changes.

Applicability

Confirm that ACF or Secure Custom Fields is active, or that its registrations exist (acf/init, acf_add_local_field_group, an acf-json/ folder, get_field). If not, report Not used in this project for the ACF parts. Review plain post type and taxonomy modeling only when the request asks for it.

Inputs to establish

ACF edition and version (or Secure Custom Fields), WordPress version, where field definitions live (database, Local JSON path, PHP), field keys and names involved, return formats, record volume per post type, consumers of the data (templates, blocks, REST, GraphQL, feeds, imports), multisite and translation plugin use, and whether a disposable copy of the site exists.

Inspect project evidence before asking. State material assumptions.

Route the task

Hand off: block structure and Interactivity API to wp-devkit-block-development; WPGraphQL schema and caching to wp-devkit-headless-and-wpgraphql; REST route design and permissions to wp-devkit-rest-api-development; deployment of schema changes to wp-devkit-ci-cd-and-release-engineering; broad data upgrade strategy to wp-devkit-migration-upgrade-review; XSS or authorization defects with a reachable path to wp-devkit-security-review; measured whole-site slowness to wp-devkit-performance-review.

Code Review Workflow

1. Name the entities, their lifecycle needs and their consumers. Check the modeling choice against the decision table before judging field types.
2. Find the schema authority (database, Local JSON, PHP) and verify duplicates, load paths and key/name stability. Do not conclude from one file.
3. Trace each value from storage through formatting to the sink. Check return format, reference meta, escaping at output and exposure through REST/GraphQL.
4. Check every write path (admin, acf_form, REST, import, WP-CLI, update_field calls) enforces the same domain rules.
5. For queries, count participating records, inspect key/type/format, and measure or EXPLAIN before calling a query slow.
6. For a model change, map old to new, list consumers, and define backfill, dual-read, verification and rollback. Review does not run them.

A finding needs a reachable path and impact. A different modeling opinion without a demonstrated cost is INFO. Insufficient evidence (no data volume, no access to the production schema) is a valid outcome: say what is missing and how to get it.

Implementation workflow

1. Define expected behavior and the smallest affected boundary; name the schema authority you will edit.
2. Edit definitions in the authority (JSON/PHP), never only in a production admin screen. Keep field keys; change names only with a migration.
3. Write the migration idempotent, resumable and dry-run by default; test on a copy; keep the old data until verified.
4. Update every consumer in the same change set (templates, blocks, REST/GraphQL, imports).
5. Run the acceptance checks; report unavailable checks as unexecuted. Deployment and live data changes need their own task scope and a backup.

Search Patterns for Quick Detection

Read-only leads from the project root; matches are candidates, not findings. Exit 0 means a match, 1 none, 2 an error.

rg -n -g '*.php' -g '!vendor' -g '!node_modules' -e 'register_post_type|register_taxonomy|register_(post|term)_meta|show_in_rest|capability_type|map_meta_cap' .
rg -n -g '*.php' -g '*.json' -g '!vendor' -g '!node_modules' -e 'acf_add_local_field_group|acf/settings/(save|load)_json|acf/json/|return_format|"key": "(field|group)_' .
rg -n -g '*.php' -g '!vendor' -g '!node_modules' -e 'update_field|add_row|update_row|acf/validate_value|acf/save_post|acf_form' .
rg -n -g '*.php' -g '!vendor' -g '!node_modules' -e "meta_query|'meta_key'|orderby.*meta_value|LIKE|get_field\(|the_field\(|get_sub_field\(" .

No match does not prove absence (helpers, generated code, JSON-only schemas). Output escaping is judged at the final sink, not by the presence of get_field.

Acceptance checks

• Schema: wp acf json status (ACF 6.8+, read-only) or compare acf-json against the database list; a fresh checkout plus sync reproduces the schema on a disposable site.
• Values: wp post meta list <id> for stored value and reference; render the page; compare get_field( $name, $id, false ) and formatted output.
• Validation: an invalid value rejected on each write path (admin form, REST, import).
• REST: GET /wp-json/wp/v2/<type>/<id>?acf_format=standard as anonymous and as a low-privilege user; no unintended fields.
• Queries: EXPLAIN or Query Monitor numbers before and after, on realistic volume.
• Migration: counts old vs new vs mismatched equal expectations; rollback path tested before old data is deleted.
• Static: phpcs WordPress standards and project PHPStan, if configured.

A pass proves the tested paths, volume and versions. It does not prove production data cleanliness, untested write paths, other consumers of the old field, or behavior of a different ACF/SCF edition.

Output Format

Review: result and scope first. Each confirmed finding: severity per the contract, file:line, actor, trigger, reachable path, impact, confidence, minimal remediation, regression check. Candidates and missing evidence in a separate list. Modeling recommendations state the decision, the reason, affected consumers and migration needs.

Implementation: changed boundaries, schema authority edited, migration steps with dry-run output, commands run with exit status, checks not run, residual risk, rollback.

References

• references/content-modeling-decisions.md: read for CPT/taxonomy/field choice and registration arguments.
• references/schema-authority-and-sync.md: read for Local JSON, PHP, database, sync and drift.
• references/values-validation-and-output.md: read for reads, writes, validation, REST, escaping, blocks.
• references/meta-queries-and-field-migrations.md: read for meta-query cost, renames, backfills.