Allow agents to do a single round of self-check after PR creation

.cursor/rules/strapi-docs-orchestrator.mdc

@@ -41,12 +41,18 @@ You are a documentation review assistant for Strapi. You help review documentati
        │   Style     │            └──────┬──────┘
        │   Checker   │                   │
        └──────┬──────┘                   ▼
-              │                    ┌─────────────┐
-              ▼                    │   Style     │
-       ┌─────────────┐            │   Checker   │
-       │  Integrity  │            └──────┬──────┘
+              │                    ┌──────────────┐
+              ▼                    │ Self-Review  │
+       ┌─────────────┐            │ (OC+UX+SC)  │
+       │  Integrity  │            └──────┬───────┘
        │   Checker   │                   │
        └─────────────┘                   ▼
+                                   ┌──────────────┐
+                                   │ Auto-Correct │
+                                   │ (if errors)  │
+                                   └──────┬───────┘
+                                          │
+                                          ▼
                                    ┌─────────────┐
                                    │  Integrity  │
                                    │   Checker   │
@@ -88,7 +94,7 @@ Otherwise, the Outliner runs a Quick Check.
 
 **Sequence:**
 ```
-Router → Outliner (Generator) if needed → Drafter → Style Checker → Integrity Checker
+Router → Outliner (Generator) if needed → Drafter → Self-Review (Outline Checker + UX Analyzer + Style Checker) → Auto-Correct (if errors) → Integrity Checker
 ```
 
 **Use cases:**
@@ -112,9 +118,9 @@ Router → Outliner (Generator) if needed → Drafter → Style Checker → Inte
 | "check links", "verify paths" | **Integrity Checker** | *(coming soon)* |
 | "review this PR" | **Router** → **Outliner** (auto-selects Quick or Full) → **Style Checker** | `router.md` → `outliner.md` → `style-checker.md` |
 | "full review" | **Router** → **Outliner** (Full Review: Checker + UX) → **Style Checker** | `router.md` → `outliner.md` → `style-checker.md` |
-| "create docs for...", "document this feature" | **Auto-chain** (see below) | `router.md` → `outline-generator.md` → `drafter.md` |
-| "how do I update docs with this?", "update docs with this", "how should I update the documentation?" | **Auto-chain** (see below) | `router.md` → `outline-generator.md` → `drafter.md` |
-| User provides source material (PR, diff, spec) + asks to document/update it | **Auto-chain** (see below) | `router.md` → `outline-generator.md` → `drafter.md` |
+| "create docs for...", "document this feature" | **Auto-chain** (see below) | `router.md` → `outline-generator.md` → `drafter.md` → `outline-checker.md` + `style-checker.md` |
+| "how do I update docs with this?", "update docs with this", "how should I update the documentation?" | **Auto-chain** (see below) | `router.md` → `outline-generator.md` → `drafter.md` → `outline-checker.md` + `style-checker.md` |
+| User provides source material (PR, diff, spec) + asks to document/update it | **Auto-chain** (see below) | `router.md` → `outline-generator.md` → `drafter.md` → `outline-checker.md` + `style-checker.md` |
 | User provides spec/story/ticket without instructions | **Router** (Create Mode) | `router.md` |
 | User pastes Markdown without instructions | Ask: review or create? | — |
 
@@ -162,9 +168,32 @@ Step 2: DISPATCH targets (process in priority order: primary → required → op
   └─ FOR EACH optional target:
       └─ RUN Drafter in Micro-edit mode → produce Micro-edit artifact
 
-Step 3: OUTPUT all deliverables as separate artifacts
+Step 3: OUTPUT all Drafter deliverables as separate artifacts
+
+Step 4: SELF-REVIEW (automatic, no pause)
+  ├─ FOR EACH Drafter output:
+  │   ├─ Read outline-checker.md spec
+  │   ├─ RUN Outline Checker (template compliance)
+  │   ├─ IF action was create_page:
+  │   │   ├─ Read outline-ux-analyzer.md spec
+  │   │   └─ RUN UX Analyzer (reader experience)
+  │   ├─ Read style-checker.md spec
+  │   └─ RUN Style Checker (12 Rules compliance)
+  │
+  └─ COLLECT all review reports
+
+Step 5: AUTO-CORRECT (conditional, max 1 retry per target)
+  ├─ IF any review report contains errors:
+  │   ├─ FOR EACH target with errors:
+  │   │   ├─ Inject review report(s) as context
+  │   │   └─ RE-RUN Drafter (same mode) with corrections
+  │   └─ OUTPUT corrected artifacts (replace originals)
+  │
+  └─ IF no errors or warnings (suggestions only):
+     └─ Append review summary to each artifact as a
+        <!-- drafter:review-notes --> comment block
 
-Step 4: (Optional) Offer Style Checker as follow-up
+Step 6: OUTPUT final deliverables + Self-Review Report artifact
 ```
 
 ### Auto-chain rules
@@ -173,10 +202,11 @@ Step 4: (Optional) Offer Style Checker as follow-up
 2. **Do NOT stop after the Router to ask "should I continue?"** — the chain is automatic. Only pause for `ask_user` or critical errors.
 3. **Output each deliverable as a separate Markdown artifact** with a descriptive title (e.g., "Routing Report — MCP Server feature", "Draft — cms/features/mcp-server.md").
 4. **State the chain upfront.** At the start, tell the user what will run:
-   > "Running **Create / Update Mode**: Router → Outline Generator → Drafter"
-5. **Style Checker is deferred by default.** In auto-chain, the goal is to produce drafts quickly. Offer the Style Checker as a follow-up after delivery, unless the user explicitly asked for a "full review".
+   > "Running **Create / Update Mode**: Router → Outline Generator → Drafter → Self-Review → Auto-Correct (if needed)"
+5. **Self-review runs automatically after the Drafter.** The Outline Checker, UX Analyzer (for `create_page` targets), and Style Checker run on every Drafter output. If errors or warnings are found, the Drafter re-runs once with the review reports as context. Suggestions are appended as review notes but do not trigger a retry. Maximum 1 retry per target — never more.
 6. **Handle multiple targets sequentially.** Process primary targets first, then required, then optional.
 7. **Respect `conditional` targets.** Do not process them until the condition is resolved.
+8. **Self-review severity threshold.** `[error]` and `[warning]` findings trigger a Drafter retry. Only `[suggestion]` findings are reported without causing re-runs. This prevents infinite loops while catching clear rule violations (e.g., "easy/simple" slipping through, missing backticks on file paths, procedures not in numbered lists).
 
 ### When Outline Generator is needed vs. straight to Drafter
 
@@ -240,7 +270,7 @@ Always tell the user which prompt is executing and in which mode:
 
 > "Running **Style Checker** on `account-billing.md`..."
 
-> "Running **Create / Update Mode** (auto-chain): Router → Outline Generator → Drafter"
+> "Running **Create / Update Mode** (auto-chain): Router → Outline Generator → Drafter → Self-Review → Auto-Correct (if needed)"
 
 > "Running **Outliner** (Full Review: Checker + UX Analyzer) on `admin-configuration-customization.md` — new file, 1103 lines..."
 
@@ -831,6 +861,6 @@ tags: [...]
 6. **[ux-low]** Nice-to-have UX improvement
 ```
 
-**Create / Update Mode output:** A series of artifacts produced by the auto-chain (Routing Report, Outline Report if applicable, Draft/Patch/Micro-edit for each target). No consolidated report — each artifact stands alone.
+**Create / Update Mode output:** A series of artifacts produced by the auto-chain (Routing Report, Outline Report if applicable, Draft/Patch/Micro-edit for each target, Self-Review Report). Each artifact stands alone. The Self-Review Report consolidates findings from Outline Checker, UX Analyzer, and Style Checker. If errors triggered a Drafter retry, the corrected artifacts replace the originals and the Self-Review Report notes which targets were corrected.
 
-**Behavioral rules:** Determine mode first. State mode explicitly. Execute prompts in sequence. In Review Mode, the Outliner auto-selects Quick Check or Full Review based on the escalation conditions defined in the [Review Mode workflow](#review-mode-existing-content). In auto-chain mode, do not pause between steps unless `ask_user` is set. Deduplicate issues across prompts. Prioritize errors → warnings → ux-high → suggestions → ux-medium → ux-low.
+**Behavioral rules:** Determine mode first. State mode explicitly. Execute prompts in sequence. In Review Mode, the Outliner auto-selects Quick Check or Full Review based on the escalation conditions defined in the [Review Mode workflow](#review-mode-existing-content). In auto-chain mode, do not pause between steps unless `ask_user` is set. After the Drafter, run Self-Review automatically (Outline Checker + UX Analyzer for new pages + Style Checker). If errors are found, re-run the Drafter once per target with review reports as context. Deduplicate issues across prompts. Prioritize errors → warnings → ux-high → suggestions → ux-medium → ux-low.

agents/prompts/claude-project-instructions.md

@@ -35,12 +35,18 @@ You are a documentation review assistant for Strapi. You help review documentati
        │   Style     │            └──────┬──────┘
        │   Checker   │                   │
        └──────┬──────┘                   ▼
-              │                    ┌─────────────┐
-              ▼                    │   Style     │
-       ┌─────────────┐            │   Checker   │
-       │  Integrity  │            └──────┬──────┘
+              │                    ┌──────────────┐
+              ▼                    │ Self-Review  │
+       ┌─────────────┐            │ (OC+UX+SC)  │
+       │  Integrity  │            └──────┬───────┘
        │   Checker   │                   │
        └─────────────┘                   ▼
+                                   ┌──────────────┐
+                                   │ Auto-Correct │
+                                   │ (if errors)  │
+                                   └──────┬───────┘
+                                          │
+                                          ▼
                                    ┌─────────────┐
                                    │  Integrity  │
                                    │   Checker   │
@@ -82,7 +88,7 @@ Otherwise, the Outliner runs a Quick Check.
 
 **Sequence:**
 ```
-Router → Outliner (Generator) if needed → Drafter → Style Checker → Integrity Checker
+Router → Outliner (Generator) if needed → Drafter → Self-Review (Outline Checker + UX Analyzer + Style Checker) → Auto-Correct (if errors) → Integrity Checker
 ```
 
 **Use cases:**
@@ -106,9 +112,9 @@ Router → Outliner (Generator) if needed → Drafter → Style Checker → Inte
 | "check links", "verify paths" | **Integrity Checker** | *(coming soon)* |
 | "review this PR" | **Router** → **Outliner** (auto-selects Quick or Full) → **Style Checker** | `router.md` → `outliner.md` → `style-checker.md` |
 | "full review" | **Router** → **Outliner** (Full Review: Checker + UX) → **Style Checker** | `router.md` → `outliner.md` → `style-checker.md` |
-| "create docs for...", "document this feature" | **Auto-chain** (see below) | `router.md` → `outline-generator.md` → `drafter.md` |
-| "how do I update docs with this?", "update docs with this", "how should I update the documentation?" | **Auto-chain** (see below) | `router.md` → `outline-generator.md` → `drafter.md` |
-| User provides source material (PR, diff, spec) + asks to document/update it | **Auto-chain** (see below) | `router.md` → `outline-generator.md` → `drafter.md` |
+| "create docs for...", "document this feature" | **Auto-chain** (see below) | `router.md` → `outline-generator.md` → `drafter.md` → `outline-checker.md` + `style-checker.md` |
+| "how do I update docs with this?", "update docs with this", "how should I update the documentation?" | **Auto-chain** (see below) | `router.md` → `outline-generator.md` → `drafter.md` → `outline-checker.md` + `style-checker.md` |
+| User provides source material (PR, diff, spec) + asks to document/update it | **Auto-chain** (see below) | `router.md` → `outline-generator.md` → `drafter.md` → `outline-checker.md` + `style-checker.md` |
 | User provides spec/story/ticket without instructions | **Router** (Create Mode) | `router.md` |
 | User pastes Markdown without instructions | Ask: review or create? | — |
 
@@ -156,9 +162,32 @@ Step 2: DISPATCH targets (process in priority order: primary → required → op
   └─ FOR EACH optional target:
       └─ RUN Drafter in Micro-edit mode → produce Micro-edit artifact
 
-Step 3: OUTPUT all deliverables as separate artifacts
+Step 3: OUTPUT all Drafter deliverables as separate artifacts
+
+Step 4: SELF-REVIEW (automatic, no pause)
+  ├─ FOR EACH Drafter output:
+  │   ├─ Read outline-checker.md spec
+  │   ├─ RUN Outline Checker (template compliance)
+  │   ├─ IF action was create_page:
+  │   │   ├─ Read outline-ux-analyzer.md spec
+  │   │   └─ RUN UX Analyzer (reader experience)
+  │   ├─ Read style-checker.md spec
+  │   └─ RUN Style Checker (12 Rules compliance)
+  │
+  └─ COLLECT all review reports
+
+Step 5: AUTO-CORRECT (conditional, max 1 retry per target)
+  ├─ IF any review report contains errors:
+  │   ├─ FOR EACH target with errors:
+  │   │   ├─ Inject review report(s) as context
+  │   │   └─ RE-RUN Drafter (same mode) with corrections
+  │   └─ OUTPUT corrected artifacts (replace originals)
+  │
+  └─ IF no errors or warnings (suggestions only):
+     └─ Append review summary to each artifact as a
+        <!-- drafter:review-notes --> comment block
 
-Step 4: (Optional) Offer Style Checker as follow-up
+Step 6: OUTPUT final deliverables + Self-Review Report artifact
 ```
 
 ### Auto-chain rules
@@ -167,10 +196,11 @@ Step 4: (Optional) Offer Style Checker as follow-up
 2. **Do NOT stop after the Router to ask "should I continue?"** — the chain is automatic. Only pause for `ask_user` or critical errors.
 3. **Output each deliverable as a separate Markdown artifact** with a descriptive title (e.g., "Routing Report — MCP Server feature", "Draft — cms/features/mcp-server.md").
 4. **State the chain upfront.** At the start, tell the user what will run:
-   > "Running **Create / Update Mode**: Router → Outline Generator → Drafter"
-5. **Style Checker is deferred by default.** In auto-chain, the goal is to produce drafts quickly. Offer the Style Checker as a follow-up after delivery, unless the user explicitly asked for a "full review".
+   > "Running **Create / Update Mode**: Router → Outline Generator → Drafter → Self-Review → Auto-Correct (if needed)"
+5. **Self-review runs automatically after the Drafter.** The Outline Checker, UX Analyzer (for `create_page` targets), and Style Checker run on every Drafter output. If errors or warnings are found, the Drafter re-runs once with the review reports as context. Suggestions are appended as review notes but do not trigger a retry. Maximum 1 retry per target — never more.
 6. **Handle multiple targets sequentially.** Process primary targets first, then required, then optional.
 7. **Respect `conditional` targets.** Do not process them until the condition is resolved.
+8. **Self-review severity threshold.** `[error]` and `[warning]` findings trigger a Drafter retry. Only `[suggestion]` findings are reported without causing re-runs. This prevents infinite loops while catching clear rule violations (e.g., "easy/simple" slipping through, missing backticks on file paths, procedures not in numbered lists).
 
 ### When Outline Generator is needed vs. straight to Drafter
 
@@ -234,7 +264,7 @@ Always tell the user which prompt is executing and in which mode:
 
 > "Running **Style Checker** on `account-billing.md`..."
 
-> "Running **Create / Update Mode** (auto-chain): Router → Outline Generator → Drafter"
+> "Running **Create / Update Mode** (auto-chain): Router → Outline Generator → Drafter → Self-Review → Auto-Correct (if needed)"
 
 > "Running **Outliner** (Full Review: Checker + UX Analyzer) on `admin-configuration-customization.md` — new file, 1103 lines..."
 
@@ -825,6 +855,6 @@ tags: [...]
 6. **[ux-low]** Nice-to-have UX improvement
 ```
 
-**Create / Update Mode output:** A series of artifacts produced by the auto-chain (Routing Report, Outline Report if applicable, Draft/Patch/Micro-edit for each target). No consolidated report — each artifact stands alone.
+**Create / Update Mode output:** A series of artifacts produced by the auto-chain (Routing Report, Outline Report if applicable, Draft/Patch/Micro-edit for each target, Self-Review Report). Each artifact stands alone. The Self-Review Report consolidates findings from Outline Checker, UX Analyzer, and Style Checker. If errors triggered a Drafter retry, the corrected artifacts replace the originals and the Self-Review Report notes which targets were corrected.
 
-**Behavioral rules:** Determine mode first. State mode explicitly. Execute prompts in sequence. In Review Mode, the Outliner auto-selects Quick Check or Full Review based on the escalation conditions defined in the [Review Mode workflow](#review-mode-existing-content). In auto-chain mode, do not pause between steps unless `ask_user` is set. Deduplicate issues across prompts. Prioritize errors → warnings → ux-high → suggestions → ux-medium → ux-low.
+**Behavioral rules:** Determine mode first. State mode explicitly. Execute prompts in sequence. In Review Mode, the Outliner auto-selects Quick Check or Full Review based on the escalation conditions defined in the [Review Mode workflow](#review-mode-existing-content). In auto-chain mode, do not pause between steps unless `ask_user` is set. After the Drafter, run Self-Review automatically (Outline Checker + UX Analyzer for new pages + Style Checker). If errors are found, re-run the Drafter once per target with review reports as context. Deduplicate issues across prompts. Prioritize errors → warnings → ux-high → suggestions → ux-medium → ux-low.