From e1c7043ba0eff30d0a98ad44d0c167fb4b7825c7 Mon Sep 17 00:00:00 2001 From: Joshua Magady Date: Tue, 21 Oct 2025 00:53:10 -0500 Subject: [PATCH] feat: add chapter-draft template to technical writing pack --- .../bmad-technical-writing/README.md | 46 +++-- .../bmad-technical-writing/config.yaml | 4 +- .../workflows/book-planning-workflow.yaml | 146 +++++++++++++++ .../workflows/code-example-workflow.yaml | 149 +++++++++++++++ .../workflows/technical-review-workflow.yaml | 176 ++++++++++++++++++ 5 files changed, 508 insertions(+), 13 deletions(-) create mode 100644 expansion-packs/bmad-technical-writing/workflows/book-planning-workflow.yaml create mode 100644 expansion-packs/bmad-technical-writing/workflows/code-example-workflow.yaml create mode 100644 expansion-packs/bmad-technical-writing/workflows/technical-review-workflow.yaml diff --git a/expansion-packs/bmad-technical-writing/README.md b/expansion-packs/bmad-technical-writing/README.md index d9bd60c3..47617be7 100644 --- a/expansion-packs/bmad-technical-writing/README.md +++ b/expansion-packs/bmad-technical-writing/README.md @@ -13,7 +13,7 @@ The Technical Writing Expansion Pack extends BMad-Method with a comprehensive su - 📋 **15 Quality Checklists** - Technical accuracy, security, performance, publisher compliance, accessibility - 🎯 **9 Professional Templates** - Book planning, chapter development, review, and publishing - 📚 **6 Knowledge Bases** - Comprehensive publisher guidelines and technical writing standards -- 🔄 **2 Core Workflows** - Chapter development and tutorial creation workflows +- 🔄 **5 Core Workflows** - Complete orchestration from book planning to technical review ## ✍️ Included Agents @@ -61,9 +61,16 @@ npx bmad-method install /bmad-tw:book-publisher ``` -### Core Workflows (Sprint 2) +### Core Workflows (Sprint 2 & 2.5) -**Chapter Development Workflow** - Complete chapter creation from outline to publisher-ready: +**Book Planning Workflow** *(Sprint 2.5)* - Complete book planning from concept to approved outline: +1. Book Publisher drafts comprehensive book proposal +2. Instructional Designer creates detailed book outline +3. Instructional Designer validates learning progression +4. Technical Editor reviews outline for clarity +5. Book Publisher verifies publisher requirements + +**Chapter Development Workflow** *(Sprint 2)* - Complete chapter creation from outline to publisher-ready: 1. Tutorial Architect creates chapter outline 2. Code Curator develops and tests all code examples 3. Tutorial Architect writes complete chapter draft @@ -72,7 +79,7 @@ npx bmad-method install 6. Technical Editor performs professional copy editing 7. Tutorial Architect finalizes chapter for publication -**Tutorial Creation Workflow** - Build effective hands-on tutorials: +**Tutorial Creation Workflow** *(Sprint 2)* - Build effective hands-on tutorials: 1. Instructional Designer designs learning path 2. Tutorial Architect creates step-by-step structure 3. Code Curator develops and tests tutorial code @@ -81,6 +88,19 @@ npx bmad-method install 6. Tutorial Architect revises based on testing 7. Instructional Designer validates learning effectiveness +**Code Example Workflow** *(Sprint 2.5)* - Develop, test, and document code examples: +1. Code Curator develops code example +2. Code Curator tests on all target platforms +3. Code Curator verifies code quality +4. Code Curator performs security review +5. Code Curator adds comprehensive documentation + +**Technical Review Workflow** *(Sprint 2.5)* - Comprehensive expert review of chapter: +1. Technical Reviewer verifies technical accuracy +2. Code Curator reviews all code examples +3. Technical Reviewer validates best practices +4. Technical Reviewer compiles comprehensive report + ### Common Use Cases - **Book Planning** - Create comprehensive book outlines with learning objectives @@ -144,13 +164,16 @@ npx bmad-method install - Manning MEAP checklist - Accessibility checklist -### Workflows (2 Core Workflows) +### Workflows (5 Core Workflows) **Sprint 2:** - `chapter-development-workflow.yaml` - Complete chapter creation workflow - `tutorial-creation-workflow.yaml` - Tutorial development workflow -**Note:** Sprint 2.5 will add 3 additional workflows (book planning, code example creation, technical review) for a total of 5 core workflows. +**Sprint 2.5:** +- `book-planning-workflow.yaml` - Book planning from concept to approved outline +- `code-example-workflow.yaml` - Code example development and testing +- `technical-review-workflow.yaml` - Comprehensive technical review ### Knowledge Bases (6 Total) @@ -212,7 +235,7 @@ Special thanks to Brian (BMad) for creating the BMad Method framework. --- -**Version:** 0.2.0 (Sprint 2 - Beta Release) +**Version:** 0.2.5 (Sprint 2.5 - Workflow Completion) **Compatible with:** BMad Method v4.0+ **Last Updated:** 2024 @@ -233,11 +256,12 @@ Special thanks to Brian (BMad) for creating the BMad Method framework. - ✅ 2 core workflows (chapter development, tutorial creation) - ✅ Expanded knowledge bases (publisher guidelines, writing standards) -## 🚧 Roadmap +**Sprint 2.5 (Complete):** Workflow orchestration completion +- ✅ 3 additional workflows: Book Planning Workflow, Code Example Workflow, Technical Review Workflow +- ✅ Total: 5 core workflows for complete book development +- ✅ Version bumped to 0.2.5 -**Sprint 2.5** (Next): -- 3 additional workflows: Book Planning Workflow, Code Example Workflow, Technical Review Workflow -- Total: 5 core workflows for complete book development +## 🚧 Roadmap **Sprint 3** (Planned): - API Documenter agent diff --git a/expansion-packs/bmad-technical-writing/config.yaml b/expansion-packs/bmad-technical-writing/config.yaml index 15123fc9..3d7d01a7 100644 --- a/expansion-packs/bmad-technical-writing/config.yaml +++ b/expansion-packs/bmad-technical-writing/config.yaml @@ -1,11 +1,11 @@ # name: bmad-technical-writing -version: 0.2.0 +version: 0.2.5 short-title: Technical Book Writing Studio description: >- Comprehensive AI-powered technical writing framework for technical book authors, technical trainers, and documentation specialists. Provides 6 - specialized agents, 2 core workflows, and professional quality assurance tools + specialized agents, 5 core workflows, and professional quality assurance tools for planning, writing, reviewing, and publishing technical books with code examples, tutorials, and learning objectives. Includes 15 checklists for technical accuracy, security, performance, publisher compliance, and diff --git a/expansion-packs/bmad-technical-writing/workflows/book-planning-workflow.yaml b/expansion-packs/bmad-technical-writing/workflows/book-planning-workflow.yaml new file mode 100644 index 00000000..937ff492 --- /dev/null +++ b/expansion-packs/bmad-technical-writing/workflows/book-planning-workflow.yaml @@ -0,0 +1,146 @@ +workflow: + id: book-planning-workflow + name: Technical Book Planning + description: Complete book planning workflow from concept to approved outline. Guides technical authors through proposal creation, outline design, learning path validation, editorial review, and publisher requirements verification. Ensures pedagogical soundness and publisher compliance before chapter development begins. + type: book-planning + project_types: + - technical-book + - tutorial-series + - training-materials + sequence: + - agent: book-publisher + creates: book-proposal.md + requires: + - book_topic + - target_audience + - publisher (optional) + notes: "Draft comprehensive book proposal using *create-proposal command. Include market analysis, competitive titles, target audience profile, unique value proposition, chapter list (high-level), author platform, and timeline. Use templates/book-proposal-tmpl.yaml. SAVE OUTPUT: Copy final proposal to docs/planning/book-proposal.md" + + - agent: instructional-designer + creates: book-outline.md + requires: book-proposal.md + notes: "Create detailed book outline using *design-outline command. Define learning progression across chapters, prerequisites for each chapter, main topics and subtopics, exercise strategy, and difficulty curve. Use templates/book-outline-tmpl.yaml. Ensure pedagogical soundness and logical skill building. SAVE OUTPUT: Copy outline to docs/planning/book-outline.md" + + - agent: instructional-designer + validates: book-outline.md + requires: book-outline.md + notes: "Validate learning progression and difficulty curve. Check prerequisite flow ensures no knowledge gaps, concepts build logically chapter by chapter, exercises progress from basic to advanced, reader can complete book successfully with stated prerequisites. Use learning-objectives-checklist.md and prerequisite-clarity-checklist.md. SAVE OUTPUT: Create validation report at docs/planning/learning-path-validation.md" + + - agent: technical-editor + reviews: book-outline.md + requires: validated outline + notes: "Review outline for clarity, consistency, and professional quality using *review-outline command. Check chapter titles are clear and compelling, topics avoid duplication, terminology is consistent, structure follows publisher best practices, accessibility considerations addressed. SAVE OUTPUT: Return polished outline with editorial notes at docs/planning/book-outline-edited.md" + + - agent: book-publisher + finalizes: book-outline.md + requires: polished outline + notes: "Verify publisher requirements and format compliance. Check outline matches publisher chapter count guidelines, technical depth appropriate for series/imprint, format follows publisher template, timeline is realistic for publication schedule. Use publisher-specific checklist (packtpub-submission-checklist.md, oreilly-format-checklist.md, or manning-meap-checklist.md). SAVE OUTPUT: Copy final approved outline to docs/planning/book-outline-final.md and set status to 'Ready for Chapter Development'" + + flow_diagram: | + ```mermaid + graph TD + A[Start: Book Concept] --> B[book-publisher: Draft Proposal] + B --> C[instructional-designer: Design Outline] + C --> D[instructional-designer: Validate Learning Path] + D --> E{Prerequisites Flow?} + E -->|Issues Found| F[instructional-designer: Adjust Outline] + F --> D + E -->|Valid| G[technical-editor: Editorial Review] + G --> H[book-publisher: Publisher Format Check] + H --> I{Meets Requirements?} + I -->|Needs Changes| J[Adjust for Publisher] + J --> G + I -->|Approved| K[Final Outline Approved] + K --> L[Ready for Chapter Development] + + B -.-> B1[Optional: Market Research] + C -.-> C1[Optional: Competitive Analysis] + D -.-> D1[Optional: Pedagogical Review] + + style L fill:#90EE90 + style B fill:#FFE4B5 + style C fill:#FFE4B5 + style D fill:#ADD8E6 + style G fill:#ADD8E6 + style H fill:#F0E68C + ``` + + decision_guidance: + when_to_use: + - Planning a new technical book from scratch + - Pitching book proposal to publisher + - Need structured approach to outline creation + - Want to validate pedagogical design before writing + - Working with traditional publisher with specific requirements + + when_not_to_use: + - Book outline already approved (jump to chapter development) + - Self-publishing without strict format requirements + - Converting existing content to book (use revision workflow) + + quality_gates: + proposal_complete: + - Market analysis included + - Target audience clearly defined + - Competitive titles identified + - Unique value proposition stated + - High-level chapter list provided + - Author platform described + - Realistic timeline included + + outline_complete: + - All chapters have clear titles + - Learning objectives defined for each chapter + - Prerequisites stated for each chapter + - Topics and subtopics outlined + - Exercise strategy defined + - Estimated page counts provided + - Checklist: prerequisite-clarity-checklist.md + + learning_path_validated: + - No knowledge gaps between chapters + - Difficulty curve is smooth + - Prerequisites are achievable + - Exercises progress appropriately + - Reader can succeed with stated background + - Checklists: learning-objectives-checklist.md, prerequisite-clarity-checklist.md + + editorial_complete: + - Chapter titles are compelling + - No topic duplication + - Terminology consistent throughout + - Structure follows best practices + - Accessibility considerations addressed + + publisher_approved: + - Chapter count matches guidelines + - Technical depth appropriate + - Format matches publisher template + - Timeline is realistic + - Checklists: publisher-specific (packtpub, oreilly, manning) + + handoff_prompts: + concept_to_proposal: "Starting book planning for {{book_topic}} targeting {{target_audience}}. Publisher: {{publisher}}. Creating comprehensive proposal." + proposal_to_outline: "Proposal approved with {{chapter_count}} planned chapters. Creating detailed pedagogical outline with learning progression." + outline_to_validation: "Book outline complete. Validating prerequisite flow and difficulty curve across {{chapter_count}} chapters." + validation_to_editorial: "Learning path validated successfully. Ready for editorial review to ensure clarity and consistency." + editorial_to_publisher: "Editorial review complete. Checking outline against {{publisher}} format requirements and submission guidelines." + publisher_to_final: "Publisher requirements verified. Book outline approved and ready for chapter development. Save to docs/planning/book-outline-final.md." + + time_estimates: + draft_proposal: "4-8 hours" + design_outline: "8-12 hours" + validate_learning_path: "3-5 hours" + editorial_review: "3-5 hours" + publisher_format_check: "2-3 hours" + total_time: "20-33 hours for complete book planning" + + best_practices: + - Start with clear target audience definition - affects everything + - Research competitive titles before outlining + - Ensure realistic prerequisites (don't assume too much) + - Build difficulty progressively (avoid knowledge jumps) + - Plan exercises early (they affect chapter structure) + - Verify publisher requirements before deep work + - Get outline approved before writing any chapters + - Consider reader's learning journey, not just content coverage diff --git a/expansion-packs/bmad-technical-writing/workflows/code-example-workflow.yaml b/expansion-packs/bmad-technical-writing/workflows/code-example-workflow.yaml new file mode 100644 index 00000000..254ad157 --- /dev/null +++ b/expansion-packs/bmad-technical-writing/workflows/code-example-workflow.yaml @@ -0,0 +1,149 @@ +workflow: + id: code-example-workflow + name: Create Tested Code Example + description: Complete code example development workflow from initial code to tested, secure, documented example. Guides code curators through development, testing, quality verification, security review, and documentation. Ensures all code examples are production-quality, secure, and well-documented before inclusion in technical content. + type: code-development + project_types: + - technical-book + - tutorial-series + - training-materials + - technical-documentation + sequence: + - agent: code-curator + creates: code-example/ + requires: + - example_purpose + - target_version + notes: "Develop code example using *create-example command. Write clean, idiomatic code that demonstrates the concept clearly. Include proper error handling, follow language conventions, add inline comments for complex logic. Use templates/code-example-tmpl.yaml. SAVE OUTPUT: Commit code to repository in examples/{{example_name}}/ folder" + + - agent: code-curator + tests: code-example/ + requires: code draft + notes: "Test code on all target platforms and versions using *test-code command. Verify code runs correctly on target version {{target_version}}, test edge cases and error conditions, verify dependencies install correctly, check compatibility across platforms. Use code-testing-checklist.md. SAVE OUTPUT: Add test results to examples/{{example_name}}/test-results.md" + + - agent: code-curator + validates: code-example/ + requires: tested code + notes: "Verify code quality and best practices using *verify-quality command. Check code follows language style guide, variable names are descriptive, functions are appropriately sized, code is DRY (no duplication), complexity is reasonable. Use code-quality-checklist.md. SAVE OUTPUT: Add quality report to examples/{{example_name}}/quality-report.md" + + - agent: code-curator + secures: code-example/ + requires: quality-verified code + notes: "Perform security review using *security-check command. Check no hardcoded secrets or credentials, input validation is present, no SQL injection vulnerabilities, dependencies have no known CVEs, secure coding practices followed. Use security-best-practices-checklist.md. SAVE OUTPUT: Add security report to examples/{{example_name}}/security-report.md" + + - agent: code-curator + documents: code-example/ + requires: secure code + notes: "Add comprehensive documentation and comments using *document-example command. Include purpose and what the example demonstrates, prerequisites and dependencies, step-by-step explanation of key code sections, expected output or behavior, common issues and troubleshooting. SAVE OUTPUT: Create README.md in examples/{{example_name}}/ with full documentation and set example status to 'Ready for Publication'" + + flow_diagram: | + ```mermaid + graph TD + A[Start: Example Purpose] --> B[code-curator: Write Code] + B --> C[code-curator: Test on Target Platforms] + C --> D{Tests Pass?} + D -->|Failures| E[Fix Issues] + E --> C + D -->|All Pass| F[code-curator: Quality Check] + F --> G{Meets Standards?} + G -->|Issues| H[Refactor Code] + H --> F + G -->|Pass| I[code-curator: Security Review] + I --> J{Security Issues?} + J -->|Found| K[Fix Security Issues] + K --> I + J -->|Clean| L[code-curator: Add Documentation] + L --> M[Example Complete] + M --> N[Ready for Publication] + + C -.-> C1[Optional: Cross-platform Testing] + F -.-> F1[Optional: Performance Profiling] + I -.-> I1[Optional: Dependency Audit] + + style N fill:#90EE90 + style B fill:#FFE4B5 + style C fill:#FFE4B5 + style F fill:#ADD8E6 + style I fill:#F08080 + style L fill:#F0E68C + ``` + + decision_guidance: + when_to_use: + - Creating code examples for technical books or tutorials + - Developing sample applications for documentation + - Building demo code for training materials + - Need production-quality, tested code examples + - Security and quality standards must be met + + when_not_to_use: + - Quick code snippets for blog posts (simplified workflow) + - Internal-only code examples (less rigor needed) + - Pseudocode or conceptual examples (no execution) + + quality_gates: + code_written: + - Code demonstrates intended concept clearly + - Follows language conventions and idioms + - Includes proper error handling + - Inline comments explain complex logic + - No obvious bugs or issues + + testing_complete: + - Runs correctly on target version + - Edge cases tested + - Error conditions handled + - Dependencies install cleanly + - Cross-platform compatibility verified (if applicable) + - Checklist: code-testing-checklist.md + + quality_verified: + - Follows language style guide + - Variable and function names are descriptive + - Functions are appropriately sized + - No code duplication (DRY) + - Complexity is reasonable for learning example + - Checklist: code-quality-checklist.md + + security_passed: + - No hardcoded secrets or credentials + - Input validation present where needed + - No injection vulnerabilities + - Dependencies have no known CVEs + - Secure coding practices followed + - Checklist: security-best-practices-checklist.md + + documentation_complete: + - Purpose clearly stated + - Prerequisites listed + - Key code sections explained + - Expected output described + - Troubleshooting guidance included + + handoff_prompts: + start_to_write: "Creating code example for {{example_purpose}} targeting version {{target_version}}. Writing clean, idiomatic code." + write_to_test: "Code draft complete at examples/{{example_name}}/. Running tests on target platforms and versions." + test_to_quality: "All tests passing. Performing code quality review against best practices and style guidelines." + quality_to_security: "Code quality verified. Running security review to check for vulnerabilities and secure coding practices." + security_to_document: "Security review passed. Adding comprehensive documentation and usage instructions." + document_to_complete: "Documentation complete. Example ready for inclusion in technical content at examples/{{example_name}}/." + + time_estimates: + write_code: "1-4 hours (depending on complexity)" + test_code: "1-2 hours" + verify_quality: "30 minutes - 1 hour" + security_check: "30 minutes - 1 hour" + document_example: "1-2 hours" + total_time: "4-10 hours per code example" + + best_practices: + - Write code as if teaching a junior developer + - Test on exact version readers will use + - Prefer clarity over cleverness in example code + - Show best practices, not shortcuts + - Include error handling even in simple examples + - Comment the "why" not just the "what" + - Test installation from scratch (fresh environment) + - Document common pitfalls proactively + - Keep examples focused (one concept per example) + - Make examples copy-paste ready but encourage understanding diff --git a/expansion-packs/bmad-technical-writing/workflows/technical-review-workflow.yaml b/expansion-packs/bmad-technical-writing/workflows/technical-review-workflow.yaml new file mode 100644 index 00000000..32beb419 --- /dev/null +++ b/expansion-packs/bmad-technical-writing/workflows/technical-review-workflow.yaml @@ -0,0 +1,176 @@ +workflow: + id: technical-review-workflow + name: Chapter Technical Review + description: Comprehensive expert technical review workflow for chapter content. Guides technical reviewers and code curators through accuracy verification, code review, best practices validation, and report compilation. Ensures technical correctness, code quality, and adherence to industry best practices before editorial polish. + type: technical-review + project_types: + - technical-book + - tutorial-series + - training-materials + - technical-documentation + sequence: + - agent: technical-reviewer + reviews: chapter-draft.md + requires: chapter_draft + notes: "Verify technical accuracy of all content using *verify-accuracy command. Check technical concepts are explained correctly, terminology is used accurately, no outdated or deprecated information, facts and claims are verifiable, technical depth is appropriate for audience. Use technical-accuracy-checklist.md. SAVE OUTPUT: Create accuracy notes at reviews/{{chapter_number}}/accuracy-notes.md with findings categorized by severity (Critical/Major/Minor)" + + - agent: code-curator + reviews: chapter-draft.md + requires: chapter_draft + notes: "Review all code examples in chapter using *review-code command. Check code runs correctly as shown, follows language best practices, error handling is appropriate, code is well-commented and explained, examples are production-quality. Use code-quality-checklist.md. Test each code example. SAVE OUTPUT: Create code review notes at reviews/{{chapter_number}}/code-notes.md with findings and test results" + + - agent: technical-reviewer + validates: chapter-draft.md + requires: chapter_draft + notes: "Validate best practices and security using *validate-practices command. Check security best practices followed in examples, no security vulnerabilities demonstrated, performance considerations addressed where relevant, deprecated APIs not used without warnings, industry standards and conventions followed. Use security-best-practices-checklist.md and performance-considerations-checklist.md. SAVE OUTPUT: Create practices notes at reviews/{{chapter_number}}/practices-notes.md" + + - agent: technical-reviewer + compiles: technical-review-report.md + requires: + - accuracy notes + - code notes + - practices notes + notes: "Compile comprehensive review report using *compile-report command. Summarize all findings by severity, provide actionable recommendations for each issue, identify patterns or recurring problems, assess overall technical quality, recommend revision priority. Use templates/technical-review-report-tmpl.yaml. SAVE OUTPUT: Create final report at reviews/{{chapter_number}}/technical-review-report.md with complete findings and recommendations" + + flow_diagram: | + ```mermaid + graph TD + A[Start: Chapter Draft] --> B[technical-reviewer: Accuracy Check] + A --> C[code-curator: Code Review] + A --> D[technical-reviewer: Best Practices Check] + + B --> E[Accuracy Notes] + C --> F[Code Notes] + D --> G[Practices Notes] + + E --> H[technical-reviewer: Compile Report] + F --> H + G --> H + + H --> I{Critical Issues?} + I -->|Yes| J[Recommend Major Revision] + I -->|No| K{Major Issues?} + K -->|Yes| L[Recommend Revision] + K -->|No| M{Minor Issues Only?} + M -->|Yes| N[Recommend Light Revision] + M -->|None| O[Approve for Editorial] + + J --> P[Technical Review Complete] + L --> P + N --> P + O --> P + + B -.-> B1[Optional: Fact Checking] + C -.-> C1[Optional: Performance Testing] + D -.-> D1[Optional: Security Audit] + + style P fill:#90EE90 + style B fill:#FFE4B5 + style C fill:#FFE4B5 + style D fill:#FFE4B5 + style H fill:#ADD8E6 + style J fill:#F08080 + style L fill:#FFD700 + style N fill:#98FB98 + style O fill:#90EE90 + ``` + + decision_guidance: + when_to_use: + - Chapter draft complete and ready for expert review + - Need comprehensive technical validation + - Code examples need expert verification + - Before editorial polish (technical review first) + - Quality standards require expert review + + when_not_to_use: + - Chapter still in early draft (premature for review) + - Only editorial review needed (use editor workflow) + - Self-review by original author (biased review) + + quality_gates: + accuracy_check_complete: + - All technical concepts verified + - Terminology usage validated + - No deprecated information found + - Facts and claims checked + - Appropriate depth confirmed + - Checklist: technical-accuracy-checklist.md + + code_review_complete: + - All code examples tested + - Code quality assessed + - Best practices verified + - Error handling reviewed + - Comments and explanations checked + - Checklist: code-quality-checklist.md + + practices_check_complete: + - Security practices validated + - No vulnerabilities found + - Performance considerations reviewed + - No deprecated APIs without warnings + - Industry standards followed + - Checklists: security-best-practices-checklist.md, performance-considerations-checklist.md + + report_compiled: + - All findings categorized by severity + - Actionable recommendations provided + - Patterns identified + - Overall quality assessed + - Revision priority recommended + + severity_definitions: + critical: + description: "Technical errors that would mislead readers or cause significant problems" + examples: + - Incorrect technical explanations + - Code that doesn't work as shown + - Security vulnerabilities in examples + - Dangerous or harmful practices demonstrated + action: "Must fix before publication" + + major: + description: "Significant issues affecting quality or reader experience" + examples: + - Suboptimal code practices + - Missing error handling + - Outdated but functional approaches + - Incomplete explanations of complex concepts + action: "Should fix before editorial review" + + minor: + description: "Small improvements that would enhance quality" + examples: + - Variable naming improvements + - Additional comments helpful + - Alternative approaches worth mentioning + - Minor optimizations + action: "Consider addressing if time permits" + + handoff_prompts: + start_to_accuracy: "Beginning technical review of chapter {{chapter_number}} draft. Starting with technical accuracy verification of all concepts and claims." + start_to_code: "Reviewing all code examples in chapter {{chapter_number}}. Will test each example and verify quality standards." + start_to_practices: "Validating best practices and security in chapter {{chapter_number}}. Checking for vulnerabilities and industry standards compliance." + all_to_compile: "Individual reviews complete. Compiling comprehensive technical review report with {{critical_count}} critical, {{major_count}} major, and {{minor_count}} minor findings." + compile_to_author: "Technical review complete for chapter {{chapter_number}}. Report available at reviews/{{chapter_number}}/technical-review-report.md. Recommendation: {{revision_priority}}." + + time_estimates: + accuracy_check: "2-3 hours (15-30 page chapter)" + code_review: "2-4 hours (depending on code complexity)" + best_practices_check: "1-2 hours" + compile_report: "1-2 hours" + total_time: "6-11 hours per chapter" + + best_practices: + - Review with beginner's mindset (assume no prior knowledge beyond prerequisites) + - Test ALL code exactly as shown in chapter + - Focus on what reader will experience + - Categorize findings by severity objectively + - Provide specific, actionable recommendations + - Note both problems AND strengths + - Consider target audience when assessing depth + - Flag security issues immediately (critical) + - Verify version compatibility explicitly + - Be thorough but constructive in feedback + - Remember: goal is reader success, not perfectionism