ace-handbook 0.19.0

data/handbook/workflow-instructions/handbook/review-guides.wf.md

@@ -0,0 +1,348 @@
+---
+doc-type: workflow
+title: Review Guides
+purpose: Documentation for ace-handbook/handbook/workflow-instructions/handbook/review-guides.wf.md
+ace-docs:
+  last-updated: 2026-03-12
+  last-checked: 2026-03-21
+---
+
+# Review Guides
+
+## Goal
+
+Systematically review multiple development guide files for compliance with standards, consistency, conceptual focus, and
+quality. This meta-workflow provides batch review capabilities for handbook maintainers to ensure guides follow
+established patterns and maintain coherent coverage of development principles and standards.
+
+## Prerequisites
+
+* Understanding of guide definition principles and standards
+* Access to handbook guide standards
+* Knowledge of existing guide patterns and organization
+* List of guide files to review (or intent to review all)
+
+## Project Context Loading
+
+* Load guide standards: `ace-handbook/handbook/guides/meta/guides-definition.g.md`
+* Load markdown standards: `ace-handbook/handbook/guides/meta/markdown-definition.g.md`
+* Load example guides from `ace-handbook/handbook/guides/`
+
+## Process Steps
+
+1.  **Define Review Scope:**
+    * Determine which guides to review:
+      * All guides in `guides/`
+      * Specific subset based on criteria (category, recent changes, specific domain)
+      * Individual guides provided by user
+    * Identify review objectives:
+      * Standards compliance and conceptual focus
+      * Language modularity implementation
+      * Cross-reference integrity
+      * Content gaps and coverage analysis
+2.  **Gather Guide Inventory:**
+    * List all guide files to review:
+      
+          find guides -name "*.g.md" -type f
+      {: .language-bash}
+    
+    * Identify language-specific sub-guides:
+      
+          find guides -name "*.md" -not -name "*.g.md" -type f
+      {: .language-bash}
+    
+    * Group guides by category (Core Process, Standards, Technical, etc.)
+    * Note file relationships and cross-references
+3.  **Initialize Review Process:**
+    * Create review session directory:
+      
+          mkdir -p dev-taskflow/current/v.X.Y.Z-release/guide-review/$(date +%Y%m%d)
+      {: .language-bash}
+    
+    * Create review summary template:
+      
+          # Guide Review Session - [Date]
+               
+          ## Review Scope
+          * Total guides reviewed: [N main guides]
+          * Language sub-guides reviewed: [N sub-guides]
+          * Review criteria: [Conceptual focus, standards compliance, consistency]
+               
+          ## Coverage Analysis
+          * Core development processes: [Status]
+          * Standards and best practices: [Status]
+          * Technical implementation guides: [Status]
+          * Meta and documentation guides: [Status]
+               
+          ## Summary Results
+          * ✅ Compliant guides: [N]
+          * ⚠️ Guides needing minor improvements: [N]
+          * ❌ Guides needing major revision: [N]
+          * 📝 Content gaps identified: [N]
+               
+          ## Detailed Findings
+          [Individual guide assessments]
+               
+          ## Recommended Actions
+          [Prioritized improvement tasks]
+      {: .language-markdown}
+4.  **Review Each Guide Systematically:**
+    
+    For each guide file, assess the following areas:
+    
+    **Conceptual Focus Compliance:**
+    
+    * ✅ Focuses on "why" (principles, concepts, standards)
+    * ✅ Explains rationale behind recommendations
+    * ✅ Avoids step-by-step procedures (leaves those to workflows)
+    * ✅ Provides decision-making context
+    **Structure and Organization:**
+    
+    * ✅ Uses proper `.g.md` naming convention
+    * ✅ Follows noun-phrase naming pattern
+    * ✅ Has clear, scannable structure with headings
+    * ✅ Organized logically for quick reference
+    **Language Modularity:**
+    
+    * ✅ Main guide is language-agnostic (if applicable)
+    * ✅ Language-specific details extracted to sub-guides
+    * ✅ Proper subdirectory structure for language variants
+    * ✅ Clear navigation between main and sub-guides
+    **Content Quality:**
+    
+    * ✅ Information is accurate and up-to-date
+    * ✅ Examples illustrate concepts (not procedures)
+    * ✅ Terminology is consistent with project standards
+    * ✅ Cross-references are accurate and helpful
+5.  **Analyze Language Modularity Implementation:**
+    
+    For guides with language-specific content:
+    
+    **Main Guide Assessment:**
+    
+    * Does it contain language-specific implementation details?
+    * Are general principles clearly separated from specifics?
+    * Does it properly reference language sub-guides?
+    **Sub-Guide Assessment:**
+    
+    * Are language-specific guides appropriately focused?
+    * Do they follow the `[topic]/[language].md` pattern?
+    * Do they integrate well with main guide principles?
+    * Are they consistent across different languages?
+    **Cross-Reference Validation:**
+    
+    * Are links between main and sub-guides accurate?
+    * Do sub-guides reference back to main principles?
+    * Are external references to guides correct?
+6.  **Document Review Findings:**
+    
+    For each guide, create a standardized assessment:
+    
+        ### [Guide Name] - [filename.g.md]
+           
+        **Overall Status:** ✅ Compliant | ⚠️ Minor Issues | ❌ Major Issues
+        **Category:** [Core Process | Standards | Technical | Meta]
+           
+        **Conceptual Focus Assessment:**
+        * Principle-based content: ✅/❌
+        * Avoids procedures: ✅/❌
+        * Provides decision context: ✅/❌
+           
+        **Structure Assessment:**
+        * Naming convention: ✅/❌
+        * Scannable organization: ✅/❌
+        * Logical flow: ✅/❌
+           
+        **Language Modularity Assessment:**
+        * Main guide language-agnostic: ✅/❌/N/A
+        * Sub-guides properly structured: ✅/❌/N/A
+        * Clear navigation: ✅/❌/N/A
+           
+        **Content Quality Assessment:**
+        * Accuracy: ✅ Current | ⚠️ Minor issues | ❌ Outdated
+        * Consistency: ✅ Consistent | ⚠️ Some issues | ❌ Inconsistent
+        * Completeness: ✅ Complete | ⚠️ Minor gaps | ❌ Major gaps
+           
+        **Cross-Reference Assessment:**
+        * Internal links: ✅ Working | ⚠️ Some broken | ❌ Many broken
+        * External references: ✅ Accurate | ⚠️ Some issues | ❌ Incorrect
+           
+        **Issues Identified:**
+        * [Specific issue 1]
+        * [Specific issue 2]
+           
+        **Recommended Actions:**
+        * [Priority level] [Specific action needed]
+    {: .language-markdown}
+
+7.  **Analyze Guide Coverage and Organization:**
+    
+    **Coverage Assessment:**
+    
+    * Are all major development areas covered?
+    * Are there gaps in standards or best practices?
+    * Do guides complement each other effectively?
+    * Are there overlaps that could be consolidated?
+    **Organization Assessment:**
+    
+    * Is the categorization in README.md logical?
+    * Are related guides clearly connected?
+    * Is the progression from basic to advanced clear?
+    * Are cross-references helping navigation?
+8.  **Check Cross-Reference Integrity:**
+    * Verify all internal links work correctly
+    * Check references to workflow instructions
+    * Validate external links and references
+    * Ensure bi-directional references where appropriate
+9.  **Prioritize Improvement Actions:**
+    
+    **Critical Issues (Fix Immediately):**
+    
+    * Guides that are procedural instead of conceptual
+    * Broken cross-references or navigation
+    * Serious inaccuracies or outdated information
+    * Major structural problems
+    **High Priority Issues (Fix Soon):**
+    
+    * Language modularity violations
+    * Inconsistent terminology usage
+    * Missing cross-references
+    * Content gaps in important areas
+    **Medium Priority Issues (Plan for Fix):**
+    
+    * Minor accuracy updates
+    * Improved examples or explanations
+    * Better organization or structure
+    * Enhanced scanability
+    **Low Priority Issues (Nice to Have):**
+    
+    * Additional examples
+    * Minor formatting improvements
+    * Enhanced cross-references
+10. **Generate Comprehensive Review Report:**
+    * Compile complete assessment of guide collection
+    * Include coverage analysis and gap identification
+    * Document cross-reference integrity status
+    * Provide actionable improvement roadmap
+    * Suggest organizational improvements
+
+## Review Criteria and Standards
+
+### Conceptual Focus Requirements
+
+* Explains principles and rationale ("why")
+* Avoids step-by-step procedures ("how")
+* Provides decision-making context
+* Links to workflows for implementation
+
+### Structure Standards
+
+* Uses `.g.md` naming convention
+* Follows noun-phrase naming pattern
+* Organized with clear, scannable headings
+* Logical flow from concepts to specifics
+
+### Language Modularity Standards
+
+* Main guides are language-agnostic
+* Language-specific content in sub-guides
+* Sub-guide pattern: `[topic]/[language].md`
+* Clear navigation between variants
+
+### Content Quality Standards
+
+* Information is accurate and current
+* Examples illustrate concepts, not procedures
+* Terminology matches project standards
+* Cross-references are accurate and helpful
+
+## Automated Review Checks
+
+### Basic Compliance Checks
+
+    # Check for proper .g.md naming
+    find guides -name "*.md" -not -name "*.g.md" -not -path "*/guides/*/" -type f
+    
+    # Check for procedural language in guides
+    grep -r "step.*:" guides/*.g.md
+    grep -r "first.*then" guides/*.g.md
+    
+    # Check for broken internal links
+    grep -r "](\./" guides/ --include="*.md"
+{: .language-bash}
+
+### Language Modularity Checks
+
+    # Find guides with potential language-specific content
+    grep -r "ruby\|python\|javascript\|typescript" guides/*.g.md
+    
+    # Check sub-guide organization
+    find guides -mindepth 2 -name "*.md" -type f
+{: .language-bash}
+
+### Cross-Reference Validation
+
+    # Check for broken README references
+    grep -f <(find guides -name "*.g.md" -exec basename {} \;) guides/README.md
+    
+    # Validate workflow references
+    grep -r "workflow-instructions/" guides/ --include="*.md"
+{: .language-bash}
+
+## Success Criteria
+
+* All targeted guides systematically reviewed
+* Conceptual focus compliance assessed for each guide
+* Language modularity implementation validated
+* Cross-reference integrity verified
+* Coverage gaps and organizational issues identified
+* Prioritized improvement plan created
+* Review session documented with actionable recommendations
+
+## Common Review Patterns
+
+### New Guide Review
+
+* Verify conceptual focus from start
+* Check proper naming and structure
+* Validate language modularity decisions
+* Ensure integration with existing guides
+
+### Existing Guide Maintenance
+
+* Update for current standards and practices
+* Check for procedural drift
+* Validate cross-references still accurate
+* Consider language modularity improvements
+
+### Collection-Wide Analysis
+
+* Identify coverage gaps and overlaps
+* Analyze organizational effectiveness
+* Plan systematic improvements
+* Consider consolidation opportunities
+
+## Error Handling
+
+**Guide contains procedural content:**
+
+* Identify specific procedural sections
+* Determine if content should move to workflow instructions
+* Plan refactoring to maintain conceptual focus
+
+**Language modularity violations found:**
+
+* Extract language-specific content to sub-guides
+* Refactor main guide to be language-agnostic
+* Create clear navigation between variants
+
+**Significant coverage gaps identified:**
+
+* Document gaps with priority assessment
+* Plan new guide creation or existing guide expansion
+* Consider impact on overall guide organization
+
+## Usage Example
+
+> "Review all development guides in guides/ for conceptual focus compliance, language modularity implementation, and
+> identify any coverage gaps in our development standards"

data/handbook/workflow-instructions/handbook/review-workflows.wf.md

@@ -0,0 +1,299 @@
+---
+doc-type: workflow
+title: Review Workflows
+purpose: Documentation for ace-handbook/handbook/workflow-instructions/handbook/review-workflows.wf.md
+ace-docs:
+  last-updated: 2026-03-12
+  last-checked: 2026-03-21
+---
+
+# Review Workflows
+
+## Goal
+
+Systematically review multiple workflow instruction files for compliance with standards, consistency, and quality. This
+meta-workflow provides batch review capabilities for handbook maintainers to ensure workflow instructions follow
+established patterns and maintain high quality across the entire collection.
+
+## Prerequisites
+
+* Understanding of workflow instruction standards and principles
+* Access to handbook guides and workflow standards
+* Knowledge of existing workflow patterns
+* List of workflow files to review (or intent to review all)
+
+## Project Context Loading
+
+* Load workflow standards: `ace-handbook/handbook/guides/meta/workflow-instructions-definition.g.md`
+* Load markdown standards as needed from `ace-handbook/handbook/guides/meta/markdown-definition.g.md`
+* Load a current workflow example via `ace-bundle wfi://handbook/manage-workflows`
+* Load a current maintenance example via `ace-bundle wfi://handbook/update-docs`
+
+## Process Steps
+
+1.  **Define Review Scope:**
+    * Determine which workflows to review:
+      * All workflows in `handbook/workflow-instructions/`
+      * Specific subset based on criteria (new, recently modified, specific category)
+      * Individual workflows provided by user
+    * Identify review objectives:
+      * Standards compliance check
+      * Consistency review across workflows
+      * Quality assessment and improvement
+      * Template synchronization validation
+2.  **Gather Workflow Inventory:**
+    * List all workflow files to review:
+      
+          find workflow-instructions -name "*.wf.md" -type f
+      {: .language-bash}
+    
+    * Group workflows by category or type for systematic review
+    * Note file modification dates and sizes for context
+    * Create review tracking structure
+3.  **Initialize Review Process:**
+    * Create review session directory:
+      
+          mkdir -p dev-taskflow/current/v.X.Y.Z-release/workflow-review/$(date +%Y%m%d)
+      {: .language-bash}
+    
+    * Create review summary template:
+      
+          # Workflow Review Session - [Date]
+               
+          ## Review Scope
+          * Total workflows reviewed: [N]
+          * Review criteria: [Standards compliance, consistency, quality]
+               
+          ## Summary Results
+          * ✅ Compliant workflows: [N]
+          * ⚠️ Workflows needing minor fixes: [N]
+          * ❌ Workflows needing major fixes: [N]
+               
+          ## Detailed Findings
+          [Individual workflow assessments]
+               
+          ## Recommended Actions
+          [Prioritized improvement tasks]
+      {: .language-markdown}
+4.  **Review Each Workflow Systematically:**
+    
+    For each workflow file, assess the following areas:
+    
+    **Structure Compliance:**
+    
+    * ✅ Contains required sections: Goal, Prerequisites, Project Context Loading, Process Steps
+    * ✅ Uses proper markdown structure and formatting
+    * ✅ Follows verb-first naming convention (.wf.md)
+    * ✅ Has clear, single-sentence goal statement
+    **Self-Containment:**
+    
+    * ✅ No external dependencies or broken references
+    * ✅ Embedded templates use proper format
+    * ✅ All necessary examples and patterns included
+    * ✅ Context loading section complete and accurate
+    **Content Quality:**
+    
+    * ✅ Instructions are clear and actionable
+    * ✅ Process steps are logically ordered
+    * ✅ Examples and commands are accurate
+    * ✅ Error handling guidance provided
+    **Consistency:**
+    
+    * ✅ Terminology matches project standards
+    * ✅ Structure follows established patterns
+    * ✅ Cross-references are accurate
+    * ✅ Template embedding follows standards
+5.  **Document Review Findings:**
+    
+    For each workflow, create a standardized assessment:
+    
+        ### [Workflow Name] - [filename.wf.md]
+           
+        **Overall Status:** ✅ Compliant | ⚠️ Minor Issues | ❌ Major Issues
+           
+        **Structure Assessment:**
+        * Required sections: ✅/❌
+        * Naming convention: ✅/❌
+        * Markdown formatting: ✅/❌
+           
+        **Self-Containment Assessment:**
+        * External dependencies: ✅ None | ⚠️ Some | ❌ Many
+        * Template embedding: ✅ Correct | ⚠️ Minor issues | ❌ Incorrect
+        * Context loading: ✅ Complete | ⚠️ Partial | ❌ Missing
+           
+        **Content Quality Assessment:**
+        * Clarity: ✅ Clear | ⚠️ Some issues | ❌ Unclear
+        * Completeness: ✅ Complete | ⚠️ Minor gaps | ❌ Major gaps
+        * Accuracy: ✅ Accurate | ⚠️ Minor errors | ❌ Major errors
+           
+        **Issues Identified:**
+        * [Specific issue 1]
+        * [Specific issue 2]
+           
+        **Recommended Actions:**
+        * [Priority level] [Specific action needed]
+    {: .language-markdown}
+
+6.  **Analyze Cross-Workflow Consistency:**
+    * Compare terminology usage across workflows
+    * Identify inconsistent patterns or structures
+    * Check for duplicate content that could be consolidated
+    * Verify cross-references between workflows are accurate
+    * Assess overall cohesion of workflow collection
+7.  **Prioritize Improvement Actions:**
+    
+    **Critical Issues (Fix Immediately):**
+    
+    * Broken references or dependencies
+    * Missing required sections
+    * Incorrect or dangerous commands
+    * Major structural problems
+    **High Priority Issues (Fix Soon):**
+    
+    * Inconsistent terminology
+    * Minor structural issues
+    * Outdated examples or patterns
+    * Missing error handling
+    **Medium Priority Issues (Plan for Fix):**
+    
+    * Clarity improvements
+    * Better examples or explanations
+    * Enhanced self-containment
+    * Template synchronization needs
+    **Low Priority Issues (Nice to Have):**
+    
+    * Minor formatting improvements
+    * Additional examples
+    * Enhanced cross-references
+8.  **Create Action Plan:**
+    * Group related issues for efficient fixing
+    * Estimate effort required for each improvement
+    * Assign priority levels and target timelines
+    * Consider impact on other workflows or guides
+    * Plan for validation after fixes are implemented
+9.  **Generate Review Report:**
+    * Compile comprehensive review summary
+    * Include statistical overview of compliance
+    * List all identified issues with priorities
+    * Provide actionable improvement plan
+    * Document review methodology for future sessions
+
+## Review Criteria and Standards
+
+### Required Workflow Sections
+
+1.  **Goal**: Clear, single-sentence objective
+2.  **Prerequisites**: Specific conditions and requirements
+3.  **Project Context Loading**: Files to load for context
+4.  **Process Steps**: Detailed, actionable instructions
+5.  **Success Criteria** or similar validation section
+
+### Self-Containment Requirements
+
+* No references to external workflow files
+* All templates embedded using proper format
+* Complete context loading section
+* All necessary examples included inline
+* No broken links or dependencies
+
+### Quality Standards
+
+* Instructions are specific and actionable
+* Examples are accurate and current
+* Error handling is provided
+* Technology-agnostic where possible
+* Consistent with project terminology
+
+### Template Embedding Standards
+
+    <templates>
+    <template path="relative/path/to/template.md">
+    [Template content]
+    </template>
+    </templates>
+{: .language-xml}
+
+## Batch Processing Patterns
+
+### Automated Checks
+
+Use shell commands to quickly identify common issues:
+
+    # Check for missing required sections
+    for file in workflow-instructions/*.wf.md; do
+      if ! grep -q "## Goal" "$file"; then
+        echo "Missing Goal section: $file"
+      fi
+    done
+    
+    # Check for external workflow references
+    grep -r "workflow-instructions/" workflow-instructions/ --include="*.wf.md"
+    
+    # Check for broken template embedding
+    grep -r "<template" workflow-instructions/ --include="*.wf.md" | grep -v "path="
+{: .language-bash}
+
+### Progress Tracking
+
+* Maintain checklist of workflows reviewed
+* Track time spent on each workflow assessment
+* Document patterns found across multiple workflows
+* Note common issues for systematic addressing
+
+## Success Criteria
+
+* All targeted workflows systematically reviewed
+* Standardized assessment completed for each workflow
+* Issues categorized by priority and type
+* Cross-workflow consistency analysis complete
+* Actionable improvement plan created with timelines
+* Review session documented for future reference
+* Critical issues identified for immediate action
+
+## Common Review Patterns
+
+### New Workflow Review
+
+* Focus on structure compliance and self-containment
+* Verify all required sections present
+* Check examples and commands for accuracy
+* Ensure proper template embedding format
+
+### Existing Workflow Maintenance
+
+* Compare against current standards
+* Check for outdated examples or patterns
+* Verify cross-references still accurate
+* Update for consistency with newer workflows
+
+### Comprehensive Collection Review
+
+* Analyze patterns across all workflows
+* Identify opportunities for standardization
+* Look for content that could be consolidated
+* Plan systematic improvements
+
+## Error Handling
+
+**Large number of workflows to review:**
+
+* Break into manageable batches (5-10 workflows per session)
+* Use automated checks to identify obvious issues first
+* Focus on critical issues before minor improvements
+
+**Inconsistent standards found:**
+
+* Document current state before making changes
+* Plan systematic updates to maintain consistency
+* Consider updating standards if patterns have evolved
+
+**Time constraints for comprehensive review:**
+
+* Prioritize critical and high-priority issues
+* Use sampling approach for large collections
+* Focus on workflows used most frequently
+
+## Usage Example
+
+> "Review all workflow instructions in workflow-instructions/ for compliance with current standards and identify any
+> inconsistencies or improvement opportunities"