GH#954: docs(agents): expand guidance for 4 recurring error patterns from superdav42

[superdav42]

What

Expands AGENTS.md agent guidance with four targeted additions for the recurring error patterns reported in issue #954 by contributor superdav42.

Why

The contributor-insight scanner detected 155 total tool failures in four categories. Previous PRs (#944, #949, #952) addressed documentation gaps; issue #954 shows the counts are still increasing for bash:other (+13) and edit:not_read_first (+13). This PR targets two new undocumented failure modes for each.

Changes per error pattern

bash:other (42x, +13 from prior filing) — Two new failure modes added to "Common bash:other Failures":

• PHPUnit --filter not matching: vendor/bin/phpunit --filter NonExistentClass exits 1 with "No tests executed!" — agents should verify test class/method names first using git ls-files 'tests/**/*Test.php'.
• Unquoted glob patterns: git ls-files inc/**/*.php (unquoted) shell-expands before git sees the pattern, producing wrong results. Always quote: git ls-files 'inc/**/*.php'.

edit:not_read_first (39x, +13 from prior filing) — Added a new "New files use Write, not Edit" paragraph clarifying that:

• Edit is for EXISTING files only and requires a prior Read.
• Write is for NEW files and does NOT require a prior Read.
• Before writing a new file, verify the parent directory exists with git ls-files.

read:file_not_found (35x, +2 from prior filing) — Added three new entries to the non-existent paths table:

• inc/class-checkout.php (root-level) → actual path is inc/checkout/class-checkout.php
• inc/class-membership.php (root-level) → model classes are in inc/models/
• lang/*.po, lang/*.mo → only lang/ultimate-multisite.pot is tracked

Verification

Doc-only change. Verified paths with git ls-files:

• inc/class-checkout.php → empty (does not exist at root)
• inc/checkout/class-checkout.php → exists
• lang/ultimate-multisite.pot → exists; no .po/.mo files tracked

Resolves #954

---

aidevops.sh v3.13.0 plugin for OpenCode v1.3.17 with claude-sonnet-4-6 spent 6m and 19,485 tokens on this as a headless worker.

[coderabbitai]

Warning

Rate limit exceeded

@superdav42 has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 18 minutes and 50 seconds before requesting another review.

To keep reviews running without waiting, you can enable usage-based add-on for your organization. This allows additional reviews beyond the hourly cap. Account admins can enable it under billing.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: a9ce081b-6adc-40c1-9a36-3d9ea7bb063c

📥 Commits

Reviewing files that changed from the base of the PR and between 01a87c3 and 4b5be3a.

📒 Files selected for processing (1)

• AGENTS.md

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/auto-20260427-060958-gh954

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

🔨 Build Complete - Ready for Testing!

📦 Download Build Artifact (Recommended)

Download the zip build, upload to WordPress and test:

• Build: ultimate-multisite
• ⬇️ Download from GitHub Actions
• ⬇️ Download without Github Account (nightly.link)

🌐 Test in WordPress Playground (Very Experimental)

Click the link below to instantly test this PR in your browser - no installation needed!
Playground support for multisite is very limitied, hopefully it will get better in the future.

🚀 Launch in Playground

Login credentials: admin / password

[github-actions]

Performance Test Results

Performance test results for b9230ba are in 🛎️!

Note: the numbers in parentheses show the difference to the previous (baseline) test run. Differences below 2% or 0.5 in absolute values are not shown.

URL: /

Run	DB Queries	Memory	Before Template	Template	WP Total	LCP	TTFB	LCP - TTFB
0	41	37.78 MB	885.50 ms (+33.50 ms / +4% )	154.50 ms	1052.50 ms	2034.00 ms (+50.00 ms / +2% )	1941.45 ms (+52.20 ms / +3% )	91.65 ms
1	56	49.03 MB	936.50 ms	146.00 ms (-3.00 ms / -2% )	1082.00 ms	2064.00 ms	1982.95 ms	81.75 ms

[superdav42]

What

Expands AGENTS.md agent guidance with four targeted additions for the recurring error patterns reported in issue #954 by contributor superdav42.

Why

The contributor-insight scanner detected 155 total tool failures in four categories. Previous PRs (#944, #949, #952) addressed documentation gaps; issue #954 shows the counts are still increasing for bash:other (+13) and edit:not_read_first (+13). This PR targets two new undocumented failure modes for each.

Changes per error pattern

bash:other (42x, +13 from prior filing) — Two new failure modes added to "Common bash:other Failures":

• PHPUnit --filter not matching: vendor/bin/phpunit --filter NonExistentClass exits 1 with "No tests executed!" — agents should verify test class/method names first using git ls-files 'tests/**/*Test.php'.
• Unquoted glob patterns: git ls-files inc/**/*.php (unquoted) shell-expands before git sees the pattern, producing wrong results. Always quote: git ls-files 'inc/**/*.php'.
  edit:not_read_first (39x, +13 from prior filing) — Added a new "New files use Write, not Edit" paragraph clarifying that:
• Edit is for EXISTING files only and requires a prior Read.
• Write is for NEW files and does NOT require a prior Read.
• Before writing a new file, verify the parent directory exists with git ls-files.
  read:file_not_found (35x, +2 from prior filing) — Added three new entries to the non-existent paths table:
• inc/class-checkout.php (root-level) → actual path is inc/checkout/class-checkout.php
• inc/class-membership.php (root-level) → model classes are in inc/models/
• lang/*.po, lang/*.mo → only lang/ultimate-multisite.pot is tracked

Verification

Doc-only change. Verified paths with git ls-files:

• inc/class-checkout.php → empty (does not exist at root)
• inc/checkout/class-checkout.php → exists
• lang/ultimate-multisite.pot → exists; no .po/.mo files tracked

---

aidevops.sh v3.13.0 plugin for OpenCode v1.3.17 with claude-sonnet-4-6 spent 6m and 19,485 tokens on this as a headless worker.

---

Merged via PR #955 to main.
Merged by deterministic merge pass (pulse-wrapper.sh).

[superdav42]

Merge Summary

Issue resolved: GH#954 — Contributor insight: 4 recurring error pattern(s) from superdav42

Changes made to AGENTS.md (34 lines added, doc-only):

• bash:other (42x): Added 2 new failure patterns:

  • PHPUnit --filter with no matching test exits 1; verify class/method names with git ls-files 'tests/**/*Test.php'
  • Unquoted glob patterns shell-expand before the command sees them; always quote: git ls-files 'inc/**/*.php'

• edit:not_read_first (39x): Added Write vs Edit distinction:

  • Write tool creates new files without a prior Read; Edit requires a prior Read on existing files
  • Agents should verify parent directory exists before using Write for new files

• read:file_not_found (35x): Added 3 new entries to the non-existent paths table:

  • inc/class-checkout.php (root-level) → actual path is inc/checkout/class-checkout.php
  • inc/class-membership.php (root-level) → model classes are in inc/models/
  • lang/*.po, lang/*.mo → only lang/ultimate-multisite.pot is tracked

Verification: All CI checks passed (PHP Lint, Code Quality, PHP 8.2–8.5, Cypress E2E, WP Performance Metrics). Merged at 9911f4b.