Add triggers for creating doc PRs when there are any changes in Free Abilities

[leonidasmi]

Fixes #

Summary

Relevant technical choices

Technical choices that affect more than this issue:

Test instructions

This PR can be acceptance tested by following these steps:
1.
1.
1.

Quality assurance

• Security - I have thought about any security implications this code might add.
• Performance - I have checked that this code doesn't impact performance (greatly).
• Caching - I have analyzed the caching methods that this code touches and have added instructions to deal with those.
• Tested - I have tested this code to the best of my abilities.
• Automated tests - I have added unit tests to verify the code works as intended.
• Testability - I have added unique ids to elements, so they can be located in automated testing.
• I have altered a filename.
  • I have adjusted the ID property accordingly and updated all internal links.
  • I have added the redirect to the _redirects file in the root of the project.

[enricobattocchi]

I tested this change in two ways.

1. Local test of the detection step

I took the detection script from this branch and ran it against real wordpress-seo diffs, built with the same git diff command and exclusions the workflow uses.

Diff	watch_paths set	Result
28.7-RC1 to 28.7-RC2	yes	agent invoked (1 file under src/abilities/)
28.7-RC1 to 28.7-RC2	no, or null	fast-path (agent skipped), same as the scheduled run on Oct 5
28.6 to 28.7-RC1	yes	agent invoked (1 file under src/abilities/)
28.6-RC1 to 28.6	yes	fast-path, no abilities changes. The comment text renders the new "no changes under the watched paths (src/abilities/)" clause correctly

The file that triggers it is src/abilities/user-interface/abilities/update-post-seo-data-ability.php. In 28.7-RC2 that change removed the AI Generate upsell from the ability's input schema field descriptions, which is documented surface. The scheduled run on Oct 5 skipped the agent for it, so this PR fixes a real miss.

2. Manual run on GitHub from this branch

Run: https://github.com/Yoast/developer/actions/runs/37451786010 (product=wordpress-seo, rc_tag=28.7-RC2)

• The detection step logged "Public surface detected" with 1 changed file under src/abilities/, and the job went down the agent path instead of the fast-path.
• The Claude agent itself did not execute: the action reports "Action skipped due to workflow validation error", which happens whenever the workflow file on the branch differs from the one on main. That is a limitation of the action, not of this PR.
• Because issue RC docs-sync audit log — Yoast SEO #390 already had the 28.7-RC2 marker from Oct 5, the safety-net step posted nothing and no PRs were opened. The run left no trace apart from its logs.

Conclusion

The trigger change works. The one thing a branch run cannot show is the agent's actual output for the abilities change. After merging, trigger the workflow with the same inputs to get the real doc PR for 28.7-RC2.

[cloudflare-workers-and-pages]

Deploying yoast-developer with    Cloudflare Pages

Latest commit:	4de7eb2
Status:	✅  Deploy successful!
Preview URL:	https://4db6a664.yoast-developer.pages.dev
Branch Preview URL:	https://enhance-triggers-for-auto-ge.yoast-developer.pages.dev

View logs

[Copilot]

Copilot review overview

🟢 Approval recommended

Watch-path detection and agent guidance are consistent, with no unresolved findings.

Review effort: Balanced
Findings: None

What changed in this PR

Extends release-candidate documentation automation to detect Free Abilities changes and evaluate whether documentation PRs are needed.

Changes:

• Invokes the agent for changes under src/abilities/ and records changed paths.
• Adds abilities documentation mapping and public-surface guidance.
• Preserves zero-PR outcomes when changes do not affect documented behavior.

File	Description
AGENT_MAP.md	Maps abilities source and documentation paths; clarifies public-surface rules.
.github/​workflows/​rc-docs-sync.yml	Adds watch-path detection and passes matching paths to the agent.
.github/​claude-agent/​run.md	Guides watched-file triage and exempts abilities from internal-surface heuristics.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.