From 39398e9eb3ee69c211f2395a7be614bf1ed8a4fc Mon Sep 17 00:00:00 2001 From: Pierre Wizla <4233866+pwizla@users.noreply.github.com> Date: Wed, 18 Mar 2026 18:15:42 +0100 Subject: [PATCH 1/5] Update Orchestrator --- agents/prompts/orchestrator.md | 110 ++++++++++++++++++++++++++++----- 1 file changed, 94 insertions(+), 16 deletions(-) diff --git a/agents/prompts/orchestrator.md b/agents/prompts/orchestrator.md index 15741dac01..a27768e3ab 100644 --- a/agents/prompts/orchestrator.md +++ b/agents/prompts/orchestrator.md @@ -49,12 +49,18 @@ When the user provides a GitHub PR as source material, use the GitHub MCP tools │ Style │ └──────┬──────┘ │ Checker │ │ └──────┬──────┘ ▼ - │ ┌─────────────┐ - ▼ │ Style │ - ┌─────────────┐ │ Checker │ - │ Integrity │ └──────┬──────┘ + │ ┌──────────────┐ + ▼ │ Self-Review │ + ┌─────────────┐ │ (OC+UX+SC) │ + │ Integrity │ └──────┬───────┘ │ Checker │ │ └─────────────┘ ▼ + ┌──────────────┐ + │ Auto-Correct │ + │ (if errors) │ + └──────┬───────┘ + │ + ▼ ┌─────────────┐ │ Integrity │ │ Checker │ @@ -85,7 +91,9 @@ Router → Outliner (Quick Check or Full Review) → Style Checker → Integrity - A document exceeds **300 lines** - The user explicitly requests "full review" or "UX analysis" -Otherwise, the Outliner runs a Quick Check. See `outliner.md` for details on mode selection logic and output formats. +Otherwise, the Outliner runs a Quick Check. + +See `outliner.md` for details on mode selection logic and output formats. **Use cases:** - Reviewing a PR before merge @@ -102,7 +110,7 @@ Otherwise, the Outliner runs a Quick Check. See `outliner.md` for details on mod **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:** @@ -117,7 +125,7 @@ Router → Outliner (Generator) if needed → Drafter → Style Checker → Inte ### Auto-Chain Execution -**When Create / Update Mode is triggered, the Orchestrator runs the full pipeline automatically.** It does not stop after each step to ask the user to proceed — it chains the steps until the Drafter has produced output for all targets. +**When Create / Update Mode is triggered, the Orchestrator runs the full pipeline automatically.** It does not stop after each step to ask the user to proceed — it chains the steps until the Drafter has produced output for all targets, the self-review has run, and any error-level issues have been auto-corrected. #### Execution algorithm @@ -151,7 +159,29 @@ Router → Outliner (Generator) if needed → Drafter → Style Checker → Inte 3. OUTPUT all Drafter deliverables as separate artifacts -4. (Optional) RUN Style Checker on Drafter output if user requested a "full review" +4. SELF-REVIEW (automatic, no pause) + │ + ├─ FOR EACH Drafter output: + │ ├─ RUN Outline Checker (template compliance) + │ ├─ IF action was create_page: + │ │ └─ RUN UX Analyzer (reader experience) + │ └─ RUN Style Checker (12 Rules compliance) + │ + └─ COLLECT all review reports + +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 (only warnings/suggestions): + └─ Append review summary to each artifact as a + comment block + +6. OUTPUT final deliverables + consolidated Self-Review Report artifact ``` #### Key rules for auto-chain execution @@ -160,9 +190,10 @@ Router → Outliner (Generator) if needed → Drafter → Style Checker → Inte 2. **Do NOT pause between Router and Drafter** unless `ask_user` is set or a critical error occurs. 3. **Output each step's result as a separate artifact** with descriptive titles (e.g., "Routing Report — MCP Server feature", "Outline — cms/features/mcp-server.md", "Draft — cms/features/mcp-server.md"). 4. **Only the Outline Generator needs the full Router report.** The Drafter receives the outline (for Compose) or the target info + source material (for Patch/Micro-edit). -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 ("Would you like me to run a style check on this draft?") unless the user explicitly asked for a full review. +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 are found, the Drafter re-runs once with the review reports as context. Warnings and 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 (with OG → Drafter), then required (Drafter Patch), then optional (Drafter Micro-edit). Each produces its own artifact. 7. **Respect `conditional` targets.** Do not process them until the condition is resolved. If the Router sets `ask_user`, present the question and wait. +8. **Self-review severity threshold.** Only `[error]`-level findings trigger a Drafter retry. `[warning]` and `[suggestion]` findings are reported but do not cause 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 OG is needed vs. straight to Drafter @@ -202,11 +233,13 @@ The key distinction: 3. **Outliner → Drafter** *(create mode only)*: Outline Generator passes the approved outline structure; Drafter fills in content. -4. **Outliner → Style Checker** *(review mode)*: Outliner completes structure check (and UX analysis if Full Review); Style Checker receives the same content for prose review. +4. **Drafter → Self-Review** *(create/update mode)*: Drafter output is automatically reviewed by Outline Checker, UX Analyzer (for new pages), and Style Checker. If errors are found, the Drafter re-runs once with the review reports as context. -5. **Style Checker → Integrity Checker**: Style Checker completes; Integrity Checker receives content for technical verification. +5. **Outliner → Style Checker** *(review mode)*: Outliner completes structure check (and UX analysis if Full Review); Style Checker receives the same content for prose review. -6. **All Prompts → Orchestrator**: Each prompt returns a structured report; Orchestrator consolidates into final output. +6. **Style Checker → Integrity Checker**: Style Checker completes; Integrity Checker receives content for technical verification. + +7. **All Prompts → Orchestrator**: Each prompt returns a structured report; Orchestrator consolidates into final output. **Key principle:** Each prompt focuses on its domain. No prompt should duplicate another's checks. @@ -257,7 +290,7 @@ When a workflow involves creating a branch or opening a PR (typically in Create/ - User provides source material (PR, diff, spec, Notion doc, pasted code changes) and asks to create or update documentation - User provides a PR link/diff and asks what documentation changes are needed **and** wants them written (not just analyzed) -**Disambiguation:** If the user says "what docs need updating?" without asking for the actual writing, run the Router only. If they say "update the docs with this" or "how do I update docs?", run the full auto-chain (Router → OG if needed → Drafter). +**Disambiguation:** If the user says "what docs need updating?" without asking for the actual writing, run the Router only. If they say "update the docs with this" or "how do I update docs?", run the full auto-chain (Router → OG if needed → Drafter → Self-Review → Auto-Correct if needed). --- @@ -313,12 +346,58 @@ When consolidating reports from multiple prompts, the Orchestrator produces: --- +### Self-Review Report Format + +When the self-review loop runs in Create / Update Mode, the Orchestrator produces a separate report: + +```markdown +# Self-Review Report + +**Mode:** Create / Update — Self-Review +**Date:** [timestamp] + +--- + +## Summary + +| Target | Outline Checker | UX Analyzer | Style Checker | Retry? | +|--------|----------------|-------------|---------------|--------| +| `path/to/file.md` | X errors, Y warnings | ✅ or N/A | X errors, Y warnings | Yes/No | + +--- + +## Findings by target + +### `path/to/file.md` + +#### Structure +[Outline Checker findings] + +#### UX (if create_page) +[UX Analyzer findings] + +#### Style +[Style Checker findings] + +#### Auto-Correct applied +[What was corrected in the retry, or "No retry needed"] + +--- + +## Remaining issues (warnings/suggestions not auto-corrected) + +1. **[warning]** [Issue description] +2. **[suggestion]** [Issue description] +``` + +--- + ### Behavioral Notes 1. **Determine mode first**: Before calling any prompt, identify which mode applies based on user intent. 2. **State the mode explicitly**: Tell the user which mode is being executed. - > "Running **Create / Update Mode**: Router → Outline Generator → Drafter" + > "Running **Create / Update Mode**: Router → Outline Generator → Drafter → Self-Review → Auto-Correct (if needed)" > "Running **Review Mode** (Full Review): Router → Outliner (Checker + UX Analyzer) → Style Checker" 3. **Execute prompts in sequence**: Each prompt must complete before the next one starts. @@ -344,5 +423,4 @@ When consolidating reports from multiple prompts, the Orchestrator produces: - **Parallel execution**: Run independent prompts (e.g., Style Checker and Integrity Checker) in parallel - **Incremental review**: Only run prompts relevant to the changed content in a PR - **Custom workflows**: Allow users to define custom prompt sequences -- **Caching**: Cache Router results to avoid re-detecting document type -- **Auto-retry**: If Style Checker finds errors in Drafter output, re-run Drafter once with the report as context (max 1 retry) \ No newline at end of file +- **Caching**: Cache Router results to avoid re-detecting document type \ No newline at end of file From 017b478a78c40b341827993ae7cbb0466a65be0a Mon Sep 17 00:00:00 2001 From: Pierre Wizla <4233866+pwizla@users.noreply.github.com> Date: Wed, 18 Mar 2026 18:20:22 +0100 Subject: [PATCH 2/5] Update Claude Project instructions --- agents/prompts/claude-project-instructions.md | 59 ++++++++++++++----- 1 file changed, 44 insertions(+), 15 deletions(-) diff --git a/agents/prompts/claude-project-instructions.md b/agents/prompts/claude-project-instructions.md index 36d8a57a27..4b0658b15b 100644 --- a/agents/prompts/claude-project-instructions.md +++ b/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,31 @@ 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 (only warnings/suggestions): + └─ Append review summary as comment -Step 4: (Optional) Offer Style Checker as follow-up +Step 6: OUTPUT final deliverables + Self-Review Report artifact ``` ### Auto-chain rules @@ -167,10 +195,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 are found, the Drafter re-runs once with the review reports as context. Warnings and 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.** Only `[error]`-level findings trigger a Drafter retry. `[warning]` and `[suggestion]` findings are reported but do not cause re-runs. This prevents infinite loops while catching clear rule violations. ### When Outline Generator is needed vs. straight to Drafter @@ -234,7 +263,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 +854,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. \ No newline at end of file +**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. \ No newline at end of file From da09d9990fdcd3b8744a7364ef823449af88adce Mon Sep 17 00:00:00 2001 From: Pierre Wizla <4233866+pwizla@users.noreply.github.com> Date: Wed, 18 Mar 2026 18:30:40 +0100 Subject: [PATCH 3/5] Update Drafter interface --- agents/prompts/shared/drafter-interface.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/agents/prompts/shared/drafter-interface.md b/agents/prompts/shared/drafter-interface.md index 49e27d28d3..1643623442 100644 --- a/agents/prompts/shared/drafter-interface.md +++ b/agents/prompts/shared/drafter-interface.md @@ -347,8 +347,8 @@ These questions were resolved during design (2025-02-11) and are documented here ### 4. Validation loop -**Decision:** v1 uses manual re-runs. If the Style Checker finds issues, the user decides whether to re-run the Drafter with the Style Checker report as additional input. +**Decision:** The Orchestrator runs a self-review loop after the Drafter completes. The Outline Checker, UX Analyzer (for `create_page` targets), and Style Checker run automatically on every Drafter output. If any report contains `[error]`-level findings, the Drafter re-runs once with the review reports injected as context. Maximum 1 retry per target, never more. -**Future enhancement:** The Orchestrator may support an `auto_retry: once` option — if the Style Checker reports errors (not warnings or suggestions), the Drafter re-runs once with the Style Checker report injected as context. Maximum 1 retry, never more. This prevents infinite loops while catching clear violations (e.g., "easy" slipping through, missing backticks on file paths). +**Severity threshold:** Only errors trigger a retry. Warnings and suggestions are appended as `` comments but do not cause re-runs. This prevents infinite loops while catching clear violations (e.g., "easy" slipping through, missing backticks on file paths, procedures not in numbered lists). -**Rationale:** Automated re-runs are valuable but risky if unbounded. A single retry with a severity threshold (errors only) balances automation with predictability. \ No newline at end of file +**Rationale:** Automated re-runs are valuable but risky if unbounded. A single retry with a severity threshold (errors only) balances automation with predictability. The expanded self-review (Outline Checker + UX Analyzer + Style Checker, not just Style Checker) ensures structural and experiential issues are also caught before delivery. \ No newline at end of file From 695622b3ce38bbf358699e56da958ccb8359c68e Mon Sep 17 00:00:00 2001 From: Pierre Wizla <4233866+pwizla@users.noreply.github.com> Date: Wed, 18 Mar 2026 18:34:53 +0100 Subject: [PATCH 4/5] Update Cursor rule --- .cursor/rules/strapi-docs-orchestrator.mdc | 59 ++++++++++++++++------ 1 file changed, 44 insertions(+), 15 deletions(-) diff --git a/.cursor/rules/strapi-docs-orchestrator.mdc b/.cursor/rules/strapi-docs-orchestrator.mdc index 6b67d9eee1..1fcbf0912c 100644 --- a/.cursor/rules/strapi-docs-orchestrator.mdc +++ b/.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,31 @@ 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 (only warnings/suggestions): + └─ Append review summary as comment -Step 4: (Optional) Offer Style Checker as follow-up +Step 6: OUTPUT final deliverables + Self-Review Report artifact ``` ### Auto-chain rules @@ -173,10 +201,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 are found, the Drafter re-runs once with the review reports as context. Warnings and 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.** Only `[error]`-level findings trigger a Drafter retry. `[warning]` and `[suggestion]` findings are reported but do not cause re-runs. This prevents infinite loops while catching clear rule violations. ### When Outline Generator is needed vs. straight to Drafter @@ -240,7 +269,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 +860,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. \ No newline at end of file +**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. \ No newline at end of file From 5d9719c04be00efe012df6121a8490e43dc15a58 Mon Sep 17 00:00:00 2001 From: Pierre Wizla <4233866+pwizla@users.noreply.github.com> Date: Wed, 18 Mar 2026 18:39:12 +0100 Subject: [PATCH 5/5] Include warning-type issues in self-check run --- .cursor/rules/strapi-docs-orchestrator.mdc | 9 +++++---- agents/prompts/claude-project-instructions.md | 9 +++++---- agents/prompts/orchestrator.md | 4 ++-- agents/prompts/shared/drafter-interface.md | 2 +- 4 files changed, 13 insertions(+), 11 deletions(-) diff --git a/.cursor/rules/strapi-docs-orchestrator.mdc b/.cursor/rules/strapi-docs-orchestrator.mdc index 1fcbf0912c..ccd77494f5 100644 --- a/.cursor/rules/strapi-docs-orchestrator.mdc +++ b/.cursor/rules/strapi-docs-orchestrator.mdc @@ -189,8 +189,9 @@ Step 5: AUTO-CORRECT (conditional, max 1 retry per target) │ │ └─ RE-RUN Drafter (same mode) with corrections │ └─ OUTPUT corrected artifacts (replace originals) │ - └─ IF no errors (only warnings/suggestions): - └─ Append review summary as comment + └─ IF no errors or warnings (suggestions only): + └─ Append review summary to each artifact as a + comment block Step 6: OUTPUT final deliverables + Self-Review Report artifact ``` @@ -202,10 +203,10 @@ Step 6: OUTPUT final deliverables + Self-Review Report artifact 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 → 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 are found, the Drafter re-runs once with the review reports as context. Warnings and suggestions are appended as review notes but do not trigger a retry. Maximum 1 retry per target — never more. +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.** Only `[error]`-level findings trigger a Drafter retry. `[warning]` and `[suggestion]` findings are reported but do not cause re-runs. This prevents infinite loops while catching clear rule violations. +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 diff --git a/agents/prompts/claude-project-instructions.md b/agents/prompts/claude-project-instructions.md index 4b0658b15b..51b1154711 100644 --- a/agents/prompts/claude-project-instructions.md +++ b/agents/prompts/claude-project-instructions.md @@ -183,8 +183,9 @@ Step 5: AUTO-CORRECT (conditional, max 1 retry per target) │ │ └─ RE-RUN Drafter (same mode) with corrections │ └─ OUTPUT corrected artifacts (replace originals) │ - └─ IF no errors (only warnings/suggestions): - └─ Append review summary as comment + └─ IF no errors or warnings (suggestions only): + └─ Append review summary to each artifact as a + comment block Step 6: OUTPUT final deliverables + Self-Review Report artifact ``` @@ -196,10 +197,10 @@ Step 6: OUTPUT final deliverables + Self-Review Report artifact 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 → 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 are found, the Drafter re-runs once with the review reports as context. Warnings and suggestions are appended as review notes but do not trigger a retry. Maximum 1 retry per target — never more. +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.** Only `[error]`-level findings trigger a Drafter retry. `[warning]` and `[suggestion]` findings are reported but do not cause re-runs. This prevents infinite loops while catching clear rule violations. +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 diff --git a/agents/prompts/orchestrator.md b/agents/prompts/orchestrator.md index a27768e3ab..f62faa8407 100644 --- a/agents/prompts/orchestrator.md +++ b/agents/prompts/orchestrator.md @@ -177,7 +177,7 @@ Router → Outliner (Generator) if needed → Drafter → Self-Review (Outline C │ │ └─ RE-RUN Drafter (same mode) with corrections │ └─ OUTPUT corrected artifacts (replace originals) │ - └─ IF no errors (only warnings/suggestions): + └─ IF no errors or warnings (suggestions only): └─ Append review summary to each artifact as a comment block @@ -190,7 +190,7 @@ Router → Outliner (Generator) if needed → Drafter → Self-Review (Outline C 2. **Do NOT pause between Router and Drafter** unless `ask_user` is set or a critical error occurs. 3. **Output each step's result as a separate artifact** with descriptive titles (e.g., "Routing Report — MCP Server feature", "Outline — cms/features/mcp-server.md", "Draft — cms/features/mcp-server.md"). 4. **Only the Outline Generator needs the full Router report.** The Drafter receives the outline (for Compose) or the target info + source material (for Patch/Micro-edit). -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 are found, the Drafter re-runs once with the review reports as context. Warnings and suggestions are appended as review notes but do not trigger a retry. Maximum 1 retry per target — never more. +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 (with OG → Drafter), then required (Drafter Patch), then optional (Drafter Micro-edit). Each produces its own artifact. 7. **Respect `conditional` targets.** Do not process them until the condition is resolved. If the Router sets `ask_user`, present the question and wait. 8. **Self-review severity threshold.** Only `[error]`-level findings trigger a Drafter retry. `[warning]` and `[suggestion]` findings are reported but do not cause 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). diff --git a/agents/prompts/shared/drafter-interface.md b/agents/prompts/shared/drafter-interface.md index 1643623442..3a00694d9a 100644 --- a/agents/prompts/shared/drafter-interface.md +++ b/agents/prompts/shared/drafter-interface.md @@ -349,6 +349,6 @@ These questions were resolved during design (2025-02-11) and are documented here **Decision:** The Orchestrator runs a self-review loop after the Drafter completes. The Outline Checker, UX Analyzer (for `create_page` targets), and Style Checker run automatically on every Drafter output. If any report contains `[error]`-level findings, the Drafter re-runs once with the review reports injected as context. Maximum 1 retry per target, never more. -**Severity threshold:** Only errors trigger a retry. Warnings and suggestions are appended as `` comments but do not cause re-runs. This prevents infinite loops while catching clear violations (e.g., "easy" slipping through, missing backticks on file paths, procedures not in numbered lists). +**Severity threshold:** Errors and warnings trigger a retry. Only suggestions are appended as `` comments without causing re-runs. **Rationale:** Automated re-runs are valuable but risky if unbounded. A single retry with a severity threshold (errors only) balances automation with predictability. The expanded self-review (Outline Checker + UX Analyzer + Style Checker, not just Style Checker) ensures structural and experiential issues are also caught before delivery. \ No newline at end of file