Wp Acf And Content Modeling

WordPress ACF and Content Modeling Skill

Overview

Systematic review skill for WordPress projects that rely on Advanced Custom Fields and custom content architecture. Core principle: a healthy WordPress content model is durable, query-aware, editor-friendly, and predictable to migrate. Review focuses on CPT and taxonomy design, field-group boundaries, naming consistency, storage strategy, ACF JSON synchronization, and the long-term cost of meta-heavy patterns. Report findings grouped by file or subsystem with severity labels (CRITICAL, WARNING, INFO), line references where possible, and concrete remediation guidance.

When to Use

Use when:

• Auditing a plugin or theme that registers custom post types, taxonomies, or ACF field groups
• Reviewing acf_add_local_field_group() or field group JSON exports
• Checking whether repeaters / flexible content are the right fit for the content problem
• Evaluating options pages, relationship fields, clone fields, or block field groups
• Investigating slow admin screens or expensive meta_query usage in content-heavy builds
• Planning a new content model for an editorial site, directory, landing-page builder, or headless setup
• Reviewing ACF JSON sync, field key drift, or environment-to-environment portability

Don't use for:

• Generic plugin architecture without meaningful ACF/content-model work (use wp-plugin-development)
• Pure REST route design (use wp-rest-api-development)
• Gutenberg block implementation details unrelated to field modeling (use wp-block-development)
• Performance audits not tied to content schema or metadata access (use wp-performance-review)
• WooCommerce domain modeling (use wp-woocommerce-dev unless the issue is truly generic ACF modeling)

Review Workflow

Follow this seven-step workflow.

1. Identify the model boundary

   • What is the real domain: articles, locations, staff, products, events, landing pages, settings, or reusable content fragments?
   • Determine whether the model is single-site, multisite, or headless-facing.
   • Inventory CPTs, taxonomies, options pages, and field groups before evaluating implementation quality.

2. Check core content entities first

   • Validate each CPT has a clear purpose and does not merely duplicate posts/pages without a reason.
   • Check whether taxonomies model classification and relationships better than extra text/meta fields.
   • Flag overloaded post types used as catch-alls for unrelated content.

3. Review field-group architecture

   • Inspect location rules, naming conventions, instructions, conditional logic, defaults, and required flags.
   • Check whether field groups are split by editorial task instead of becoming giant monoliths.
   • Verify repeaters and flexible content are used intentionally, not as a substitute for missing entity design.

4. Scan for CRITICAL patterns

   • Field names or data shapes changed without a migration path.
   • Environment-specific field keys relied on directly in code.
   • Content that should be relational or taxonomic stored as plain text blobs.
   • Massive meta_query dependence for core archive/search behavior with no mitigation.
   • Flexible-content or repeater structures used where separate entities are clearly required.
   • Options-page values treated as request-specific content without cache or invalidation awareness.

5. Check WARNING patterns

   • Ambiguous field names (title, image, link) with no domain prefix or context.
   • Duplicate field groups or cloned definitions drifting across environments.
   • Relationship/post object fields with no return-format consistency.
   • Fields exposed to editors with weak instructions, no defaults, or unclear conditional logic.
   • ACF JSON enabled inconsistently or committed unreliably.
   • Repeater-heavy landing pages likely to become impossible to query, reuse, or migrate.

6. Note INFO improvements

   • Taxonomies could improve filtering, SEO, or editorial consistency.
   • An options page could replace duplicated per-page settings.
   • A custom table may be justified for high-volume structured data.
   • Shared components may benefit from clone fields or a reusable block strategy.
   • Field instructions, tabs, and groups could reduce editor error rates.

7. Report with context-aware severity

   • Enterprise/editorial site: prioritize governance, migration safety, query behavior, and authoring ergonomics.
   • Marketing/landing-page builder: prioritize maintainability and editorial constraints over abstract purity.
   • Headless site: prioritize schema stability, API exposure shape, and relationship modeling.
   • Add cross-skill notes when findings should be followed by wp-rest-api-development, wp-performance-review, or wp-block-development.

Model-Level Checks

Content Type Design (ACF-01)

CRITICAL

• Multiple unrelated business concepts forced into one CPT with flags like type, layout, or kind doing all the work
• A CPT exists only to simulate grouped fields that belong on an existing content type
• Important relational content stored in serialized arrays or long text fields instead of structured entities

WARNING

• CPT labels, supports, or archive behavior do not match editorial intent
• Post types rely on custom fields for primary titles or slugs when core title/slug should carry that job
• Content discoverability depends entirely on custom sorting/meta instead of taxonomy or date semantics

INFO

• A taxonomy may be better than another boolean/select field
• A small reusable post type may simplify repeated section content or shared landing-page fragments

Taxonomy Design (ACF-02)

CRITICAL

• Taxonomy-worthy classification modeled as free-text fields, causing duplicate spellings and broken filters
• Relationship semantics forced into repeated text/select fields instead of terms or relationship fields

WARNING

• Taxonomies are too broad, mixing audience, topic, location, and workflow state in one structure
• A hierarchical taxonomy is used where flat tagging would be simpler, or vice versa
• Term metadata is added for core entity content that likely deserves its own entity instead

INFO

• Taxonomies can often replace fragile editor-entered labels and improve queryability

Field Naming and Schema Stability (ACF-03)

CRITICAL

• Code depends on field keys like field_123abc instead of stable field names when not required
• Field names renamed with no migration or backward-compatibility handling
• Two unrelated fields share nearly identical names across contexts, leading to template confusion

WARNING

• Names are too generic (title, cta, copy, image) and lose meaning outside one template
• Prefixing is inconsistent across domains (hero_, event_, team_ mixed unpredictably)
• Return formats vary silently between field groups for the same conceptual field

INFO

• Prefix related fields by domain or component to improve grepability and future migrations