implement-task: add Step 10 invariant capture audit#40
Conversation
After the review cycle settles, prompt the agent to self-audit whether implementation or review surfaced any invariant the next agent doing similar work would want to know up front. Most tasks answer no and exit cleanly. When the answer is yes, the agent opens a separate docs-only PR off fork/trunk touching AGENTS.md or docs/ — never bundled with the implementation PR. This closes the invariants-graduation gap that's been ad-hoc so far — authors had to remember to update package docs on their own initiative, and learnings like the eslint-disable-line mechanism (PR #36) or the withTooltips prop requirement got captured only because somebody happened to think of it. The audit prompt makes capture systematic without forcing busywork: it's non-blocking, and most tasks have nothing to capture. Concrete trigger examples are pulled from real recent surprises so the agent has a template for "yes" vs "no". A new HARD rule enforces the docs-PR-must-be-separate constraint. Discussed with @chi-hsuan.huang on RSM-3462. Implements item (3) of the inner-loop three-layer model. Item (1) (issue clarity at dispatch) and item (2) (PR review cycle handles clarification) need no new work. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
Thank you for your PR! When contributing to Jetpack, we have a few suggestions that can help us test and review your patch:
This comment will be updated as you work on your PR and make changes. If you think that some of those checks are not needed for your PR, please explain why you think so. Thanks for cooperation 🤖 🔴 Action required: Please include detailed testing steps, explaining how to test your change, like so: 🔴 Action required: We would recommend that you add a section to the PR description to specify whether this PR includes any changes to data or privacy, like so: Follow this PR Review Process:
If you have questions about anything, reach out in #jetpack-developers for guidance! |
There was a problem hiding this comment.
Pull request overview
Adds a new Step 10 ("Invariant capture audit") to the premium-analytics-implement-task skill, prompting the agent to capture newly-learned invariants in a separate docs-only follow-up PR off fork/trunk after the review cycle settles. Frontmatter description is updated and a new HARD rule enforces the separation between implementation and docs PRs.
Changes:
- Add Step 10 with self-audit question, "yes" triggers, destination guidance (AGENTS.md vs docs/), and the exact shell sequence for the follow-up PR.
- Update frontmatter
descriptionto mention the audit step. - Add HARD rule forbidding bundling the invariant-capture PR with the implementation PR/branch.
Summary
.agents/skills/premium-analytics-implement-task.md, run after the review cycle has settleddescriptionto mention the audit stepRefs: RSM-3462 item (3) of the three-layer-model discussion (partial — only the invariants-graduation layer; items 1 and 2 require no work per comment on RSM-3462).
What Step 10 does
Asks the agent one self-audit question while context is still warm:
The skill gives concrete "yes" triggers — required-but-non-obvious props (e.g.
withTooltips), lint-pipeline workarounds (e.g. inline vsnext-lineeslint-disable), load-bearing build/boot steps — all pulled from real surprises in past milestone tasks.fork/trunk(never on the implementation branch) touching onlyAGENTS.mdordocs/. The skill includes the exact shell sequence for branching, changelogger entry, commit, push, and/jetpack-pr.Why now
Today, invariants graduation is ad-hoc — authors update
AGENTS.mdif they happen to think of it. The 4-roundeslint-disable-linemechanism saga (PR #36) and thewithTooltipsprop requirement got captured only because someone remembered. This Step makes capture systematic without busywork: non-blocking, most tasks answer no, and when they answer yes the docs PR is small and scoped.Test plan
fork/trunk, changelog entry, no implementation-file contamination)🤖 Generated with Claude Code