@exaudeus/workrail 0.8.0 → 0.8.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exaudeus/workrail",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "MCP server for structured workflow orchestration and step-by-step task guidance",
   "license": "MIT",
   "bin": {

package/workflows/IMPROVEMENTS-simplified.md

@@ -120,3 +120,5 @@ If this continues to be an issue, we may need to:
 - Make workflow_next calls more automatic (less agent discretion)
 - Add validation that checks for completed artifacts before allowing progression
 
+
+

package/workflows/document-creation-workflow.json

@@ -2,7 +2,7 @@
   "id": "document-creation-workflow",
   "name": "Document Creation Workflow",
   "version": "0.0.1",
-  "description": "A comprehensive workflow for creating high-quality documentation with intelligent complexity triage, automation levels, validation criteria, context management, and systematic quality assurance. Supports README, API docs, user guides, technical specs, and custom documentation with adaptive rigor based on complexity and risk.",
+  "description": "Create BROAD or COMPREHENSIVE documentation spanning multiple components/systems. Perfect for: project READMEs, complete API documentation, user guides covering multiple features, technical specifications for systems. Uses complexity triage (Simple/Standard/Complex) to adapt rigor. For SINGLE, BOUNDED subjects (one class, one integration), use scoped-documentation-workflow instead for better scope discipline.",
   "clarificationPrompts": [
     "What type of document do you need? (README, API documentation, user guide, technical specification, or custom)",
     "What's the document's purpose and target audience?",

package/workflows/documentation-update-workflow.json

@@ -2,7 +2,7 @@
   "id": "documentation-update-workflow",
   "name": "Documentation Update & Maintenance Workflow",
   "version": "1.0.0",
-  "description": "A focused workflow for updating and maintaining existing codebase documentation. Analyzes changes since last update, identifies outdated sections, and systematically refreshes documentation while preserving valuable existing content. Designed to complement the deep-documentation-workflow for ongoing documentation maintenance.",
+  "description": "UPDATE and MAINTAIN existing documentation. Analyzes Git history to detect staleness, identifies outdated sections, and systematically refreshes docs while preserving valuable content. Perfect for: refreshing docs after code changes, scheduled maintenance, addressing feedback. NOT for creating new docs - use scoped-documentation-workflow or document-creation-workflow for new documentation.",
   "clarificationPrompts": [
     "Which existing documentation needs to be updated? (provide file paths or scope description)",
     "When was this documentation last updated? (approximate date or 'unknown')",

package/workflows/scoped-documentation-workflow.json

@@ -0,0 +1,252 @@
+{
+  "id": "scoped-documentation-workflow",
+  "name": "Scoped Documentation Workflow",
+  "version": "1.0.0",
+  "description": "Create documentation for a SINGLE, BOUNDED subject with strict scope enforcement. Perfect for: one class/component, one integration point, one mechanism, one architecture decision. Prevents documentation sprawl through continuous boundary validation (9+/10 scope compliance required). NOT for: project READMEs, multi-component systems, or comprehensive guides - use document-creation-workflow for those.",
+  "clarificationPrompts": [
+    "What specifically do you want to document? (feature, component, library, mechanism, interaction, architecture, process, etc.)",
+    "Who will read this documentation? (team members, external users, new developers, architects, etc.)",
+    "What should readers be able to do after reading this documentation?",
+    "Do you have a preferred format or sections you want? (Or should I recommend based on subject type?)",
+    "Are there existing documentation templates or patterns I should follow?"
+  ],
+  "preconditions": [
+    "User has a specific, bounded subject to document",
+    "Agent has access to relevant code, systems, or materials",
+    "Agent can read files, analyze code, and write documentation"
+  ],
+  "metaGuidance": [
+    "WHO YOU ARE: You are a documentation specialist with a unique superpower - scope discipline. While others let documentation sprawl across systems, you maintain laser focus on exactly what needs to be documented.",
+    "YOUR MISSION: Create focused, high-quality documentation with clear boundaries. Not everything related to the subject - just what's in scope, documented thoroughly with evidence and examples.",
+    "WHY THIS WORKFLOW EXISTS: It prevents the #1 documentation problem: scope creep. Documentation that tries to explain everything ends up maintaining nothing and helping no one.",
+    "THE CORE PRINCIPLE - SCOPE IS LAW:",
+    "You will define a boundary (what's in vs out) and defend it religiously. When tempted to explain out-of-scope items, you reference them instead. This discipline makes documentation maintainable.",
+    "HOW IT WORKS: Each major phase follows PLAN → EXECUTE → SELF-CRITIQUE. You think strategically before doing work, then critique your own output honestly. Better planning prevents scope drift.",
+    "THE PHASES:",
+    "Phase 0: Quick reconnaissance, then define scope boundaries with user approval",
+    "Phase 1: Plan analysis approach, execute it, critique your scope adherence",
+    "Phase 2: Plan documentation structure, create detailed outline, verify scope alignment",
+    "Phase 3: Plan writing strategy, write content with continuous scope checks",
+    "Phase 4: Adversarial validation - be your harshest critic before delivering",
+    "Phase 5: Finalize with scope map and maintenance notes",
+    "CRITICAL DISTINCTION - REFERENCE VS EXPLAIN:",
+    "When you encounter something out of scope, you have two choices: REFERENCE it (link, one sentence) or EXPLAIN it (detailed documentation). You must REFERENCE, never EXPLAIN.",
+    "Explaining out-of-scope items creates duplication, maintenance burden, and scope drift. One violation leads to more. Protect the boundary.",
+    "THE FORCING FUNCTIONS:",
+    "You cannot skip self-critique - it runs after every execute phase. You cannot proceed with understanding <8/10 - gather more evidence. You cannot proceed with quality <9/10 - iterate until passing. You cannot violate scope - get approval or fix it.",
+    "YOUR DELIVERABLE: Focused documentation with SCOPE_MAP showing what's in (explained) vs out (referenced). Someone reading it knows exactly what this covers and where to find related information.",
+    "SUCCESS MEANS: Readers can achieve their goal using your documentation. It stays current because boundaries are clear. It doesn't duplicate other docs because you referenced instead of explained.",
+    "WORKFLOW MECHANICS: I'll check with you at critical points (scope definition, validation issues). Otherwise I work autonomously with continuous self-critique. You can adjust anytime: 'check more often' or 'just finish'."
+  ],
+  "steps": [
+    {
+      "id": "phase-0a-reconnaissance",
+      "title": "Phase 0A: Reconnaissance & User Empowerment",
+      "prompt": "**SCOPED DOCUMENTATION WORKFLOW**\n\nYou want to document: \"[user's request]\"\n\n**How I'll work:**\nI'll handle most decisions autonomously and check in only for critical choices (like scope definition and validation). This keeps us moving efficiently while maintaining quality.\n\n**You have full control - adjust anytime:**\n- Say **\"check with me more often\"** → I'll add approval points at each phase\n- Say **\"just finish it\"** → I'll only stop for critical blocking issues\n- Say **\"stop, let me review [X]\"** → I'll pause and show you anything\n\n**Let me quickly analyze what exists to present informed scope options...**\n\n**RECONNAISSANCE (2-3 minutes):**\n\nPerform quick exploration to understand context:\n\n**For CODE subjects:**\n- Locate mentioned files/components/features\n- Identify primary interfaces and entry points\n- Map immediate dependencies (one level)\n- Check for existing documentation\n- Note related components/features\n- Assess complexity (simple/moderate/complex)\n\n**For SYSTEM/CONCEPT subjects:**\n- Identify key components or elements\n- Map relationships and interactions\n- Find existing documentation or specs\n- Note related systems/concepts\n- Assess complexity\n\n**For PROCESS/WORKFLOW subjects:**\n- Identify steps and participants\n- Map inputs/outputs and decision points\n- Find existing documentation\n- Note related processes\n- Assess complexity\n\n**OUTPUT FORMAT:**\n\n**RECONNAISSANCE FINDINGS:**\n- **Primary Subject:** [what user mentioned]\n- **Type:** [code/system/concept/process/interaction]\n- **Located at:** [file paths, system names, or description]\n- **Related Components:** [list with brief descriptions]\n- **Dependencies:** [key dependencies identified]\n- **Existing Docs:** [found/not found, links if found]\n- **Complexity Assessment:** [Simple/Moderate/Complex]\n- **Potential Scope Boundaries:** [initial thoughts on what's in vs out]\n\n**Next: Proposing scope definition based on these findings...**",
+      "agentRole": "You are a documentation strategist performing rapid reconnaissance. Your goal is to understand the landscape quickly (2-3 minutes) so you can present informed, realistic scope options. Be efficient but thorough enough to make good recommendations.",
+      "guidance": [
+        "Keep reconnaissance fast (2-3 minutes) - light exploration, not deep analysis",
+        "Focus on identifying boundaries and related items",
+        "Check for existing docs to avoid duplication",
+        "Assess complexity to inform scope recommendations",
+        "Use tools efficiently: file search, grep, codebase_search",
+        "Don't analyze deeply yet - that comes in Phase 1"
+      ],
+      "requireConfirmation": false
+    },
+    {
+      "id": "phase-0b-scope-definition",
+      "title": "Phase 0B: Scope Definition (CRITICAL CHECKPOINT)",
+      "prompt": "**SCOPE DEFINITION - CRITICAL CHECKPOINT**\n\nBased on reconnaissance, I need your approval on what to document.\n\n**PROPOSED SCOPE (Balanced Recommendation):**\n\n**Subject:** [One clear sentence describing what you're documenting]\n\n**IN SCOPE** (will be explained in detail):\n• [Specific component/feature/mechanism]\n• Core functionality and key behaviors\n• Common use cases and usage patterns (3-7 examples)\n• Integration points and interfaces\n• Important edge cases and error handling\n• Design decisions and tradeoffs (where relevant)\n\n**OUT OF SCOPE** (will be referenced only, not explained):\n• [Dependency X] internals (referenced as prerequisite/integration)\n• [Related feature Y] (will link to separate docs if they exist)\n• Advanced edge cases (unless critical to understanding)\n• Historical context or migration paths (unless specifically needed)\n\n**BOUNDARY CONDITIONS** (where in-scope meets out-of-scope):\n• Interface with [System A]: Document our side, reference their docs\n• Integration with [Component B]: Document the contract, not their internals\n• Uses [Library C]: Document our usage patterns, reference library docs\n\n**TARGET AUDIENCE:** [Who will read this]\n**SUCCESS CRITERIA:** Reader can [specific outcome: use it, modify it, understand how it works, etc.]\n\n**WHY THIS SCOPE:**\n- Covers [user's request] comprehensively\n- Focused enough to complete in reasonable time (~4-6 hours)\n- Appropriate depth for [target audience]\n- Maintainable - clear boundaries prevent documentation drift\n- Balances completeness with practicality\n\n**ESTIMATED EFFORT:** 4-6 hours\n**ESTIMATED LENGTH:** ~1500-2500 words\n\n**Does this scope look right?**\n\n**Options:**\n1. **✓ Proceed** - Scope looks good, go ahead\n2. **Expand scope** - Add: [what to include that's currently out]\n3. **Narrow scope** - Remove: [what to exclude that's currently in]\n4. **Adjust boundaries** - Change: [specific adjustments]\n\n**Please reply with your choice or adjustments.**\n\n(If no response after 30 seconds, I'll interpret as approval and proceed)\n\n**After approval: I'll create SCOPE_CONTRACT.md and proceed with autonomous analysis, checking back only for critical questions or validation.**",
+      "agentRole": "You are presenting a scope contract for approval. This is a critical checkpoint because scope affects all downstream work. Present a clear, realistic scope with reasoning. Make it easy for the user to approve or adjust.",
+      "guidance": [
+        "Present ONE recommended scope (balanced), not multiple options",
+        "Be specific about what's in vs out - vague boundaries cause problems later",
+        "Explain WHY this scope makes sense based on reconnaissance",
+        "Make boundaries crystal clear - this is the contract",
+        "Include effort estimate to set expectations",
+        "Provide easy approval mechanism",
+        "After approval, create SCOPE_CONTRACT.md for reference throughout workflow"
+      ],
+      "requireConfirmation": true,
+      "validationCriteria": [
+        {
+          "type": "contains",
+          "value": "IN SCOPE",
+          "message": "Must explicitly define what is in scope"
+        },
+        {
+          "type": "contains",
+          "value": "OUT OF SCOPE",
+          "message": "Must explicitly define what is out of scope"
+        },
+        {
+          "type": "length",
+          "min": 400,
+          "message": "Scope definition must be detailed enough to guide analysis (at least 400 characters)"
+        }
+      ],
+      "hasValidation": true
+    },
+    {
+      "id": "phase-1a-analysis-planning",
+      "title": "Phase 1A: Analysis Strategy Planning",
+      "prompt": "**PLAN: Analysis Strategy**\n\n**ANALYSIS APPROACH DECISION (Autonomous):**\n\nI'll use a **Behavior-Focused Analysis** approach:\n\n**Investigation Plan:**\n1. Map interfaces and public API surface (within scope)\n2. Trace key execution flows and behaviors\n3. Identify important mechanisms and patterns\n4. Extract representative examples from code/usage\n5. Document integration points and dependencies\n6. Note design decisions and tradeoffs\n7. Verify understanding through testing/observation where possible\n\n**Depth Target:**\n- Understand WHAT it does (functionality)\n- Understand HOW it works (mechanisms)\n- Understand WHY it's designed this way (key decisions)\n- Stop before deep implementation minutiae (unless in scope)\n\n**Scope Violation Prevention Strategy:**\n\nI've identified these temptation points where I might drift out of scope:\n\n1. **Risk:** Diving into [Dependency X] implementation\n   **Prevention:** Only document its interface/contract. If I start reading its internals, STOP.\n   \n2. **Risk:** Explaining [Related Feature Y] in detail\n   **Prevention:** Reference it only. One sentence about what it does, link to docs.\n   \n3. **Risk:** Over-analyzing [Low-Level Detail Z]\n   **Prevention:** Keep at appropriate abstraction level for target audience.\n\n**Evidence Collection Plan:**\n- Code examples: Extract 5-7 representative usage patterns\n- Behavior observation: [Test/run code if applicable]\n- Documentation review: Check comments, existing docs for design context\n- Dependency contracts: Document interfaces only\n\n**PROCEEDING TO ANALYSIS EXECUTION...**",
+      "agentRole": "You are planning your analysis approach. This is autonomous (no user checkpoint) but you must document your strategy clearly. The plan guides your execution and prevents scope drift.",
+      "guidance": [
+        "Choose behavior-focused approach by default (works for most cases)",
+        "Explicitly identify scope violation risks - forces you to think about boundaries",
+        "Document prevention strategies - these become your guardrails",
+        "Be specific about what you'll investigate and what you'll skip",
+        "This plan is your contract with yourself - follow it in Phase 1B"
+      ],
+      "requireConfirmation": false
+    },
+    {
+      "id": "phase-1b-analysis-execution",
+      "title": "Phase 1B: Analysis Execution with Self-Critique",
+      "prompt": "**EXECUTE: Scoped Analysis**\n\nExecuting analysis plan from Phase 1A...\n\n**ANALYSIS PROCESS:**\n\nFollow your investigation plan systematically:\n\n**For CODE subjects:**\n- Read in-scope files/components\n- Trace key execution paths (within scope)\n- Map public interfaces and APIs\n- Extract code examples showing usage\n- Note design patterns and decisions\n- Document integration points\n\n**For SYSTEM/CONCEPT subjects:**\n- Map components and their relationships\n- Trace data/control flow\n- Identify key behaviors and mechanisms\n- Extract examples or scenarios\n- Note design tradeoffs\n- Document integration patterns\n\n**For PROCESS subjects:**\n- Map steps and decision points\n- Identify participants and roles\n- Trace typical and edge-case paths\n- Extract example scenarios\n- Note design rationale\n- Document integration points\n\n**BOUNDARY ENFORCEMENT (continuous):**\n\nWhen you encounter something outside scope:\n- ✅ **REFERENCE IT:** \"This integrates with [System X] via [interface]\"\n- ✅ **LINK TO DOCS:** \"For [System X] details, see [link]\"\n- ❌ **DON'T EXPLAIN IT:** Don't dive into how it works internally\n- ❌ **DON'T ANALYZE IT:** Don't read its code or trace its logic\n\n**TEMPTATION LOGGING:**\n\nLog every time you're tempted to go out of scope:\n- \"Almost analyzed [X] implementation but stopped - out of scope\"\n- \"Tempted to explain [Y] mechanism but only referenced it\"\n- \"Started reading [Z] file but caught myself - dependency only\"\n\n**CREATE ANALYSIS.md with:**\n\n## Subject Overview\n- What it is and what it does\n- Key purpose and use cases\n\n## Core Components/Elements\n- Main parts (within scope)\n- How they relate/interact\n\n## Key Behaviors and Mechanisms\n- How it works (step-by-step where helpful)\n- Important patterns\n\n## Integration Points\n- Dependencies (interface-level only)\n- Consumers/users of this\n- Key contracts\n\n## Examples and Usage Patterns\n- Representative examples (5-7)\n- Common scenarios\n\n## Design Decisions and Tradeoffs\n- Why it's built this way\n- Key choices made\n\n## Scope Boundary Log\n- Items encountered but not analyzed (out of scope)\n- Temptations stopped\n\n---\n\n**SELF-CRITIQUE (MANDATORY):**\n\nAnswer these questions honestly:\n\n**1. Did I stay within scope boundaries?**\n→ [YES/NO with evidence]\n→ If NO: [What violations? Get user approval to adjust]\n\n**2. Did I analyze any out-of-scope dependencies in detail?**\n→ [YES/NO with specifics]\n→ Temptations logged: [count and list]\n\n**3. What tempted me to go off-track?**\n→ [List specific items and how you stopped]\n\n**4. Is my understanding depth appropriate for the scope?**\n→ [Too shallow/Right level/Too deep]\n→ Evidence: [why you think so]\n\n**5. Did I gather sufficient evidence for claims I'll make in documentation?**\n→ [YES/NO with assessment]\n→ Examples collected: [count]\n→ Behaviors verified: [how]\n\n**6. What am I still uncertain about (within scope)?**\n→ [List specific uncertainties]\n→ **CRITICAL:** Any uncertainty that blocks documentation must be resolved\n\n**7. Understanding confidence rating: __/10**\n→ **FORCING FUNCTION:** If <8/10, I MUST gather more evidence before proceeding\n→ If <8: [What additional analysis needed?]\n\n**8. Any scope violations or major uncertainties discovered?**\n→ If YES: This triggers CRITICAL CHECKPOINT for user input\n\n---\n\n**OUTPUT:**\n\nIf understanding ≥8/10 AND no critical issues:\n→ \"Analysis complete. Understanding: [X]/10. Proceeding to structure planning...\"\n\nIf understanding <8/10:\n→ \"Understanding insufficient ([X]/10). Gathering more evidence on: [specifics]...\"\n→ [Continue analysis until ≥8/10]\n\nIf critical blocking question:\n→ \"**CRITICAL CHECKPOINT:** I need your input on: [specific question]\"\n→ [Wait for user response]\n\nIf scope violations discovered:\n→ \"**SCOPE VIOLATION DETECTED:** Found [X] which affects scope boundary. Need approval to: [adjust scope / stay course]\"\n→ [Wait for user response]",
+      "agentRole": "You are executing analysis with rigorous scope enforcement and self-critique. This is autonomous unless you hit a critical blocker. Be thorough in analysis but ruthless about scope boundaries. Self-critique is mandatory and must be honest.",
+      "guidance": [
+        "Follow your Phase 1A plan systematically",
+        "Log EVERY temptation to drift out of scope - this proves discipline",
+        "Reference out-of-scope items, never explain them",
+        "Gather concrete evidence - examples, code snippets, observed behaviors",
+        "Self-critique must be honest - this is quality assurance",
+        "Understanding <8/10 is a forcing function - keep analyzing",
+        "Critical questions or scope violations trigger user checkpoint",
+        "Create ANALYSIS.md as structured artifact for later phases",
+        "Document design decisions - they inform documentation narrative"
+      ],
+      "requireConfirmation": false
+    },
+    {
+      "id": "phase-2a-structure-planning",
+      "title": "Phase 2A: Plan Documentation Structure",
+      "prompt": "**PLAN: Documentation Structure Strategy**\n\n**STRUCTURE PLANNING (Autonomous):**\n\nBased on analysis, I'll design the documentation structure.\n\n**PLANNING QUESTIONS:**\n\n1. **What structure best serves this subject?**\n   - For CODE: Comprehensive Guide (overview → how it works → usage → reference)\n   - For SYSTEMS: Architecture Guide (components → interactions → integration)\n   - For CONCEPTS: Explanation Guide (problem → solution → examples → applications)\n   - For PROCESSES: Workflow Guide (overview → steps → decision points → examples)\n\n2. **What's the optimal information flow for target audience?**\n   - What do they need to know first?\n   - What order builds understanding naturally?\n   - Where should examples appear?\n\n3. **How many sections and what depth?**\n   - Based on scope complexity\n   - Based on target audience expertise\n   - Based on success criteria (use it? modify it? understand internals?)\n\n4. **Scope alignment in structure:**\n   - Which sections document in-scope items?\n   - Where do out-of-scope items get referenced?\n   - How to make boundaries clear?\n\n**CHOSEN STRUCTURE: Comprehensive Guide**\n\n**Planned Sections:**\n\n```\n1. Overview & Context (~200 words)\n   - What [subject] is and why it exists\n   - Key concepts and terminology\n   - Quick usage example\n\n2. How It Works (~400-600 words)\n   - Core mechanisms (step-by-step)\n   - Key behaviors and patterns\n   - Integration points and dependencies\n   \n3. Usage Guide (~500-700 words)\n   - Getting started / Basic usage\n   - Common patterns (5-7 examples)\n   - Best practices\n   \n4. Reference (~300-500 words)\n   - [API/Interface/Component reference as appropriate]\n   - Parameters, options, configurations\n   \n5. Edge Cases & Troubleshooting (~200-300 words)\n   - Important gotchas\n   - Common issues and solutions\n   - Limitations\n   \n6. Related Documentation (~100 words)\n   - Dependencies (with links)\n   - Related features/systems (with links)\n   - Further reading\n```\n\n**Total Estimated Length:** ~1800-2500 words\n\n**WHY THIS STRUCTURE:**\n- Serves [target audience] who need to [success criteria]\n- Progressive disclosure: overview → understanding → usage → reference\n- Examples throughout, not isolated\n- Troubleshooting integrated for practical use\n- Clear scope boundaries in \"Related Documentation\" section\n\n**SCOPE COMPLIANCE CHECK:**\n✅ Every section maps to in-scope items from ANALYSIS.md\n✅ Out-of-scope items only in \"Related Documentation\"\n✅ No section would require explaining out-of-scope dependencies\n✅ Structure matches SCOPE_CONTRACT.md\n\n**PROCEEDING TO CREATE DETAILED OUTLINE...**",
+      "agentRole": "You are planning the documentation structure. Think strategically about what structure best serves the target audience and scope. This is the PLAN step - you'll create the detailed outline in Phase 2B.",
+      "guidance": [
+        "Choose structure based on subject type and audience needs",
+        "Consider information flow and progressive disclosure",
+        "Ensure every section maps to in-scope items",
+        "Plan for appropriate depth based on scope and audience",
+        "This is planning only - detailed outline comes next"
+      ],
+      "requireConfirmation": false
+    },
+    {
+      "id": "phase-2b-detailed-outline",
+      "title": "Phase 2B: Create Detailed Outline",
+      "prompt": "**EXECUTE: Creating Detailed Outline**\n\nFollowing the structure plan from Phase 2A, creating detailed outline...\n\n**DETAILED OUTLINE CREATION:**\n\nFor each section from Phase 2A, create specific content outline based on ANALYSIS.md:\n\n**1. Overview & Context**\n- **What:** [One-sentence description from analysis]\n- **Why:** [Purpose and problem it solves from analysis]\n- **Key Concepts:** [2-3 terms that need definition]\n- **Quick Example:** [Simplest usage pattern from analysis examples]\n\n**2. How It Works**\n- **2.1 Core Mechanism:** [Step-by-step explanation - from analysis mechanisms section]\n- **2.2 Key Behaviors:** [3-4 important behaviors from analysis]\n- **2.3 Integration Points:** [How it connects to dependencies - interface level only]\n\n**3. Usage Guide**\n- **3.1 Getting Started:** [Setup/initialization steps from analysis]\n- **3.2 Common Patterns:** [5-7 examples from analysis]\n  - Pattern 1: [Common use case A - from analysis example 1]\n  - Pattern 2: [Common use case B - from analysis example 2]\n  - Pattern 3: [Integration scenario - from analysis example 3]\n  - Pattern 4: [Edge case handling - from analysis example 4]\n  - Pattern 5: [Advanced usage - from analysis example 5]\n  - Pattern 6-7: [Additional examples if analysis has them]\n- **3.3 Best Practices:** [From design decisions in analysis]\n\n**4. Reference**\n- [API methods / Configuration options / Components / etc.]\n- [Specific items from analysis - organized logically]\n- [Parameters, types, return values, descriptions]\n\n**5. Edge Cases & Troubleshooting**\n- **Gotcha 1:** [From analysis edge cases]\n- **Gotcha 2:** [From analysis limitations]\n- **Issue → Solution pairs:** [From analysis and testing]\n\n**6. Related Documentation**\n- **Dependencies:** [From analysis dependency section - with links if available]\n- **Related Features:** [From analysis related components - with links]\n- **Further Reading:** [Background concepts or advanced topics]\n\n---\n\n**SELF-CRITIQUE (Mandatory):**\n\n**1. Does every section map to items from ANALYSIS.md?**\n→ [YES/NO with verification]\n→ If NO: [What's missing from analysis? Need to go back?]\n\n**2. Are out-of-scope items only in \"Related Documentation\"?**\n→ [YES/NO with check]\n→ If NO: [Which sections have out-of-scope items? Fix them]\n\n**3. Is the flow logical for target audience?**\n→ [YES/NO with reasoning]\n→ If NO: [How should it be reordered?]\n\n**4. Does this outline serve the success criteria?**\n→ [YES/NO - can readers achieve their goal?]\n→ If NO: [What's missing?]\n\n**5. Can I write each section from my analysis?**\n→ [YES/NO for each section]\n→ If NO for any: [What additional analysis needed? Block and gather more]\n\n**6. Outline completeness confidence: __/10**\n→ **FORCING FUNCTION:** If <8/10, identify gaps and address them\n\n**7. Scope compliance in outline: __/10**\n→ Must be ≥9/10 to proceed\n\n**OUTLINE QUALITY CHECK:**\n- Specific enough to guide writing? ✓/✗\n- All examples sourced from analysis? ✓/✗\n- No out-of-scope explanations planned? ✓/✗\n- Appropriate depth for each section? ✓/✗\n\n**OUTPUT: OUTLINE.md created**\n\n**If outline passes self-critique: Proceeding to writing planning...**\n**If issues found: Fix them now before planning writing.**",
+      "agentRole": "You are creating a detailed outline based on your structure plan and analysis findings. This is execution with mandatory self-critique. Be specific and thorough - this outline guides all writing.",
+      "guidance": [
+        "Pull every content point from ANALYSIS.md - don't invent new content",
+        "Be specific - vague outline leads to vague documentation",
+        "Every example must be from analysis - no making up examples",
+        "Self-critique is mandatory - catch scope issues before writing",
+        "Outline quality <8/10 means you need more analysis",
+        "Scope compliance <9/10 is a blocker - fix before proceeding"
+      ],
+      "requireConfirmation": false
+    },
+    {
+      "id": "phase-3a-writing-strategy",
+      "title": "Phase 3A: Plan Writing Strategy",
+      "prompt": "**PLAN: Writing Strategy**\n\n**WRITING APPROACH PLANNING (Autonomous):**\n\nBefore writing, plan HOW I'll write systematically.\n\n**PLANNING DECISIONS:**\n\n**1. Writing Order:**\n- **Recommended:** Follow outline order (1 → 2 → 3 → 4 → 5 → 6)\n- **Rationale:** Each section builds on previous understanding\n- **Alternative:** Write reference first if it's the clearest? [NO - stick to logical flow]\n\n**2. Scope Enforcement Strategy:**\n- **After every paragraph:** Check scope compliance\n- **Boundary markers:** Use explicit \"See [Link]\" for out-of-scope items\n- **Temptation logging:** Track what I almost explained but stopped\n- **Red flags:** Watch for: explaining dependencies, analyzing out-of-scope code, diving too deep\n\n**3. Example Integration:**\n- Pull examples from ANALYSIS.md examples section\n- Test/verify each example before including\n- Format consistently (code blocks, clear explanations)\n- Show complete, runnable examples (not fragments)\n\n**4. Self-Critique Checkpoints:**\n- After each section: Run 3-question scope check\n- Midpoint (after section 3): Overall quality check\n- End: Comprehensive self-audit before validation\n\n**5. Quality Standards During Writing:**\n- Accuracy: Every claim must trace to ANALYSIS.md\n- Clarity: Write for [target audience] at [expertise level]\n- Completeness: Cover all outline points\n- Scope: Zero out-of-scope explanations\n\n**RISK MITIGATION:**\n\nIdentified writing risks and prevention:\n\n**Risk 1:** Drifting into explaining [Dependency X]\n**Prevention:** When I mention it, use template: \"This integrates with [X] via [interface]. See [X Docs].\"\n\n**Risk 2:** Going too deep in \"How It Works\" section\n**Prevention:** Stick to behavior description, not implementation minutiae. Check: \"Is this level appropriate for scope?\"\n\n**Risk 3:** Creating new examples not from analysis\n**Prevention:** Only use examples from ANALYSIS.md. If I need more, note it as needing more analysis.\n\n**Risk 4:** Scope creep in Usage Guide\n**Prevention:** Each pattern must use only in-scope features. Check examples against scope contract.\n\n**WRITING CHECKPOINTS:**\n- Checkpoint 1: After Section 1 (Overview) - verify foundation is solid\n- Checkpoint 2: After Section 3 (Usage Guide) - halfway check\n- Checkpoint 3: After Section 6 (Complete) - final self-audit\n\n**PLAN CONFIRMED. PROCEEDING TO CONTENT CREATION...**",
+      "agentRole": "You are planning your writing approach strategically. Think about HOW you'll write to maintain quality and scope discipline. This is the PLAN step - actual writing comes in Phase 3B.",
+      "guidance": [
+        "Plan for scope enforcement - this is the #1 risk",
+        "Identify specific risks for this subject and plan prevention",
+        "Decide on checkpoint frequency for self-critique",
+        "Commit to only using examples from analysis",
+        "This planning prevents drift during writing"
+      ],
+      "requireConfirmation": false
+    },
+    {
+      "id": "phase-3b-content-creation",
+      "title": "Phase 3B: Execute Content Creation with Continuous Scope Monitoring",
+      "prompt": "**EXECUTE: Creating Documentation Content**\n\nExecuting writing strategy from Phase 3A, following detailed outline from Phase 2B...\n\n**WRITING PROCESS (Section by Section):**\n\n**For Each Section:**\n1. Draft content from outline and ANALYSIS.md\n2. Add examples from analysis (tested/verified)\n3. Check scope compliance (inline)\n4. Verify clarity for target audience\n5. Mark out-of-scope references clearly\n\n**SCOPE ENFORCEMENT (Continuous):**\n\n**After EVERY paragraph, ask yourself:**\n- ❓ Am I explaining something in-scope or out-of-scope?\n- ❓ If out-of-scope: Am I referencing (✓) or explaining (✗)?\n- ❓ Is this depth appropriate for scope definition?\n- ❓ Would a reader understand this is a boundary?\n\n**Marking Boundaries Clearly:**\n\n✅ GOOD (reference only):\n- \"This uses the CacheManager (see Cache Documentation) to store results.\"\n- \"For authentication details, see Auth Service Documentation.\"\n- \"Built on top of the standard logging framework.\"\n\n❌ BAD (explaining out-of-scope):\n- \"The CacheManager works by maintaining an in-memory LRU cache that...\"\n- \"Authentication is handled using JWT tokens which are validated by...\"\n- \"Logging uses Winston with custom transports configured to...\"\n\n**WRITING SECTIONS:**\n\n**Section 1: Overview & Context**\n[Write ~200 words covering what, why, key concepts, quick example]\n\n**Self-Check:**\n☑️ Scope compliant? [Check: no out-of-scope explanations]\n☑️ Clear for audience? [Check: terminology defined, example works]\n☑️ Accurate? [Check: claims match analysis]\n\n**Section 2: How It Works**\n[Write ~400-600 words covering mechanisms, behaviors, integration points]\n\n**Self-Check:**\n☑️ Scope compliant? [Check: dependencies referenced only, not explained]\n☑️ Clear for audience? [Check: step-by-step where helpful]\n☑️ Accurate? [Check: behaviors verified in analysis]\n\n**Section 3: Usage Guide**\n[Write ~500-700 words with getting started + 5-7 examples]\n\n**Self-Check:**\n☑️ Scope compliant? [Check: examples use in-scope features only]\n☑️ Clear for audience? [Check: examples are complete and runnable]\n☑️ Accurate? [Check: examples tested/verified]\n\n**Section 4: Reference**\n[Write ~300-500 words with detailed reference material]\n\n**Self-Check:**\n☑️ Scope compliant? [Check: only in-scope items documented]\n☑️ Clear for audience? [Check: comprehensive and well-organized]\n☑️ Accurate? [Check: parameters, types, behaviors correct]\n\n**Section 5: Edge Cases & Troubleshooting**\n[Write ~200-300 words with gotchas and solutions]\n\n**Self-Check:**\n☑️ Scope compliant? [Check: edge cases are in-scope ones]\n☑️ Clear for audience? [Check: actionable solutions provided]\n☑️ Accurate? [Check: issues and solutions verified]\n\n**Section 6: Related Documentation**\n[Write ~100 words with links and brief context]\n\n**Self-Check:**\n☑️ Scope compliant? [Check: just references, no explanations]\n☑️ Helpful? [Check: clear what each link covers]\n\n---\n\n**DRAFT COMPLETE - FINAL SELF-CRITIQUE:**\n\n**Scope Compliance Audit (Read through line by line):**\n- Lines documenting in-scope items: [count/percentage]\n- Lines referencing out-of-scope items: [count - should be minimal]\n- Lines explaining out-of-scope items: [count - should be ZERO]\n- Violations found: [list any violations found]\n\n**If violations found:** Fix them now before validation\n\n**Quality Self-Assessment:**\n- Accuracy (claims match analysis): __/10\n- Clarity (audience will understand): __/10\n- Completeness (all in-scope items covered): __/10\n- Scope compliance (no violations): __/10\n\n**Issues Found During Writing:**\n- [List any issues discovered and how you addressed them]\n\n**Ready for Validation:** [YES if all self-checks passed]\n\n**PROCEEDING TO ADVERSARIAL VALIDATION...**",
+      "agentRole": "You are writing documentation with continuous scope monitoring. This is autonomous - no user checkpoint unless you find issues. Write clearly for target audience, maintain scope boundaries ruthlessly, and conduct honest self-critique after each section.",
+      "guidance": [
+        "Write section by section following detailed outline",
+        "Pull content from ANALYSIS.md - don't invent new information",
+        "Check scope after every paragraph - it's that important",
+        "Mark boundaries explicitly so readers know what's in vs out",
+        "Examples must be complete, tested, and in-scope",
+        "Self-critique after each section - catch issues early",
+        "Fix violations immediately, don't leave them for validation",
+        "Be honest in quality self-assessment",
+        "If you discover critical inaccuracies, that triggers user checkpoint"
+      ],
+      "requireConfirmation": false
+    },
+    {
+      "id": "phase-4-adversarial-validation",
+      "title": "Phase 4: Adversarial Validation (CRITICAL CHECKPOINT)",
+      "prompt": "**ADVERSARIAL VALIDATION - CRITICAL CHECKPOINT**\n\nI've completed the documentation. Now I'll be my harshest critic.\n\n**VALIDATION PROCESS:**\n\n**1. SCOPE COMPLIANCE AUDIT (Line by Line):**\n\nGo through every paragraph:\n- ✓ Documents in-scope items\n- ✓ References (not explains) out-of-scope items\n- ✗ Explains out-of-scope items (VIOLATION)\n- ✗ Analyzes dependencies in detail (VIOLATION)\n\n**Scope Compliance Result: __/10**\n\n**Violations Found:**\n[If any: List specific violations with line/section references]\n[If violations: Fix them and re-audit]\n\n**Must be ≥9/10 to proceed**\n\n---\n\n**2. COMPLETENESS CHECK:**\n\nAgainst SCOPE_CONTRACT.md, verify:\n- ✓ Every in-scope item documented\n- ✓ All promised examples included\n- ✓ All behaviors explained\n- ✓ All integration points covered\n- ✗ Missing: [any in-scope items not documented]\n\n**Completeness Result: __/10**\n\n**Gaps Found:**\n[If any: List what's missing and why]\n[If gaps: Add missing content and re-check]\n\n**Must be ≥9/10 to proceed**\n\n---\n\n**3. ACCURACY VALIDATION:**\n\n**Technical Claims Verification:**\n- All behaviors described match analysis? ✓/✗\n- All code examples tested/verified? ✓/✗\n- All API signatures correct? ✓/✗\n- All integration descriptions accurate? ✓/✗\n\n**Uncertainties:**\n[List any claims you're not 100% certain about]\n\n**Accuracy Result: __/10**\n\n**Issues Found:**\n[If any: List specific accuracy concerns]\n\n**Critical Uncertainties Requiring User Confirmation:**\n[If any: List specific questions that block 9+/10 confidence]\n\n**Must be ≥9/10 to proceed** (may require user input)\n\n---\n\n**4. CLARITY ASSESSMENT:**\n\n**For Target Audience [audience type]:**\n- Can they understand the overview? ✓/✗\n- Can they follow the mechanisms explanation? ✓/✗\n- Can they use the examples successfully? ✓/✗\n- Can they find reference information? ✓/✗\n- Can they solve problems with troubleshooting section? ✓/✗\n\n**Clarity Result: __/10**\n\n**Improvements Needed:**\n[If any: List sections that could be clearer]\n\n**Must be ≥8/10 to proceed** (lower threshold - clarity is more subjective)\n\n---\n\n**5. ADVERSARIAL REVIEW QUESTIONS:**\n\n**Challenge yourself:**\n\n1. **Would a peer reviewer find scope violations I missed?**\n   → [Honest assessment]\n\n2. **Is there anything in-scope that's missing?**\n   → [Check completeness honestly]\n\n3. **Would I bet my reputation on every technical claim?**\n   → [Identify any shaky claims]\n\n4. **Could the target audience actually use this successfully?**\n   → [Put yourself in their shoes]\n\n5. **Will this become stale/incorrect quickly?**\n   → [Maintainability check]\n\n---\n\n**VALIDATION SUMMARY:**\n\n**Metrics:**\n- Scope Compliance: __/10 (need ≥9)\n- Completeness: __/10 (need ≥9)\n- Accuracy: __/10 (need ≥9)\n- Clarity: __/10 (need ≥8)\n- **Overall: __/10**\n\n**Status:**\n[PASS / FAIL with specifics]\n\n---\n\n**IF ALL METRICS MEET THRESHOLDS AND NO CRITICAL ISSUES:**\n\n✅ Validation passed. Minor improvements made:\n[List any minor issues fixed]\n\nReady for finalization.\n\n---\n\n**IF CRITICAL ISSUES FOUND (triggers user checkpoint):**\n\n**CRITICAL CHECKPOINT REQUIRED**\n\n**Issues Requiring Your Input:**\n\n**1. Accuracy Confirmation Needed:**\n- Question: [Specific technical question where you're uncertain]\n- Context: [Why this matters for documentation]\n- Current documentation says: [what you wrote]\n- Need your confirmation: [specific yes/no or factual answer]\n\n**2. Scope Violations Found:**\n- Violation: [Specific violation]\n- Location: [Section/paragraph]\n- Fix options:\n  a) Remove explanation, convert to reference only\n  b) Adjust scope to include this (expand scope contract)\n- Recommendation: [Your suggestion]\n\n**3. Quality Below Threshold:**\n- Metric: [Which metric failed]\n- Score: [X/10] (need [threshold])\n- Issues: [Specific problems]\n- Fix plan: [How you'll address it]\n\n**Your Input Required:**\n[Specific questions or decisions needed]\n\n**Once you respond, I'll implement fixes and re-validate.**\n\n---\n\n**IF MINOR ISSUES (below threshold but fixable):**\n\nI found issues preventing validation pass:\n- [List specific issues]\n\nFixing these issues now...\n[Make fixes]\n\nRe-validating...\n[Run validation again until passing]\n\n**After Passing Validation: Proceed to finalization**",
+      "agentRole": "You are conducting rigorous adversarial validation. Be your harshest critic. This is a CRITICAL CHECKPOINT if you find issues requiring user input (accuracy questions, scope violations, quality failures). Otherwise, fix issues and iterate until passing all thresholds.",
+      "guidance": [
+        "Be genuinely adversarial - actively look for problems",
+        "Scope compliance must be ≥9/10 - this is non-negotiable",
+        "Completeness must be ≥9/10 - check against scope contract systematically",
+        "Accuracy must be ≥9/10 - any uncertainty triggers user checkpoint",
+        "Clarity must be ≥8/10 - lower threshold but still important",
+        "If below threshold, fix and re-validate - no proceeding with poor quality",
+        "Critical issues (accuracy uncertainty, scope violations, quality failures) trigger user checkpoint",
+        "Minor issues should be fixed autonomously and re-validated",
+        "Be honest in self-assessment - this is quality assurance",
+        "Document all issues found and fixes made"
+      ],
+      "requireConfirmation": true,
+      "validationCriteria": [
+        {
+          "type": "contains",
+          "value": "Scope Compliance",
+          "message": "Must include scope compliance audit with rating"
+        },
+        {
+          "type": "contains",
+          "value": "Completeness",
+          "message": "Must include completeness check with rating"
+        },
+        {
+          "type": "contains",
+          "value": "Accuracy",
+          "message": "Must include accuracy validation with rating"
+        },
+        {
+          "type": "contains",
+          "value": "Clarity",
+          "message": "Must include clarity assessment with rating"
+        },
+        {
+          "type": "regex",
+          "pattern": "(9|10)/10",
+          "message": "Must show at least one metric meeting threshold (9+/10)"
+        }
+      ],
+      "hasValidation": true
+    },
+    {
+      "id": "phase-5-finalization",
+      "title": "Phase 5: Finalization & Delivery",
+      "prompt": "**FINALIZATION: Preparing Final Deliverable**\n\nValidation passed. Finalizing documentation...\n\n**FINAL STEPS:**\n\n**1. Incorporate Validation Feedback**\n[If user provided any feedback in Phase 4, incorporate it now]\n- Accuracy confirmations: [Applied]\n- Scope adjustments: [Applied]\n- Other feedback: [Applied]\n\n**2. Polish and Format**\n- Consistent heading levels\n- Code formatting (syntax highlighting hints)\n- Links working (internal and external)\n- Table of contents (if appropriate)\n- Consistent terminology throughout\n\n**3. Add Metadata**\n\nAt top of documentation:\n```\n---\nSubject: [What this documents]\nScope: [Brief scope description]\nAudience: [Target readers]\nLast Updated: [Date]\nStatus: Complete\n---\n```\n\n**4. Create Scope Map**\n\nCreate SCOPE_MAP.md:\n```markdown\n# Scope Map: [Subject] Documentation\n\n## What's Documented (In Scope)\n- [List in-scope items with brief descriptions]\n- [Link to sections in main doc]\n\n## What's Referenced (Out of Scope)\n- [Dependency X]: [Brief description] → [Link to its docs]\n- [Feature Y]: [Brief description] → [Link to its docs]\n\n## Integration Points\n- [Where this connects to other systems]\n- [Interface contracts documented]\n\n## How This Fits in the Larger System\n[Context diagram or description]\n\n## Related Documentation\n- [Links to related docs with descriptions]\n```\n\n**5. Create Maintenance Guide**\n\nCreate MAINTENANCE_NOTES.md:\n```markdown\n# Maintenance Guide: [Subject] Documentation\n\n## When to Update This Documentation\n- When [in-scope item X] changes\n- When new [functionality Y] is added to scope\n- When [integration point Z] contract changes\n\n## What to Check\n- [Specific sections to review for accuracy]\n- [Examples to re-test]\n- [Integration points to verify]\n\n## Scope Boundaries\n- Remember: [Dependency A] is out of scope - reference only\n- Remember: [Feature B] has its own docs - don't duplicate\n\n## Key Dependencies\n- [Dependency]: [Why it matters] → [Where documented]\n\n## Ownership\n- Primary: [Team/person if known]\n- Scope: [What's covered]\n```\n\n---\n\n**DELIVERY PACKAGE COMPLETE**\n\n**📦 Final Deliverable:**\n\n**1. Main Documentation: [SUBJECT]_Documentation.md** (~[word count] words)\n   Comprehensive guide covering:\n   - Overview and context\n   - How it works (mechanisms and behaviors)\n   - Usage guide with [N] examples\n   - Complete reference\n   - Edge cases and troubleshooting\n   - Related documentation links\n\n**2. Scope Map: SCOPE_MAP.md**\n   Clear visualization of:\n   - What's in scope (documented here)\n   - What's out of scope (referenced only)\n   - How this fits in the larger system\n\n**3. Maintenance Guide: MAINTENANCE_NOTES.md**\n   Guidance for keeping docs current:\n   - When to update\n   - What to check\n   - Scope reminders\n\n**4. Original Artifacts (for reference):**\n   - SCOPE_CONTRACT.md (the approved boundary)\n   - ANALYSIS.md (the investigation findings)\n\n---\n\n**📊 QUALITY METRICS ACHIEVED:**\n\n- ✅ Scope Compliance: [X]/10 (≥9 required)\n- ✅ Completeness: [X]/10 (≥9 required)\n- ✅ Accuracy: [X]/10 (≥9 required)\n- ✅ Clarity: [X]/10 (≥8 required)\n- ✅ **Overall: [X]/10**\n\n**📈 SCOPE DISCIPLINE:**\n- Temptations to drift: [N] (all stopped)\n- Scope violations: 0\n- Out-of-scope items referenced: [N]\n- Out-of-scope items explained: 0 ✓\n\n---\n\n**✅ DOCUMENTATION READY TO USE**\n\n**Subject:** [What was documented]\n**Scope:** [Brief description of boundaries]\n**Quality:** [Overall score]/10\n**Maintainability:** Scope boundaries clear, maintenance guide provided\n\n**Next Steps (if any):**\n[Any identified follow-up documentation needs]\n[Any related features that might need separate docs]\n\n**Thank you for using Scoped Documentation Workflow!**",
+      "agentRole": "You are finalizing and delivering the documentation package. This is autonomous - polish, package, and deliver with comprehensive summary. Include all artifacts and clear quality metrics.",
+      "guidance": [
+        "Incorporate any Phase 4 feedback first",
+        "Polish formatting and consistency",
+        "Add metadata for maintainability",
+        "Create scope map for clarity about boundaries",
+        "Create maintenance guide for future updates",
+        "Include all artifacts (scope contract, analysis) for reference",
+        "Provide clear quality metrics summary",
+        "Celebrate scope discipline - highlight temptations stopped",
+        "Suggest next steps if relevant",
+        "Make deliverable professional and complete"
+      ],
+      "requireConfirmation": false
+    }
+  ]
+}
+