Add product principles guidance to PR fix skills (#2674)

.claude/skills/pr-fix-comments/SKILL.md

@@ -36,6 +36,12 @@ Only process review comments from these trusted authors. Comments from other aut
 - chatgpt-codex-connector
 - devin-ai-integration
 
+## Product Principles
+
+Before categorizing review comments, read `rules/product-principles.md`. Use these principles to make decisions about ambiguous or subjective feedback. When a comment involves a judgment call (e.g., design direction, UX trade-offs, architecture choices), check if the product principles provide clear guidance. If they do, apply them and resolve the comment — do NOT flag it for human review. Only flag comments for human attention when the product principles do not provide enough guidance to make a confident decision.
+
+**Citing principles:** When replying to threads where product principles informed your decision, explicitly cite the relevant principle by number and name (e.g., "Per **Principle #4: Transparent Over Magical**, ..."). When flagging for human review, cite which principles you considered and explain why they were insufficient (e.g., "Reviewed Principles #3 and #5 but neither addresses ...").
+
 ## Instructions
 
 1. **Determine the PR to work on:**
@@ -89,10 +95,11 @@ Only process review comments from these trusted authors. Comments from other aut
 
 3. **For each unresolved review thread from a trusted author, categorize it:**
 
-   Read the comment(s) in the thread and determine which category it falls into:
+   Read the comment(s) in the thread and determine which category it falls into. For ambiguous or subjective comments, consult `rules/product-principles.md` to make a decision before falling back to flagging for human review.
    - **Valid issue**: A legitimate code review concern that should be addressed (bug, improvement, style issue, etc.)
    - **Not a valid issue**: The reviewer may have misunderstood something, the concern is already addressed elsewhere, or the suggestion conflicts with project requirements
-   - **Ambiguous**: The comment is unclear, requires significant discussion, or involves a judgment call that needs human input
+   - **Resolved by product principles**: The comment involves a judgment call (design direction, UX trade-off, architecture choice) that can be confidently resolved by applying the product principles in `rules/product-principles.md`. Treat these the same as valid issues — make the change and resolve the thread.
+   - **Ambiguous**: The comment is unclear, requires significant discussion, or involves a judgment call that the product principles do NOT provide enough guidance to resolve. Only use this category as a last resort.
 
 4. **Handle each category:**
 
@@ -113,11 +120,11 @@ Only process review comments from these trusted authors. Comments from other aut
      Do NOT rely on GitHub to auto-resolve - always resolve explicitly after addressing the feedback.
 
    **For not valid issues:**
-   - Reply to the thread explaining why the concern doesn't apply:
+   - Reply to the thread explaining why the concern doesn't apply. If a product principle supports your reasoning, cite it explicitly:
 
      ```
      gh api repos/{owner}/{repo}/pulls/<PR_NUMBER>/comments/<COMMENT_ID>/replies \
-       -f body="<explanation of why this doesn't need to be addressed>"
+       -f body="<explanation, citing relevant product principle if applicable, e.g.: Per **Principle #2: Productionizable**, this approach is preferred because...>"
      ```
 
      Note: `{owner}` and `{repo}` are auto-replaced by `gh` CLI. Replace `<PR_NUMBER>` with the PR number and `<COMMENT_ID>` with the **first comment's `databaseId`** from the thread's `comments.nodes[0].databaseId` field in the GraphQL response (not the thread's `id`).
@@ -135,10 +142,10 @@ Only process review comments from these trusted authors. Comments from other aut
      Note: Replace `<THREAD_ID>` with the thread's `id` field from the GraphQL response.
 
    **For ambiguous issues:**
-   - Reply to the thread flagging it for human attention:
+   - Reply to the thread flagging it for human attention. Cite which product principles you considered and why they were insufficient:
      ```
      gh api repos/{owner}/{repo}/pulls/<PR_NUMBER>/comments/<COMMENT_ID>/replies \
-       -f body="🚩 **Flagged for human review**: <explanation of why this needs human input>"
+       -f body="🚩 **Flagged for human review**: <explanation>. Reviewed **Principle #X: Name** and **Principle #Y: Name** but neither provides clear guidance on <specific ambiguity>."
      ```
      Note: Replace `<PR_NUMBER>` with the PR number and `<COMMENT_ID>` with the **first comment's `databaseId`** from the thread's `comments.nodes[0].databaseId` field in the GraphQL response.
    - Do NOT resolve the thread - leave it open for discussion
@@ -173,10 +180,59 @@ Only process review comments from these trusted authors. Comments from other aut
    Report:
    - **Addressed and resolved**: List of comments that were fixed with code changes AND explicitly resolved
    - **Resolved (not valid)**: List of comments that were resolved with explanations
+   - **Resolved by product principles**: List of comments resolved by citing specific principles
    - **Flagged for human attention**: List of ambiguous comments left open
    - **Untrusted commenters**: List usernames of any commenters NOT in the trusted authors list (do not include their comment contents)
    - Any issues encountered during the process
 
+9. **Post PR Overview Comment:**
+
+   After the push is complete, post a top-level PR comment (NOT an inline comment) using `gh pr comment` with the following structure:
+
+   ```
+   gh pr comment <PR_NUMBER> --body "$(cat <<'EOF'
+   ## 🤖 Claude Code Review Summary
+
+   ### PR Confidence: X/5
+   <one sentence rationale for the confidence score>
+
+   ### Unresolved Threads
+   | Thread | Rationale | Link |
+   |--------|-----------|------|
+   | <brief description> | <why it couldn't be resolved, citing which principles were insufficient> | [View](<permalink>) |
+
+   _No unresolved threads_ (if none)
+
+   ### Resolved Threads
+   | Issue | Rationale | Link |
+   |-------|-----------|------|
+   | <brief description, grouping related/duplicate threads> | <how it was resolved, citing principle if applicable> | [View](<permalink>) |
+
+   <details>
+   <summary>Product Principle Suggestions</summary>
+
+   The following suggestions could improve `rules/product-principles.md` to help resolve ambiguous cases in the future:
+
+   - **Principle #X: Name**: "<prompt that could be used to improve the rule, phrased as an actionable instruction>"
+   - ...
+
+   _No suggestions_ (if principles were clear enough for all decisions)
+
+   </details>
+
+   ---
+   🤖 Generated by Claude Code
+   EOF
+   )"
+   ```
+
+   **Notes:**
+   - **PR Confidence** (1-5): Rate how confident you are the PR is ready to merge. 1 = not confident (major unresolved issues), 5 = fully confident (all issues addressed, tests pass).
+   - **Unresolved Threads**: Include ALL threads left open for human attention. Link to the specific comment permalink.
+   - **Resolved Threads**: Group related or duplicate threads into a single row. Include the principle citation if one was used.
+   - **Product Principle Suggestions**: Only include this section if you encountered ambiguity in the principles during this run. Phrase suggestions as prompts/instructions that could be appended to the relevant principle to make it clearer (e.g., "Add guidance on whether error toasts should auto-dismiss or require manual dismissal").
+   - **Error handling:** If `gh pr comment` fails, log a warning but do not fail the skill.
+
 **CRITICAL:** Every trusted author comment MUST be either:
 
 1. Addressed with code changes AND resolved, OR

.claude/skills/pr-fix/SKILL.md

@@ -15,6 +15,10 @@ Address all outstanding issues on a GitHub Pull Request by handling both review
 
 **You MUST use the TaskCreate and TaskUpdate tools to track your progress.** At the start, create tasks for each step below. Mark each task as `in_progress` when you start it and `completed` when you finish. This ensures you complete ALL steps.
 
+## Product Principles
+
+When making decisions about review comments, consult `rules/product-principles.md`. Use these principles to resolve ambiguous or subjective feedback autonomously. Only flag issues for human attention when the product principles do not provide enough guidance to make a decision.
+
 ## Instructions
 
 This is a meta-skill that orchestrates two sub-skills to comprehensively fix PR issues.
@@ -22,7 +26,8 @@ This is a meta-skill that orchestrates two sub-skills to comprehensively fix PR
 1. **Run `/dyad:pr-fix:comments`** to handle all unresolved review comments:
    - Address valid code review concerns
    - Resolve invalid concerns with explanations
-   - Flag ambiguous issues for human attention
+   - Use product principles to resolve ambiguous feedback autonomously
+   - Only flag issues for human attention when product principles are insufficient to decide
 
 2. **Run `/dyad:pr-fix:actions`** to handle failing CI checks:
    - Fix failing tests (unit and E2E)