docs(principles): turn feedback into reusable rules - #672
Conversation
Houses the methodology that was removed from cypress-io/cypress.io's design-system-access.md (which is now access-only): how to vet feedback framed as a principle (sounds-principled-but-isn't / conflicts / additive), and the living-document loop for adding principles. Direct-to-canon via PR; no separate staging log. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
cypress-design
 |
||||||||||||||||||||||||||||
| Project |
cypress-design
|
| Branch Review |
ryanjwilke/principles-maintenance-readme
|
| Run status |
|
| Run duration | 02m 17s |
| Commit |
|
| Committer | Ryan Wilke |
| View all properties for this run ↗︎ | |
| Test results | |
|---|---|
 |
0
|
 |
0
|
 |
0
|
 |
0
|
 |
2
|
| View all changes introduced in this branch ↗︎ | |
Warning
No Report: Something went wrong and we could not generate a report for the Application Quality products.
- Rename principles/README.md → principles/learning-from-feedback.md so agents discover it by topic, not by folder convention. - Add "Notice → Extract → Test → Codify" loop at the top so the trigger is every piece of feedback, not just feedback framed as a principle. - Link from .agents/index.md under Principles and cross-link from feedback.md. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
ryanjwilke
changed the title
…comments Principles - learning-from-feedback.md: name the sources of feedback up top (teammates, other agents, Copilot, automation). Rewrite Extract so the agent asks the human for the *why* behind a fix and turns that answer into the rule. Reframe the verbatim quote as a live confirmation with the human during review/reply — not an internal check. - index.md: strengthen the trigger so an agent fetches this on every feedback exchange, not only when "principle" is named. - feedback.md: same trigger language on the cross-link. Skill - cy-review-pr-comments.md: port the cypress.io version's improvements — fetch from any author (not just Copilot), Step 4.5 sign-off before executing, reply-then-resolve back-to-back per thread, hard-stop conditions for Copilot loops. Keep cypress-design's repo policies and known-issues.md path. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Docs-only PR that adds a new .agents/principles/learning-from-feedback.md principle (a Notice → Extract → Test → Codify loop for turning every feedback exchange into a candidate reusable rule), wires it into the agent router and cross-links it from feedback.md, and in the same pass overhauls the cy-review-pr-comments skill to handle reviews from any author (not just Copilot) with safer pagination, root-comment filtering, a user sign-off step, and Copilot re-review hard-stops.
Changes:
- New principle file
learning-from-feedback.mdplus index/cross-link entries to make it discoverable from a cold start. cy-review-pr-commentsbroadened beyond Copilot: noise-bot filter, paginated GraphQL, root-comment-only filtering,TOTAL_INSCOPEsanity check, Step 4.5 sign-off, reply-then-resolve per thread, and Step 7 re-review with hard-stop conditions.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| .agents/principles/learning-from-feedback.md | New principle establishing the Notice → Extract → Test → Codify loop for turning feedback into rules. |
| .agents/principles/feedback.md | Adds a Related-section link to the new principle. |
| .agents/index.md | Registers the new principle in the router with a fetch trigger. |
| .agents/skills/cy-review-pr-comments.md | Broadens scope to all authors, adds pagination, root-comment filter, sanity check, Step 4.5 sign-off, reply-then-resolve, and Copilot re-review hard stops. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
cypress-design
|
||||||||||||||||||||||||||||
| Project |
cypress-design
|
| Branch Review |
main
|
| Run status |
|
| Run duration | 02m 13s |
| Commit |
|
| Committer | Ryan Wilke |
| View all properties for this run ↗︎ | |
| Test results | |
|---|---|
|
|
0
|
|
|
0
|
|
|
0
|
|
|
0
|
|
|
2
|
| View all changes introduced in this branch ↗︎ | |
Warning
No Report: Something went wrong and we could not generate a report for the Application Quality products.
What & why
I keep giving the same feedback in Slack, Zoom, Claude, and GitHub. The goal of this repo is to capture those points once so any agent reviewing Cypress work brings the same perspective I would — as close to cloning my judgment as the system allows.
For that to work, agents need a file that fires on every feedback exchange, not only when someone says the word "principle." That's what
.agents/principles/learning-from-feedback.mddoes. After reading it, a reviewer (human or agent) should:How
.agents/principles/learning-from-feedback.mdwith a Notice → Extract → Test → Codify loop at the top, then the vetting checks (sounds-principled-but-isn't / conflicts / additive refinement) and the PR-as-record path for adding a new principle..agents/index.mdso the router actually surfaces it.principles/feedback.mdso anyone fetched for "giving feedback" also gets this.Replaces what was removed from cypress-io/cypress.io#2517's
design-system-access.md(now correctly access-only). Complements #670 (which added "Apply the principle; don't cite it" tofeedback.md).Where to focus review
feedback.mdorux.mdthat should be removed?Note
Low Risk
Changes are limited to agent guidance and GitHub CLI workflow docs; no application runtime, auth, or data paths are modified.
Overview
Adds
.agents/principles/learning-from-feedback.md, which tells agents to run Notice → Extract → Test → Codify on every feedback exchange (any channel, any author), vet candidates against existing principles, and record new rules via PR tocypress-design. The agent index andfeedback.mdnow route to it;feedback.mdclarifies when to quote principles vs apply them without citation.In the same pass,
cy-review-pr-commentsis broadened from Copilot-only to all unresolved review authors (minus CI noise bots), with safer paginated GraphQL, root-comment-only threading, and aTOTAL_INSCOPEsanity check. Triage adds human-high-signal rules, mandatory Step 4.5 user sign-off before replies/resolves, reply-then-resolve per thread, optional Copilot re-review viagh pr edit, and hard stops to avoid endless review loops.Reviewed by Cursor Bugbot for commit 2881877. Bugbot is set up for automated code reviews on this repo. Configure here.