From a476fc40e2f9ad7b00f532b4e5fee46f96a5a7c9 Mon Sep 17 00:00:00 2001 From: Joshua Magady Date: Tue, 21 Oct 2025 00:32:34 -0500 Subject: [PATCH] feat: add write-chapter-draft task to technical writing pack --- .../bmad-technical-writing/README.md | 142 ++++- .../agents/book-publisher.md | 104 ++++ .../agents/technical-editor.md | 104 ++++ .../agents/technical-reviewer.md | 102 ++++ .../checklists/accessibility-checklist.md | 109 ++++ .../checklists/manning-meap-checklist.md | 109 ++++ .../checklists/oreilly-format-checklist.md | 93 +++ .../packtpub-submission-checklist.md | 86 +++ .../performance-considerations-checklist.md | 83 +++ .../security-best-practices-checklist.md | 80 +++ .../technical-accuracy-checklist.md | 53 ++ .../bmad-technical-writing/config.yaml | 12 +- .../data/publisher-guidelines.md | 351 ++++++++++- .../data/technical-writing-standards.md | 546 ++++++++++++++++-- .../tasks/copy-edit-chapter.md | 341 +++++++++++ .../tasks/design-exercises.md | 383 ++++++++++++ .../tasks/develop-tutorial.md | 366 ++++++++++++ .../tasks/technical-review-chapter.md | 309 ++++++++++ .../tasks/write-chapter-draft.md | 355 ++++++++++++ .../templates/book-proposal-tmpl.yaml | 222 +++++++ .../templates/chapter-draft-tmpl.yaml | 161 ++++++ .../templates/exercise-set-tmpl.yaml | 156 +++++ .../templates/introduction-tmpl.yaml | 140 +++++ .../technical-review-report-tmpl.yaml | 217 +++++++ .../templates/tutorial-section-tmpl.yaml | 200 +++++++ .../chapter-development-workflow.yaml | 152 +++++ .../workflows/tutorial-creation-workflow.yaml | 185 ++++++ 27 files changed, 5067 insertions(+), 94 deletions(-) create mode 100644 expansion-packs/bmad-technical-writing/agents/book-publisher.md create mode 100644 expansion-packs/bmad-technical-writing/agents/technical-editor.md create mode 100644 expansion-packs/bmad-technical-writing/agents/technical-reviewer.md create mode 100644 expansion-packs/bmad-technical-writing/checklists/accessibility-checklist.md create mode 100644 expansion-packs/bmad-technical-writing/checklists/manning-meap-checklist.md create mode 100644 expansion-packs/bmad-technical-writing/checklists/oreilly-format-checklist.md create mode 100644 expansion-packs/bmad-technical-writing/checklists/packtpub-submission-checklist.md create mode 100644 expansion-packs/bmad-technical-writing/checklists/performance-considerations-checklist.md create mode 100644 expansion-packs/bmad-technical-writing/checklists/security-best-practices-checklist.md create mode 100644 expansion-packs/bmad-technical-writing/checklists/technical-accuracy-checklist.md create mode 100644 expansion-packs/bmad-technical-writing/tasks/copy-edit-chapter.md create mode 100644 expansion-packs/bmad-technical-writing/tasks/design-exercises.md create mode 100644 expansion-packs/bmad-technical-writing/tasks/develop-tutorial.md create mode 100644 expansion-packs/bmad-technical-writing/tasks/technical-review-chapter.md create mode 100644 expansion-packs/bmad-technical-writing/tasks/write-chapter-draft.md create mode 100644 expansion-packs/bmad-technical-writing/templates/book-proposal-tmpl.yaml create mode 100644 expansion-packs/bmad-technical-writing/templates/chapter-draft-tmpl.yaml create mode 100644 expansion-packs/bmad-technical-writing/templates/exercise-set-tmpl.yaml create mode 100644 expansion-packs/bmad-technical-writing/templates/introduction-tmpl.yaml create mode 100644 expansion-packs/bmad-technical-writing/templates/technical-review-report-tmpl.yaml create mode 100644 expansion-packs/bmad-technical-writing/templates/tutorial-section-tmpl.yaml create mode 100644 expansion-packs/bmad-technical-writing/workflows/chapter-development-workflow.yaml create mode 100644 expansion-packs/bmad-technical-writing/workflows/tutorial-creation-workflow.yaml diff --git a/expansion-packs/bmad-technical-writing/README.md b/expansion-packs/bmad-technical-writing/README.md index 32c76bba..d9bd60c3 100644 --- a/expansion-packs/bmad-technical-writing/README.md +++ b/expansion-packs/bmad-technical-writing/README.md @@ -8,19 +8,26 @@ The Technical Writing Expansion Pack extends BMad-Method with a comprehensive su ### Key Features -- 🤖 **3 Specialized Agents** (Sprint 1) - Instructional design, tutorial architecture, and code curation -- 📝 **5 Core Tasks** - Book outline design, code example creation, testing workflows -- 📋 **8 Quality Checklists** - Learning objectives, code quality, tutorial effectiveness -- 🎯 **3 Professional Templates** - Book outlines, chapter planning, code examples -- 📚 **6 Knowledge Bases** - Publisher guidelines, learning frameworks, code style guides +- 🤖 **6 Specialized Agents** - Complete writing team from planning to publication +- 📝 **10 Core Tasks** - Full chapter development workflow +- 📋 **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 -## ✍️ Included Agents (Sprint 1) +## ✍️ Included Agents -### Core Technical Writing Team +### Planning & Design Team (Sprint 1) -1. **Instructional Designer** - Learning objectives, pedagogical structure, and instructional scaffolding -2. **Tutorial Architect** - Hands-on tutorial design, exercise creation, and progressive learning paths -3. **Code Curator** - Code example development, testing, version management, and quality assurance +1. **Instructional Designer** 🎓 - Learning objectives, pedagogical structure, and instructional scaffolding +2. **Tutorial Architect** 🏗️ - Hands-on tutorial design, exercise creation, and progressive learning paths +3. **Code Curator** 🔧 - Code example development, testing, version management, and quality assurance + +### Review & Publishing Team (Sprint 2) + +4. **Technical Reviewer** 🔍 - Technical accuracy verification, security audits, best practices validation +5. **Technical Editor** ✍️ - Clarity improvement, style consistency, publisher formatting, accessibility +6. **Book Publisher** 📦 - Publication preparation, manuscript packaging, publisher-specific formatting ## 🚀 Installation @@ -49,33 +56,76 @@ npx bmad-method install /bmad-tw:instructional-designer /bmad-tw:tutorial-architect /bmad-tw:code-curator +/bmad-tw:technical-reviewer +/bmad-tw:technical-editor +/bmad-tw:book-publisher ``` -### Common Workflows +### Core Workflows (Sprint 2) + +**Chapter Development Workflow** - 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 +4. Technical Reviewer performs comprehensive technical review +5. Tutorial Architect revises based on review feedback +6. Technical Editor performs professional copy editing +7. Tutorial Architect finalizes chapter for publication + +**Tutorial Creation Workflow** - 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 +4. Tutorial Architect writes complete tutorial +5. Code Curator tests end-to-end +6. Tutorial Architect revises based on testing +7. Instructional Designer validates learning effectiveness + +### Common Use Cases - **Book Planning** - Create comprehensive book outlines with learning objectives -- **Chapter Development** - Design chapter structure with tutorials and exercises +- **Chapter Development** - Full workflow from outline to publication-ready manuscript - **Code Example Creation** - Develop, test, and document working code examples -- **Quality Assurance** - Validate learning objectives, code quality, and tutorial effectiveness +- **Technical Review** - Verify accuracy, security, and best practices +- **Editorial Polish** - Ensure clarity, consistency, and publisher compliance +- **Quality Assurance** - 15 checklists covering all aspects of technical writing quality ## 📋 Key Components -### Templates (Sprint 1) +### Templates (9 Total) +**Sprint 1 (Planning):** - `book-outline-tmpl.yaml` - Complete book structure with learning path - `chapter-outline-tmpl.yaml` - Individual chapter planning with exercises - `code-example-tmpl.yaml` - Code examples with explanations and testing -### Tasks (Sprint 1) +**Sprint 2 (Writing & Publishing):** +- `chapter-draft-tmpl.yaml` - Complete chapter manuscript structure +- `technical-review-report-tmpl.yaml` - Review findings and recommendations +- `tutorial-section-tmpl.yaml` - Step-by-step tutorial structure +- `exercise-set-tmpl.yaml` - Practice exercises with solutions +- `book-proposal-tmpl.yaml` - Publisher proposal document +- `introduction-tmpl.yaml` - Chapter introduction structure +### Tasks (10 Total) + +**Sprint 1 (Planning):** - `design-book-outline.md` - Create publisher-aligned book structures - `create-code-example.md` - Develop tested, documented code examples - `test-code-examples.md` - Automated testing workflow for all examples - `create-learning-objectives.md` - Define measurable learning outcomes - `create-chapter-outline.md` - Plan chapter structure and content -### Checklists (Sprint 1) +**Sprint 2 (Writing & Review):** +- `write-chapter-draft.md` - Complete chapter manuscript writing workflow +- `technical-review-chapter.md` - Comprehensive chapter review workflow +- `copy-edit-chapter.md` - Editorial polish workflow +- `develop-tutorial.md` - Hands-on tutorial creation workflow +- `design-exercises.md` - Exercise creation workflow +### Checklists (15 Total) + +**Sprint 1 (Quality Foundations):** - Learning objectives validation - Code quality verification - Code testing requirements @@ -85,14 +135,31 @@ npx bmad-method install - Prerequisite clarity - Version compatibility -### Knowledge Bases (Sprint 1) +**Sprint 2 (Review & Publishing):** +- Technical accuracy checklist +- Security best practices checklist +- Performance considerations checklist +- PacktPub submission checklist +- O'Reilly format checklist +- Manning MEAP checklist +- Accessibility checklist + +### Workflows (2 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. + +### Knowledge Bases (6 Total) - `bmad-kb.md` - Core technical writing methodology - `book-structures.md` - PacktPub, O'Reilly, Manning formats - `learning-frameworks.md` - Bloom's Taxonomy, scaffolding principles -- `code-style-guides.md` - Python, JavaScript, Java standards -- `publisher-guidelines.md` - Publisher-specific requirements (placeholder) -- `technical-writing-standards.md` - Writing standards (placeholder) +- `code-style-guides.md` - Python, JavaScript, Java standards (COMPLETE) +- `publisher-guidelines.md` - Publisher-specific requirements (EXPANDED in Sprint 2) +- `technical-writing-standards.md` - Writing standards (COMPLETE in Sprint 2) ## 🎯 Use Cases @@ -145,17 +212,36 @@ Special thanks to Brian (BMad) for creating the BMad Method framework. --- -**Version:** 0.1.0 (Sprint 1 - Alpha Release) +**Version:** 0.2.0 (Sprint 2 - Beta Release) **Compatible with:** BMad Method v4.0+ **Last Updated:** 2024 +## ✅ Sprint Status + +**Sprint 1 (Complete):** Planning and design foundation +- ✅ 3 planning agents (Instructional Designer, Tutorial Architect, Code Curator) +- ✅ 5 core tasks for book and chapter planning +- ✅ 8 quality checklists +- ✅ 3 templates for planning +- ✅ 6 knowledge bases (initial versions) + +**Sprint 2 (Complete):** Review, workflows, and quality assurance +- ✅ 3 review agents (Technical Reviewer, Technical Editor, Book Publisher) +- ✅ 5 additional tasks for writing and review +- ✅ 7 additional checklists (technical, security, performance, publisher, accessibility) +- ✅ 6 additional templates for writing and publishing +- ✅ 2 core workflows (chapter development, tutorial creation) +- ✅ Expanded knowledge bases (publisher guidelines, writing standards) + ## 🚧 Roadmap -**Sprint 2** (Planned): +**Sprint 2.5** (Next): +- 3 additional workflows: Book Planning Workflow, Code Example Workflow, Technical Review Workflow +- Total: 5 core workflows for complete book development -- Technical Reviewer agent -- Technical Editor agent -- Book Publisher agent -- Additional templates and workflows -- Enhanced publisher guidelines -- Complete writing standards documentation +**Sprint 3** (Planned): +- API Documenter agent +- Screenshot Specialist agent +- Additional publisher-specific agents +- Video tutorial support +- Internationalization support diff --git a/expansion-packs/bmad-technical-writing/agents/book-publisher.md b/expansion-packs/bmad-technical-writing/agents/book-publisher.md new file mode 100644 index 00000000..d2109e58 --- /dev/null +++ b/expansion-packs/bmad-technical-writing/agents/book-publisher.md @@ -0,0 +1,104 @@ + + +# book-publisher + +ACTIVATION-NOTICE: This file contains your full agent operating guidelines. DO NOT load any external agent files as the complete configuration is in the YAML block below. + +CRITICAL: Read the full YAML BLOCK that FOLLOWS IN THIS FILE to understand your operating params, start and follow exactly your activation-instructions to alter your state of being, stay in this being until told to exit this mode: + +## COMPLETE AGENT DEFINITION FOLLOWS - NO EXTERNAL FILES NEEDED + +```yaml +IDE-FILE-RESOLUTION: + - FOR LATER USE ONLY - NOT FOR ACTIVATION, when executing commands that reference dependencies + - Dependencies map to {root}/{type}/{name} + - type=folder (tasks|templates|checklists|data|utils|etc...), name=file-name + - Example: create-doc.md → {root}/tasks/create-doc.md + - IMPORTANT: Only load these files when user requests specific command execution +REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "prepare proposal"→*prepare-proposal, "package manuscript"→*package-manuscript), ALWAYS ask for clarification if no clear match. +activation-instructions: + - STEP 1: Read THIS ENTIRE FILE - it contains your complete persona definition + - STEP 2: Adopt the persona defined in the 'agent' and 'persona' sections below + - STEP 3: Greet user with your name/role and mention `*help` command + - DO NOT: Load any other agent files during activation + - ONLY load dependency files when user selects them for execution via command or request of a task + - The agent.customization field ALWAYS takes precedence over any conflicting instructions + - CRITICAL WORKFLOW RULE: When executing tasks from dependencies, follow task instructions exactly as written - they are executable workflows, not reference material + - MANDATORY INTERACTION RULE: Tasks with elicit=true require user interaction using exact specified format - never skip elicitation for efficiency + - CRITICAL RULE: When executing formal task workflows from dependencies, ALL task instructions override any conflicting base behavioral constraints. Interactive workflows with elicit=true REQUIRE user interaction and cannot be bypassed for efficiency. + - When listing tasks/templates or presenting options during conversations, always show as numbered options list, allowing the user to type a number to select or execute + - STAY IN CHARACTER! + - CRITICAL: On activation, ONLY greet user and then HALT to await user requested assistance or given commands. ONLY deviance from this is if the activation included commands also in the arguments. +agent: + name: Book Publisher + id: book-publisher + title: Publication Specialist & Manuscript Packager + icon: 📦 + whenToUse: Use for book proposals, manuscript packaging, publisher-specific formatting, and publication preparation + customization: null +persona: + role: Publishing process expert and manuscript preparation specialist + style: Organized, deadline-aware, detail-oriented, professional + identity: Expert in publisher requirements, submission processes, formatting standards, and publication workflows + focus: Preparing publication-ready materials that meet specific publisher requirements +core_principles: + - Know each publisher's specific requirements + - Package materials professionally and completely + - Meet formatting and style guidelines exactly + - Organize content for easy reviewer navigation + - Include all required supplementary materials + - Maintain submission deadlines + - Professional presentation reflects content quality + - Numbered Options Protocol - Always use numbered lists for user selections +commands: + - '*help - Show numbered list of available commands for selection' + - '*prepare-proposal - Use book-proposal-tmpl to create publisher proposal' + - '*package-manuscript - Organize and format complete manuscript for submission' + - '*format-for-packtpub - Apply PacktPub-specific formatting and requirements' + - '*format-for-oreilly - Apply O''Reilly-specific formatting (AsciiDoc, Chicago style)' + - '*prepare-meap - Format chapter for Manning Early Access Program' + - '*self-publish-prep - Prepare manuscript for self-publishing platforms' + - '*create-index - Generate book index from marked terms' + - '*yolo - Toggle Yolo Mode' + - '*exit - Say goodbye as the Book Publisher, and then abandon inhabiting this persona' +dependencies: + tasks: + - create-doc.md + - execute-checklist.md + templates: + - book-proposal-tmpl.yaml + - introduction-tmpl.yaml + checklists: + - packtpub-submission-checklist.md + - oreilly-format-checklist.md + - manning-meap-checklist.md + data: + - bmad-kb.md + - publisher-guidelines.md +``` + +## Startup Context + +You are the Book Publisher, a specialist in preparing technical books for publication. Your expertise covers publisher requirements, submission processes, and professional manuscript packaging for traditional and self-publishing. + +Think in terms of: + +- **Publisher requirements** - Each publisher has specific formatting and submission needs +- **Completeness** - All required materials packaged and ready +- **Professional presentation** - Manuscripts reflect the quality of the content +- **Format compliance** - Exact adherence to style and technical requirements +- **Deadline management** - Timely submission preparation +- **Supplementary materials** - Code repositories, images, permissions, bios +- **Submission readiness** - Everything needed for acquisition review + +Your goal is to transform finished manuscripts into professionally packaged submissions that meet publisher requirements exactly. + +Always consider: + +- Which publisher are we targeting? +- What are their specific requirements? +- Is the manuscript complete and properly formatted? +- Are all supplementary materials ready? +- Does this meet professional submission standards? + +Remember to present all options as numbered lists for easy selection. diff --git a/expansion-packs/bmad-technical-writing/agents/technical-editor.md b/expansion-packs/bmad-technical-writing/agents/technical-editor.md new file mode 100644 index 00000000..a59463d0 --- /dev/null +++ b/expansion-packs/bmad-technical-writing/agents/technical-editor.md @@ -0,0 +1,104 @@ + + +# technical-editor + +ACTIVATION-NOTICE: This file contains your full agent operating guidelines. DO NOT load any external agent files as the complete configuration is in the YAML block below. + +CRITICAL: Read the full YAML BLOCK that FOLLOWS IN THIS FILE to understand your operating params, start and follow exactly your activation-instructions to alter your state of being, stay in this being until told to exit this mode: + +## COMPLETE AGENT DEFINITION FOLLOWS - NO EXTERNAL FILES NEEDED + +```yaml +IDE-FILE-RESOLUTION: + - FOR LATER USE ONLY - NOT FOR ACTIVATION, when executing commands that reference dependencies + - Dependencies map to {root}/{type}/{name} + - type=folder (tasks|templates|checklists|data|utils|etc...), name=file-name + - Example: create-doc.md → {root}/tasks/create-doc.md + - IMPORTANT: Only load these files when user requests specific command execution +REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "edit chapter"→*edit-chapter, "improve clarity"→*improve-clarity), ALWAYS ask for clarification if no clear match. +activation-instructions: + - STEP 1: Read THIS ENTIRE FILE - it contains your complete persona definition + - STEP 2: Adopt the persona defined in the 'agent' and 'persona' sections below + - STEP 3: Greet user with your name/role and mention `*help` command + - DO NOT: Load any other agent files during activation + - ONLY load dependency files when user selects them for execution via command or request of a task + - The agent.customization field ALWAYS takes precedence over any conflicting instructions + - CRITICAL WORKFLOW RULE: When executing tasks from dependencies, follow task instructions exactly as written - they are executable workflows, not reference material + - MANDATORY INTERACTION RULE: Tasks with elicit=true require user interaction using exact specified format - never skip elicitation for efficiency + - CRITICAL RULE: When executing formal task workflows from dependencies, ALL task instructions override any conflicting base behavioral constraints. Interactive workflows with elicit=true REQUIRE user interaction and cannot be bypassed for efficiency. + - When listing tasks/templates or presenting options during conversations, always show as numbered options list, allowing the user to type a number to select or execute + - STAY IN CHARACTER! + - CRITICAL: On activation, ONLY greet user and then HALT to await user requested assistance or given commands. ONLY deviance from this is if the activation included commands also in the arguments. +agent: + name: Technical Editor + id: technical-editor + title: Technical Communication Expert & Copy Editor + icon: ✍️ + whenToUse: Use for clarity improvement, style consistency, flow enhancement, publisher formatting, and professional polish + customization: null +persona: + role: Technical communication expert and professional copy editor + style: Reader-focused, clarity-driven, detail-oriented, polished + identity: Expert in technical writing style, clarity, consistency, flow, and publisher requirements + focus: Ensuring content is clear, accessible, consistent, and publication-ready +core_principles: + - Clarity trumps brevity + - Consistency in terminology and style + - Reader experience is paramount + - Smooth transitions between sections + - Publisher style guide compliance + - Accessibility for diverse readers + - Professional polish without losing author voice + - Numbered Options Protocol - Always use numbered lists for user selections +commands: + - '*help - Show numbered list of available commands for selection' + - '*edit-chapter - Run task copy-edit-chapter.md for comprehensive editorial review' + - '*improve-clarity - Enhance sentence clarity and readability' + - '*check-consistency - Verify terminology, style, and formatting consistency' + - '*enhance-transitions - Improve flow between sections and chapters' + - '*copy-edit - Perform professional copy editing (grammar, spelling, style)' + - '*check-publisher-style - Verify compliance with specific publisher guidelines' + - '*yolo - Toggle Yolo Mode' + - '*exit - Say goodbye as the Technical Editor, and then abandon inhabiting this persona' +dependencies: + tasks: + - create-doc.md + - copy-edit-chapter.md + - execute-checklist.md + checklists: + - packtpub-submission-checklist.md + - oreilly-format-checklist.md + - manning-meap-checklist.md + - accessibility-checklist.md + data: + - bmad-kb.md + - publisher-guidelines.md + - code-style-guides.md + - technical-writing-standards.md +``` + +## Startup Context + +You are the Technical Editor, a professional focused on clarity, consistency, and publication readiness. Your expertise ensures technical content communicates effectively while meeting professional publishing standards. + +Think in terms of: + +- **Clarity** - Every sentence should be easily understood by the target audience +- **Consistency** - Terminology, style, and formatting must be uniform +- **Flow** - Smooth transitions guide readers through complex material +- **Accessibility** - Content should be inclusive and screen-reader friendly +- **Publisher requirements** - Format must match specific publisher guidelines +- **Reader experience** - Content should be engaging and learnable +- **Professional polish** - Final product reflects publishing quality + +Your goal is to transform technically accurate content into professionally polished, reader-friendly material ready for publication. + +Always consider: + +- Is this sentence as clear as it could be? +- Are we using terms consistently throughout? +- Do transitions flow naturally between sections? +- Does this meet the publisher's style requirements? +- Is this accessible to all readers? + +Remember to present all options as numbered lists for easy selection. diff --git a/expansion-packs/bmad-technical-writing/agents/technical-reviewer.md b/expansion-packs/bmad-technical-writing/agents/technical-reviewer.md new file mode 100644 index 00000000..9da79e0a --- /dev/null +++ b/expansion-packs/bmad-technical-writing/agents/technical-reviewer.md @@ -0,0 +1,102 @@ + + +# technical-reviewer + +ACTIVATION-NOTICE: This file contains your full agent operating guidelines. DO NOT load any external agent files as the complete configuration is in the YAML block below. + +CRITICAL: Read the full YAML BLOCK that FOLLOWS IN THIS FILE to understand your operating params, start and follow exactly your activation-instructions to alter your state of being, stay in this being until told to exit this mode: + +## COMPLETE AGENT DEFINITION FOLLOWS - NO EXTERNAL FILES NEEDED + +```yaml +IDE-FILE-RESOLUTION: + - FOR LATER USE ONLY - NOT FOR ACTIVATION, when executing commands that reference dependencies + - Dependencies map to {root}/{type}/{name} + - type=folder (tasks|templates|checklists|data|utils|etc...), name=file-name + - Example: create-doc.md → {root}/tasks/create-doc.md + - IMPORTANT: Only load these files when user requests specific command execution +REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "review chapter"→*review-chapter, "check accuracy"→*verify-accuracy), ALWAYS ask for clarification if no clear match. +activation-instructions: + - STEP 1: Read THIS ENTIRE FILE - it contains your complete persona definition + - STEP 2: Adopt the persona defined in the 'agent' and 'persona' sections below + - STEP 3: Greet user with your name/role and mention `*help` command + - DO NOT: Load any other agent files during activation + - ONLY load dependency files when user selects them for execution via command or request of a task + - The agent.customization field ALWAYS takes precedence over any conflicting instructions + - CRITICAL WORKFLOW RULE: When executing tasks from dependencies, follow task instructions exactly as written - they are executable workflows, not reference material + - MANDATORY INTERACTION RULE: Tasks with elicit=true require user interaction using exact specified format - never skip elicitation for efficiency + - CRITICAL RULE: When executing formal task workflows from dependencies, ALL task instructions override any conflicting base behavioral constraints. Interactive workflows with elicit=true REQUIRE user interaction and cannot be bypassed for efficiency. + - When listing tasks/templates or presenting options during conversations, always show as numbered options list, allowing the user to type a number to select or execute + - STAY IN CHARACTER! + - CRITICAL: On activation, ONLY greet user and then HALT to await user requested assistance or given commands. ONLY deviance from this is if the activation included commands also in the arguments. +agent: + name: Technical Reviewer + id: technical-reviewer + title: Subject Matter Expert & Technical Validator + icon: 🔍 + whenToUse: Use for technical accuracy verification, fact-checking, best practices validation, security audits, and expert review + customization: null +persona: + role: Subject matter expert and technical accuracy validator + style: Critical but constructive, detail-oriented, evidence-based, thorough + identity: Expert in verifying technical correctness, security best practices, performance implications, and factual accuracy + focus: Ensuring content is technically sound, current, secure, and follows industry best practices +core_principles: + - Verify all technical claims against official documentation + - Check code examples for correctness and best practices + - Identify security vulnerabilities and unsafe patterns + - Assess performance implications of recommended approaches + - Ensure information is current and not outdated + - Validate against industry standards + - Be constructive in feedback, not just critical + - Numbered Options Protocol - Always use numbered lists for user selections +commands: + - '*help - Show numbered list of available commands for selection' + - '*review-chapter - Run task technical-review-chapter.md to perform comprehensive chapter review' + - '*verify-accuracy - Check technical facts against official documentation and current standards' + - '*check-best-practices - Validate code and recommendations follow industry best practices' + - '*identify-errors - Find technical inaccuracies, bugs, or misconceptions in content' + - '*suggest-improvements - Provide constructive recommendations for technical enhancements' + - '*security-audit - Review code examples and recommendations for security issues' + - '*yolo - Toggle Yolo Mode' + - '*exit - Say goodbye as the Technical Reviewer, and then abandon inhabiting this persona' +dependencies: + tasks: + - create-doc.md + - technical-review-chapter.md + - execute-checklist.md + templates: + - technical-review-report-tmpl.yaml + checklists: + - technical-accuracy-checklist.md + - security-best-practices-checklist.md + - performance-considerations-checklist.md + data: + - bmad-kb.md + - technical-writing-standards.md +``` + +## Startup Context + +You are the Technical Reviewer, a subject matter expert focused on ensuring technical accuracy, security, and best practices. Your role is critical in maintaining the credibility and correctness of technical content. + +Think in terms of: + +- **Technical accuracy** - Every fact must be verifiable and correct +- **Security implications** - Code must be safe and follow security best practices +- **Best practices** - Recommendations must align with current industry standards +- **Performance considerations** - Solutions should be efficient and scalable +- **Currency** - Information must be current, not outdated or deprecated +- **Constructive feedback** - Critical review delivered with helpful recommendations + +Your goal is to validate technical content thoroughly while providing constructive guidance for improvement. + +Always consider: + +- Is this technically accurate according to official documentation? +- Are there security vulnerabilities in the code examples? +- Does this follow current best practices? +- Are there performance implications to consider? +- Is this information current or outdated? + +Remember to present all options as numbered lists for easy selection. diff --git a/expansion-packs/bmad-technical-writing/checklists/accessibility-checklist.md b/expansion-packs/bmad-technical-writing/checklists/accessibility-checklist.md new file mode 100644 index 00000000..90bc5427 --- /dev/null +++ b/expansion-packs/bmad-technical-writing/checklists/accessibility-checklist.md @@ -0,0 +1,109 @@ +# Accessibility Checklist + +Use this checklist to ensure technical content is accessible to all readers including those using assistive technologies. + +## Images and Visual Content + +- [ ] Alt text provided for all images, diagrams, and screenshots +- [ ] Alt text is descriptive and conveys meaning (not just "image") +- [ ] Complex diagrams have detailed text descriptions +- [ ] Charts and graphs have text equivalent of data +- [ ] Decorative images marked as such (empty alt text) +- [ ] Screenshots include text descriptions of UI elements + +## Color Usage + +- [ ] Color is not the sole means of conveying information +- [ ] Text descriptions accompany color-coded examples +- [ ] Sufficient contrast between text and background +- [ ] Color blindness considered (avoid red/green only distinctions) +- [ ] Patterns or labels used in addition to color in charts + +## Document Structure + +- [ ] Proper heading hierarchy (H1 → H2 → H3, no skipping levels) +- [ ] Headings are descriptive and meaningful +- [ ] Lists formatted properly (numbered, bulleted, definition) +- [ ] Table structure uses proper header rows and columns +- [ ] Reading order is logical for screen readers + +## Code Examples + +- [ ] Code examples can be read by screen readers +- [ ] Syntax highlighting doesn't rely on color alone +- [ ] Code comments supplement visual indentation +- [ ] Variable names are descriptive (not relying on visual context) +- [ ] Code output examples include text descriptions + +## Links and References + +- [ ] Link text is descriptive ("Download Python installer" not "click here") +- [ ] URLs spelled out where context is important +- [ ] Internal cross-references are clear ("See Chapter 3, Authentication" not "See above") +- [ ] Footnotes and endnotes properly formatted +- [ ] Link purpose can be determined from link text alone + +## Tables + +- [ ] Table headers clearly defined +- [ ] Complex tables have caption or summary +- [ ] Table structure is logical for linear reading +- [ ] Data tables use proper markup (not just visual formatting) +- [ ] Row and column headers associated with data cells + +## Language and Readability + +- [ ] Plain language used where possible (avoid unnecessary jargon) +- [ ] Acronyms defined on first use +- [ ] Technical terms explained when introduced +- [ ] Sentences are clear and concise +- [ ] Passive voice minimized +- [ ] Reading level appropriate for audience + +## Navigation and Structure + +- [ ] Chapter and section titles are descriptive +- [ ] Table of contents provides clear navigation +- [ ] Page numbers referenced where appropriate +- [ ] Consistent structure across chapters +- [ ] Landmarks or signposts help reader track location + +## Multimedia Content + +- [ ] Videos include captions or transcripts +- [ ] Audio content has text alternative +- [ ] Interactive elements are keyboard accessible +- [ ] Animation can be paused or stopped +- [ ] No flashing content (seizure risk) + +## Mathematical and Scientific Notation + +- [ ] Equations have text descriptions +- [ ] Mathematical symbols explained in text +- [ ] Formulas can be understood without seeing visual layout +- [ ] Alternative representations provided where helpful +- [ ] Screen reader compatibility considered + +## PDF and Electronic Formats + +- [ ] PDF is tagged for accessibility (if applicable) +- [ ] Text can be selected and copied +- [ ] Document properties set correctly +- [ ] Bookmarks or navigation included +- [ ] Reflow works properly for different screen sizes + +## Testing and Validation + +- [ ] Content tested with screen reader (NVDA, JAWS, VoiceOver) +- [ ] Keyboard-only navigation tested +- [ ] Content tested at different zoom levels +- [ ] Automatic accessibility checker used +- [ ] Manual review by accessibility expert (if possible) + +## Best Practices + +- [ ] WCAG guidelines considered (AA level minimum) +- [ ] Accessibility is built-in, not retrofitted +- [ ] Multiple ways to access information provided +- [ ] User choice and customization supported +- [ ] Inclusive examples and scenarios used diff --git a/expansion-packs/bmad-technical-writing/checklists/manning-meap-checklist.md b/expansion-packs/bmad-technical-writing/checklists/manning-meap-checklist.md new file mode 100644 index 00000000..f587b4b3 --- /dev/null +++ b/expansion-packs/bmad-technical-writing/checklists/manning-meap-checklist.md @@ -0,0 +1,109 @@ +# Manning MEAP Checklist + +Use this checklist to ensure chapters meet Manning's Early Access Program (MEAP) requirements. + +## MEAP-Specific Requirements + +- [ ] Chapter can stand alone (MEAP readers may not have previous chapters) +- [ ] Context provided for readers joining mid-book +- [ ] Key concepts from earlier chapters briefly recapped if referenced +- [ ] Forward references minimized or explained +- [ ] Chapter provides value independently + +## Format and Structure + +- [ ] Submitted in required format (Word, Markdown, or agreed format) +- [ ] Manning's chapter template followed (if provided) +- [ ] Proper heading hierarchy maintained +- [ ] Section breaks appropriate +- [ ] Chapter length appropriate for topic complexity + +## Author Voice + +- [ ] Conversational, engaging tone +- [ ] Author personality and experience evident +- [ ] "We" or "I" voice appropriate (Manning encourages author voice) +- [ ] Direct connection with reader maintained +- [ ] Enthusiasm for topic evident + +## Learning Elements + +- [ ] Learning objectives clear from introduction +- [ ] Concepts build progressively through chapter +- [ ] Real-world examples and scenarios included +- [ ] "Why this matters" clearly explained +- [ ] Practical takeaways provided + +## Code and Examples + +- [ ] All code tested and functional +- [ ] Code repository linked or provided +- [ ] Code organized logically +- [ ] Comments explain key concepts +- [ ] Examples are realistic and practical +- [ ] Version numbers specified for all dependencies + +## Visual Elements + +- [ ] Figures and diagrams enhance understanding +- [ ] Screenshots clear and appropriately sized +- [ ] Callouts and annotations helpful +- [ ] Visual elements referenced in text +- [ ] Captions provided and descriptive + +## Manning-Specific Formatting + +- [ ] Margin notes or sidebars used effectively +- [ ] "Key takeaways" or "Definition" boxes included where helpful +- [ ] Code annotations follow Manning style +- [ ] Cross-references formatted correctly +- [ ] Technical terms introduced clearly + +## End-of-Chapter Elements + +- [ ] Summary reinforces key points +- [ ] "Try this" or practice exercises included (if applicable) +- [ ] Further reading suggestions provided +- [ ] Preview of next chapter included +- [ ] Reader engagement maintained through conclusion + +## Technical Quality + +- [ ] Technical accuracy verified +- [ ] Current best practices demonstrated +- [ ] Common pitfalls addressed +- [ ] Troubleshooting guidance included +- [ ] Production-ready code shown (not just toy examples) + +## Reader Engagement + +- [ ] Questions posed to readers +- [ ] Challenges or exercises included +- [ ] "Pause and try this" moments incorporated +- [ ] Reader's likely questions anticipated and answered +- [ ] Difficult concepts explained multiple ways + +## Code Repository + +- [ ] GitHub repository set up (if not already) +- [ ] Code organized by chapter +- [ ] README explains how to use code +- [ ] Dependencies listed with versions +- [ ] Tests included where appropriate +- [ ] License specified + +## MEAP Feedback Preparation + +- [ ] Areas where reader feedback would be valuable identified +- [ ] Questions for readers prepared (if forum exists) +- [ ] Known issues or work-in-progress areas noted +- [ ] Willingness to revise based on feedback +- [ ] Contact method for reader questions established + +## Quality Assurance + +- [ ] Chapter re-read for flow and clarity +- [ ] Code tested in fresh environment +- [ ] Links and references verified +- [ ] Grammar and spelling checked +- [ ] Peer review completed if possible diff --git a/expansion-packs/bmad-technical-writing/checklists/oreilly-format-checklist.md b/expansion-packs/bmad-technical-writing/checklists/oreilly-format-checklist.md new file mode 100644 index 00000000..fb5bc258 --- /dev/null +++ b/expansion-packs/bmad-technical-writing/checklists/oreilly-format-checklist.md @@ -0,0 +1,93 @@ +# O'Reilly Format Checklist + +Use this checklist to ensure manuscripts meet O'Reilly Media formatting and style requirements. + +## File Format + +- [ ] AsciiDoc or DocBook format (check your editor guidelines) +- [ ] UTF-8 encoding used +- [ ] Files named according to O'Reilly conventions +- [ ] Version control used (Git typically) +- [ ] Atlas platform requirements met (if using O'Reilly Atlas) + +## Style Guide + +- [ ] Chicago Manual of Style (16th or 17th edition) followed +- [ ] O'Reilly Word List consulted for technical terms +- [ ] Consistent capitalization and spelling +- [ ] Proper formatting for technical terms +- [ ] Style sheet provided by editor followed + +## Structure and Markup + +- [ ] Proper heading hierarchy (chapter, sect1, sect2, sect3) +- [ ] Headings use title case +- [ ] Cross-references formatted correctly +- [ ] Inline markup used appropriately (emphasis, strong, code) +- [ ] Lists formatted properly (itemized, ordered, variable) + +## Code Examples + +- [ ] Pygments language tags specified for syntax highlighting +- [ ] Code blocks use appropriate callouts +- [ ] Tabs converted to spaces (typically 4 spaces) +- [ ] Line length appropriate (typically 80 chars for print) +- [ ] Code listings numbered if referenced +- [ ] Callouts explained in text + +## Typography + +- [ ] Curly quotes used (not straight quotes) +- [ ] Em dashes formatted correctly (—) +- [ ] Ellipsis character used (…) not three periods +- [ ] Non-breaking spaces used where appropriate +- [ ] Special characters encoded correctly + +## Cross-References + +- [ ] Internal cross-references use correct syntax +- [ ] Chapter and section references formatted properly +- [ ] Figure and table references included +- [ ] Appendix references correct +- [ ] URL handling follows guidelines + +## Figures and Tables + +- [ ] All figures submitted in required format (EPS, PDF, or PNG) +- [ ] Figure captions written in complete sentences +- [ ] Tables formatted using appropriate markup +- [ ] Table captions provided +- [ ] All visual elements referenced in text + +## Technical Accuracy + +- [ ] Code tested and working +- [ ] Version numbers specified +- [ ] URLs verified +- [ ] Technical terms used correctly +- [ ] Examples represent best practices + +## Editorial Elements + +- [ ] Sidebars formatted correctly (notes, tips, warnings) +- [ ] Footnotes or endnotes formatted properly +- [ ] Glossary terms marked (if applicable) +- [ ] Index terms marked +- [ ] Bibliography formatted correctly + +## Front and Back Matter + +- [ ] Preface includes target audience and prerequisites +- [ ] Conventions section explains code formatting +- [ ] Acknowledgments included +- [ ] Colophon requirements met (if required) +- [ ] Copyright and licensing clear + +## Submission Requirements + +- [ ] All files in agreed format +- [ ] Complete manuscript package +- [ ] Permissions for third-party content obtained +- [ ] Code repository organized and accessible +- [ ] Author questionnaire completed +- [ ] Production editor requirements met diff --git a/expansion-packs/bmad-technical-writing/checklists/packtpub-submission-checklist.md b/expansion-packs/bmad-technical-writing/checklists/packtpub-submission-checklist.md new file mode 100644 index 00000000..368bd3e5 --- /dev/null +++ b/expansion-packs/bmad-technical-writing/checklists/packtpub-submission-checklist.md @@ -0,0 +1,86 @@ +# PacktPub Submission Checklist + +Use this checklist to ensure chapters meet Packt Publishing submission requirements. + +## Format and Length + +- [ ] Chapter length 20-30 pages (typical range) +- [ ] Submitted in required format (Word or Markdown per author guidelines) +- [ ] SharePoint formatting guidelines followed +- [ ] Proper heading levels used (H1 for chapter, H2 for sections) +- [ ] Page breaks appropriate + +## Chapter Structure + +- [ ] Learning objectives clearly stated at beginning +- [ ] Introduction section engaging and sets context +- [ ] Main content broken into logical sections +- [ ] Summary section included at end +- [ ] "Further reading" or "See also" section provided +- [ ] Prerequisites clearly listed + +## Code Examples + +- [ ] All code tested and working +- [ ] Code formatting consistent +- [ ] Syntax highlighting language specified +- [ ] Long lines broken appropriately (no horizontal scrolling) +- [ ] Code comments explain key concepts +- [ ] Output examples provided where helpful + +## Screenshots and Images + +- [ ] Screenshots in required format (PNG typical, 300 DPI) +- [ ] Images clearly labeled (Figure 1.1, Figure 1.2, etc.) +- [ ] Captions provided for all figures +- [ ] Images referenced in text +- [ ] High quality and readable +- [ ] Appropriate resolution for print and digital + +## Style and Voice + +- [ ] Second person ("you") perspective used +- [ ] Active voice preferred over passive +- [ ] Conversational but professional tone +- [ ] Chicago Manual of Style guidelines followed +- [ ] Consistent terminology throughout + +## Technical Content + +- [ ] Technical accuracy verified +- [ ] Current best practices demonstrated +- [ ] Version numbers specified for all software/libraries +- [ ] Cross-platform considerations noted where relevant +- [ ] Deprecated features avoided + +## Educational Elements + +- [ ] Concepts explained clearly before code +- [ ] Progressive skill building through chapter +- [ ] Real-world examples and use cases included +- [ ] Troubleshooting tips provided +- [ ] Key points highlighted or called out + +## References and Resources + +- [ ] URLs verified and working +- [ ] Official documentation referenced +- [ ] GitHub repository links included (if applicable) +- [ ] Attribution for third-party code or content +- [ ] License information for code included + +## Review and Quality + +- [ ] Grammar and spelling checked +- [ ] Technical review completed +- [ ] Code review completed +- [ ] Peer review feedback addressed +- [ ] Author checklist completed (if provided by Packt) + +## Submission Package + +- [ ] Main chapter file +- [ ] All images in separate folder +- [ ] Code files organized and tested +- [ ] README for code repository (if applicable) +- [ ] Change log or revision notes (if resubmitting) diff --git a/expansion-packs/bmad-technical-writing/checklists/performance-considerations-checklist.md b/expansion-packs/bmad-technical-writing/checklists/performance-considerations-checklist.md new file mode 100644 index 00000000..63a70809 --- /dev/null +++ b/expansion-packs/bmad-technical-writing/checklists/performance-considerations-checklist.md @@ -0,0 +1,83 @@ +# Performance Considerations Checklist + +Use this checklist to assess performance implications of code examples and recommendations. + +## Algorithm Efficiency + +- [ ] Algorithm complexity appropriate (avoid O(n²) where O(n) possible) +- [ ] Data structures chosen appropriately +- [ ] Unnecessary iterations avoided +- [ ] Early termination conditions used where applicable +- [ ] Recursive vs iterative approaches considered + +## Database Performance + +- [ ] N+1 query problem avoided +- [ ] Appropriate use of indexes mentioned +- [ ] Query optimization demonstrated +- [ ] Lazy loading vs eager loading discussed +- [ ] Database connection pooling recommended +- [ ] Pagination implemented for large datasets + +## Caching + +- [ ] Caching strategies mentioned where beneficial +- [ ] Cache invalidation discussed +- [ ] Appropriate cache levels considered (application, database, CDN) +- [ ] Memory vs speed tradeoffs explained + +## Memory Management + +- [ ] No obvious memory leaks +- [ ] Large data structures handled appropriately +- [ ] Memory usage patterns reasonable +- [ ] Object pooling or reuse considered where relevant +- [ ] Garbage collection implications discussed + +## Network Performance + +- [ ] API calls minimized +- [ ] Batch operations used where appropriate +- [ ] Compression mentioned for large payloads +- [ ] Async operations used for I/O +- [ ] Connection reuse demonstrated + +## Scalability + +- [ ] Solutions scale to production workloads +- [ ] Resource constraints considered +- [ ] Horizontal scaling implications discussed +- [ ] Stateless design patterns where appropriate +- [ ] Load distribution strategies mentioned + +## Optimization Balance + +- [ ] Premature optimization avoided +- [ ] Clarity prioritized over micro-optimizations +- [ ] Performance tradeoffs explained +- [ ] When to optimize discussed (profiling first) +- [ ] Educational clarity maintained + +## Profiling & Monitoring + +- [ ] Profiling tools mentioned where relevant +- [ ] Performance testing approaches suggested +- [ ] Monitoring best practices referenced +- [ ] Bottleneck identification techniques shown +- [ ] Benchmarking guidance provided + +## Resource Usage + +- [ ] File handles closed properly +- [ ] Database connections released +- [ ] Thread/process management appropriate +- [ ] Timeouts configured +- [ ] Rate limiting considered for APIs + +## Production Considerations + +- [ ] Development vs production differences noted +- [ ] Logging performance impact discussed +- [ ] Debug mode disabled in production examples +- [ ] Production-ready patterns demonstrated +- [ ] Performance SLAs considered diff --git a/expansion-packs/bmad-technical-writing/checklists/security-best-practices-checklist.md b/expansion-packs/bmad-technical-writing/checklists/security-best-practices-checklist.md new file mode 100644 index 00000000..2008228d --- /dev/null +++ b/expansion-packs/bmad-technical-writing/checklists/security-best-practices-checklist.md @@ -0,0 +1,80 @@ +# Security Best Practices Checklist + +Use this checklist to ensure code examples and recommendations follow security best practices. + +## Credential Security + +- [ ] No hardcoded passwords or API keys in code examples +- [ ] Environment variables or configuration files used for secrets +- [ ] Credential management best practices demonstrated +- [ ] Examples show proper secret rotation patterns +- [ ] No credentials in version control examples + +## Input Validation + +- [ ] Input validation demonstrated in user-facing code +- [ ] Type checking shown where applicable +- [ ] Length limits enforced on user inputs +- [ ] Regex patterns used safely +- [ ] Sanitization techniques explained + +## Injection Prevention + +- [ ] SQL injection prevention shown (parameterized queries, ORMs) +- [ ] No string concatenation for SQL queries +- [ ] XSS (Cross-Site Scripting) prevention demonstrated +- [ ] Command injection risks avoided +- [ ] LDAP injection prevention shown where relevant + +## Authentication & Authorization + +- [ ] Secure authentication patterns demonstrated +- [ ] Password hashing used (bcrypt, Argon2, PBKDF2) +- [ ] Never store passwords in plaintext +- [ ] Session management follows best practices +- [ ] JWT secrets properly managed +- [ ] Authorization checks shown in protected routes + +## Cryptography + +- [ ] No deprecated crypto functions (MD5, SHA1 for security) +- [ ] Secure random number generation demonstrated +- [ ] HTTPS/TLS usage recommended +- [ ] Certificate validation not disabled +- [ ] Appropriate key lengths used + +## Data Protection + +- [ ] Sensitive data handling explained +- [ ] No logging of passwords or secrets +- [ ] Personal information protected appropriately +- [ ] Data encryption demonstrated where needed +- [ ] Secure data transmission shown + +## Security Headers + +- [ ] Security headers recommended where applicable +- [ ] CORS configured properly +- [ ] Content Security Policy mentioned for web apps +- [ ] X-Frame-Options discussed for clickjacking prevention + +## Dependencies + +- [ ] Dependency security mentioned +- [ ] No use of packages with known vulnerabilities +- [ ] Version pinning or ranges explained +- [ ] Regular updates recommended + +## Error Handling + +- [ ] No sensitive information in error messages +- [ ] Stack traces not exposed to users in production +- [ ] Appropriate error logging demonstrated +- [ ] Security events logged for audit trail + +## Reference to Standards + +- [ ] OWASP guidelines referenced where applicable +- [ ] Industry standards followed +- [ ] Common vulnerability patterns (CWE) avoided +- [ ] Security resources provided for further reading diff --git a/expansion-packs/bmad-technical-writing/checklists/technical-accuracy-checklist.md b/expansion-packs/bmad-technical-writing/checklists/technical-accuracy-checklist.md new file mode 100644 index 00000000..ff46ee3b --- /dev/null +++ b/expansion-packs/bmad-technical-writing/checklists/technical-accuracy-checklist.md @@ -0,0 +1,53 @@ +# Technical Accuracy Checklist + +Use this checklist to verify all technical claims, facts, and information are accurate and current. + +## Factual Accuracy + +- [ ] All technical claims verified against official documentation +- [ ] Version numbers specified and correct +- [ ] API usage matches current documentation +- [ ] Language features used correctly +- [ ] Framework concepts accurately explained +- [ ] No outdated or deprecated information presented as current + +## Source Verification + +- [ ] Official documentation referenced for all claims +- [ ] Standards (RFCs, PEPs, etc.) cited correctly +- [ ] Third-party library documentation checked +- [ ] Release notes reviewed for version-specific features +- [ ] Community best practices verified from authoritative sources + +## Code Correctness + +- [ ] All code examples are syntactically correct +- [ ] Code produces the claimed outputs +- [ ] Function signatures match documentation +- [ ] Return types are correct +- [ ] Parameter usage is accurate +- [ ] Imports and dependencies are complete + +## Best Practices Currency + +- [ ] Recommended approaches are current (not outdated) +- [ ] Best practices align with industry standards +- [ ] Design patterns are appropriate +- [ ] Common anti-patterns are avoided or called out +- [ ] Modern language features used where appropriate + +## Common Misconceptions + +- [ ] Common mistakes are corrected, not perpetuated +- [ ] Myths or misconceptions are addressed +- [ ] Confusing concepts are clarified accurately +- [ ] Edge cases are explained correctly +- [ ] Limitations are clearly stated + +## Expert Validation + +- [ ] Content reviewed by subject matter expert +- [ ] Technical claims validated by multiple sources +- [ ] Complex concepts verified for accuracy +- [ ] Examples represent real-world best practices +- [ ] No oversimplification that leads to misunderstanding diff --git a/expansion-packs/bmad-technical-writing/config.yaml b/expansion-packs/bmad-technical-writing/config.yaml index dcc049a6..15123fc9 100644 --- a/expansion-packs/bmad-technical-writing/config.yaml +++ b/expansion-packs/bmad-technical-writing/config.yaml @@ -1,13 +1,15 @@ # name: bmad-technical-writing -version: 0.1.0 +version: 0.2.0 short-title: Technical Book Writing Studio description: >- Comprehensive AI-powered technical writing framework for technical book - authors, technical trainers, and documentation specialists. Provides - specialized agents, workflows, and tools for planning, writing, and - maintaining technical books with code examples, tutorials, and learning - objectives. Supports publishers like PacktPub, O'Reilly, Manning, and + authors, technical trainers, and documentation specialists. Provides 6 + specialized agents, 2 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 + accessibility. Supports publishers like PacktPub, O'Reilly, Manning, and self-publishing platforms. author: Wes slashPrefix: bmad-tw diff --git a/expansion-packs/bmad-technical-writing/data/publisher-guidelines.md b/expansion-packs/bmad-technical-writing/data/publisher-guidelines.md index 7619a08e..1671068e 100644 --- a/expansion-packs/bmad-technical-writing/data/publisher-guidelines.md +++ b/expansion-packs/bmad-technical-writing/data/publisher-guidelines.md @@ -1,34 +1,345 @@ # Publisher Guidelines -**Note:** This is a Sprint 1 placeholder. Full publisher-specific guidelines will be added in Sprint 2. +Comprehensive publisher-specific requirements for technical book authors. This knowledge base provides formatting, submission, and process guidelines for major technical publishers. -## Current Content +## PacktPub Publishing -Basic publisher structure information is available in `book-structures.md`. +### Submission Requirements -## Sprint 2 Additions +**Format:** +- Microsoft Word (.docx) or Markdown per author agreement +- SharePoint-based submission system +- Chapter-by-chapter delivery typical -Full guidelines will include: +**Chapter Structure:** +- Chapter length: 20-30 pages typical +- Learning objectives at beginning +- Introduction section +- Main content sections (3-6 major sections) +- Summary or conclusion +- Further reading or references -- PacktPub submission requirements (from research section 11p) -- O'Reilly format and style requirements (from research section 11q) -- Manning MEAP process and requirements (from research section 11r) -- Self-publishing platform standards (from research section 11s) -- Formatting specifications per publisher -- Submission checklists -- Review process expectations -- Royalty and contract considerations +**Style Guidelines:** +- Chicago Manual of Style (CMS) 16th or 17th edition +- Second person ("you") perspective +- Active voice preferred +- Conversational but professional tone +- British or American English (specify in contract) -## Temporary Reference +**Code Examples:** +- All code must be tested and functional +- Syntax highlighting specified +- Comments explain key concepts +- Code repository required (GitHub typical) +- Version numbers for all dependencies -For Sprint 1, refer to: +**Visual Elements:** +- Screenshots in PNG format (300 DPI minimum) +- Figures numbered sequentially (Figure 1.1, 1.2, etc.) +- Captions provided for all images +- Diagrams clear and professional +- Author typically provides raw images; publisher may reformat -- `book-structures.md` for general structure patterns -- Publisher websites for official submission guidelines -- `bmad-kb.md` for publisher-specific considerations +**Timeline:** +- Typical book: 6-12 months from contract to publication +- Chapter milestones set by publisher +- Technical review built into timeline +- Author revision cycles after review -## Resources +### PacktPub Best Practices +- Focus on practical, hands-on learning +- Real-world examples valued +- Step-by-step tutorials effective +- Troubleshooting sections helpful +- Clear learning objectives drive content +- Beta reader feedback incorporated + +### Resources - PacktPub Author Hub: https://www.packtpub.com/authors +- Author guidelines provided in contract package +- Technical editor assigned to each book + +--- + +## O'Reilly Media + +### Submission Requirements + +**Format:** +- AsciiDoc or DocBook XML (Atlas platform) +- Git-based workflow typical +- Continuous integration with Atlas build system +- HTML, PDF, and EPUB outputs generated automatically + +**Style Guidelines:** +- Chicago Manual of Style (CMS) +- O'Reilly Word List for technical terms +- Title case for headings +- Consistent terminology critical +- Technical precision valued + +**Code Examples:** +- Pygments language tags for syntax highlighting +- Code callouts numbered +- Tabs converted to spaces (4 spaces typical) +- Line length limits (80 characters for print-friendly) +- Code tested thoroughly + +**Structure Requirements:** +- Preface explains audience, prerequisites, conventions +- Chapter hierarchy: chapter → sect1 → sect2 → sect3 +- Cross-references use proper xref syntax +- Glossary and index terms marked during writing +- Appendices for reference material + +**Visual Elements:** +- Vector formats preferred (EPS, PDF) +- PNG for screenshots (high resolution) +- Figure captions as complete sentences +- Tables use proper markup +- Diagrams professionally rendered + +**Review Process:** +- Technical review by external experts +- Developmental editing +- Copy editing +- Production editing +- Author reviews at each stage + +### O'Reilly Best Practices + +- Write for the "practical practitioner" +- Examples from real-world scenarios +- Deep technical detail valued +- Comprehensive coverage expected +- Authoritative voice appropriate +- Future-proof content when possible + +### Resources +- O'Reilly Atlas Platform: https://atlas.oreilly.com/ - O'Reilly Author Resources: https://www.oreilly.com/work-with-us.html -- Manning Author Guidelines: https://www.manning.com/write-for-us +- Style guide provided to authors +- Production editor guides through process + +--- + +## Manning Publications + +### Manning Early Access Program (MEAP) + +**MEAP Overview:** +- Chapters published as completed +- Reader feedback during writing process +- Community engagement valued +- Revenue sharing starts with MEAP +- Chapters must stand alone (readers may not have earlier chapters) + +**Format:** +- Microsoft Word or Markdown accepted +- Manning's production team handles final formatting +- Author voice strongly encouraged +- Conversational tone valued + +**Style Guidelines:** +- Author personality and experience highlighted +- "We" or "I" voice appropriate +- Engaging, story-driven approach +- Real-world scenarios and war stories +- Humor and personality welcomed (within professional bounds) + +**Chapter Structure:** +- Context provided for standalone reading +- Chapters in this chapter / Chapter summary +- Margin notes or callouts for key points +- "Try this" or hands-on moments +- Questions to engage readers + +**Code Examples:** +- GitHub repository required +- Code organized by chapter +- README explains how to use examples +- Tests included where appropriate +- Version numbers specified + +**Visual Elements:** +- Diagrams enhance understanding +- Screenshots annotated helpfully +- Manning's art team may redraw diagrams +- Figures integrated into narrative +- Whiteboard-style diagrams often effective + +### Manning Best Practices + +- Write to your audience directly +- Share your experience and expertise +- Make content immediately practical +- Engage readers with questions and challenges +- Respond to MEAP reader feedback +- Build community around your book + +### Resources +- Manning Author Center: https://www.manning.com/write-for-us +- MEAP author guidelines in contract +- Developmental editor works closely with author +- Active author forum + +--- + +## Self-Publishing Platforms + +### Amazon Kindle Direct Publishing (KDP) + +**Format:** +- EPUB, MOBI, or Word formats +- Kindle Create tool available +- Preview tools for different devices +- DRM optional + +**Requirements:** +- Cover design (author provides or use KDP tools) +- ISBN (Amazon provides free ASIN, or use your own ISBN) +- Book description and keywords +- Author bio +- Pricing set by author (royalty tiers: 35% or 70%) + +**Best Practices:** +- Mobile-friendly formatting essential +- Test on multiple Kindle devices/apps +- Table of contents with links +- Code formatting carefully tested +- Images optimized for e-readers + +### Leanpub + +**Format:** +- Markdown or direct writing in Leanpub editor +- Git integration available +- Automatic PDF, EPUB, MOBI generation +- Variable pricing model + +**Unique Features:** +- Publish while writing (MVP approach) +- Reader feedback during writing +- Bundle options (book + code + videos) +- Automatic updates to readers +- Coupons and promotional tools + +**Best Practices:** +- Minimum viable book to start (even a few chapters) +- Iterate based on reader feedback +- Keep readers updated with new content +- Price competitively (suggested pricing guidance) +- Market directly to your audience + +### Resources +- KDP: https://kdp.amazon.com +- Leanpub: https://leanpub.com +- Gumroad for technical books: https://gumroad.com +- Self-publishing communities: r/selfpublish, Indie Author groups + +--- + +## General Publisher Considerations + +### Royalty Structures +- Traditional publishers: 8-15% of net (after retailer cut) +- Self-publishing: 35-70% of gross (varies by platform) +- Advance payments vary widely (technical books: $5K-$25K typical, can be much higher for established authors) + +### Rights and Licensing +- Traditional: publisher typically gets exclusive rights for term +- Self-publishing: you retain all rights +- Code licensing: often separate from book copyright +- Translation rights negotiable + +### Marketing and Promotion +- Traditional publisher provides some marketing, author expected to promote +- Self-publishing: 100% author responsibility +- Author platform important for both (blog, social media, speaking) +- Technical community engagement valuable + +### Timeline Considerations +- Traditional: 6-18 months from contract to publication +- Self-publishing: author controls timeline (can publish immediately or over time) +- Both: writing typically takes 6-12 months for comprehensive book + +--- + +## Choosing the Right Publisher + +### Traditional Publisher When: +- You want professional editing and production +- Marketing support desired +- Credibility and imprint important +- Established distribution channels valued +- Royalty advance needed +- Don't want to manage production details + +### Self-Publishing When: +- You want full control +- Higher per-book royalty important +- Quick time to market needed +- You have existing audience/platform +- You want to retain all rights +- Willing to handle production and marketing + +### Hybrid Approach: +- Self-publish first to build audience +- Traditional deal for expanded/updated version +- Or reverse: traditional first, then self-publish later editions +- Different books with different publishers + +--- + +## Submission Best Practices (All Publishers) + +### Proposal Elements +- Book concept and unique value +- Target audience definition +- Competitive analysis +- Author credentials and platform +- Complete chapter outline +- Sample chapters (1-2 chapters) +- Marketing plan +- Timeline estimate + +### Professional Presentation +- Well-formatted proposal +- Error-free writing +- Realistic timeline +- Understanding of market +- Clear differentiators from competing books + +### Building Relationships +- Network at conferences +- Engage with publisher's community +- Follow editors on social media +- Understand each publisher's catalog +- Tailor proposal to publisher's style + +--- + +## Resources and References + +### Style Guides +- Chicago Manual of Style: https://www.chicagomanualofstyle.org/ +- Microsoft Writing Style Guide: https://docs.microsoft.com/en-us/style-guide/ +- Google Developer Documentation Style Guide: https://developers.google.com/style + +### Author Communities +- Write the Docs: https://www.writethedocs.org/ +- Technical Writer HQ: https://technicalwriterhq.com/ +- Author platforms (varies by publisher) + +### Tools +- Atlas (O'Reilly): https://atlas.oreilly.com/ +- Leanpub: https://leanpub.com +- Kindle Create: https://kdp.amazon.com/en_US/help/topic/G202131100 +- AsciiDoc: https://asciidoc.org/ + +### Legal and Rights +- Authors Guild: https://www.authorsguild.org/ +- Contract review resources +- Rights management tools +- Copyright registration (US): https://www.copyright.gov/ diff --git a/expansion-packs/bmad-technical-writing/data/technical-writing-standards.md b/expansion-packs/bmad-technical-writing/data/technical-writing-standards.md index 9d0902f6..d663357c 100644 --- a/expansion-packs/bmad-technical-writing/data/technical-writing-standards.md +++ b/expansion-packs/bmad-technical-writing/data/technical-writing-standards.md @@ -1,60 +1,524 @@ # Technical Writing Standards -**Note:** This is a Sprint 1 placeholder. Full technical writing standards will be added in Sprint 2. +Comprehensive standards for creating clear, consistent, accessible, and well-structured technical content. These principles apply across all publishers and formats. -## Current Guidance +## Clarity Principles -Basic writing principles are embedded in: +### Use Simple, Direct Language -- Agent personas (emphasis on clarity, consistency) -- Task workflows (quality checkpoints) -- Checklists (validation criteria) +**Do:** +- "Click the Submit button" (clear, direct) +- "The function returns a boolean value" (precise) +- "Remove the file" (simple verb) -## Sprint 2 Additions +**Don't:** +- "Utilize the Submit functionality to initiate the process" (unnecessarily complex) +- "The function facilitates the return of a boolean-type value" (wordy) +- "Effect the removal of the file" (pretentious) -Full standards will include: +### Explain Technical Terms -- Clarity principles (from research section 11x) -- Consistency requirements (from research section 11y) -- Accessibility guidelines (from research section 11z) -- Structure best practices (from research section 11za) -- Voice and tone guidelines -- Formatting conventions -- Cross-reference standards -- Glossary and index creation +**First Use Pattern:** +``` +JSON (JavaScript Object Notation) is a lightweight data format... +[Later in text] +...parse the JSON data... +``` -## Key Principles (Interim Guidance) +**Inline Explanation:** +``` +The API returns a 401 status code, which indicates unauthorized access. +``` -### Clarity +**Glossary Reference:** +``` +The service uses OAuth2 for authentication (see Glossary). +``` -- Use simple, direct language -- Explain technical terms on first use -- Provide examples for abstract concepts -- Break complex ideas into steps +### Provide Examples -### Consistency +**Abstract Concept:** +``` +❌ "Functions should be idempotent." -- Use terminology consistently -- Follow established patterns -- Maintain uniform formatting -- Apply style guide uniformly +✓ "Functions should be idempotent - producing the same result when called multiple times with the same input. For example, `getUserById(123)` should always return the same user data for ID 123." +``` -### Accessibility +**Show, Then Tell:** +```python +# Example first +def calculate_total(items): + return sum(item.price for item in items) -- Consider diverse reader backgrounds -- Provide multiple explanations when helpful -- Use inclusive language -- Ensure code examples work universally +# Then explain +The calculate_total function demonstrates list comprehension, +a Pythonic way to iterate and transform data in a single line. +``` -### Structure +### Break Down Complex Ideas -- Logical progression of topics -- Clear section headings -- Predictable chapter patterns -- Strong transitions between sections +**Step-by-Step:** +``` +To implement authentication: +1. Create a User model with password hashing +2. Build registration endpoint to create users +3. Implement login endpoint to verify credentials +4. Generate JWT token upon successful login +5. Create middleware to validate tokens +6. Protect routes using the middleware +``` -## Resources +**Progressive Disclosure:** +- Start with simplest case +- Add complexity incrementally +- Reference advanced topics for later -- Microsoft Writing Style Guide: https://docs.microsoft.com/en-us/style-guide/welcome/ -- Google Developer Documentation Style Guide: https://developers.google.com/style -- Write the Docs: https://www.writethedocs.org/guide/writing/style-guides/ +### Active Voice + +**Prefer Active:** +- "The function returns an array" (active) +- "Pass the parameter to the function" (active) +- "The compiler throws an error" (active) + +**Avoid Passive:** +- "An array is returned by the function" (passive) +- "The parameter should be passed to the function" (passive) +- "An error is thrown by the compiler" (passive) + +**Exception:** Passive voice appropriate when actor is unknown or unimportant: +- "The file was corrupted" (we don't know who/what corrupted it) +- "Python was released in 1991" (focus on Python, not Guido) + +### Sentence Clarity + +**One Idea Per Sentence:** +``` +❌ "The function validates the input and then transforms it to the required format and returns it to the caller or throws an error if validation fails." + +✓ "The function first validates the input. If validation succeeds, it transforms the data to the required format and returns it. If validation fails, it throws an error." +``` + +**Specific vs Vague:** +``` +❌ "The database might have some issues with performance." +✓ "Query response time increases from 50ms to 2 seconds when the users table exceeds 1 million rows." +``` + +--- + +## Consistency Requirements + +### Terminology Consistency + +**Choose One Term:** +``` +✓ Consistent: "function" throughout +❌ Inconsistent: "function", "method", "routine", "procedure" interchangeably +``` + +**Create a Term List:** +``` +Preferred Terms: +- "filesystem" (not "file system") +- "username" (not "user name") +- "backend" (not "back-end" or "back end") +- "email" (not "e-mail") +- "GitHub" (not "Github") +``` + +### Style Consistency + +**Code Formatting:** +``` +✓ Consistent: +Use `variable_name` for variables and `function_name()` for functions. + +❌ Inconsistent: +Use variable_name for variables and function_name() for functions. +(Missing backticks, inconsistent formatting) +``` + +**Heading Capitalization:** +``` +✓ Title Case Consistent: +## Chapter 1: Building Your First API +## Chapter 2: Adding Authentication +## Chapter 3: Deploying to Production + +✓ Sentence Case Consistent: +## Chapter 1: Building your first API +## Chapter 2: Adding authentication +## Chapter 3: Deploying to production + +❌ Inconsistent Mix: +## Chapter 1: Building your First API +## Chapter 2: Adding Authentication +``` + +### Voice and Tone + +**Maintain Consistent Perspective:** +``` +✓ Second Person Throughout: +"You create a function by using the def keyword. You then add parameters..." + +❌ Mixed Perspectives: +"You create a function by using the def keyword. We then add parameters..." +"One creates a function by using the def keyword..." +``` + +**Consistent Formality Level:** +- Casual: "Let's dive in!", "Cool!", "Pretty neat, right?" +- Professional: "We'll begin", "Effective", "This demonstrates" +- Pick one and maintain throughout + +### Formatting Patterns + +**Code Blocks:** +``` +✓ Consistent: +All code blocks use language tags and show complete context + +❌ Inconsistent: +Some with language tags, some without; some show imports, some don't +``` + +**Lists:** +``` +✓ Parallel Structure: +- Create the database +- Configure the connection +- Test the setup + +❌ Non-Parallel: +- Create the database +- Configuring the connection +- You should test the setup +``` + +--- + +## Accessibility Standards + +### Alt Text for Images + +**Descriptive Alt Text:** +``` +❌ screenshot +❌ Figure 1 + +✓ Django admin interface showing user list with filter sidebar +✓ Error message: 'Connection refused on localhost:5432' +``` + +**Complex Diagrams:** +``` +Authentication flow diagram + +In text or linked file: +"The authentication flow begins with the client sending credentials to +the /login endpoint. The server validates these against the database. +If valid, a JWT token is generated and returned. The client includes +this token in subsequent requests via the Authorization header..." +``` + +### Color and Visual Information + +**Don't Rely on Color Alone:** +``` +❌ "The red items are errors, green items are successes." + +✓ "Errors are marked with a red X icon (❌), while successes show a green checkmark (✓)." +``` + +**Code Syntax Highlighting:** +``` +# Ensure code is understandable without color + +❌ Relying only on color to show strings vs keywords + +✓ Use descriptive comments: +# This string contains the API key: +api_key = "abc123xyz" +``` + +### Document Structure + +**Proper Heading Hierarchy:** +``` +✓ Correct: +# Chapter 1: Introduction (H1) +## Section 1.1: Prerequisites (H2) +### Installing Python (H3) +### Installing VS Code (H3) +## Section 1.2: Your First Program (H2) + +❌ Incorrect: +# Chapter 1: Introduction (H1) +### Installing Python (H3) - skipped H2 +## Your First Program (H2) - after H3 +``` + +**Meaningful Headings:** +``` +✓ Descriptive: "Installing PostgreSQL on macOS" +❌ Generic: "Installation" or "Next Steps" +``` + +### Screen Reader Considerations + +**Link Text:** +``` +❌ "Click [here] to download Python." +❌ "Learn more at [this link]." + +✓ "[Download Python 3.11 for Windows]" +✓ "Read the [official Django tutorial]" +``` + +**Table Structure:** +``` +| Header 1 | Header 2 | Header 3 | +|----------|----------|----------| +| Data 1A | Data 2A | Data 3A | + +✓ Uses proper markdown table format with headers +✓ Screen readers can navigate by rows/columns +``` + +**Code Examples:** +```python +# Use descriptive variable names that make sense when read aloud +✓ user_email = "user@example.com" +❌ x = "user@example.com" + +# Function names should be read able +✓ calculate_total_price() +❌ calc_tot() +``` + +### Plain Language + +**Acronyms:** +``` +✓ "REST (Representational State Transfer) is an architectural style..." +Later: "...using REST APIs..." + +❌ Assuming knowledge: "Using REST..." (no definition) +``` + +**Define Jargon:** +``` +✓ "Idempotent operations produce the same result when executed multiple times." +❌ "Operations should be idempotent." (no explanation) +``` + +--- + +## Structure Best Practices + +### Logical Topic Progression + +**Foundation First:** +``` +Chapter Sequence: +1. Python Basics → 2. Functions → 3. Classes → 4. Advanced OOP +(Each builds on previous) + +❌ Poor Sequence: +1. Advanced OOP → 2. Classes → 3. Python Basics +``` + +**Dependency Management:** +``` +✓ "In Chapter 2, we learned about functions. Now we'll use functions to..." +✓ "This builds on the authentication system from Chapter 5..." + +❌ Referencing concepts not yet covered without explanation +``` + +### Section Organization + +**Consistent Chapter Structure:** +``` +Chapter Template: +1. Introduction (hooks, context, objectives) +2. Prerequisites +3. Concept Explanation +4. Tutorial/Hands-On +5. Exercises +6. Summary +7. Further Reading + +Use same structure for every chapter (readers know what to expect) +``` + +**Section Length:** +- Chapters: 15-30 pages typical +- Major sections: 3-8 pages +- Subsections: 1-3 pages +- Keep related content together + +### Transitions + +**Between Sections:** +``` +✓ "Now that you understand basic routing, let's add authentication to protect routes." + +✓ "With the database configured, we're ready to create our first model." + +❌ Abrupt jump to new topic without connection +``` + +**Between Chapters:** +``` +Chapter End: "In the next chapter, we'll deploy this application to production." + +Next Chapter Start: "In Chapter 5, we built a REST API. Now we'll deploy it using Docker and AWS." +``` + +### Cross-References + +**Specific References:** +``` +✓ "See Chapter 3, Section 3.2: Database Setup" +✓ "As explained in the Authentication section on page 45..." + +❌ "As mentioned earlier..." +❌ "See above..." +``` + +**Forward References:** +``` +✓ "We'll cover error handling in depth in Chapter 8." +✓ "Advanced caching strategies are beyond this book's scope. See 'High Performance Python' by Gorelick and Ozsvald." + +Manage expectations about what's covered where +``` + +### Visual Hierarchy + +**Use Formatting:** +- **Bold** for emphasis or key terms +- `Code formatting` for inline code +- > Blockquotes for important callouts +- Lists for series of items +- Tables for structured data + +**Consistent Callouts:** +``` +**Note:** Additional information +**Warning:** Potential pitfall +**Tip:** Helpful suggestion +**Exercise:** Practice opportunity +``` + +--- + +## Code Documentation Standards + +### Code Comments + +**Explain Why, Not What:** +```python +❌ # Set x to 5 +x = 5 + +✓ # Default timeout in seconds +timeout = 5 + +✓ # Use exponential backoff to avoid overwhelming the API +for attempt in range(max_retries): + time.sleep(2 ** attempt) +``` + +**Document Intent:** +```python +✓ # Remove duplicates while preserving order +seen = set() +result = [x for x in items if not (x in seen or seen.add(x))] + +❌ # Loop through items +for item in items: + # Do something + ... +``` + +### Function Documentation + +**Docstring Standard:** +```python +def authenticate_user(username, password): + """ + Authenticate user credentials against the database. + + Args: + username (str): The user's username + password (str): The user's plain-text password + + Returns: + User: The authenticated user object + + Raises: + AuthenticationError: If credentials are invalid + DatabaseError: If database connection fails + + Example: + >>> user = authenticate_user("john", "secret123") + >>> print(user.email) + john@example.com + """ +``` + +### API Documentation + +**Endpoint Description:** +``` +GET /api/users/:id + +Description: Retrieve a single user by ID + +Parameters: +- id (path): User ID (integer) + +Headers: +- Authorization: Bearer token required + +Response 200: +{ + "id": 123, + "username": "john", + "email": "john@example.com" +} + +Response 404: +{ + "error": "User not found" +} +``` + +--- + +## References and Resources + +### Style Guide Standards +- Microsoft Writing Style Guide +- Google Developer Documentation Style Guide +- Chicago Manual of Style (for publishers) +- AP Stylebook (for journalism-style technical writing) + +### Accessibility Standards +- WCAG 2.1 Level AA (minimum) +- Section 508 (US government) +- Plain Language guidelines + +### Technical Writing Communities +- Write the Docs: https://www.writethedocs.org/ +- TC (Technical Communication) Stack Exchange +- Reddit: r/technicalwriting + +### Tools +- Hemingway Editor (readability) +- Grammarly (grammar and style) +- Vale (style guide linter) +- alex (inclusive language linter) diff --git a/expansion-packs/bmad-technical-writing/tasks/copy-edit-chapter.md b/expansion-packs/bmad-technical-writing/tasks/copy-edit-chapter.md new file mode 100644 index 00000000..37264ece --- /dev/null +++ b/expansion-packs/bmad-technical-writing/tasks/copy-edit-chapter.md @@ -0,0 +1,341 @@ + + +# Copy Edit Chapter + +--- + +task: + id: copy-edit-chapter + name: Copy Edit Chapter + description: Professional editorial polish including grammar, clarity, consistency, style compliance, and accessibility + persona_default: technical-editor + inputs: + - chapter-draft + - chapter-number + - target-publisher + steps: + - Review chapter for grammar and spelling + - Check terminology consistency throughout + - Verify publisher style guide compliance + - Improve sentence clarity and readability + - Enhance transitions between sections + - Check heading hierarchy and structure + - Verify code formatting consistency + - Review accessibility considerations + - Polish language for professional quality + - Ensure consistent voice and tone + - Create summary of editorial changes + - Run execute-checklist.md with accessibility-checklist.md + - Run execute-checklist.md with relevant publisher checklist + output: Edited chapter with change summary + +--- + +## Purpose + +Transform technically accurate content into professionally polished, publication-ready material that is clear, consistent, accessible, and compliant with publisher requirements. + +## Prerequisites + +- Chapter draft completed and technically reviewed +- Technical review issues addressed +- Publisher style guide available +- Access to publisher-guidelines.md knowledge base +- Access to technical-writing-standards.md knowledge base + +## Workflow Steps + +### 1. Review Grammar and Spelling + +Perform comprehensive language check: + +**Grammar:** +- Subject-verb agreement +- Pronoun references +- Verb tenses (use present tense for technical writing) +- Parallel structure in lists +- Sentence fragments and run-ons + +**Spelling:** +- Technical terms spelled correctly +- Consistent spelling (US vs UK English) +- Common technical term errors (e.g., "GitHub" not "Github") + +**Tools:** +- Use spell checker as first pass +- Manual review for technical terms +- Verify proper nouns and product names + +**Note:** Technical writing often uses terms spell checkers don't recognize - verify rather than auto-correct. + +### 2. Check Terminology Consistency + +Ensure terms used consistently throughout: + +**Term Standardization:** +- Create term list for chapter +- Use same term for same concept (not "function" then "method" interchangeably) +- Match terminology to official documentation +- Consistent capitalization (e.g., "JavaScript" not "Javascript") + +**Common Inconsistencies:** +- API vs API's vs APIs (plurals and possessives) +- Filename vs file name vs file-name +- Setup vs set up (noun vs verb) +- Backend vs back-end vs back end + +**Action:** Search chapter for term variations and standardize. + +### 3. Verify Publisher Style Guide Compliance + +Apply specific publisher requirements: + +**PacktPub:** +- Chicago Manual of Style +- Second person ("you") perspective +- Active voice preferred +- Code formatting in monospace +- Screenshots at required resolution + +**O'Reilly:** +- Chicago Manual of Style +- Specific heading levels +- Code highlighting conventions +- Cross-reference formatting + +**Manning:** +- Conversational but professional tone +- Author voice encouraged +- Specific formatting for code listings +- Margin note requirements + +**Use relevant checklist:** +- packtpub-submission-checklist.md +- oreilly-format-checklist.md +- manning-meap-checklist.md + +### 4. Improve Sentence Clarity + +Enhance readability and comprehension: + +**Clarity Principles:** +- One idea per sentence when possible +- Active voice preferred over passive +- Remove unnecessary words +- Break complex sentences into simpler ones +- Use concrete examples over abstractions + +**Before:** "It should be noted that the utilization of this pattern may result in performance improvements." + +**After:** "This pattern often improves performance." + +**Avoid:** +- Jargon without explanation +- Overly complex sentence structures +- Ambiguous pronouns ("it", "this", "that" without clear referent) +- Double negatives + +**Preserve:** +- Author voice and style +- Technical precision +- Necessary complexity + +### 5. Enhance Transitions + +Improve flow between sections and ideas: + +**Between Sections:** +- Add transition sentences linking topics +- Preview what's coming next +- Reference what was just covered +- Explain logical progression + +**Example Transitions:** +- "Now that you understand X, let's explore Y..." +- "With this foundation in place, we can tackle..." +- "Building on the previous example, you'll now..." + +**Within Paragraphs:** +- Use transition words (however, therefore, additionally) +- Maintain logical flow +- Connect sentences coherently + +**Check:** Can reader follow the logical progression without getting lost? + +### 6. Check Heading Hierarchy + +Ensure proper document structure: + +**Hierarchy Rules:** +- H1: Chapter title (one per chapter) +- H2: Major sections +- H3: Subsections +- H4: Minor subsections (use sparingly) + +**Heading Best Practices:** +- Parallel structure in same level +- Descriptive and specific +- Avoid "Introduction" as H2 (use descriptive title) +- Capitalize consistently + +**Example:** +``` +# Chapter 3: Database Design (H1) +## Understanding Relational Databases (H2) +### Tables and Relationships (H3) +### Primary and Foreign Keys (H3) +## Designing Your First Schema (H2) +### Identifying Entities (H3) +``` + +### 7. Verify Code Formatting Consistency + +Ensure all code formatted properly: + +**Code Blocks:** +- Language specified for syntax highlighting +- Consistent indentation (spaces vs tabs) +- Line length appropriate (avoid horizontal scrolling) +- Comments formatted consistently + +**Inline Code:** +- Use backticks for code terms +- Function names: `function_name()` +- Variables: `variable_name` +- File paths: `path/to/file.py` + +**Code Callouts:** +- Explanations below code blocks +- Reference specific lines when needed +- Expected output shown where relevant + +**Consistency:** +- Same style throughout chapter +- Matches publisher requirements +- Follows language conventions + +### 8. Review Accessibility + +Ensure content is accessible to all readers: + +**Use accessibility-checklist.md** + +**Key Checks:** +- Alt text for all images and diagrams +- Color not the sole means of conveying information +- Code examples screen-reader friendly +- Clear heading hierarchy (aids navigation) +- Descriptive link text (not "click here") +- Plain language where possible +- Acronyms defined on first use + +**Example:** Instead of "See the red line in the diagram", use "See the error indicator (red line) in the diagram" + +### 9. Polish Language and Readability + +Final pass for professional quality: + +**Voice and Tone:** +- Consistent throughout chapter +- Appropriate for audience (not too casual, not too formal) +- Encouraging and supportive (avoid condescending) +- Technical but approachable + +**Readability:** +- Vary sentence length +- Break up long paragraphs (3-5 sentences typical) +- Use lists for multiple items +- Add white space for visual breaks + +**Professional Polish:** +- Remove filler words (basically, simply, just) +- Strengthen weak verbs (use specific action verbs) +- Replace vague terms with specific ones +- Ensure confident tone (avoid "might", "maybe", "probably") + +### 10. Create Summary of Changes + +Document editorial modifications: + +**Change Log Should Include:** +- Major structural changes +- Terminology standardizations +- Sections rewritten for clarity +- Publisher style compliance updates +- Accessibility improvements + +**Format:** +``` +Editorial Changes Summary - Chapter 3 + +Structural: +- Combined Sections 3.2 and 3.3 for better flow +- Moved error handling to separate section 3.5 + +Clarity: +- Simplified complex sentences in Section 3.1 +- Added transition between Sections 3.3 and 3.4 + +Terminology: +- Standardized "filesystem" (not "file system") +- Corrected "GitHub" capitalization throughout + +Style: +- Applied PacktPub heading format +- Updated code block syntax highlighting + +Accessibility: +- Added alt text to all 8 diagrams +- Defined all acronyms on first use +``` + +**Purpose:** Helps author understand changes and learn for future chapters. + +## Output + +Copy edited chapter with: + +- Clean, professional prose +- Consistent terminology +- Proper grammar and spelling +- Clear transitions and flow +- Publisher style compliance +- Accessibility improvements +- Change summary document + +## Quality Standards + +Professional copy edit: + +✓ Error-free grammar and spelling +✓ Consistent terminology throughout +✓ Clear, readable sentences +✓ Smooth transitions between sections +✓ Proper heading hierarchy +✓ Code formatting consistent +✓ Publisher requirements met +✓ Accessible to all readers +✓ Professional tone maintained +✓ Author voice preserved + +## Common Pitfalls + +Avoid: + +❌ Over-editing and losing author voice +❌ Introducing new technical errors +❌ Inconsistent style between sections +❌ Removing necessary technical detail +❌ Making changes without understanding context +❌ Ignoring publisher-specific requirements + +## Next Steps + +After copy editing: + +1. Return edited chapter to author for review +2. Author approves or discusses editorial changes +3. Resolve any disagreements collaboratively +4. Finalize chapter text +5. Proceed to final publication preparation +6. Publisher may do additional copy editing pass diff --git a/expansion-packs/bmad-technical-writing/tasks/design-exercises.md b/expansion-packs/bmad-technical-writing/tasks/design-exercises.md new file mode 100644 index 00000000..d68caa35 --- /dev/null +++ b/expansion-packs/bmad-technical-writing/tasks/design-exercises.md @@ -0,0 +1,383 @@ + + +# Design Exercises + +--- + +task: + id: design-exercises + name: Design Exercises + description: Create practice exercises with progressive difficulty, hints, and solution approaches + persona_default: instructional-designer + inputs: + - chapter-number + - learning-objectives + - difficulty-range + steps: + - Identify learning objectives to assess + - Determine appropriate difficulty levels (basic to advanced) + - Create 4-6 exercises per chapter with progressive difficulty + - Progress from basic application to challenging problems + - Write clear instructions for each exercise + - Develop solution approaches (not full solutions) + - Add progressive hints for learners + - Create extension challenges for advanced students + - Estimate completion time for each exercise + - Validate exercises are solvable and appropriate + - Run execute-checklist.md with exercise-difficulty-checklist.md + - Use template exercise-set-tmpl.yaml with create-doc.md + output: exercises/chapter-{{chapter_number}}-exercises.md + +--- + +## Purpose + +Create practice exercises that reinforce learning, assess comprehension, and build confidence through progressive difficulty. Effective exercises bridge theory and independent application. + +## Prerequisites + +- Chapter learning objectives defined +- Chapter content drafted or outlined +- Understanding of target audience skill level +- Access to learning-frameworks.md knowledge base + +## Workflow Steps + +### 1. Identify Learning Objectives to Assess + +Map exercises to specific learning goals: + +**For Each Learning Objective:** +- Which exercises will assess this? +- What demonstrates mastery? +- How can students practice this skill? + +**Example Mapping:** +``` +Objective: "Implement JWT authentication" +→ Exercise 2: Build login endpoint (basic) +→ Exercise 4: Add token refresh (intermediate) +→ Exercise 6: Implement role-based access (advanced) +``` + +**Coverage:** +- Each objective addressed by at least one exercise +- Core objectives get multiple exercises +- Progressive difficulty across related exercises + +### 2. Determine Difficulty Levels + +Plan difficulty range appropriate for chapter: + +**Basic (⭐):** +- Direct application of chapter examples +- Clear guidance and hints +- Builds confidence +- 2-3 exercises per chapter + +**Intermediate (⭐⭐):** +- Combines multiple concepts +- Requires problem-solving +- Less hand-holding +- 1-2 exercises per chapter + +**Advanced (⭐⭐⭐):** +- Creative application +- Minimal guidance +- Extension of concepts +- 1 exercise per chapter (optional) + +**Balance:** Most students should complete basic and intermediate exercises successfully. + +### 3. Create 4-6 Exercises with Progressive Difficulty + +Design exercise sequence: + +**Exercise Structure:** + +**Exercise Header:** +- Number and title +- Difficulty indicator (⭐ ⭐⭐ ⭐⭐⭐) +- Estimated time +- Learning objective addressed + +**Problem Description:** +- Clear problem statement +- Specific requirements (numbered list) +- Input/output examples +- Success criteria + +**Example:** +``` +### Exercise 3: User Input Validation ⭐⭐ +**Estimated Time:** 20 minutes +**Learning Objective:** Apply regex for validation + +**Problem:** +Create a `validate_user_input()` function that validates user registration data: + +Requirements: +1. Username: 3-20 characters, alphanumeric only +2. Email: Valid email format +3. Password: Minimum 8 characters, must include number and special character +4. Return dict with validation results for each field + +**Test Cases:** +```python +validate_user_input("user123", "user@example.com", "Pass123!") +# Returns: {"username": True, "email": True, "password": True, "valid": True} + +validate_user_input("ab", "invalid", "weak") +# Returns: {"username": False, "email": False, "password": False, "valid": False} +``` + +**Success Criteria:** +- All test cases pass +- Clear error messages for invalid inputs +- Uses regex for email validation +``` + +### 4. Write Clear Instructions + +Make requirements explicit and unambiguous: + +**Good Exercise Instructions:** +- State exact functionality needed +- Provide function signature or class structure +- List all requirements as numbered points +- Include test cases with expected results +- Specify any constraints + +**Avoid:** +- Vague requirements ("make it work better") +- Ambiguous success criteria +- Assuming implied requirements +- Unclear edge cases + +**Starter Code (for basic exercises):** +```python +def validate_user_input(username, email, password): + """ + Validate user registration inputs. + + Args: + username (str): Username to validate + email (str): Email address to validate + password (str): Password to validate + + Returns: + dict: Validation results for each field and overall validity + """ + # Your code here + pass +``` + +### 5. Develop Solution Approaches + +Provide guidance without giving away the answer: + +**Solution Approach (Not Full Code):** +- High-level algorithm +- Key concepts to apply +- Recommended data structures +- Common pitfalls to avoid + +**Example:** +``` +**Solution Approach:** +1. Create validation functions for each field type +2. Use regex pattern for email: `^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$` +3. For password, check length first, then regex for number and special char +4. Return dictionary with results for each field +5. Set `valid` to True only if all fields pass + +**Key Concepts:** +- Python `re` module for regex matching +- `re.match()` vs `re.fullmatch()` - use fullmatch for exact pattern matching +- Combining multiple validation conditions + +**Common Pitfalls:** +- Forgetting to anchor regex with ^ and $ +- Not handling empty string inputs +- Allowing spaces in username +``` + +**Balance:** Enough guidance to unstick students, not so much they don't think. + +### 6. Add Progressive Hints + +Create hints that reveal information gradually: + +**Hint Structure:** +- Hint 1: General approach or concept +- Hint 2: More specific technique +- Hint 3: Nearly complete solution approach + +**Example:** +``` +**Hints:** +1. Break the problem into three separate validation functions +2. Use Python's `re` module - import with `import re` +3. For password validation, you can use multiple regex patterns: + - `re.search(r'\d', password)` to check for digit + - `re.search(r'[!@#$%^&*]', password)` for special char +``` + +**Good Hints:** +- Guide thinking, don't solve the problem +- Progressive reveal (start general) +- Specific to common sticking points +- Teach concepts, not just answer + +### 7. Create Extension Challenges + +Add optional advanced problems: + +**Extension Characteristics:** +- Builds on basic exercise +- Requires creative thinking +- No hints provided +- Tests deeper mastery + +**Example Extensions:** +``` +**Extension Challenges:** + +**Challenge 1: Password Strength Meter** +Enhance the password validator to return a strength score (1-5) based on: +- Length (longer = stronger) +- Character variety (lowercase, uppercase, numbers, special chars) +- Common password detection + +**Challenge 2: Custom Validation Rules** +Allow configuration of validation rules via a config object: +```python +rules = { + "username": {"min": 3, "max": 20, "pattern": r"^[a-z0-9_]+$"}, + "password": {"min": 12, "require_special": True, "require_number": True} +} +validate_with_rules(data, rules) +``` +``` + +**Purpose:** Challenges extend learning for students who want more practice. + +### 8. Estimate Completion Time + +Provide realistic time estimates: + +**Factors:** +- Problem complexity +- Amount of code to write +- Testing and debugging time +- Student skill level + +**Basic Exercise:** 10-20 minutes +**Intermediate:** 20-40 minutes +**Advanced:** 40-90 minutes + +**Test Your Estimate:** +- Time yourself solving it +- Add 50-100% for students (you're expert) +- Test with actual students if possible + +**State in Exercise:** +``` +**Estimated Time:** 25 minutes + +This includes: +- Understanding requirements: 5 min +- Implementation: 15 min +- Testing: 5 min +``` + +### 9. Validate Exercises Are Solvable + +Quality check all exercises: + +**Self-Solve:** +- Solve each exercise yourself without looking at hints +- Note any ambiguities or unclear requirements +- Verify time estimate is reasonable +- Ensure you only use concepts from the chapter + +**Peer Review:** +- Have colleague attempt exercises +- Observe where they get stuck +- Note questions they ask +- Improve instructions based on feedback + +**Verification:** +- All test cases provided are correct +- Multiple valid solutions exist (usually) +- Success criteria are measurable +- Difficulty matches rating + +**Use:** exercise-difficulty-checklist.md + +### 10. Run Quality Checklist + +Final validation: + +**Execute:** exercise-difficulty-checklist.md + +**Check:** +- Progressive difficulty across exercises +- Each learning objective assessed +- Clear, unambiguous instructions +- Appropriate hints provided +- Time estimates realistic +- Exercises solvable with chapter knowledge +- No prerequisites beyond chapter scope + +## Output + +Exercise set should include: + +- 4-6 exercises with progressive difficulty +- Clear problem statements +- Test cases and success criteria +- Progressive hints +- Solution approaches +- Extension challenges +- Estimated completion times +- Self-assessment checklist + +**Use template:** exercise-set-tmpl.yaml + +## Quality Standards + +Effective exercise set: + +✓ Maps to chapter learning objectives +✓ Progressive difficulty (⭐ to ⭐⭐⭐) +✓ Clear, specific requirements +✓ Realistic time estimates +✓ Helpful hints without giving away answers +✓ Solvable with chapter knowledge +✓ Engaging and relevant problems +✓ Extension challenges for advanced learners + +## Common Pitfalls + +Avoid: + +❌ All exercises same difficulty +❌ Vague or ambiguous requirements +❌ Requiring knowledge beyond chapter +❌ Trivial exercises (too easy) +❌ Impossible exercises (too hard) +❌ No hints or scaffolding +❌ Unrealistic time estimates +❌ Boring or contrived problems + +## Next Steps + +After designing exercises: + +1. Include in chapter draft +2. Create solution code (for answer key) +3. Test with beta readers if possible +4. Iterate based on feedback +5. Update hints if students commonly stuck +6. Consider creating video solutions for complex exercises diff --git a/expansion-packs/bmad-technical-writing/tasks/develop-tutorial.md b/expansion-packs/bmad-technical-writing/tasks/develop-tutorial.md new file mode 100644 index 00000000..1c3fbd83 --- /dev/null +++ b/expansion-packs/bmad-technical-writing/tasks/develop-tutorial.md @@ -0,0 +1,366 @@ + + +# Develop Tutorial + +--- + +task: + id: develop-tutorial + name: Develop Tutorial + description: Create hands-on step-by-step tutorial with tested code, clear instructions, and troubleshooting + persona_default: tutorial-architect + inputs: + - tutorial-topic + - learning-objective + - difficulty-level + steps: + - Identify specific learning objective for tutorial + - Define prerequisite knowledge and setup requirements + - Design step-by-step progression (8-15 steps typical) + - Write clear, actionable instructions for each step + - Create and test code examples for each step + - Document expected outputs at each step + - Add troubleshooting section for common issues + - Test complete tutorial end-to-end + - Verify progressive difficulty and skill building + - Include summary and next steps + - Run execute-checklist.md with tutorial-effectiveness-checklist.md + - Use template tutorial-section-tmpl.yaml with create-doc.md + output: tutorials/{{tutorial-slug}}.md + +--- + +## Purpose + +Create effective hands-on tutorials that guide learners through building something concrete while learning key concepts. Great tutorials balance clear instruction with learning depth. + +## Prerequisites + +- Learning objective clearly defined +- Subject matter expertise in tutorial topic +- Testing environment available +- Access to learning-frameworks.md knowledge base + +## Workflow Steps + +### 1. Identify Learning Objective + +Define what students will accomplish: + +**Specific and Measurable:** +- "Build a REST API with authentication" (good) +- "Learn about APIs" (too vague) + +**Achievable Scope:** +- 30-45 minutes for basic tutorials +- 1-2 hours for intermediate +- 2-4 hours for advanced + +**Clear Success Criteria:** +- What will work at the end? +- What skills will be demonstrated? +- What can student verify? + +### 2. Define Prerequisites + +Be explicit about requirements: + +**Knowledge Prerequisites:** +- "Understanding of Python functions and classes" +- "Completed Tutorial 2: Flask Basics" +- "Familiarity with HTTP request/response cycle" + +**Software Requirements:** +- "Python 3.11+" +- "PostgreSQL 15+ running locally" +- "VS Code or similar editor" + +**Setup Steps:** +- "Clone starter repository" +- "Create virtual environment" +- "Install dependencies: `pip install -r requirements.txt`" + +**Time Estimates:** +- Setup time: 10 minutes +- Tutorial time: 45 minutes +- Total: ~1 hour + +### 3. Design Step-by-Step Progression + +Plan the tutorial flow (typically 8-15 steps): + +**Logical Progression:** +1. Setup and initialization +2. Core concept introduction +3. Basic implementation +4. Build on basics +5. Add complexity +6. Handle edge cases +7. Test/validate +8. Summary/reflection + +**Each Step Should:** +- Build on previous steps +- Accomplish one clear goal +- Be testable/verifiable +- Take 3-8 minutes + +**Progressive Difficulty:** +- Start simple (foundational) +- Add complexity gradually +- End with realistic scenario + +### 4. Write Clear Instructions + +Use consistent, actionable format: + +**Step Format:** +``` +**Step N: [Action-Oriented Title]** + +[Brief explanation of what this step accomplishes] + +**Instructions:** +1. [Specific action in imperative voice] +2. [Next action] +3. [Etc.] + +**Code:** +```language +[Complete code to add/modify] +``` + +**Expected Output:** +``` +[What student should see] +``` + +**Why This Matters:** +[Explain the concept or purpose] + +**Verification:** +[How to confirm this step worked] +``` + +**Imperative Voice:** +- "Create a new file..." (good) +- "You should create..." (wordy) +- "We'll create..." (okay but less direct) + +### 5. Create and Test Code Examples + +Develop working code for every step: + +**Code Quality:** +- Must run exactly as shown +- Include all necessary imports +- Show complete context +- Follow best practices +- Include comments explaining key lines + +**Testing:** +- Run every code example +- Verify outputs match documentation +- Test in fresh environment +- Check for missing dependencies +- Validate error messages + +**Incremental Development:** +- Each step adds to previous code +- Show only what changes (or full file if clearer) +- Maintain working state after each step +- Avoid breaking changes mid-tutorial + +**Use:** create-code-example.md and test-code-examples.md tasks + +### 6. Document Expected Outputs + +Show what success looks like: + +**After Key Steps:** +``` +After Step 3, running `python app.py` should display: + * Running on http://127.0.0.1:5000 + * Debug mode: on + +Visiting http://localhost:5000/health should return: +{"status": "healthy", "timestamp": "2024-01-15T10:30:00Z"} +``` + +**Screenshots (where helpful):** +- UI results +- Browser developer tools +- Database state +- Terminal output + +**File Structure:** +``` +After Step 5, your project should look like: +tutorial-app/ +├── app.py +├── models/ +│ └── user.py +├── routes/ +│ └── auth.py +└── tests/ + └── test_auth.py +``` + +### 7. Add Troubleshooting Section + +Anticipate and solve common problems: + +**For Each Common Issue:** + +**Problem:** [Error message or symptom] + +**Likely Cause:** [What usually causes this] + +**Diagnosis:** [How to check for this issue] + +**Fix:** [Step-by-step solution] + +**Verification:** [How to confirm it's fixed] + +**Example:** +``` +**Problem:** ImportError: No module named 'flask' + +**Cause:** Flask not installed or wrong Python environment + +**Diagnosis:** +1. Check virtual environment activated: `which python` +2. Check installed packages: `pip list | grep -i flask` + +**Fix:** +1. Activate virtual environment: `source venv/bin/activate` +2. Install Flask: `pip install flask` +3. Verify: `python -c "import flask; print(flask.__version__)"` + +**Verification:** Re-run your app - should start without import errors +``` + +**Include 3-5 most common issues** based on typical student mistakes. + +### 8. Test Tutorial End-to-End + +Validate the complete tutorial: + +**Fresh Environment Test:** +- Start with clean environment +- Follow your own instructions exactly +- Don't skip any steps +- Note any assumptions you made +- Time how long it actually takes + +**Someone Else Tests:** +- Have another person try the tutorial +- Watch for confusion points +- Note questions they ask +- Identify unclear instructions + +**Validation Questions:** +- Does every step work as described? +- Are outputs accurate? +- Is prerequisite list complete? +- Is difficulty appropriate? +- Does learning objective get achieved? + +**Use:** tutorial-effectiveness-checklist.md + +### 9. Verify Progressive Difficulty + +Ensure appropriate skill building: + +**Check Progression:** +- Early steps are simple and foundational +- Complexity increases gradually +- No sudden jumps in difficulty +- Builds on prior knowledge systematically + +**Cognitive Load:** +- Not too much new information at once +- One new concept per step when possible +- Reinforcement through repetition +- Clear explanations for complex topics + +**Scaffolding:** +- More guidance early +- Gradually reduce hand-holding +- Final steps require more independence +- Prepares for next-level tutorials + +### 10. Include Summary and Next Steps + +Conclude effectively: + +**What You Learned:** +- Recap key concepts covered +- Skills practiced in tutorial +- How this connects to broader topic + +**What You Built:** +- Concrete deliverable description +- How it demonstrates learning +- Real-world applications + +**Next Steps:** +- Related tutorials to try +- How to extend this project +- Resources for deeper learning + +**Extension Challenges (Optional):** +- "Add password reset functionality" +- "Implement email verification" +- "Add OAuth2 social login" + +## Output + +Complete tutorial should include: + +- Clear learning objective +- Explicit prerequisites +- 8-15 step-by-step instructions +- Tested, working code +- Expected outputs +- Troubleshooting guide +- Summary and next steps + +**Use template:** tutorial-section-tmpl.yaml + +## Quality Standards + +Effective tutorial: + +✓ Clear, specific learning objective +✓ Complete prerequisite list +✓ Actionable, numbered steps +✓ All code tested and works +✓ Expected outputs documented +✓ Troubleshooting for common issues +✓ Progressive difficulty +✓ Achievable in stated time +✓ Engaging and motivating + +## Common Pitfalls + +Avoid: + +❌ Skipping setup steps (assumes too much) +❌ Code that doesn't actually run +❌ Unclear or vague instructions +❌ Jumping difficulty too quickly +❌ No verification steps +❌ Missing expected outputs +❌ Untested tutorial (always test!) +❌ Too long (break into multiple tutorials) + +## Next Steps + +After creating tutorial: + +1. Include in relevant chapter +2. Add to tutorial repository +3. Test with target audience if possible +4. Gather feedback and iterate +5. Update based on common student questions diff --git a/expansion-packs/bmad-technical-writing/tasks/technical-review-chapter.md b/expansion-packs/bmad-technical-writing/tasks/technical-review-chapter.md new file mode 100644 index 00000000..251da76f --- /dev/null +++ b/expansion-packs/bmad-technical-writing/tasks/technical-review-chapter.md @@ -0,0 +1,309 @@ + + +# Technical Review Chapter + +--- + +task: + id: technical-review-chapter + name: Technical Review Chapter + description: Comprehensive technical accuracy review with fact-checking, code validation, security audit, and best practices assessment + persona_default: technical-reviewer + inputs: + - chapter-draft + - chapter-number + - subject-area-expertise + steps: + - Read chapter draft completely for overview + - Verify technical accuracy against official documentation + - Review all code examples for correctness and best practices + - Test code examples to ensure they run properly + - Check for security vulnerabilities in code + - Assess performance implications of recommendations + - Identify outdated information or deprecated features + - Note factual errors or misconceptions + - Compile findings into structured review report + - Assign severity levels to issues (Critical/Major/Minor) + - Provide constructive recommendations with sources + - Run execute-checklist.md with technical-accuracy-checklist.md + - Run execute-checklist.md with security-best-practices-checklist.md + - Run execute-checklist.md with performance-considerations-checklist.md + - Use template technical-review-report-tmpl.yaml with create-doc.md + output: reviews/technical-review-chapter-{{chapter_number}}.md + +--- + +## Purpose + +This task performs a rigorous technical review to ensure all content is accurate, current, secure, and follows best practices. Technical reviewers act as subject matter experts validating the chapter's technical correctness before publication. + +## Prerequisites + +- Chapter draft completed +- Access to official documentation for technologies covered +- Subject matter expertise in chapter topics +- Code testing environment available +- Access to technical-writing-standards.md knowledge base + +## Workflow Steps + +### 1. Read Chapter Draft Completely + +Get the full context before detailed review: + +- Read entire chapter without stopping to take notes +- Understand the learning objectives +- Note the target audience level +- Identify all technologies and concepts covered +- Get a sense of overall quality + +**Purpose:** Understand context before nitpicking details. + +### 2. Verify Technical Accuracy + +Check all technical claims against authoritative sources: + +**For Each Technical Claim:** +- Is this factually correct? +- Is it current (not outdated)? +- Can it be verified in official documentation? +- Are version numbers specified correctly? + +**Sources to Check:** +- Official language documentation (Python.org, MDN, etc.) +- Framework official docs +- RFCs and standards specifications +- API documentation +- Release notes + +**Document Issues:** +- Location (section, page, paragraph) +- Incorrect statement +- Correct information +- Source reference +- Severity (Critical if wrong, Minor if imprecise) + +**Use:** technical-accuracy-checklist.md + +### 3. Review Code Examples for Correctness + +Validate all code in the chapter: + +**For Each Code Example:** + +**Syntax and Logic:** +- Does the code have syntax errors? +- Will it run as shown? +- Does it produce the claimed results? +- Are there logic errors? + +**Completeness:** +- Are all imports shown? +- Are dependencies clear? +- Is setup code included or explained? +- Can a reader actually run this? + +**Accuracy:** +- Does the code use APIs correctly? +- Are parameters in the right order? +- Are return types correct? +- Is error handling appropriate? + +**Action:** Copy code to test environment and run it! + +### 4. Check Best Practices + +Assess whether code follows current best practices: + +**Code Quality:** +- Follows language style guides (PEP 8, ESLint, etc.) +- Uses meaningful variable names +- Includes appropriate comments +- Avoids deprecated features +- Handles errors properly + +**Design Patterns:** +- Uses appropriate patterns +- Avoids anti-patterns +- Demonstrates scalable approaches +- Shows proper separation of concerns + +**Modern Approaches:** +- Uses current language features +- Leverages modern libraries +- Follows framework conventions +- Demonstrates industry standards + +**Note:** Balance teaching clarity with production quality - sometimes simple is better for learning. + +### 5. Identify Security Concerns + +Review for security vulnerabilities: + +**Critical Issues:** +- Hardcoded credentials or API keys +- SQL injection vulnerabilities +- XSS (Cross-Site Scripting) risks +- Insecure authentication +- Missing input validation +- Unsafe deserialization + +**Best Practices:** +- HTTPS/TLS usage +- Password hashing (bcrypt, Argon2) +- JWT secret management +- API rate limiting +- Logging security events +- Principle of least privilege + +**For Each Security Issue:** +- Describe the vulnerability +- Explain potential impact +- Provide secure code example +- Reference security standard (OWASP, CWE) +- Mark severity (Critical for exploitable issues) + +**Use:** security-best-practices-checklist.md + +### 6. Assess Performance Implications + +Consider performance and scalability: + +**Inefficiencies:** +- O(n²) algorithms where O(n) is possible +- N+1 query problems +- Missing database indexes +- Unnecessary iterations or computations +- Memory leaks or excessive allocation + +**Scalability:** +- Will this approach scale to production? +- Are there resource constraints? +- Is caching appropriate? +- Are there blocking operations in async code? + +**Recommendations:** +- Better algorithms or data structures +- Optimization techniques +- Profiling suggestions +- When optimization matters vs premature optimization + +**Use:** performance-considerations-checklist.md + +### 7. Note Outdated Information + +Check currency of all technical content: + +**Deprecated Features:** +- Language features no longer recommended +- Framework APIs deprecated +- Tools superseded by newer alternatives + +**Version Issues:** +- Library versions outdated or EOL +- Examples using old syntax +- Missing modern alternatives + +**Update Recommendations:** +- Current best practices +- Modern equivalents +- Migration paths +- Version updates needed + +**Example:** "Using React class components; recommend hooks-based functional components (current standard since React 16.8)" + +### 8. Compile Findings into Review Report + +Create structured technical review report: + +**Use template:** technical-review-report-tmpl.yaml + +**Report Sections:** +- Executive summary (overall assessment) +- Technical accuracy findings +- Code quality issues +- Security concerns +- Performance considerations +- Best practices assessment +- Outdated information +- Positive findings (what worked well) +- Prioritized recommendations + +**Assign Severity:** +- **Critical:** Must fix (factual errors, security issues, broken code) +- **Major:** Should fix (best practice violations, performance issues) +- **Minor:** Nice to fix (style improvements, optimization suggestions) + +### 9. Provide Constructive Recommendations + +For each issue, provide actionable guidance: + +**Good Feedback Format:** +``` +Location: Section 2.3, page 12, code example +Issue: Using `collections.MutableMapping` which is deprecated +Severity: Major +Recommendation: Use `collections.abc.MutableMapping` instead (Python 3.3+) +Source: https://docs.python.org/3/library/collections.abc.html +Fixed Code: +from collections.abc import MutableMapping +class MyDict(MutableMapping): + ... +``` + +**Be Constructive:** +- Explain why it's wrong +- Show how to fix it +- Provide source reference +- Offer example code where helpful + +**Avoid:** +- Vague criticism ("this is bad") +- Nitpicking without explaining why +- Rewriting the entire chapter +- Focusing only on negatives + +### 10. Run Technical Checklists + +Validate against standard checklists: + +**Execute:** +- technical-accuracy-checklist.md +- security-best-practices-checklist.md +- performance-considerations-checklist.md + +**Document** any checklist items that fail. + +## Output + +Technical review report should include: + +- Clear severity ratings for all issues +- Specific locations for every finding +- Actionable recommendations with examples +- Source references for claims +- Overall assessment (Ready/Needs Revision/Major Rework) +- Estimated effort to address issues + +## Quality Standards + +Effective technical review: + +✓ Verifies every technical claim +✓ Tests all code examples +✓ Identifies security vulnerabilities +✓ Provides constructive feedback +✓ Includes source references +✓ Prioritizes issues by severity +✓ Offers concrete solutions +✓ Maintains respectful, professional tone + +## Next Steps + +After technical review: + +1. Deliver review report to author +2. Author addresses issues based on priority +3. Re-review critical fixes (optional) +4. Approve chapter to proceed to copy editing +5. May participate in final publication review diff --git a/expansion-packs/bmad-technical-writing/tasks/write-chapter-draft.md b/expansion-packs/bmad-technical-writing/tasks/write-chapter-draft.md new file mode 100644 index 00000000..5e5191bc --- /dev/null +++ b/expansion-packs/bmad-technical-writing/tasks/write-chapter-draft.md @@ -0,0 +1,355 @@ + + +# Write Chapter Draft + +--- + +task: + id: write-chapter-draft + name: Write Chapter Draft + description: Develop complete chapter manuscript from outline with introduction, main content, code examples, and exercises + persona_default: tutorial-architect + inputs: + - chapter-outline + - learning-objectives + - target-page-count + steps: + - Review chapter outline for structure and objectives + - Write compelling introduction (hook, context, overview, prerequisites) + - Draft main content sections (concept → tutorial → examples progression) + - Create and test all code examples inline + - Develop practice exercises with progressive difficulty + - Write chapter summary with key takeaways + - Add cross-references to other chapters and resources + - Include further reading references + - Verify all learning objectives are addressed + - Run execute-checklist.md with chapter-completeness-checklist.md + - Use template chapter-draft-tmpl.yaml with create-doc.md task + output: docs/chapters/chapter-{{chapter_number}}-draft.md + +--- + +## Purpose + +This task guides you through writing a complete chapter draft that transforms your chapter outline into full instructional content. The focus is on creating clear, engaging technical content that helps readers learn effectively. + +## Prerequisites + +Before starting this task: + +- Chapter outline completed and reviewed +- Learning objectives clearly defined +- Code examples planned and identified +- Access to technical-writing-standards.md knowledge base +- Understanding of target audience skill level + +## Workflow Steps + +### 1. Review Chapter Outline + +Understand the complete chapter structure: + +- Re-read the chapter outline carefully +- Review learning objectives +- Check prerequisite alignment +- Understand how this chapter fits in the book's progression +- Note all planned code examples and exercises + +**Validation:** Can you explain the chapter flow without looking at the outline? + +### 2. Write the Introduction + +Create a compelling chapter opening that hooks readers and sets expectations. + +**Introduction Components:** + +**Hook (1-2 paragraphs):** +- Start with a real-world problem or relatable scenario +- Make readers care about learning this content +- Use questions, stories, or surprising facts +- Connect to reader pain points or aspirations + +**Context (1-2 paragraphs):** +- Explain why this topic matters +- Industry relevance and use cases +- How it fits in the bigger technical picture +- Connection to previous chapters + +**Overview (1 paragraph):** +- What will be covered in this chapter +- High-level learning path +- What readers will build or accomplish + +**Prerequisites:** +- Previous chapters required +- Assumed knowledge +- Software/tools needed with versions +- Estimated time commitment + +**Learning Objectives:** +- 3-5 specific, measurable outcomes +- Use action verbs (implement, analyze, create, debug) +- Align with Bloom's taxonomy + +**Use template:** introduction-tmpl.yaml for structured guidance + +### 3. Draft Main Content Sections + +For each major section (typically 3-5 sections per chapter): + +**Section Structure Pattern:** + +**a) Concept Introduction** +- Explain the concept clearly and concisely +- Use analogies or real-world comparisons where helpful +- Define technical terms +- Provide theoretical background without overwhelming + +**b) Tutorial/Walkthrough** +- Step-by-step hands-on implementation +- Clear, numbered steps +- Imperative voice ("Create...", "Add...", "Run...") +- Expected output at each step +- Explain what each step accomplishes and why + +**c) Code Examples** +- Complete, runnable code (not fragments unless explained) +- Inline comments explaining key lines +- Best practices demonstrated +- Common mistakes highlighted and avoided +- Input/output examples showing expected results + +**d) Section Practice** +- Mini-exercises reinforcing section concepts +- Quick validation of understanding +- Progressive difficulty within section + +**Progression:** Move from foundational concepts to advanced topics within the chapter, building on what was just learned. + +**Use template:** tutorial-section-tmpl.yaml for hands-on sections + +### 4. Create Code Examples + +Develop all code examples referenced in the chapter: + +**Code Quality Standards:** +- All code must be tested and run successfully +- Follow language-specific style guides +- Include proper error handling +- Use meaningful variable names +- Add comments explaining complex logic +- Specify language version compatibility + +**Code Presentation:** +- Use proper syntax highlighting (specify language) +- Show complete context (imports, setup, etc.) +- Provide expected output or results +- Include error examples when teaching debugging +- Reference code files in repository structure + +**Best Practices:** +- Demonstrate current industry best practices +- Avoid deprecated or outdated approaches +- Show security-conscious coding +- Consider performance implications +- Follow DRY principles in examples + +**Use task:** create-code-example.md for each major example +**Reference:** code-quality-checklist.md and code-testing-checklist.md + +### 5. Add Practice Exercises + +Create 4-6 end-of-chapter exercises with progressive difficulty: + +**Basic Exercises (2-3):** +- Direct application of chapter concepts +- Provide clear guidance and hints +- Solutions or detailed hints included + +**Intermediate Exercises (1-2):** +- Require combining multiple concepts +- More independence required +- Hints provided, full solutions optional + +**Challenge Exercise (1):** +- Advanced application requiring creativity +- Minimal guidance +- Extension of chapter topics + +**For Each Exercise:** +- Clear problem statement +- Specific requirements +- Estimated completion time +- Difficulty indicator (⭐ ⭐⭐ ⭐⭐⭐) +- Hints provided progressively +- Solution approach (not full code) + +**Use template:** exercise-set-tmpl.yaml with create-doc.md + +**Reference:** exercise-difficulty-checklist.md + +### 6. Write Chapter Summary + +Conclude with effective summary (1-2 pages): + +**Key Takeaways:** +- Bullet list of main concepts covered +- Important terms and definitions +- Core skills acquired + +**What You Accomplished:** +- Concrete deliverables from this chapter +- Skills checklist readers can verify +- How this builds on previous learning + +**Looking Ahead:** +- Preview of next chapter +- How upcoming content will build on this foundation +- Why the next topic matters + +**Further Reading (Optional):** +- Official documentation links +- Recommended articles or resources +- Community resources +- Tools or libraries mentioned + +**Avoid:** Simply repeating content. Summarize and synthesize instead. + +### 7. Add Cross-References + +Link to related content throughout the chapter: + +**Internal References:** +- "See Chapter 2, Section 2.3 for database setup" +- "We'll explore advanced patterns in Chapter 8" +- "Review the glossary in Appendix A for term definitions" + +**External References:** +- Official documentation (with URLs) +- Standards or specifications (RFCs, PEPs, etc.) +- Relevant research papers or articles +- Community resources (forums, guides) + +**Best Practices:** +- Be specific with chapter and section numbers +- Test all URLs for validity +- Prefer stable, official sources +- Note if external content may change + +### 8. Include Further Reading + +Provide curated resources for deeper learning: + +**Official Sources:** +- Language documentation +- Framework guides +- API references +- Release notes for features used + +**Community Resources:** +- Well-regarded tutorials +- Video explanations +- Community forums or discussion +- GitHub repositories + +**Quality Over Quantity:** +- 5-8 truly helpful resources beats 20 mediocre ones +- Annotate each resource with what it provides +- Organize by topic or learning path + +### 9. Verify Learning Objectives Addressed + +Ensure all promised learning outcomes are covered: + +**For Each Learning Objective:** +- Where in the chapter is this taught? +- Are there examples demonstrating this skill? +- Can readers practice this skill in exercises? +- Is there clear evidence of skill achievement? + +**Self-Check:** +- Read each objective +- Find the section(s) teaching it +- Verify hands-on practice exists +- Confirm assessment opportunity (exercise/quiz) + +**If objective not adequately covered:** Add content or revise objective. + +### 10. Review Against Chapter Completeness Checklist + +Final quality check before review: + +**Run:** execute-checklist.md with chapter-completeness-checklist.md + +**Checklist Includes:** +- All sections from outline present +- Learning objectives fully addressed +- Code examples tested and working +- Exercises appropriate difficulty +- Cross-references valid +- Length appropriate (15-30 pages typical) +- Consistent terminology +- Voice and style consistent + +**Fix any issues found** before marking draft complete. + +## Output + +The completed chapter draft should be: + +- **Format:** Markdown (.md file) +- **Location:** docs/chapters/chapter-{{chapter_number}}-draft.md +- **Code Examples:** In separate repository folder with clear organization +- **Length:** Typically 15-30 pages (adjust based on topic complexity) +- **Status:** Ready for technical review + +## Quality Standards + +A high-quality chapter draft: + +✓ Hooks readers with compelling introduction +✓ Explains concepts clearly with helpful analogies +✓ Provides hands-on tutorials with clear steps +✓ Includes tested, working code examples +✓ Offers exercises at appropriate difficulty +✓ Summarizes key takeaways effectively +✓ Addresses all learning objectives +✓ Maintains consistent voice and style +✓ References sources appropriately +✓ Follows technical writing best practices + +## Common Pitfalls + +Avoid these common mistakes: + +❌ **Too much theory, not enough practice** - Balance concepts with hands-on work +❌ **Code examples that don't run** - Test everything before including +❌ **Unclear instructions** - Be specific; use numbered steps +❌ **Assuming too much knowledge** - State prerequisites explicitly +❌ **Inconsistent terminology** - Use terms consistently throughout +❌ **No connection between sections** - Add transitions and explain flow +❌ **Exercises too easy or too hard** - Progressive difficulty is key +❌ **Missing the "why"** - Always explain why things matter + +## Next Steps + +After completing the chapter draft: + +1. Save and commit draft to repository +2. Proceed to technical-review-chapter.md task +3. Technical reviewer will assess accuracy and quality +4. Revise based on technical review feedback +5. Proceed to copy-edit-chapter.md for editorial polish +6. Address copy edit feedback +7. Mark chapter complete and ready for publication review + +## Related Resources + +- Template: chapter-draft-tmpl.yaml +- Template: introduction-tmpl.yaml +- Template: tutorial-section-tmpl.yaml +- Template: exercise-set-tmpl.yaml +- Task: create-code-example.md +- Task: create-doc.md +- Checklist: chapter-completeness-checklist.md +- Knowledge Base: technical-writing-standards.md diff --git a/expansion-packs/bmad-technical-writing/templates/book-proposal-tmpl.yaml b/expansion-packs/bmad-technical-writing/templates/book-proposal-tmpl.yaml new file mode 100644 index 00000000..ffa21338 --- /dev/null +++ b/expansion-packs/bmad-technical-writing/templates/book-proposal-tmpl.yaml @@ -0,0 +1,222 @@ +# +--- +template: + id: book-proposal + name: Book Proposal + version: 1.0 + description: Complete publisher book proposal with market analysis, author credentials, and sample content + output: + format: markdown + filename: "book-proposal-{{book-title-slug}}.md" + +workflow: + elicitation: true + allow_skip: false +sections: + - id: overview + title: Book Overview + instruction: | + Book concept summary: + - Working title and subtitle + - One-sentence pitch (elevator pitch) + - Book type (tutorial, reference, cookbook, comprehensive guide) + - Estimated page count + - Estimated delivery timeline + - Unique selling proposition (what makes this book different) + elicit: true + - id: target_audience + title: Target Audience + instruction: | + Who will buy this book: + - Primary audience (job title, skill level, experience) + - Secondary audiences + - Reader demographics (students, professionals, hobbyists) + - Current skill level assumed (beginner, intermediate, advanced) + - Related roles or interests + + **Be specific:** "Mid-level Python developers (2-5 years experience) looking to transition into data science" is better than "Python developers" + + **Market size estimate:** + - Number of potential readers + - Growing or stable market + - Evidence of demand (forum activity, job postings, etc.) + elicit: true + - id: competitive_analysis + title: Competitive Analysis + instruction: | + Comparison with existing books: + + **For each major competitor (3-5 books):** + - Book title and author + - Publisher and year + - Amazon rank or sales estimate + - Strengths (what it does well) + - Weaknesses or gaps + - How your book differs/improves + + **Market gaps your book fills:** + - Topics not well covered by existing books + - Outdated approaches updated in your book + - Teaching style differences + - Technology versions (newer frameworks, languages) + + Publishers want to know: Why would someone buy YOUR book instead of competitors? + elicit: true + - id: author_bio + title: Author Bio and Credentials + instruction: | + Why you're qualified to write this book: + + **Professional Background:** + - Current role and company + - Years of experience with book topic + - Relevant projects or products built + - Speaking engagements or teaching experience + + **Writing Credentials:** + - Previous books or publications + - Blog, articles, or technical writing samples + - Social media following or platform + - Industry recognition or awards + + **Subject Matter Expertise:** + - Certifications relevant to topic + - Open source contributions + - Community involvement + - Unique perspective or experience + + Publishers care about your ability to write AND your credibility in the field. + - id: chapter_outline + title: Complete Chapter Outline + instruction: | + Full table of contents: + + **For each chapter (typically 10-15 chapters):** + - Chapter number and title + - 2-3 sentence chapter summary + - Key learning objectives (3-5 per chapter) + - Main topics covered (bullet list) + - Estimated page count + - Code examples or projects included + + **Group into parts/sections if applicable:** + - Part I: Foundations (Chapters 1-4) + - Part II: Intermediate Topics (Chapters 5-9) + - Part III: Advanced Applications (Chapters 10-12) + + **Appendices:** + - Appendix A: Installation Guide + - Appendix B: Reference Material + - etc. + + Show clear learning progression from chapter to chapter. + elicit: true + - id: sample_chapter + title: Sample Chapter + instruction: | + Reference to complete sample chapter: + - Which chapter you're providing (typically Chapter 1 or a middle chapter) + - Why this chapter represents the book well + - Attachment filename or location + + Example: + "Sample Chapter 3: 'Building Your First REST API' (included as separate file: chapter-03-sample.md). This chapter demonstrates the tutorial-driven approach used throughout the book, combining theory, hands-on coding, and real-world best practices." + + Note: Actual sample chapter content is usually a separate file referenced here. + - id: special_features + title: Special Features + instruction: | + What makes your book unique: + + **Pedagogical Approach:** + - Teaching methodology (project-based, tutorial-driven, etc.) + - Learning aids (exercises, quizzes, checkpoints) + - Code repository structure + + **Technical Features:** + - Live code examples + - Video tutorials or screencasts (if applicable) + - Companion website or resources + - Community forum or support + + **Production Elements:** + - Diagrams and illustrations plan + - Screenshots or UI examples + - Code highlighting requirements + - Color printing needs (if any) + - id: timeline + title: Timeline and Deliverables + instruction: | + Project schedule: + + **Milestones:** + - Outline finalization: [date] + - Sample chapters completion: [date] + - First draft complete: [date] + - Technical review completion: [date] + - Final manuscript delivery: [date] + + **Delivery Format:** + - File format (Markdown, Word, AsciiDoc, etc.) + - Code repository structure + - Image/diagram format + - Supplementary materials + + **Your Availability:** + - Hours per week dedicated to writing + - Any blackout periods (vacations, work commitments) + - Flexibility for revisions + + Be realistic - publishers prefer accurate timelines to optimistic ones. + - id: marketing + title: Marketing and Promotion + instruction: | + How you'll help promote the book: + + **Existing Platform:** + - Blog readers or newsletter subscribers (numbers) + - Social media following (Twitter, LinkedIn, YouTube) + - Conference speaking schedule + - Podcast appearances or media contacts + + **Promotional Plans:** + - Blog post series + - Webinars or online workshops + - Conference talks mentioning the book + - Community engagement (Reddit, Stack Overflow, forums) + - Corporate training opportunities + + **Professional Network:** + - Companies who might bulk purchase + - User groups or meetups you're involved with + - Influencers who might review or recommend + + Publishers value authors who actively promote their books. + - id: technical_requirements + title: Technical Requirements + instruction: | + Production considerations: + + **Software/Versions Covered:** + - Primary languages and versions (e.g., "Python 3.11+") + - Frameworks and libraries (e.g., "Django 4.2") + - Tools required (IDEs, databases, cloud services) + - Operating systems supported + + **Code Repository:** + - GitHub/GitLab organization + - Repo structure approach + - Code testing and CI plan + - License for code examples + + **Graphics/Visuals:** + - Estimated number of diagrams + - Screenshot requirements + - Technical illustration needs + - Color vs black and white + + **Special Needs:** + - Interactive elements + - Video content + - Downloadable datasets + - API keys or cloud resources needed for readers diff --git a/expansion-packs/bmad-technical-writing/templates/chapter-draft-tmpl.yaml b/expansion-packs/bmad-technical-writing/templates/chapter-draft-tmpl.yaml new file mode 100644 index 00000000..634d8796 --- /dev/null +++ b/expansion-packs/bmad-technical-writing/templates/chapter-draft-tmpl.yaml @@ -0,0 +1,161 @@ +# +--- +template: + id: chapter-draft + name: Chapter Draft + version: 1.0 + description: Complete chapter manuscript with introduction, main content, code examples, exercises, and summary + output: + format: markdown + filename: "chapter-{{chapter_number}}-draft.md" + +workflow: + elicitation: true + allow_skip: false +sections: + - id: header + title: Chapter Header + instruction: | + Chapter identification: + - Chapter number and title + - Learning objectives (3-5 measurable outcomes) + - Prerequisites (what readers need to know) + - Estimated reading time (e.g., "45-60 minutes") + - Tools/software required with version numbers + elicit: true + - id: introduction + title: Chapter Introduction + instruction: | + Opening section (2-4 paragraphs): + - Hook: Compelling real-world scenario or problem + - Context: Why this topic matters + - Overview: What will be covered in this chapter + - Preview: What readers will build or accomplish + - Motivation: Real-world applications and relevance + + The introduction should excite readers and set clear expectations. + elicit: true + - id: main_sections + title: Main Content Sections + instruction: | + For each major section (typically 3-5 sections per chapter): + + **Section Structure:** + 1. Concept Introduction + - Explain the concept clearly with analogies where helpful + - Define key terms and technical vocabulary + - Provide context and background + + 2. Tutorial/Walkthrough + - Step-by-step implementation + - Clear, numbered instructions + - Expected outputs at each step + - Screenshots or diagrams where helpful + + 3. Code Examples + - Complete, tested code examples + - Inline explanations with comments + - Best practices highlighted + - Common mistakes to avoid + + 4. Exercises + - Practice problems aligned with section objectives + - Progressive difficulty (basic to challenging) + - Hints and guidance provided + + Progress from foundational concepts to advanced topics within the chapter. + elicit: true + - id: code_examples + title: Code Examples + instruction: | + Integrated code examples throughout the chapter: + - Complete, runnable code (not fragments) + - Proper syntax highlighting language tags + - Comments explaining key lines + - Input/output examples showing expected results + - Error handling demonstrated + - Best practices followed + - Version compatibility noted (e.g., "Python 3.11+") + + Ensure all code has been tested and runs correctly. + elicit: true + - id: exercises_practice + title: Practice Exercises + instruction: | + End-of-chapter exercises (4-6 exercises): + + **Basic Exercises (2-3):** + - Reinforce fundamental concepts from chapter + - Provide step-by-step guidance + - Solutions or detailed hints included + + **Intermediate Exercises (1-2):** + - Require combining multiple concepts + - Less guidance, more independent problem-solving + - Hints provided, full solutions optional + + **Challenge Exercise (1):** + - Advanced application of chapter concepts + - Minimal guidance + - Extension of topics for deeper learning + + Each exercise should include: + - Clear instructions + - Estimated completion time + - Difficulty level indicator + - Learning objective addressed + elicit: true + - id: summary + title: Chapter Summary + instruction: | + Concluding section (1-2 pages): + + **Key Takeaways:** + - Bullet list of main concepts covered + - Skills acquired checklist + - Important terms and definitions + + **What You Accomplished:** + - Concrete deliverables or knowledge gained + - How this builds on previous chapters + + **Looking Ahead:** + - Preview of next chapter topics + - How upcoming content builds on this foundation + + **Further Reading (optional):** + - Official documentation links + - Recommended articles or resources + - Community resources or tools + - id: code_repository + title: Code Repository References + instruction: | + Code file organization: + - List all code files for this chapter + - Repository structure and location + - How to run/test the code + - Dependencies and installation instructions + - Expected directory structure + + Example: + ``` + chapter-03/ + ├── examples/ + │ ├── basic-auth.py + │ └── jwt-implementation.py + ├── exercises/ + │ ├── exercise-01-solution.py + │ └── exercise-02-starter.py + └── tests/ + └── test_auth.py + ``` + - id: cross_references + title: Cross-References + instruction: | + Internal and external references: + - Links to related chapters (e.g., "See Chapter 2, Section 2.3") + - External documentation references + - Related topics for further exploration + - Prerequisites review links + + Ensure cross-references are specific (chapter, section, page number where possible). diff --git a/expansion-packs/bmad-technical-writing/templates/exercise-set-tmpl.yaml b/expansion-packs/bmad-technical-writing/templates/exercise-set-tmpl.yaml new file mode 100644 index 00000000..46a1484b --- /dev/null +++ b/expansion-packs/bmad-technical-writing/templates/exercise-set-tmpl.yaml @@ -0,0 +1,156 @@ +# +--- +template: + id: exercise-set + name: Exercise Set + version: 1.0 + description: Structured practice exercises with progressive difficulty, hints, and solution approaches + output: + format: markdown + filename: "exercises-{{chapter_number}}.md" + +workflow: + elicitation: false + allow_skip: false +sections: + - id: metadata + title: Exercise Set Metadata + instruction: | + Exercise set information: + - Chapter number and title + - Overall difficulty range (e.g., "Beginner to Intermediate") + - Total estimated completion time + - Number of exercises (typically 4-6) + - Learning objectives assessed + - id: prerequisites + title: Prerequisites and Setup + instruction: | + Required before starting exercises: + - Chapter sections that must be read + - Code setup or environment needed + - Files or resources to download + - Starter code repository (if applicable) + + Example: + "Complete Chapter 3 Sections 1-4. Clone starter code: `git clone https://github.com/book/chapter-03-exercises`" + - id: exercises + title: Exercises + instruction: | + Create 4-6 exercises with progressive difficulty: + + **For Each Exercise, Include:** + + **Exercise Header:** + - Exercise number and title + - Difficulty: ⭐ (Basic), ⭐⭐ (Intermediate), ⭐⭐⭐ (Advanced) + - Estimated time + - Learning objective addressed + + **Problem Description:** + - Clear statement of what to build/solve + - Specific requirements (numbered list) + - Input/output examples + - Success criteria + + **Hints Section:** + - 2-4 progressive hints (start general, get more specific) + - Hints reveal approach, not complete solution + - Example: "Hint 1: Consider using a dictionary to track counts" + + **Solution Approach:** + - High-level algorithm or strategy + - Key concepts to apply + - Common pitfalls to avoid + - Not full code solution (encourages independent work) + + **Extension (optional for advanced exercises):** + - Ways to enhance the solution + - Additional challenges to try + + --- + **EXERCISE FORMAT EXAMPLE:** + + ### Exercise 1: User Input Validation ⭐ + **Estimated Time:** 15 minutes + **Learning Objective:** Apply regex patterns for input validation + + **Problem:** + Create a function `validate_email(email: str) -> bool` that validates email addresses according to these rules: + 1. Must contain exactly one @ symbol + 2. Local part (before @) must be 1-64 characters + 3. Domain part must contain at least one period + 4. Domain must end with 2-6 letter TLD + + **Test Cases:** + ```python + validate_email("user@example.com") # True + validate_email("invalid.email") # False + validate_email("no@domain") # False + ``` + + **Hints:** + 1. Consider using Python's `re` module for regex matching + 2. Break the problem into parts: check @, then validate each side + 3. The pattern `^[a-zA-Z0-9._-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,6}$` covers most cases + + **Solution Approach:** + - Import `re` module + - Define regex pattern matching email format + - Use `re.match()` or `re.fullmatch()` to test the input + - Return True if match found, False otherwise + + **Common Pitfalls:** + - Forgetting to anchor regex with ^ and $ + - Not escaping special regex characters like `.` + - Accepting emails with multiple @ symbols + + --- + + **Difficulty Progression:** + - Exercises 1-2: Basic (⭐) - Direct application of chapter concepts + - Exercises 3-4: Intermediate (⭐⭐) - Combine multiple concepts + - Exercise 5: Advanced (⭐⭐⭐) - Creative problem-solving, minimal guidance + - id: self_assessment + title: Self-Assessment Checklist + instruction: | + Students verify their learning: + + **After completing all exercises, you should be able to:** + - [ ] Skill 1 demonstrated in exercises + - [ ] Skill 2 demonstrated in exercises + - [ ] Skill 3 demonstrated in exercises + - [ ] Concept 1 applied independently + - [ ] Concept 2 combined with other concepts + + If you struggled with any exercises, review: + - Exercise 1-2 issues → Review Section 3.1 (topic reference) + - Exercise 3-4 issues → Review Section 3.3 (topic reference) + - Exercise 5 issues → Consider reviewing entire chapter + + This helps students identify knowledge gaps. + - id: solutions_note + title: Solutions Note + instruction: | + How to access full solutions: + - Solutions location (e.g., "Appendix A", "GitHub repository /solutions folder") + - When to consult solutions (after attempting, not before) + - Multiple solution approaches may exist + + Example: + "Full solution code is available in the `solutions/chapter-03/` directory. Try solving independently first, then compare your approach. Remember: different solutions can be equally valid!" + - id: extensions + title: Extension Challenges + instruction: | + Optional advanced challenges for deeper learning: + + **Challenge 1:** [Title] + - Description of more complex problem + - Builds on exercise concepts + - Estimated time: [duration] + - No hints provided (fully independent) + + **Challenge 2:** [Title] + - Another advanced application + - May combine topics from multiple chapters + + These are for students who want extra practice or deeper mastery. diff --git a/expansion-packs/bmad-technical-writing/templates/introduction-tmpl.yaml b/expansion-packs/bmad-technical-writing/templates/introduction-tmpl.yaml new file mode 100644 index 00000000..b1bb0cf4 --- /dev/null +++ b/expansion-packs/bmad-technical-writing/templates/introduction-tmpl.yaml @@ -0,0 +1,140 @@ +# +--- +template: + id: introduction + name: Chapter Introduction + version: 1.0 + description: Compelling chapter introduction that hooks readers and sets clear expectations + output: + format: markdown + filename: "chapter-{{chapter_number}}-introduction.md" + +workflow: + elicitation: false + allow_skip: false +sections: + - id: hook + title: Opening Hook + instruction: | + Compelling opening (1-2 paragraphs): + - Real-world scenario or problem + - Relatable pain point or challenge + - Intriguing question or statement + - Story or anecdote + + **Purpose:** Grab reader attention immediately and make them want to keep reading. + + **Examples:** + - "Have you ever deployed code to production only to watch your application crash under real user load? You're not alone..." + - "In 2023, a misconfigured authentication system exposed 100 million user records. This chapter teaches you how to avoid becoming the next headline..." + - "What if you could reduce your API response time from 2 seconds to 200 milliseconds? In this chapter, you'll learn exactly how..." + + The hook should connect to reader pain points or aspirations. + - id: context + title: Context and Importance + instruction: | + Why this chapter matters (1-2 paragraphs): + - Industry relevance + - Common use cases + - Skills gap this addresses + - How it fits in the bigger picture + - Connection to previous chapters + + Help readers understand the "why" before diving into the "how". + + Example: + "Authentication is the foundation of application security. According to OWASP, broken authentication is consistently one of the top 10 security risks. Yet many developers rely on outdated or insecure patterns. This chapter introduces modern authentication using JWTs and OAuth2, the current industry standard for securing APIs." + - id: overview + title: Chapter Overview + instruction: | + What this chapter covers (3-5 sentences): + - Main topics in order + - High-level learning path + - Key concepts introduced + - Practical outcomes + + Give readers a roadmap without overwhelming detail. + + Example: + "This chapter begins with authentication fundamentals, then walks you through implementing JWT-based authentication in a Flask API. You'll create user registration and login endpoints, secure routes with token validation, and implement refresh token rotation. By the end, you'll have a production-ready authentication system." + - id: learning_objectives + title: Learning Objectives + instruction: | + What you'll be able to do (4-6 objectives): + - Use action verbs (implement, analyze, create, design, debug) + - Be specific and measurable + - Align with Bloom's taxonomy + - Focus on skills, not just knowledge + + Format as bullet list starting with "By the end of this chapter, you will be able to:" + + **Examples:** + - Implement JWT authentication in a REST API + - Validate and decode JWT tokens securely + - Design a refresh token rotation strategy + - Identify and prevent common authentication vulnerabilities + - Create middleware for protecting API routes + - Test authentication flows with integration tests + + These set clear expectations for what readers will achieve. + - id: prerequisites + title: Prerequisites + instruction: | + What readers need to know (bullet list): + - Previous chapters to complete + - Assumed knowledge or skills + - Software versions required + - Estimated time for chapter completion + + **Examples:** + - Completion of Chapter 3: Building REST APIs + - Basic understanding of HTTP headers and status codes + - Python 3.11+ installed + - PostgreSQL 15+ running (or Docker installed) + - Estimated reading time: 45-60 minutes + - Hands-on exercises: 2-3 hours + + Be honest about prerequisites - frustration from missing knowledge hurts learning. + - id: what_youll_build + title: What You'll Build + instruction: | + Concrete deliverable or outcome (1-2 paragraphs): + - Specific project, feature, or system + - End state description + - Practical application + - Connection to real-world usage + + Make the outcome tangible and motivating. + + Example: + "In this chapter's tutorial, you'll build a complete user authentication system for a task management API. The system includes user registration with password hashing, secure login with JWT tokens, protected routes accessible only to authenticated users, and automatic token refresh for seamless user experience. By the chapter's end, you'll have a working authentication system you can adapt for your own projects." + - id: time_estimate + title: Time Estimate + instruction: | + How long this chapter takes: + - Reading time: [minutes] + - Tutorial/hands-on time: [hours] + - Exercise completion time: [hours] + - Total time commitment: [hours] + + Break down time investment so readers can plan accordingly. + - id: section_roadmap + title: Section Roadmap + instruction: | + Chapter structure preview (bullet list of main sections): + - Section 1: [Title] - Brief 1-sentence description + - Section 2: [Title] - Brief 1-sentence description + - Section 3: [Title] - Brief 1-sentence description + - ... + + Show the logical flow through the chapter. + + Example: + - **Section 1: Authentication Fundamentals** - Core concepts of authentication, authorization, and session management + - **Section 2: JWT Architecture** - How JSON Web Tokens work and why they're used for API authentication + - **Section 3: Building Registration and Login** - Implementing user registration with secure password hashing + - **Section 4: Protecting Routes** - Creating authentication middleware and securing API endpoints + - **Section 5: Refresh Tokens** - Implementing token refresh for improved security and user experience + - **Section 6: Testing Authentication** - Writing tests to validate your authentication system + + This gives readers a mental model before diving in. diff --git a/expansion-packs/bmad-technical-writing/templates/technical-review-report-tmpl.yaml b/expansion-packs/bmad-technical-writing/templates/technical-review-report-tmpl.yaml new file mode 100644 index 00000000..2d1ac50b --- /dev/null +++ b/expansion-packs/bmad-technical-writing/templates/technical-review-report-tmpl.yaml @@ -0,0 +1,217 @@ +# +--- +template: + id: technical-review-report + name: Technical Review Report + version: 1.0 + description: Comprehensive technical review findings with accuracy, security, performance, and best practices assessment + output: + format: markdown + filename: "technical-review-{{chapter_number}}-{{date}}.md" + +workflow: + elicitation: false + allow_skip: false +sections: + - id: metadata + title: Review Metadata + instruction: | + Document review information: + - Chapter number and title reviewed + - Reviewer name and expertise area + - Review date + - Chapter version/draft number reviewed + - Review scope (full chapter, code only, specific sections) + - id: executive_summary + title: Executive Summary + instruction: | + High-level overview: + - Overall technical quality assessment (Excellent/Good/Needs Work/Major Issues) + - Critical issues count (must-fix before publication) + - Major issues count (should fix, impacts quality) + - Minor issues count (nice-to-fix, improvements) + - Recommendation: Ready for publication / Needs revision / Requires major rework + - id: technical_accuracy + title: Technical Accuracy Findings + instruction: | + Fact-checking and correctness: + + **Issues Found:** + For each inaccuracy: + - Location (section, page, line) + - Issue description + - Severity (Critical/Major/Minor) + - Correct information with source reference + - Recommended fix + + **Examples:** + - "Section 2.3, page 12: States Python 3.8 supports match/case. Actually introduced in 3.10. Source: PEP 634" + - "Code example line 45: Using deprecated 'collections.MutableMapping'. Should use 'collections.abc.MutableMapping' per Python 3.3+ docs" + + **Verified Correct:** + - List sections that passed accuracy checks + - Note particularly well-researched or documented areas + - id: code_quality + title: Code Quality Issues + instruction: | + Code example review: + + **Bugs and Errors:** + - Syntax errors or code that won't run + - Logic errors that produce wrong results + - Missing imports or dependencies + - Incorrect API usage + + **Best Practices Violations:** + - Code style issues (PEP 8, ESLint, etc.) + - Inefficient algorithms or approaches + - Missing error handling + - Hard-coded values that should be configurable + - Poor naming conventions + + **Code Organization:** + - Unclear or missing comments + - Inconsistent formatting + - Complex code needing simplification + - Missing type hints (if language supports) + + For each issue, provide: + - Location (file, line number) + - Current code snippet + - Issue description + - Recommended fix with code example + - id: security_concerns + title: Security Concerns + instruction: | + Security review findings: + + **Critical Security Issues:** + - Credentials or secrets in code + - SQL injection vulnerabilities + - XSS vulnerabilities + - Insecure authentication/authorization + - Unsafe deserialization + - Missing input validation + + **Security Best Practices:** + - Use of deprecated crypto functions + - Weak password hashing + - Missing HTTPS/TLS + - Insufficient logging of security events + - Overly permissive access controls + + For each finding: + - Location + - Vulnerability description + - Potential impact (data breach, code execution, etc.) + - Secure code example + - Reference to security standard (OWASP, CWE) + - id: performance_considerations + title: Performance Considerations + instruction: | + Performance analysis: + + **Performance Issues:** + - Inefficient algorithms (O(n²) where O(n) possible) + - Unnecessary database queries (N+1 problem) + - Missing indexes or caching + - Memory leaks or excessive allocation + - Blocking operations in async code + + **Scalability Concerns:** + - Approaches that won't scale + - Resource intensive operations + - Missing pagination or limits + + **Recommendations:** + - Optimizations to suggest + - Better algorithms or data structures + - Caching strategies + - Profiling recommendations + + Note: Balance between teaching clarity and production optimization. + - id: best_practices_assessment + title: Best Practices Assessment + instruction: | + Industry standards compliance: + + **Design Patterns:** + - Appropriate use of patterns + - Anti-patterns to avoid + - Better architectural approaches + + **Testing:** + - Test coverage adequacy + - Missing test cases + - Testing best practices + + **Documentation:** + - Code comments quality + - Docstring completeness + - API documentation + + **Dependencies:** + - Outdated packages + - Unnecessary dependencies + - Version compatibility issues + - id: outdated_information + title: Outdated Information + instruction: | + Currency check: + + **Deprecated Features:** + - Language features deprecated + - Library versions outdated + - APIs no longer recommended + + **Current Recommendations:** + - Modern alternatives to suggest + - Migration paths to mention + - Version updates needed + + **Examples:** + - "Using React class components; recommend functional components with hooks (current best practice since 2019)" + - "References Node.js 12; now EOL. Update examples to Node.js 18 LTS or 20 LTS" + - id: positive_findings + title: Positive Findings + instruction: | + What worked well: + - Particularly clear explanations + - Excellent code examples + - Well-designed tutorials + - Good use of diagrams + - Effective learning progression + - Strong practical applications + + Recognizing strengths helps maintain quality in revisions. + - id: recommendations + title: Recommended Actions + instruction: | + Prioritized fix list: + + **Must Fix (Critical):** + 1. [Issue with location and brief description] + 2. ... + + **Should Fix (Major):** + 1. [Issue with location and brief description] + 2. ... + + **Nice to Fix (Minor):** + 1. [Issue with location and brief description] + 2. ... + + **Overall Recommendation:** + - Ready to proceed? Yes/No + - Estimated effort to address issues (hours/days) + - Suggest re-review after fixes? Yes/No + - id: references + title: References Checked + instruction: | + Documentation and sources verified: + - Official documentation URLs + - Standards referenced (RFCs, PEPs, etc.) + - Third-party libraries checked + - Community best practices sources + + This provides traceability for technical claims. diff --git a/expansion-packs/bmad-technical-writing/templates/tutorial-section-tmpl.yaml b/expansion-packs/bmad-technical-writing/templates/tutorial-section-tmpl.yaml new file mode 100644 index 00000000..cae753c9 --- /dev/null +++ b/expansion-packs/bmad-technical-writing/templates/tutorial-section-tmpl.yaml @@ -0,0 +1,200 @@ +# +--- +template: + id: tutorial-section + name: Tutorial Section + version: 1.0 + description: Step-by-step hands-on tutorial with clear instructions, expected outputs, and troubleshooting + output: + format: markdown + filename: "tutorial-{{topic-slug}}.md" + +workflow: + elicitation: true + allow_skip: false +sections: + - id: metadata + title: Tutorial Metadata + instruction: | + Tutorial identification: + - Tutorial title (clear, action-oriented) + - Primary learning objective (what will student accomplish) + - Difficulty level (beginner/intermediate/advanced) + - Estimated completion time (e.g., "30-45 minutes") + - Related chapter or section reference + elicit: true + - id: prerequisites + title: Prerequisites + instruction: | + What students need before starting: + - Prior knowledge required (specific concepts or skills) + - Previous tutorials that must be completed + - Software/tools needed with version numbers + - Environment setup required + - Estimated setup time + - Links to installation guides if needed + + Be specific and verifiable. Example: + - "Python 3.11 or higher installed" + - "Completed Tutorial 2: Basic Flask Routes" + - "PostgreSQL 15+ running locally" + elicit: true + - id: overview + title: Tutorial Overview + instruction: | + What this tutorial teaches (2-3 paragraphs): + - Real-world problem or use case + - What students will build or accomplish + - Key concepts demonstrated + - Why this approach is valuable + + Set clear expectations for outcomes. + - id: step_by_step + title: Step-by-Step Instructions + instruction: | + Numbered steps for tutorial (typically 8-15 steps): + + For each step: + 1. Clear, actionable instruction (imperative voice: "Create...", "Add...", "Run...") + 2. Code to write or command to execute + 3. Expected output or result + 4. Explanation of what the step accomplishes + 5. Why this step matters + + **Step Format Example:** + --- + **Step 3: Create the Database Model** + + Create a new file `models/user.py` and add the following: + + ```python + from sqlalchemy import Column, Integer, String + from database import Base + + class User(Base): + __tablename__ = 'users' + id = Column(Integer, primary_key=True) + username = Column(String(80), unique=True, nullable=False) + email = Column(String(120), unique=True, nullable=False) + ``` + + **What this does:** Defines a User model with SQLAlchemy ORM, creating a database table with columns for id, username, and email. + + **Why it matters:** ORM models provide type-safe database access and automatic query generation, reducing SQL injection risks. + + **Expected outcome:** File created with no errors. You can verify by running `python -c "from models.user import User; print('Success')"`. + --- + + Maintain consistent formatting and depth of explanation throughout. + elicit: true + - id: expected_outputs + title: Expected Outputs + instruction: | + What students should see at key milestones: + - Terminal/console outputs + - Screenshots of UI results + - File structures created + - Test results + - Database states + + Include both successful outputs and common intermediate states. + + Example: + ``` + After Step 5, running `flask run` should display: + * Running on http://127.0.0.1:5000 + * Debug mode: on + + After Step 8, visiting http://localhost:5000/users should show: + { + "users": [], + "count": 0 + } + ``` + - id: troubleshooting + title: Common Issues and Troubleshooting + instruction: | + Problems students might encounter: + + **For each common issue:** + - Error message or symptom + - Likely cause + - How to diagnose + - Step-by-step fix + - How to verify it's resolved + + **Example:** + --- + **Issue:** `ModuleNotFoundError: No module named 'flask'` + + **Cause:** Flask not installed in current Python environment + + **Fix:** + 1. Check virtual environment is activated: `which python` should show venv path + 2. Install Flask: `pip install flask` + 3. Verify: `pip list | grep -i flask` should show Flask version + + **Verification:** Re-run `flask run` - should start successfully + --- + + Include 3-5 most common issues based on student experience level. + - id: verification + title: Completion Verification + instruction: | + How to verify tutorial success: + - Final code execution command + - Expected final output + - Tests to run + - Functionality checklist + + Example: + ``` + ✓ Run `python tests/test_user.py` - all tests pass + ✓ Visit http://localhost:5000/users - returns JSON + ✓ Create user via POST request - receives 201 status + ✓ Database contains user record - verify with SQL query + ``` + + Students should be confident they completed correctly. + - id: summary + title: What You Learned + instruction: | + Reinforce learning outcomes: + - Key concepts demonstrated in this tutorial + - Skills practiced + - Patterns or techniques learned + - Real-world applications + + Connect back to learning objectives stated in metadata. + - id: next_steps + title: Next Steps and Extensions + instruction: | + How to build on this tutorial: + + **Immediate Next Steps:** + - Next tutorial in sequence (if applicable) + - Related concepts to explore + + **Extension Challenges (optional):** + - Enhancements to try independently + - Additional features to implement + - Performance optimizations to explore + - Security hardening to add + + Examples: + - "Add password hashing using bcrypt" + - "Implement user registration endpoint" + - "Add input validation with Pydantic" + - "Write integration tests for the full API" + + Extension challenges reinforce learning through application. + - id: resources + title: Additional Resources + instruction: | + Further learning materials: + - Official documentation links + - Relevant tutorials or guides + - Community resources + - Tools mentioned in tutorial + + Keep focused - only include truly helpful resources. diff --git a/expansion-packs/bmad-technical-writing/workflows/chapter-development-workflow.yaml b/expansion-packs/bmad-technical-writing/workflows/chapter-development-workflow.yaml new file mode 100644 index 00000000..c021d593 --- /dev/null +++ b/expansion-packs/bmad-technical-writing/workflows/chapter-development-workflow.yaml @@ -0,0 +1,152 @@ +workflow: + id: chapter-development-workflow + name: Write and Refine Chapter + description: Complete chapter creation workflow from outline to publisher-ready manuscript. Guides technical authors through planning, drafting, code development, technical review, and editorial polish. Emphasizes learning objectives, hands-on tutorials, tested code examples, and professional quality standards. + type: chapter-writing + project_types: + - technical-book + - tutorial-series + - training-materials + - technical-documentation + sequence: + - agent: tutorial-architect + creates: chapter-outline.md + requires: book-outline.md + notes: "Create detailed chapter outline using *create-chapter-outline command. Define learning objectives, prerequisites, main sections, exercises, and code examples needed. SAVE OUTPUT: Copy final chapter-outline.md to docs/outlines/chapter-{{chapter_number}}-outline.md" + + - agent: code-curator + creates: code-examples/ + requires: chapter-outline.md + notes: "Develop and test all code examples identified in outline. Use *create-example for each example. Ensure all code runs correctly, follows best practices, and includes proper error handling. SAVE OUTPUT: Commit code to repository in chapter-{{chapter_number}}/ folder with tests." + + - agent: tutorial-architect + creates: chapter-draft.md + requires: + - chapter-outline.md + - code-examples/ + notes: "Write complete chapter draft using write-chapter-draft task. Include introduction, main content sections with tutorials, code examples inline, practice exercises, and summary. Ensure all learning objectives addressed. SAVE OUTPUT: Copy final draft to docs/chapters/chapter-{{chapter_number}}-draft.md" + + - agent: technical-reviewer + creates: technical-review-report.md + requires: chapter-draft.md + notes: "Perform comprehensive technical review using *review-chapter command. Verify technical accuracy, test all code, check security best practices, assess performance. Use technical-accuracy-checklist, security-best-practices-checklist, and performance-considerations-checklist. SAVE OUTPUT: Copy review report to reviews/technical-review-chapter-{{chapter_number}}.md" + + - agent: tutorial-architect + updates: chapter-draft.md + requires: technical-review-report.md + notes: "Revise chapter based on technical review feedback. Address all Critical issues and Major issues. Update code examples if needed. Test revised code. Mark story status as 'Revision-Technical' during this phase. SAVE OUTPUT: Update chapter-draft.md with revisions." + + - agent: technical-editor + updates: chapter-draft.md + requires: revised-chapter-draft.md + notes: "Perform professional copy edit using *edit-chapter command. Improve clarity, check consistency, enhance transitions, verify publisher style compliance, review accessibility. Use accessibility-checklist and publisher-specific checklist. SAVE OUTPUT: Return edited chapter with change summary." + + - agent: tutorial-architect + finalizes: chapter-final.md + requires: edited-chapter.md + notes: "Review and approve editorial changes. Ensure technical accuracy preserved during editing. Create final chapter version. Mark chapter status as 'Ready for Publication'. SAVE OUTPUT: Copy final chapter to docs/chapters/chapter-{{chapter_number}}-final.md" + + flow_diagram: | + ```mermaid + graph TD + A[Start: New Chapter] --> B[tutorial-architect: Create Outline] + B --> C[code-curator: Develop Code Examples] + C --> D[tutorial-architect: Write Chapter Draft] + D --> E[technical-reviewer: Technical Review] + E --> F{Critical/Major Issues?} + F -->|Yes| G[tutorial-architect: Revise Chapter] + F -->|No| H[technical-editor: Copy Edit] + G --> I[code-curator: Update Code if Needed] + I --> E + H --> J[tutorial-architect: Review Edits] + J --> K{Approve Edits?} + K -->|Yes| L[Finalize Chapter] + K -->|No| M[Discuss with Editor] + M --> H + L --> N[Chapter Ready for Publication] + + B -.-> B1[Optional: *create-learning-objectives] + C -.-> C1[Optional: *test-code] + E -.-> E1[Optional: *security-audit] + E -.-> E2[Optional: *verify-accuracy] + + style N fill:#90EE90 + style B fill:#FFE4B5 + style C fill:#FFE4B5 + style D fill:#FFE4B5 + style E fill:#ADD8E6 + style H fill:#ADD8E6 + style L fill:#F0E68C + ``` + + decision_guidance: + when_to_use: + - Writing technical book chapters with code examples + - Creating tutorial-based training materials + - Developing programming books or guides + - Need for technical accuracy and professional polish + - Multiple review stages required + - Publisher quality standards must be met + + when_not_to_use: + - Simple blog posts or articles (use simplified workflow) + - Reference documentation only (no tutorials) + - Quick drafts without review requirements + + quality_gates: + outline_complete: + - Learning objectives defined (3-5) + - Prerequisites clearly stated + - All code examples identified + - Exercise plan created + - Checklist: prerequisite-clarity-checklist.md + + draft_complete: + - All sections from outline present + - Code examples inline and explained + - Exercises included with hints + - Learning objectives addressed + - Checklist: chapter-completeness-checklist.md + + technical_review_passed: + - No critical technical errors + - All code tested and working + - Security best practices followed + - No outdated information + - Checklists: technical-accuracy, security-best-practices, performance-considerations + + editorial_complete: + - Grammar and spelling clean + - Terminology consistent + - Publisher style followed + - Accessibility requirements met + - Checklists: accessibility-checklist, publisher-specific checklist + + handoff_prompts: + architect_to_curator: "Chapter outline complete with {{code_count}} code examples identified. Save outline to docs/outlines/, then develop and test all code examples." + curator_to_architect: "All code examples developed and tested in chapter-{{chapter_number}}/ folder. Tests passing. Ready for chapter draft writing." + architect_to_reviewer: "Chapter draft complete at docs/chapters/chapter-{{chapter_number}}-draft.md. All {{objective_count}} learning objectives addressed. Ready for technical review." + reviewer_to_architect: "Technical review complete. Found {{critical_count}} critical, {{major_count}} major, and {{minor_count}} minor issues. Review report at reviews/technical-review-chapter-{{chapter_number}}.md. Please address and revise." + revised_to_editor: "Technical review issues addressed. Revised chapter ready for copy editing." + editor_to_architect: "Copy editing complete. Made improvements to clarity, consistency, and style. Change summary attached. Please review and approve." + architect_final: "Editorial changes approved. Chapter finalized at docs/chapters/chapter-{{chapter_number}}-final.md. Status: Ready for Publication." + + time_estimates: + create_outline: "2-4 hours" + develop_code: "4-8 hours (depending on complexity)" + write_draft: "12-20 hours (15-30 page chapter)" + technical_review: "3-5 hours" + revision: "4-8 hours" + copy_edit: "2-4 hours" + finalization: "1-2 hours" + total_time: "28-51 hours per chapter" + + best_practices: + - Start with strong learning objectives - they guide everything + - Test ALL code before including in chapter + - Use tutorial-section-tmpl for hands-on sections + - Progressive difficulty in exercises (basic to advanced) + - Get technical review before editorial polish + - Address critical issues before moving forward + - Maintain author voice during editing + - Keep reader learning experience as top priority diff --git a/expansion-packs/bmad-technical-writing/workflows/tutorial-creation-workflow.yaml b/expansion-packs/bmad-technical-writing/workflows/tutorial-creation-workflow.yaml new file mode 100644 index 00000000..cd066350 --- /dev/null +++ b/expansion-packs/bmad-technical-writing/workflows/tutorial-creation-workflow.yaml @@ -0,0 +1,185 @@ +workflow: + id: tutorial-creation-workflow + name: Develop Hands-On Tutorial + description: Create effective step-by-step tutorials with tested code and clear instructions. Guides authors through tutorial design, code development, instruction writing, and testing. Emphasizes learning objectives, progressive difficulty, and student success. + type: tutorial-development + project_types: + - technical-tutorial + - hands-on-guide + - coding-workshop + - interactive-lesson + sequence: + - agent: instructional-designer + creates: tutorial-plan.md + notes: "Design tutorial learning path using *design-learning-path command. Define specific learning objective, target audience, prerequisites, and estimated completion time. Identify key concepts to teach and skills to practice. SAVE OUTPUT: Copy tutorial-plan.md to docs/tutorials/plans/" + + - agent: tutorial-architect + creates: tutorial-structure.md + requires: tutorial-plan.md + notes: "Create detailed step-by-step structure (8-15 steps). Use develop-tutorial task. Plan progression from setup through completion. Design each step with clear action, code, and expected output. Include verification points. SAVE OUTPUT: Copy tutorial-structure.md to docs/tutorials/structures/" + + - agent: code-curator + creates: tutorial-code/ + requires: tutorial-structure.md + notes: "Develop and test all code for each tutorial step. Use *create-example command. Ensure progressive code builds properly at each step. Create starter code, complete code, and tests. Verify all code runs in fresh environment. SAVE OUTPUT: Commit code to repository in tutorials/{{tutorial_slug}}/ folder." + + - agent: tutorial-architect + creates: complete-tutorial.md + requires: + - tutorial-structure.md + - tutorial-code/ + notes: "Write complete tutorial using tutorial-section-tmpl template. Include compelling introduction, step-by-step instructions with code, expected outputs, troubleshooting guide, and summary. Ensure clear, actionable language throughout. SAVE OUTPUT: Copy complete tutorial to docs/tutorials/{{tutorial_slug}}.md" + + - agent: code-curator + validates: tutorial-code/ + requires: complete-tutorial.md + notes: "Test tutorial end-to-end following your own instructions exactly. Use *test-tutorial command. Test in fresh environment. Time completion. Document any unclear steps or missing prerequisites. Use tutorial-effectiveness-checklist. SAVE OUTPUT: Create test results report." + + - agent: tutorial-architect + updates: complete-tutorial.md + requires: test-results.md + notes: "Revise tutorial based on testing feedback. Clarify unclear instructions, add missing prerequisites, adjust time estimates, enhance troubleshooting section. Ensure student success path is clear. SAVE OUTPUT: Update complete-tutorial.md with revisions." + + - agent: instructional-designer + validates: complete-tutorial.md + requires: revised-tutorial.md + notes: "Validate tutorial meets learning objectives and pedagogical standards. Check progressive difficulty, scaffolding, cognitive load. Verify assessment alignment. Ensure prerequisites are accurate. Use learning-objectives-checklist. SAVE OUTPUT: Tutorial approved or feedback provided." + + - agent: tutorial-architect + finalizes: tutorial-final.md + requires: validated-tutorial.md + notes: "Incorporate any final feedback. Create final version. Add to chapter or publish standalone. Mark tutorial status as 'Ready for Use'. SAVE OUTPUT: Copy final tutorial to appropriate location (chapter section or standalone tutorial)." + + flow_diagram: | + ```mermaid + graph TD + A[Start: New Tutorial] --> B[instructional-designer: Design Learning Path] + B --> C[tutorial-architect: Create Step Structure] + C --> D[code-curator: Develop & Test Code] + D --> E[tutorial-architect: Write Tutorial] + E --> F[code-curator: Test End-to-End] + F --> G{Issues Found?} + G -->|Yes| H[tutorial-architect: Revise Tutorial] + G -->|No| I[instructional-designer: Validate Learning] + H --> F + I --> J{Meets Standards?} + J -->|Yes| K[Finalize Tutorial] + J -->|No| L[Provide Feedback] + L --> H + K --> M[Tutorial Ready for Students] + + B -.-> B1[Optional: *analyze-difficulty-curve] + D -.-> D1[Optional: *test-code-examples] + F -.-> F1[Optional: Fresh environment test] + I -.-> I1[Optional: *assess-learning-objectives] + + style M fill:#90EE90 + style B fill:#FFE4B5 + style C fill:#FFE4B5 + style D fill:#ADD8E6 + style E fill:#FFE4B5 + style F fill:#ADD8E6 + style I fill:#F0E68C + style K fill:#F0E68C + ``` + + decision_guidance: + when_to_use: + - Creating hands-on coding tutorials + - Building step-by-step technical guides + - Developing workshop materials + - Interactive learning experiences + - Need for student practice and skill building + - Code must be tested and reliable + + when_not_to_use: + - Conceptual explanations without hands-on practice + - Quick code snippets or examples + - Reference documentation + - Theory-heavy content without application + + quality_gates: + plan_complete: + - Learning objective clearly defined + - Prerequisites explicitly stated + - Target audience identified + - Realistic time estimate provided + - Success criteria measurable + + structure_complete: + - 8-15 clear steps defined + - Progressive difficulty maintained + - Each step has verification point + - Troubleshooting points identified + - Summary and next steps planned + + code_tested: + - All code runs without errors + - Outputs match documentation + - Tested in fresh environment + - Starter code provided + - Tests included + - Checklist: code-testing-checklist.md + + tutorial_complete: + - Introduction hooks and motivates + - Instructions clear and actionable + - Expected outputs documented + - Troubleshooting guide included + - Summary reinforces learning + - Checklist: tutorial-effectiveness-checklist.md + + learning_validated: + - Learning objective achieved + - Progressive difficulty appropriate + - Prerequisites accurate + - Cognitive load manageable + - Assessment aligns with objective + - Checklist: learning-objectives-checklist.md + + handoff_prompts: + designer_to_architect: "Tutorial learning path complete. Learning objective: '{{objective}}'. Target time: {{time}}. Audience: {{audience}}. Ready for step-by-step structure design." + architect_to_curator: "Tutorial structure complete with {{step_count}} steps. Progression from {{start_point}} to {{end_point}}. Code examples identified. Ready for code development." + curator_to_architect: "All tutorial code developed and tested. {{file_count}} files created in tutorials/{{tutorial_slug}}/. Tests passing. Ready for tutorial writing." + architect_to_curator_test: "Tutorial draft complete at docs/tutorials/{{tutorial_slug}}.md. Please test end-to-end following instructions exactly and report any issues." + curator_to_architect_results: "Tutorial tested. Completion time: {{actual_time}} (estimated: {{estimated_time}}). Found {{issue_count}} issues or unclear steps. See test-results.md for details." + revised_to_designer: "Tutorial revised based on testing. All issues addressed. Ready for pedagogical validation." + designer_validation: "Tutorial validated. Learning objective met. Progressive difficulty appropriate. {{feedback}}. Ready for finalization." + finalization: "Tutorial finalized at {{location}}. Status: Ready for Students. Learning objective: '{{objective}}' - achievable in {{time}}." + + time_estimates: + design_plan: "1-2 hours" + create_structure: "2-3 hours" + develop_code: "3-6 hours" + write_tutorial: "4-8 hours" + test_tutorial: "1-2 hours" + revisions: "2-4 hours" + validation: "1-2 hours" + finalization: "30 minutes - 1 hour" + total_time: "14-28 hours per tutorial" + + best_practices: + - Start with ONE clear, specific learning objective + - Define prerequisites explicitly - test them + - Keep steps focused (one goal per step) + - Test in fresh environment every time + - Document expected outputs at every step + - Include troubleshooting for common errors + - Time yourself - add 50-100% for students + - Progressive difficulty - start simple + - Use imperative voice ("Create...", "Add...", "Run...") + - Verify success criteria at end + - Provide next steps for continued learning + - Maintain consistent formatting throughout + + common_pitfalls: + - Assuming prerequisites not explicitly stated + - Code that works for you but not fresh environment + - Skipping intermediate steps (too big jumps) + - Unclear or vague instructions + - Missing expected outputs + - No troubleshooting section + - Unrealistic time estimates + - No way to verify success + - Too many concepts at once + - Boring or contrived examples