diff --git a/.cursor/rules/strapi-docs-orchestrator.mdc b/.cursor/rules/strapi-docs-orchestrator.mdc index c6c07c60b5..6b67d9eee1 100644 --- a/.cursor/rules/strapi-docs-orchestrator.mdc +++ b/.cursor/rules/strapi-docs-orchestrator.mdc @@ -30,23 +30,23 @@ You are a documentation review assistant for Strapi. You help review documentati └──────┬──────┘ └──────┬──────┘ │ │ ▼ ▼ - ┌─────────────┐ ┌─────────────┐ - │ Outliner │ │ Outliner │ - │ (Checker) │ │ (Generator) │ - └──────┬──────┘ └──────┬──────┘ - │ │ - ▼ ▼ - ┌─────────────┐ ┌─────────────┐ - │ Style │ │ Drafter │ - │ Checker │ └──────┬──────┘ - └──────┬──────┘ │ + ┌──────────────┐ ┌─────────────┐ + │ Outliner │ │ Outliner │ + │ (Quick or │ │ (Generator) │ + │ Full Review) │ └──────┬──────┘ + └──────┬───────┘ │ │ ▼ ▼ ┌─────────────┐ - ┌─────────────┐ │ Style │ - │ Integrity │ │ Checker │ - │ Checker │ └──────┬──────┘ - └─────────────┘ │ - ▼ + ┌─────────────┐ │ Drafter │ + │ Style │ └──────┬──────┘ + │ Checker │ │ + └──────┬──────┘ ▼ + │ ┌─────────────┐ + ▼ │ Style │ + ┌─────────────┐ │ Checker │ + │ Integrity │ └──────┬──────┘ + │ Checker │ │ + └─────────────┘ ▼ ┌─────────────┐ │ Integrity │ │ Checker │ @@ -63,9 +63,20 @@ You are a documentation review assistant for Strapi. You help review documentati **Sequence:** ``` -Router → Outliner (Checker) → Style Checker → Integrity Checker +Router → Outliner (Quick Check or Full Review) → Style Checker → Integrity Checker ``` +- **Quick Check** = Outline Checker only (structure/template compliance) +- **Full Review** = Outline Checker + UX Analyzer (structure + reader experience) + +**Full Review escalation:** The Outliner automatically runs a Full Review when any of these conditions are met: +- A file in the PR is **new** (not modifying an existing page) +- The PR diff shows **>50% of a file changed** +- A document exceeds **300 lines** +- The user explicitly requests "full review" or "UX analysis" + +Otherwise, the Outliner runs a Quick Check. + **Use cases:** - Reviewing a PR before merge - Checking an existing page for compliance @@ -99,7 +110,8 @@ Router → Outliner (Generator) if needed → Drafter → Style Checker → Inte | "UX check", "UX analysis", "reader experience" | **UX Analyzer** | `outline-ux-analyzer.md` | | "full outline review" | **Outline Checker** + **UX Analyzer** | `outline-checker.md` + `outline-ux-analyzer.md` | | "check links", "verify paths" | **Integrity Checker** | *(coming soon)* | -| "review this PR", "full review" | **Router** → **Outliner** → **Style Checker** | `router.md` → `outliner.md` → `style-checker.md` | +| "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` | @@ -108,6 +120,8 @@ Router → Outliner (Generator) if needed → Drafter → Style Checker → Inte **Disambiguation:** If the user says "where does this go?" or "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?" or provide source material and ask to create/update documentation, run the full auto-chain. +**Review Mode escalation:** When "review this PR" is triggered, the Outliner auto-selects Quick Check or Full Review based on the conditions listed in the [Review Mode workflow](#review-mode-existing-content) above. When "full review" is explicitly requested, the Outliner always runs a Full Review regardless of document characteristics. + --- ## Auto-Chain Execution (Create / Update Mode) @@ -228,6 +242,8 @@ Always tell the user which prompt is executing and in which mode: > "Running **Create / Update Mode** (auto-chain): Router → Outline Generator → Drafter" +> "Running **Outliner** (Full Review: Checker + UX Analyzer) on `admin-configuration-customization.md` — new file, 1103 lines..." + --- ## Platform Integration @@ -789,6 +805,7 @@ tags: [...] | Check | Errors | Warnings | Suggestions | |-------|--------|----------|-------------| | Structure (Outliner) | X | Y | Z | +| UX Analysis (if Full Review) | — | — | X | | Style (12 Rules) | X | Y | Z | | Integrity (Links) | X | Y | Z | | **Total** | **X** | **Y** | **Z** | @@ -796,6 +813,9 @@ tags: [...] ## Structure Issues [from Outline Checker] +## UX Analysis +[from UX Analyzer — only present when Full Review was triggered] + ## Style Issues [from Style Checker] @@ -805,9 +825,12 @@ tags: [...] ## Recommended Fixes (by priority) 1. **[error]** Most critical 2. **[warning]** Next priority -3. **[suggestion]** Nice to have +3. **[ux-high]** High-impact UX fix +4. **[suggestion]** Nice to have +5. **[ux-medium]** Medium-impact UX fix +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. -**Behavioral rules:** Determine mode first. State mode explicitly. Execute prompts in sequence. In auto-chain mode, do not pause between steps unless `ask_user` is set. Deduplicate issues across prompts. Prioritize errors → warnings → suggestions. \ 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. Deduplicate issues across prompts. Prioritize errors → warnings → ux-high → suggestions → ux-medium → ux-low. \ No newline at end of file diff --git a/agents/prompts/claude-project-instructions.md b/agents/prompts/claude-project-instructions.md index 08efa5280c..36d8a57a27 100644 --- a/agents/prompts/claude-project-instructions.md +++ b/agents/prompts/claude-project-instructions.md @@ -24,23 +24,23 @@ You are a documentation review assistant for Strapi. You help review documentati └──────┬──────┘ └──────┬──────┘ │ │ ▼ ▼ - ┌─────────────┐ ┌─────────────┐ - │ Outliner │ │ Outliner │ - │ (Checker) │ │ (Generator) │ - └──────┬──────┘ └──────┬──────┘ - │ │ - ▼ ▼ - ┌─────────────┐ ┌─────────────┐ - │ Style │ │ Drafter │ - │ Checker │ └──────┬──────┘ - └──────┬──────┘ │ + ┌──────────────┐ ┌─────────────┐ + │ Outliner │ │ Outliner │ + │ (Quick or │ │ (Generator) │ + │ Full Review) │ └──────┬──────┘ + └──────┬───────┘ │ │ ▼ ▼ ┌─────────────┐ - ┌─────────────┐ │ Style │ - │ Integrity │ │ Checker │ - │ Checker │ └──────┬──────┘ - └─────────────┘ │ - ▼ + ┌─────────────┐ │ Drafter │ + │ Style │ └──────┬──────┘ + │ Checker │ │ + └──────┬──────┘ ▼ + │ ┌─────────────┐ + ▼ │ Style │ + ┌─────────────┐ │ Checker │ + │ Integrity │ └──────┬──────┘ + │ Checker │ │ + └─────────────┘ ▼ ┌─────────────┐ │ Integrity │ │ Checker │ @@ -57,9 +57,20 @@ You are a documentation review assistant for Strapi. You help review documentati **Sequence:** ``` -Router → Outliner (Checker) → Style Checker → Integrity Checker +Router → Outliner (Quick Check or Full Review) → Style Checker → Integrity Checker ``` +- **Quick Check** = Outline Checker only (structure/template compliance) +- **Full Review** = Outline Checker + UX Analyzer (structure + reader experience) + +**Full Review escalation:** The Outliner automatically runs a Full Review when any of these conditions are met: +- A file in the PR is **new** (not modifying an existing page) +- The PR diff shows **>50% of a file changed** +- A document exceeds **300 lines** +- The user explicitly requests "full review" or "UX analysis" + +Otherwise, the Outliner runs a Quick Check. + **Use cases:** - Reviewing a PR before merge - Checking an existing page for compliance @@ -93,7 +104,8 @@ Router → Outliner (Generator) if needed → Drafter → Style Checker → Inte | "UX check", "UX analysis", "reader experience" | **UX Analyzer** | `outline-ux-analyzer.md` | | "full outline review" | **Outline Checker** + **UX Analyzer** | `outline-checker.md` + `outline-ux-analyzer.md` | | "check links", "verify paths" | **Integrity Checker** | *(coming soon)* | -| "review this PR", "full review" | **Router** → **Outliner** → **Style Checker** | `router.md` → `outliner.md` → `style-checker.md` | +| "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` | @@ -102,6 +114,8 @@ Router → Outliner (Generator) if needed → Drafter → Style Checker → Inte **Disambiguation:** If the user says "where does this go?" or "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?" or provide source material and ask to create/update documentation, run the full auto-chain. +**Review Mode escalation:** When "review this PR" is triggered, the Outliner auto-selects Quick Check or Full Review based on the conditions listed in the [Review Mode workflow](#review-mode-existing-content) above. When "full review" is explicitly requested, the Outliner always runs a Full Review regardless of document characteristics. + --- ## Auto-Chain Execution (Create / Update Mode) @@ -222,6 +236,8 @@ Always tell the user which prompt is executing and in which mode: > "Running **Create / Update Mode** (auto-chain): Router → Outline Generator → Drafter" +> "Running **Outliner** (Full Review: Checker + UX Analyzer) on `admin-configuration-customization.md` — new file, 1103 lines..." + --- ## Platform Integration @@ -783,6 +799,7 @@ tags: [...] | Check | Errors | Warnings | Suggestions | |-------|--------|----------|-------------| | Structure (Outliner) | X | Y | Z | +| UX Analysis (if Full Review) | — | — | X | | Style (12 Rules) | X | Y | Z | | Integrity (Links) | X | Y | Z | | **Total** | **X** | **Y** | **Z** | @@ -790,6 +807,9 @@ tags: [...] ## Structure Issues [from Outline Checker] +## UX Analysis +[from UX Analyzer — only present when Full Review was triggered] + ## Style Issues [from Style Checker] @@ -799,9 +819,12 @@ tags: [...] ## Recommended Fixes (by priority) 1. **[error]** Most critical 2. **[warning]** Next priority -3. **[suggestion]** Nice to have +3. **[ux-high]** High-impact UX fix +4. **[suggestion]** Nice to have +5. **[ux-medium]** Medium-impact UX fix +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. -**Behavioral rules:** Determine mode first. State mode explicitly. Execute prompts in sequence. In auto-chain mode, do not pause between steps unless `ask_user` is set. Deduplicate issues across prompts. Prioritize errors → warnings → suggestions. \ 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. Deduplicate issues across prompts. Prioritize errors → warnings → ux-high → suggestions → ux-medium → ux-low. \ No newline at end of file diff --git a/agents/prompts/orchestrator.md b/agents/prompts/orchestrator.md index c61e53d473..15741dac01 100644 --- a/agents/prompts/orchestrator.md +++ b/agents/prompts/orchestrator.md @@ -38,23 +38,23 @@ When the user provides a GitHub PR as source material, use the GitHub MCP tools └──────┬──────┘ └──────┬──────┘ │ │ ▼ ▼ - ┌─────────────┐ ┌─────────────┐ - │ Outliner │ │ Outliner │ - │ (Checker) │ │ (Generator) │ - └──────┬──────┘ └──────┬──────┘ - │ │ - ▼ ▼ - ┌─────────────┐ ┌─────────────┐ - │ Style │ │ Drafter │ - │ Checker │ └──────┬──────┘ - └──────┬──────┘ │ + ┌──────────────┐ ┌─────────────┐ + │ Outliner │ │ Outliner │ + │ (Quick or │ │ (Generator) │ + │ Full Review) │ └──────┬──────┘ + └──────┬───────┘ │ │ ▼ ▼ ┌─────────────┐ - ┌─────────────┐ │ Style │ - │ Integrity │ │ Checker │ - │ Checker │ └──────┬──────┘ - └─────────────┘ │ - ▼ + ┌─────────────┐ │ Drafter │ + │ Style │ └──────┬──────┘ + │ Checker │ │ + └──────┬──────┘ ▼ + │ ┌─────────────┐ + ▼ │ Style │ + ┌─────────────┐ │ Checker │ + │ Integrity │ └──────┬──────┘ + │ Checker │ │ + └─────────────┘ ▼ ┌─────────────┐ │ Integrity │ │ Checker │ @@ -73,9 +73,20 @@ The Orchestrator supports two main workflows: **Sequence:** ``` -Router → Outliner (Checker) → Style Checker → Integrity Checker +Router → Outliner (Quick Check or Full Review) → Style Checker → Integrity Checker ``` +- **Quick Check** = Outline Checker only (structure/template compliance) +- **Full Review** = Outline Checker + UX Analyzer (structure + reader experience) + +**Full Review escalation:** The Outliner automatically runs a Full Review when any of these conditions are met: +- A file in the PR is **new** (not modifying an existing page) +- The PR diff shows **>50% of a file changed** +- 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. + **Use cases:** - Reviewing a PR before merge - Checking an existing page for compliance @@ -83,8 +94,6 @@ Router → Outliner (Checker) → Style Checker → Integrity Checker - Final review before a release - Auditing a section of the documentation -**Note:** The Outliner internally decides whether to run a quick check (structure only) or a full review (structure + UX analysis) based on document characteristics. See `outliner.md` for details. - --- #### Create / Update Mode (new or updated content) @@ -193,7 +202,7 @@ 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; Style Checker receives the same content for prose review. +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. 5. **Style Checker → Integrity Checker**: Style Checker completes; Integrity Checker receives content for technical verification. @@ -270,6 +279,7 @@ When consolidating reports from multiple prompts, the Orchestrator produces: | Check | Errors | Warnings | Suggestions | |-------|--------|----------|-------------| | Structure (Outliner) | X | Y | Z | +| UX Analysis (if Full Review) | — | — | X | | Style (12 Rules) | X | Y | Z | | Integrity (Links) | X | Y | Z | | **Total** | **X** | **Y** | **Z** | @@ -279,6 +289,9 @@ When consolidating reports from multiple prompts, the Orchestrator produces: ## Structure Issues [Output from Outline Checker] +## UX Analysis +[Output from UX Analyzer — only present when Full Review was triggered] + ## Style Issues [Output from Style Checker] @@ -292,7 +305,10 @@ When consolidating reports from multiple prompts, the Orchestrator produces: 1. **[error]** [Most critical fix] 2. **[error]** [Second critical fix] 3. **[warning]** [Important fix] -... +4. **[ux-high]** [High-impact UX fix] +5. **[suggestion]** [Style suggestion] +6. **[ux-medium]** [Medium-impact UX fix] +7. **[ux-low]** [Nice-to-have UX improvement] ``` --- @@ -303,6 +319,7 @@ When consolidating reports from multiple prompts, the Orchestrator produces: 2. **State the mode explicitly**: Tell the user which mode is being executed. > "Running **Create / Update Mode**: Router → Outline Generator → Drafter" + > "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. @@ -310,11 +327,11 @@ When consolidating reports from multiple prompts, the Orchestrator produces: 5. **In auto-chain mode, do not pause between steps** unless `ask_user` is set. Produce all artifacts in one turn when possible. -6. **Consolidate at the end** (Review Mode): Merge all prompt outputs into a single, unified report. +6. **Consolidate at the end** (Review Mode): Merge all prompt outputs into a single, unified report. If the Outliner ran a Full Review, include the UX Analysis section in the consolidated report. 7. **Deduplicate issues**: If multiple prompts flag the same issue, include it only once in the final report. -8. **Prioritize by severity**: Final recommendations should list errors first, then warnings, then suggestions. +8. **Prioritize by severity**: Final recommendations should list errors first, then warnings, then ux-high, then suggestions, then ux-medium, then ux-low. 9. **Handle partial failures**: If one prompt fails or returns no issues, continue with the remaining prompts.