docs: strengthen AGENTS.md to reduce recurring agent error patterns (GH#948)#949
Conversation
…atterns Addresses 4 recurring tool failure modes reported in #948: - webfetch:other (39x): add WooCommerce docs and WP Plugin Handbook to prohibited URL list - read:file_not_found (33x): add inc/functions.php, inc/admin.php, SECURITY.md, coverage-html to do-not-exist table - edit:not_read_first (26x): add concrete anti-pattern/correct-pattern code examples - bash:other (29x): surface all 4 checks in new Quick Session Checklist at top of Agent Guidance Fixes #948
|
MERGE_SUMMARY What was doneStrengthened AGENTS.md agent guidance to address 4 recurring tool failure patterns from issue #948. Changes:
How verified
Resolves #948 aidevops.sh v3.11.3 plugin for OpenCode v1.3.17 with claude-sonnet-4-6 spent 6m and 14,164 tokens on this as a headless worker. |
📝 WalkthroughWalkthrough
Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes Possibly related PRs
Suggested labels
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
🔨 Build Complete - Ready for Testing!📦 Download Build Artifact (Recommended)Download the zip build, upload to WordPress and test:
🌐 Test in WordPress Playground (Very Experimental)Click the link below to instantly test this PR in your browser - no installation needed! Login credentials: |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (1)
AGENTS.md (1)
301-316: Excellent examples that clearly demonstrate the Read→Edit sequencing requirement.The anti-pattern and correct-pattern code blocks make the
edit:not_read_firstfailure mode immediately understandable. The inline comment explaining why the anti-pattern fails is particularly helpful.Optional: Specify language identifier to satisfy markdown linter.
The fenced code blocks at lines 303 and 311 trigger MD040 (fenced-code-language) warnings. Adding a
textidentifier would silence the linter without changing the content.✨ Optional fix for markdown linting
Line 303:
-**Anti-pattern (causes `edit:not_read_first` failure):** - -``` +**Anti-pattern (causes `edit:not_read_first` failure):** + +```text Read(inc/models/class-membership.php)Line 311:
-**Correct pattern:** - -``` +**Correct pattern:** + +```text Read(inc/models/class-membership.php)🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@AGENTS.md` around lines 301 - 316, The fenced code blocks demonstrating the Read→Edit sequencing (the blocks containing the lines starting with "Read(inc/models/class-membership.php)" and the subsequent example blocks showing the anti-pattern and correct pattern) lack a language identifier and trigger MD040; update both fenced code blocks to use a neutral identifier (e.g., ```text) so the examples remain unchanged but the markdown linter is satisfied.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@AGENTS.md`:
- Around line 301-316: The fenced code blocks demonstrating the Read→Edit
sequencing (the blocks containing the lines starting with
"Read(inc/models/class-membership.php)" and the subsequent example blocks
showing the anti-pattern and correct pattern) lack a language identifier and
trigger MD040; update both fenced code blocks to use a neutral identifier (e.g.,
```text) so the examples remain unchanged but the markdown linter is satisfied.
|
Performance Test Results Performance test results for 4176f25 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:
|
* GH#951: add bin/check-env.sh and update AGENTS.md Quick Session Checklist Adds a runnable bash script that checks all development prerequisites in one pass (PHP, composer, npm, wp-cli, WordPress dev env, WP test suite, xdebug) and prints actionable fix instructions for anything missing. Updates AGENTS.md Quick Session Checklist item 4 to surface this script as the first thing to run, consolidating the individual inline checks that were scattered across the section. Rationale: five documentation-only PRs (#920, #929, #933, #944, #949) have already strengthened the written guidance for the four recurring error patterns in issue #951. The remaining gap for bash:other is converting the prerequisite check from prose instructions into a runnable script that exits 1 on failure, so agents can detect missing tools without reading multiple documentation sections. Resolves #951 * fix(check-env): add CWD guard so script always runs from repo root Addresses CodeRabbit review: path-based checks (vendor/, node_modules/, ../wordpress/) are relative to CWD, which caused spurious failures if the script was invoked from a subdirectory or editor task with a non-root CWD. The guard computes the repo root from the script's own location and cd's to it before performing any checks, so the output is always correct regardless of where the caller's working directory was.
1 participant
Summary
Addresses 4 recurring tool failure patterns reported in issue #948 (contributor insight from superdav42):
What changed
EDIT: AGENTS.md - added Quick Session Checklist section, expanded do-not-exist table, added anti-pattern examples, expanded webfetch prohibited list.
Verification
Confirming new do-not-exist entries are absent: git ls-files 'inc/functions.php' 'inc/admin.php' 'SECURITY.md' returns empty for all three.
Resolves #948
aidevops.sh v3.11.3 plugin for OpenCode v1.3.17 with claude-sonnet-4-6 spent 5m and 13,647 tokens on this as a headless worker.
Summary by CodeRabbit