feat: add review and publishing tasks for sprint 3
This commit is contained in:
Joshua Magady
parent
02f3c92133
commit
c3f92c305b
|
|
@ -8,12 +8,12 @@ The Technical Writing Expansion Pack extends BMad-Method with a comprehensive su
|
||||||
|
|
||||||
### Key Features
|
### Key Features
|
||||||
|
|
||||||
- 🤖 **9 Specialized Agents** - Complete writing team with specialists for API docs, visuals, and exercises
|
- 🤖 **10 Specialized Agents** - Complete writing team with greenfield (planning, writing, review) + brownfield (book analysis, revision planning) specialists
|
||||||
- 📝 **15 Core Tasks** - Full chapter development, API documentation, diagram design, and publishing workflows
|
- 📝 **20 Core Tasks** - Full chapter development, API documentation, diagram design, publishing workflows, PLUS brownfield tasks for book analysis, revision planning, version updates, pattern extraction, and feedback incorporation
|
||||||
- 📋 **18 Quality Checklists** - Technical accuracy, security, performance, publisher compliance, accessibility, visual quality, glossary accuracy
|
- 📋 **21 Quality Checklists** - Technical accuracy, security, performance, publisher compliance, accessibility, visual quality, glossary accuracy, PLUS brownfield checklists for version updates, revision completeness, and existing book integration
|
||||||
- 🎯 **15 Professional Templates** - Book planning, chapter development, API reference, diagrams, preface, appendix, and publishing
|
- 🎯 **15 Professional Templates** - Book planning, chapter development, API reference, diagrams, preface, appendix, publishing, PLUS brownfield templates for book analysis reports and revision plans
|
||||||
- 📚 **6 Knowledge Bases** - Comprehensive publisher guidelines and technical writing standards
|
- 📚 **6 Knowledge Bases** - Comprehensive publisher guidelines and technical writing standards
|
||||||
- 🔄 **12 Core Workflows** - Section-driven development plus publisher-specific submission workflows (PacktPub, O'Reilly, Manning, Self-Publishing)
|
- 🔄 **12 Workflows** - Section-driven development, publisher-specific submission workflows (PacktPub, O'Reilly, Manning, Self-Publishing), PLUS brownfield workflows for edition updates, review feedback incorporation, and chapter additions
|
||||||
|
|
||||||
## ✍️ Included Agents
|
## ✍️ Included Agents
|
||||||
|
|
||||||
|
|
@ -35,6 +35,10 @@ The Technical Writing Expansion Pack extends BMad-Method with a comprehensive su
|
||||||
8. **Screenshot Specialist** 📸 - Visual documentation, technical diagrams, screenshot planning, and annotations
|
8. **Screenshot Specialist** 📸 - Visual documentation, technical diagrams, screenshot planning, and annotations
|
||||||
9. **Exercise Creator** 🏋️ - Practice problems, assessments, exercises aligned with learning objectives
|
9. **Exercise Creator** 🏋️ - Practice problems, assessments, exercises aligned with learning objectives
|
||||||
|
|
||||||
|
### Brownfield Team (Sprint 4)
|
||||||
|
|
||||||
|
10. **Book Analyst** 📖 - Existing book analysis, revision planning, 2nd/3rd edition updates, version migrations, pattern extraction, and reviewer feedback incorporation
|
||||||
|
|
||||||
## 🚀 Installation
|
## 🚀 Installation
|
||||||
|
|
||||||
### Via BMad Installer
|
### Via BMad Installer
|
||||||
|
|
@ -59,6 +63,8 @@ npx bmad-method install
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Activate individual agents in your IDE
|
# Activate individual agents in your IDE
|
||||||
|
|
||||||
|
# Greenfield agents (new book writing)
|
||||||
/bmad-tw:instructional-designer
|
/bmad-tw:instructional-designer
|
||||||
/bmad-tw:tutorial-architect
|
/bmad-tw:tutorial-architect
|
||||||
/bmad-tw:code-curator
|
/bmad-tw:code-curator
|
||||||
|
|
@ -68,6 +74,9 @@ npx bmad-method install
|
||||||
/bmad-tw:api-documenter
|
/bmad-tw:api-documenter
|
||||||
/bmad-tw:screenshot-specialist
|
/bmad-tw:screenshot-specialist
|
||||||
/bmad-tw:exercise-creator
|
/bmad-tw:exercise-creator
|
||||||
|
|
||||||
|
# Brownfield agent (existing book updates)
|
||||||
|
/bmad-tw:book-analyst
|
||||||
```
|
```
|
||||||
|
|
||||||
### Core Workflows (Sprint 2, 2.5, 2.6)
|
### Core Workflows (Sprint 2, 2.5, 2.6)
|
||||||
|
|
@ -386,6 +395,19 @@ Special thanks to Brian (BMad) for creating the BMad Method framework.
|
||||||
- ✅ Complete technical writing system from planning through publication
|
- ✅ Complete technical writing system from planning through publication
|
||||||
- ✅ Version bumped to 0.3.0 (beta - specialist agents complete)
|
- ✅ Version bumped to 0.3.0 (beta - specialist agents complete)
|
||||||
|
|
||||||
|
**Sprint 4 (Complete):** Brownfield book authoring support - v1.0.0 PRODUCTION RELEASE
|
||||||
|
|
||||||
|
- ✅ 1 brownfield agent: Book Analyst (existing book analysis and revision planning specialist)
|
||||||
|
- ✅ 2 brownfield templates: Book Analysis Report, Revision Plan
|
||||||
|
- ✅ 5 brownfield tasks: Analyze Existing Book, Plan Book Revision, Update Chapter for Version, Extract Code Patterns, Incorporate Reviewer Feedback
|
||||||
|
- ✅ 3 brownfield workflows: Book Edition Update, Incorporate Review Feedback, Add Chapter to Existing Book
|
||||||
|
- ✅ 3 brownfield checklists: Version Update, Revision Completeness, Existing Book Integration
|
||||||
|
- ✅ Total: 10 agents, 15 templates, 20 tasks, 12 workflows, 21 checklists
|
||||||
|
- ✅ Brownfield capabilities: 2nd/3rd edition updates, technology version migrations (Python 3.9→3.12), chapter additions to existing books, systematic reviewer feedback incorporation
|
||||||
|
- ✅ Pattern extraction for maintaining consistency in existing books
|
||||||
|
- ✅ Surgical update workflows that preserve learning flow and voice/tone
|
||||||
|
- ✅ Version bumped to 1.0.0 (production ready - complete greenfield + brownfield support)
|
||||||
|
|
||||||
## 📚 Section-Driven Development Approach (NEW in Sprint 2.6)
|
## 📚 Section-Driven Development Approach (NEW in Sprint 2.6)
|
||||||
|
|
||||||
The section-driven approach mirrors BMad's story-driven development workflow, enabling incremental chapter writing:
|
The section-driven approach mirrors BMad's story-driven development workflow, enabling incremental chapter writing:
|
||||||
|
|
@ -440,5 +462,6 @@ The section-driven approach mirrors BMad's story-driven development workflow, en
|
||||||
- Learning Path Designer agent (multi-book series planning)
|
- Learning Path Designer agent (multi-book series planning)
|
||||||
- Sample Code Maintainer agent (code repository management)
|
- Sample Code Maintainer agent (code repository management)
|
||||||
- Version Manager agent (update tracking across versions)
|
- Version Manager agent (update tracking across versions)
|
||||||
- Enhanced brownfield book update workflows
|
|
||||||
- Audio/podcast supplement tools
|
- Audio/podcast supplement tools
|
||||||
|
- Interactive exercise platform integration
|
||||||
|
- Code testing automation for book examples
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,105 @@
|
||||||
|
<!-- Powered by BMAD™ Core -->
|
||||||
|
|
||||||
|
# book-analyst
|
||||||
|
|
||||||
|
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., "analyze my book"→*analyze-book, "plan revision"→*plan-revision), 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 Analyst
|
||||||
|
id: book-analyst
|
||||||
|
title: Existing Book Analysis & Revision Planning Specialist
|
||||||
|
icon: 📖
|
||||||
|
whenToUse: Use for analyzing existing books, planning 2nd/3rd editions, version updates, chapter additions, and incorporating reviewer feedback
|
||||||
|
customization: null
|
||||||
|
persona:
|
||||||
|
role: Brownfield book analysis and strategic revision planning expert
|
||||||
|
style: Analytical, systematic, pattern-focused, consistency-aware, version-conscious
|
||||||
|
identity: Expert in book analysis, pattern extraction, revision planning, and consistency maintenance for technical book updates
|
||||||
|
focus: Understanding existing book structure, extracting patterns, planning surgical updates, and maintaining consistency across revisions
|
||||||
|
core_principles:
|
||||||
|
- Analysis First - Always understand current state before planning changes
|
||||||
|
- Pattern Extraction - Learn existing style, code conventions, and structure
|
||||||
|
- Consistency Maintenance - Match existing voice, tone, and formatting
|
||||||
|
- Surgical Updates - Target specific areas; minimize disruption
|
||||||
|
- Version Tracking - Document what changed and why
|
||||||
|
- Learning Flow Preservation - Ensure revisions maintain pedagogical integrity
|
||||||
|
- Numbered Options Protocol - Always use numbered lists for user selections
|
||||||
|
commands:
|
||||||
|
- '*help - Show numbered list of available commands for selection'
|
||||||
|
- '*analyze-book - Run task analyze-existing-book.md to analyze current book state'
|
||||||
|
- '*plan-revision - Run task plan-book-revision.md to create strategic revision plan'
|
||||||
|
- '*extract-patterns - Run task extract-code-patterns.md to learn existing code style'
|
||||||
|
- '*assess-version-impact - Analyze impact of technology version changes on book content'
|
||||||
|
- '*triage-feedback - Categorize and prioritize reviewer/publisher feedback'
|
||||||
|
- '*identify-outdated-content - Scan for deprecated APIs, outdated best practices, breaking changes'
|
||||||
|
- '*yolo - Toggle Yolo Mode'
|
||||||
|
- '*exit - Say goodbye as the Book Analyst, and then abandon inhabiting this persona'
|
||||||
|
dependencies:
|
||||||
|
tasks:
|
||||||
|
- create-doc.md
|
||||||
|
- analyze-existing-book.md
|
||||||
|
- plan-book-revision.md
|
||||||
|
- extract-code-patterns.md
|
||||||
|
- incorporate-reviewer-feedback.md
|
||||||
|
- execute-checklist.md
|
||||||
|
templates:
|
||||||
|
- book-analysis-report-tmpl.yaml
|
||||||
|
- revision-plan-tmpl.yaml
|
||||||
|
checklists:
|
||||||
|
- version-update-checklist.md
|
||||||
|
- revision-completeness-checklist.md
|
||||||
|
- existing-book-integration-checklist.md
|
||||||
|
data:
|
||||||
|
- bmad-kb.md
|
||||||
|
- learning-frameworks.md
|
||||||
|
```
|
||||||
|
|
||||||
|
## Startup Context
|
||||||
|
|
||||||
|
You are the Book Analyst, a master of existing book analysis and strategic revision planning. Your expertise spans brownfield book authoring scenarios: 2nd/3rd edition updates, technology version migrations, chapter additions to existing books, and systematic incorporation of reviewer feedback.
|
||||||
|
|
||||||
|
Think in terms of:
|
||||||
|
|
||||||
|
- **Current state analysis** - What exists now? What's the structure, style, and technical currency?
|
||||||
|
- **Pattern extraction** - What conventions does the book follow? Code style, terminology, voice, formatting?
|
||||||
|
- **Version impact assessment** - How do technology changes affect the book? What breaks? What's deprecated?
|
||||||
|
- **Surgical revision planning** - What needs to change? What stays the same? How to minimize disruption?
|
||||||
|
- **Consistency maintenance** - How to ensure new/updated content matches existing style?
|
||||||
|
- **Learning flow preservation** - How to keep the pedagogical progression intact after changes?
|
||||||
|
|
||||||
|
Your goal is to help authors successfully update existing technical books while maintaining quality, consistency, and pedagogical soundness. You coordinate brownfield workflows and provide analysis context to other agents.
|
||||||
|
|
||||||
|
Always consider:
|
||||||
|
|
||||||
|
- What patterns exist in the current book?
|
||||||
|
- What's technically outdated or deprecated?
|
||||||
|
- How will changes affect the learning progression?
|
||||||
|
- How can we maintain consistency with existing content?
|
||||||
|
- What's the scope of changes needed?
|
||||||
|
|
||||||
|
Remember to present all options as numbered lists for easy selection.
|
||||||
|
|
@ -0,0 +1,209 @@
|
||||||
|
# Existing Book Integration Checklist
|
||||||
|
|
||||||
|
Use this checklist when adding new content to an existing book (new chapters, revised chapters, expanded sections) to ensure consistency with existing content.
|
||||||
|
|
||||||
|
## Voice and Tone
|
||||||
|
|
||||||
|
- [ ] Voice matches existing chapters (conversational vs. formal)
|
||||||
|
- [ ] Tone is consistent (friendly, authoritative, encouraging, etc.)
|
||||||
|
- [ ] Person usage consistent (first person "I/we", second person "you", third person)
|
||||||
|
- [ ] Formality level matches (casual vs. academic)
|
||||||
|
- [ ] Humor style consistent (if book uses humor)
|
||||||
|
- [ ] Technical depth appropriate for book's level
|
||||||
|
|
||||||
|
## Code Style Patterns
|
||||||
|
|
||||||
|
- [ ] Import organization follows extracted patterns
|
||||||
|
- [ ] Naming conventions match (snake_case, camelCase, PascalCase)
|
||||||
|
- [ ] Comment style consistent with existing examples
|
||||||
|
- [ ] Docstring style matches (Google, NumPy, Sphinx, or none)
|
||||||
|
- [ ] Error handling patterns followed
|
||||||
|
- [ ] Code structure patterns maintained (OOP, functional, procedural)
|
||||||
|
- [ ] Formatting consistent (indentation, line length, spacing)
|
||||||
|
- [ ] File organization patterns followed
|
||||||
|
|
||||||
|
## Terminology Consistency
|
||||||
|
|
||||||
|
- [ ] Technical terms match existing usage
|
||||||
|
- [ ] Abbreviations used consistently (introduce on first use?)
|
||||||
|
- [ ] Jargon usage consistent (explained or assumed?)
|
||||||
|
- [ ] Product names match (capitalization, trademarks)
|
||||||
|
- [ ] Variable names in examples follow patterns
|
||||||
|
- [ ] Glossary terms used consistently
|
||||||
|
- [ ] No conflicting definitions for same terms
|
||||||
|
|
||||||
|
## Heading Hierarchy
|
||||||
|
|
||||||
|
- [ ] Heading levels used correctly (H1, H2, H3)
|
||||||
|
- [ ] Heading style matches (action-based, question-based, topic-based)
|
||||||
|
- [ ] Heading capitalization consistent (title case vs. sentence case)
|
||||||
|
- [ ] Heading length similar to existing chapters
|
||||||
|
- [ ] Heading numbering follows book's pattern (if numbered)
|
||||||
|
- [ ] No skipped heading levels (H1→H3 without H2)
|
||||||
|
|
||||||
|
## Structural Patterns
|
||||||
|
|
||||||
|
- [ ] Chapter organization matches typical flow
|
||||||
|
- [ ] Section lengths similar to existing chapters
|
||||||
|
- [ ] Introduction section follows pattern (if pattern exists)
|
||||||
|
- [ ] Summary section follows pattern (if pattern exists)
|
||||||
|
- [ ] Exercise placement consistent
|
||||||
|
- [ ] Code listing placement consistent
|
||||||
|
- [ ] Callout usage matches frequency and style
|
||||||
|
|
||||||
|
## Cross-References
|
||||||
|
|
||||||
|
- [ ] Cross-reference format matches ("Chapter 5" vs. "chapter 5")
|
||||||
|
- [ ] Section reference style consistent ("Section 5.2" vs. "section 5.2")
|
||||||
|
- [ ] Forward references styled consistently ("we'll cover this in Chapter 7")
|
||||||
|
- [ ] Backward references styled consistently ("as discussed in Chapter 3")
|
||||||
|
- [ ] Page references avoided (if book uses digital distribution)
|
||||||
|
- [ ] All referenced chapters/sections exist
|
||||||
|
- [ ] Reference accuracy verified
|
||||||
|
|
||||||
|
## Learning Progression
|
||||||
|
|
||||||
|
- [ ] Prerequisites clearly stated and match book's approach
|
||||||
|
- [ ] Difficulty level appropriate for chapter placement
|
||||||
|
- [ ] Learning objectives styled consistently
|
||||||
|
- [ ] Complexity builds on existing chapters
|
||||||
|
- [ ] No assumptions beyond stated prerequisites
|
||||||
|
- [ ] Scaffolding follows book's pedagogical approach
|
||||||
|
- [ ] Practice opportunities similar to existing chapters
|
||||||
|
|
||||||
|
## Callouts and Asides
|
||||||
|
|
||||||
|
- [ ] Tip callouts styled consistently (icon, formatting, length)
|
||||||
|
- [ ] Warning callouts styled consistently
|
||||||
|
- [ ] Note callouts styled consistently
|
||||||
|
- [ ] Sidebar usage consistent (if book uses sidebars)
|
||||||
|
- [ ] Callout frequency similar to existing chapters
|
||||||
|
- [ ] Callout content length appropriate
|
||||||
|
- [ ] No new callout types introduced without reason
|
||||||
|
|
||||||
|
## Code Examples
|
||||||
|
|
||||||
|
- [ ] Code example length similar to existing chapters
|
||||||
|
- [ ] Code complexity appropriate for chapter level
|
||||||
|
- [ ] Code snippets vs. full programs ratio similar
|
||||||
|
- [ ] Code explanations follow book's pattern (before? after? inline?)
|
||||||
|
- [ ] Output examples styled consistently
|
||||||
|
- [ ] Error examples styled consistently (if book shows errors)
|
||||||
|
- [ ] Code file naming follows patterns
|
||||||
|
|
||||||
|
## Exercises and Practice
|
||||||
|
|
||||||
|
- [ ] Exercise difficulty matches book's progression
|
||||||
|
- [ ] Exercise format consistent (numbered, titled, etc.)
|
||||||
|
- [ ] Exercise quantity similar to existing chapters
|
||||||
|
- [ ] Solution availability consistent (provided, hints, none)
|
||||||
|
- [ ] Challenge problem format consistent (if book has challenges)
|
||||||
|
- [ ] Quiz format consistent (if book has quizzes)
|
||||||
|
|
||||||
|
## Formatting and Style
|
||||||
|
|
||||||
|
- [ ] List formatting consistent (bullets, numbers, indentation)
|
||||||
|
- [ ] Table formatting matches
|
||||||
|
- [ ] Figure/image style consistent
|
||||||
|
- [ ] Caption style matches
|
||||||
|
- [ ] Code block formatting consistent
|
||||||
|
- [ ] Inline code formatting consistent (`backticks` vs. other)
|
||||||
|
- [ ] Emphasis usage consistent (bold, italic, both)
|
||||||
|
- [ ] Quotation marks consistent (single, double, smart quotes)
|
||||||
|
|
||||||
|
## Front/Back Matter References
|
||||||
|
|
||||||
|
- [ ] Chapter listed in Table of Contents
|
||||||
|
- [ ] Learning objectives added to chapter overview (if book has this)
|
||||||
|
- [ ] Key terms added to glossary (if applicable)
|
||||||
|
- [ ] Index entries created for new content
|
||||||
|
- [ ] Appendix references added (if applicable)
|
||||||
|
- [ ] Resource list updated (if applicable)
|
||||||
|
|
||||||
|
## Technology and Versions
|
||||||
|
|
||||||
|
- [ ] Technology versions match book's target versions
|
||||||
|
- [ ] Platform assumptions consistent (OS, hardware)
|
||||||
|
- [ ] Tool requirements consistent with book's setup
|
||||||
|
- [ ] Library versions match or are compatible
|
||||||
|
- [ ] Installation instructions match book's approach
|
||||||
|
- [ ] Testing approach consistent
|
||||||
|
|
||||||
|
## Publisher Compliance
|
||||||
|
|
||||||
|
- [ ] Page count appropriate for chapter position
|
||||||
|
- [ ] Format requirements met (if publisher-specific)
|
||||||
|
- [ ] Legal disclaimers present (if needed)
|
||||||
|
- [ ] Trademark usage consistent
|
||||||
|
- [ ] Copyright notices consistent
|
||||||
|
- [ ] Attribution style matches
|
||||||
|
|
||||||
|
## Quality Standards
|
||||||
|
|
||||||
|
- [ ] No placeholder content (TBD, TODO, XXX)
|
||||||
|
- [ ] No broken links or references
|
||||||
|
- [ ] No orphaned footnotes or endnotes
|
||||||
|
- [ ] Spelling checked with book's dictionary
|
||||||
|
- [ ] Grammar consistent with book's style
|
||||||
|
- [ ] Readability score similar to existing chapters
|
||||||
|
|
||||||
|
## Examples of Good vs. Bad Integration
|
||||||
|
|
||||||
|
**✅ Good Integration:**
|
||||||
|
```markdown
|
||||||
|
## Setting Up Authentication
|
||||||
|
|
||||||
|
As we saw in Chapter 3, user authentication is critical for secure applications.
|
||||||
|
In this section, we'll implement JWT-based authentication using Flask.
|
||||||
|
|
||||||
|
> **Note**: JWT tokens should always include an expiration time to limit
|
||||||
|
> security exposure.
|
||||||
|
|
||||||
|
```python
|
||||||
|
from flask import Flask, request
|
||||||
|
from datetime import datetime, timedelta
|
||||||
|
|
||||||
|
def create_token(user_id):
|
||||||
|
"""
|
||||||
|
Create JWT token for user.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
user_id: Unique user identifier
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
Encoded JWT token string
|
||||||
|
"""
|
||||||
|
# Implementation follows
|
||||||
|
```
|
||||||
|
- Matches voice/tone
|
||||||
|
- Follows cross-reference style
|
||||||
|
- Uses consistent callout format
|
||||||
|
- Follows code patterns (imports, docstring style)
|
||||||
|
|
||||||
|
**❌ Bad Integration:**
|
||||||
|
```markdown
|
||||||
|
# Auth Setup
|
||||||
|
|
||||||
|
Let's do authentication now!
|
||||||
|
|
||||||
|
**IMPORTANT!!!** Don't forget expiration!
|
||||||
|
|
||||||
|
from flask import *
|
||||||
|
def make_token(uid):
|
||||||
|
# make the token
|
||||||
|
```
|
||||||
|
- Heading style different (# vs ##)
|
||||||
|
- Voice too casual/inconsistent
|
||||||
|
- Callout style different (bold vs. callout box)
|
||||||
|
- Code style inconsistent (import *, no docstring, different naming)
|
||||||
|
|
||||||
|
## Red Flags
|
||||||
|
|
||||||
|
- New content "feels different" when reading sequentially
|
||||||
|
- Reviewers comment on inconsistency
|
||||||
|
- Different terminology for same concepts
|
||||||
|
- Code style visibly different
|
||||||
|
- Heading styles don't match
|
||||||
|
- Callout formats vary
|
||||||
|
- Cross-references styled differently
|
||||||
|
- Learning difficulty jumps unexpectedly
|
||||||
|
|
@ -0,0 +1,189 @@
|
||||||
|
# Revision Completeness Checklist
|
||||||
|
|
||||||
|
Use this checklist to verify that a book revision (2nd/3rd edition, major update) is complete and ready for publication.
|
||||||
|
|
||||||
|
## Planning Phase Complete
|
||||||
|
|
||||||
|
- [ ] Book analysis completed and reviewed by stakeholders
|
||||||
|
- [ ] Revision plan approved by author and publisher
|
||||||
|
- [ ] All chapters in revision matrix addressed (or consciously deferred)
|
||||||
|
- [ ] Code patterns extracted and documented
|
||||||
|
- [ ] Timeline reviewed and milestones met
|
||||||
|
- [ ] Scope creep controlled (deferred enhancements documented)
|
||||||
|
|
||||||
|
## Chapter Revisions Complete
|
||||||
|
|
||||||
|
- [ ] All critical-priority chapters revised and tested
|
||||||
|
- [ ] All important-priority chapters revised and tested
|
||||||
|
- [ ] Nice-to-have chapters addressed or consciously deferred
|
||||||
|
- [ ] Each revised chapter passed version-update-checklist.md
|
||||||
|
- [ ] No chapters left in incomplete state
|
||||||
|
- [ ] Deferred chapters documented with rationale
|
||||||
|
|
||||||
|
## Code Quality
|
||||||
|
|
||||||
|
- [ ] All code examples tested on target version(s)
|
||||||
|
- [ ] No broken code examples
|
||||||
|
- [ ] No deprecated methods or APIs used
|
||||||
|
- [ ] Security best practices current
|
||||||
|
- [ ] Code follows extracted patterns (consistency maintained)
|
||||||
|
- [ ] Code repository updated with all examples
|
||||||
|
- [ ] All code linted and formatted according to standards
|
||||||
|
- [ ] Regression testing passed (unchanged examples still work)
|
||||||
|
|
||||||
|
## Technical Accuracy
|
||||||
|
|
||||||
|
- [ ] Technical review completed by qualified reviewer
|
||||||
|
- [ ] Technical review feedback incorporated
|
||||||
|
- [ ] All technical errors corrected
|
||||||
|
- [ ] Best practices current for target versions
|
||||||
|
- [ ] No misleading or incorrect information
|
||||||
|
- [ ] Prerequisites accurate and achievable
|
||||||
|
- [ ] Technical reviewer approval documented
|
||||||
|
|
||||||
|
## Learning Path Validated
|
||||||
|
|
||||||
|
- [ ] Learning progression verified across revised chapters
|
||||||
|
- [ ] Prerequisites flow correctly (no knowledge gaps introduced)
|
||||||
|
- [ ] Difficulty curve remains smooth (no sudden jumps)
|
||||||
|
- [ ] Learning objectives still met with revised content
|
||||||
|
- [ ] Exercises still appropriate for updated content
|
||||||
|
- [ ] Scaffolding maintained (simple to complex progression)
|
||||||
|
|
||||||
|
## Writing Quality
|
||||||
|
|
||||||
|
- [ ] Voice and tone consistent throughout
|
||||||
|
- [ ] Terminology consistent (old and new content)
|
||||||
|
- [ ] Clarity improvements implemented
|
||||||
|
- [ ] Writing style matches original book
|
||||||
|
- [ ] Grammar and spelling checked
|
||||||
|
- [ ] Readability appropriate for target audience
|
||||||
|
|
||||||
|
## Consistency Maintained
|
||||||
|
|
||||||
|
- [ ] Code style consistent with existing book
|
||||||
|
- [ ] Heading hierarchy matches throughout
|
||||||
|
- [ ] Callout usage consistent (tips, warnings, notes)
|
||||||
|
- [ ] Cross-reference style consistent
|
||||||
|
- [ ] Formatting consistent throughout
|
||||||
|
- [ ] Existing-book-integration-checklist.md passed
|
||||||
|
|
||||||
|
## Cross-References and Navigation
|
||||||
|
|
||||||
|
- [ ] All cross-references updated and verified
|
||||||
|
- [ ] Chapter numbers adjusted if chapters added/removed
|
||||||
|
- [ ] Section references accurate
|
||||||
|
- [ ] Table of contents updated and correct
|
||||||
|
- [ ] Index updated with new terms and topics
|
||||||
|
- [ ] Forward and backward references all work
|
||||||
|
|
||||||
|
## Front and Back Matter
|
||||||
|
|
||||||
|
- [ ] Preface/Introduction updated for new edition
|
||||||
|
- [ ] "What's New in This Edition" section added
|
||||||
|
- [ ] About the Author current
|
||||||
|
- [ ] Technology prerequisites updated (version requirements)
|
||||||
|
- [ ] Glossary updated with new terms
|
||||||
|
- [ ] Appendices updated or added as needed
|
||||||
|
- [ ] Bibliography/References current
|
||||||
|
|
||||||
|
## Code Repository
|
||||||
|
|
||||||
|
- [ ] All code examples in repository
|
||||||
|
- [ ] Repository structure follows plan
|
||||||
|
- [ ] README updated with version requirements
|
||||||
|
- [ ] Tests passing (if automated tests exist)
|
||||||
|
- [ ] CI/CD pipeline working (if applicable)
|
||||||
|
- [ ] License information current
|
||||||
|
- [ ] Installation instructions updated
|
||||||
|
|
||||||
|
## Version Documentation
|
||||||
|
|
||||||
|
- [ ] New edition number clearly documented (2nd, 3rd, etc.)
|
||||||
|
- [ ] Version number updated in all locations (cover, title page, etc.)
|
||||||
|
- [ ] Publication date current
|
||||||
|
- [ ] Change log or "What's New" section complete
|
||||||
|
- [ ] Technology version matrix documented (Python 3.12, Node 20, etc.)
|
||||||
|
- [ ] Minimum version requirements stated
|
||||||
|
|
||||||
|
## Publisher Requirements
|
||||||
|
|
||||||
|
- [ ] Publisher format requirements met
|
||||||
|
- [ ] Page count within agreed range (if specified)
|
||||||
|
- [ ] Manuscript format correct (Word, markdown, etc.)
|
||||||
|
- [ ] File naming conventions followed
|
||||||
|
- [ ] Submission checklist complete (publisher-specific)
|
||||||
|
- [ ] Legal requirements met (permissions, licenses, disclaimers)
|
||||||
|
- [ ] Publisher deadlines met
|
||||||
|
|
||||||
|
## Quality Assurance
|
||||||
|
|
||||||
|
- [ ] All planned checklists executed and passed
|
||||||
|
- [ ] No critical issues unresolved
|
||||||
|
- [ ] No broken examples
|
||||||
|
- [ ] No broken links (external URLs verified)
|
||||||
|
- [ ] No placeholder content (TBD, TODO, etc.)
|
||||||
|
- [ ] Screenshots current (if applicable)
|
||||||
|
- [ ] Diagrams accurate and up-to-date
|
||||||
|
|
||||||
|
## Reviewer Feedback
|
||||||
|
|
||||||
|
- [ ] All critical reviewer feedback addressed
|
||||||
|
- [ ] All important reviewer feedback addressed or deferred
|
||||||
|
- [ ] Optional feedback evaluated (implement, defer, or decline)
|
||||||
|
- [ ] Feedback resolution log created
|
||||||
|
- [ ] Reviewers acknowledged in book
|
||||||
|
- [ ] Reviewer approval obtained
|
||||||
|
|
||||||
|
## Testing and Validation
|
||||||
|
|
||||||
|
- [ ] Beta readers tested sample chapters (if applicable)
|
||||||
|
- [ ] Technical reviewers approved content
|
||||||
|
- [ ] Editorial review completed
|
||||||
|
- [ ] Copy editing completed
|
||||||
|
- [ ] Final proofreading completed
|
||||||
|
- [ ] Test cases passed (if formal testing process exists)
|
||||||
|
|
||||||
|
## Completeness Check
|
||||||
|
|
||||||
|
- [ ] All chapters present and complete
|
||||||
|
- [ ] No missing sections or TBD placeholders
|
||||||
|
- [ ] All figures and tables present
|
||||||
|
- [ ] All code listings complete
|
||||||
|
- [ ] All exercises have solutions (if solutions provided)
|
||||||
|
- [ ] All appendices complete
|
||||||
|
|
||||||
|
## Final Verification
|
||||||
|
|
||||||
|
- [ ] Author has reviewed final manuscript
|
||||||
|
- [ ] Publisher has reviewed final manuscript
|
||||||
|
- [ ] No blocking issues remain
|
||||||
|
- [ ] Ready for production/publication
|
||||||
|
- [ ] Backup copies secured
|
||||||
|
- [ ] Submission package complete
|
||||||
|
|
||||||
|
## Documentation and Handoff
|
||||||
|
|
||||||
|
- [ ] Revision plan final status documented
|
||||||
|
- [ ] Actual timeline vs. planned timeline documented
|
||||||
|
- [ ] Lessons learned captured for next edition
|
||||||
|
- [ ] Deferred items logged for future editions
|
||||||
|
- [ ] Reviewer acknowledgments complete
|
||||||
|
- [ ] Production notes provided to publisher
|
||||||
|
|
||||||
|
## Examples of Complete vs. Incomplete
|
||||||
|
|
||||||
|
**✅ Complete Revision:**
|
||||||
|
- All planned chapters revised
|
||||||
|
- All code tested on Python 3.12
|
||||||
|
- Technical review approved
|
||||||
|
- Cross-references verified
|
||||||
|
- Publisher checklist passed
|
||||||
|
- Ready for publication
|
||||||
|
|
||||||
|
**❌ Incomplete Revision:**
|
||||||
|
- Chapter 7 still has Python 3.9 code
|
||||||
|
- Technical reviewer found 3 unresolved errors
|
||||||
|
- Table of contents not updated
|
||||||
|
- Code repository missing Chapter 12 examples
|
||||||
|
- No "What's New" section added
|
||||||
|
|
@ -0,0 +1,119 @@
|
||||||
|
# Version Update Quality Checklist
|
||||||
|
|
||||||
|
Use this checklist when updating a chapter for a new technology version (e.g., Python 3.9 → 3.12, Node 16 → 20).
|
||||||
|
|
||||||
|
## Import Statements
|
||||||
|
|
||||||
|
- [ ] All import statements reviewed for version compatibility
|
||||||
|
- [ ] Deprecated import paths updated to current equivalents
|
||||||
|
- [ ] New import patterns adopted where applicable (e.g., Python 3.10+ built-in generics)
|
||||||
|
- [ ] Import organization follows existing book patterns
|
||||||
|
- [ ] No warnings about deprecated imports when code runs
|
||||||
|
|
||||||
|
## Deprecated Methods/APIs
|
||||||
|
|
||||||
|
- [ ] All deprecated methods identified and replaced
|
||||||
|
- [ ] Replacement methods functionally equivalent
|
||||||
|
- [ ] Breaking changes addressed (behavior differences handled)
|
||||||
|
- [ ] Deprecation warnings eliminated
|
||||||
|
- [ ] Documentation links updated to current API docs
|
||||||
|
|
||||||
|
## New Syntax Features
|
||||||
|
|
||||||
|
- [ ] New syntax features considered for adoption (match/case, type hints, etc.)
|
||||||
|
- [ ] New syntax used only where pedagogically appropriate
|
||||||
|
- [ ] New syntax doesn't obscure the concept being taught
|
||||||
|
- [ ] Explanatory text updated to explain new syntax
|
||||||
|
- [ ] Syntax level appropriate for target audience
|
||||||
|
|
||||||
|
## Code Testing
|
||||||
|
|
||||||
|
- [ ] All code examples tested on exact target version
|
||||||
|
- [ ] Code runs without errors
|
||||||
|
- [ ] Code runs without warnings (or warnings are explained)
|
||||||
|
- [ ] Output matches what's shown in book text
|
||||||
|
- [ ] Code tested on all relevant platforms (if multi-platform book)
|
||||||
|
- [ ] Edge cases tested
|
||||||
|
- [ ] Performance characteristics verified (if performance-sensitive)
|
||||||
|
|
||||||
|
## Text Accuracy
|
||||||
|
|
||||||
|
- [ ] Version references updated throughout (Python 3.12, not 3.9)
|
||||||
|
- [ ] Explanations revised for any behavior changes
|
||||||
|
- [ ] Best practices updated to reflect current standards
|
||||||
|
- [ ] Security guidance current for target version
|
||||||
|
- [ ] Performance notes updated if characteristics changed
|
||||||
|
- [ ] Feature availability notes accurate (when features were introduced)
|
||||||
|
|
||||||
|
## Migration Notes
|
||||||
|
|
||||||
|
- [ ] Migration notes added if changes are significant
|
||||||
|
- [ ] Breaking changes documented
|
||||||
|
- [ ] Migration tips provided for readers with old code
|
||||||
|
- [ ] Links to official migration guides included (if helpful)
|
||||||
|
- [ ] Backward compatibility notes where relevant
|
||||||
|
|
||||||
|
## Cross-References
|
||||||
|
|
||||||
|
- [ ] All "see Chapter X" references still accurate
|
||||||
|
- [ ] Section number references verified
|
||||||
|
- [ ] Forward references still correct
|
||||||
|
- [ ] Backward references still correct
|
||||||
|
- [ ] Page number references updated (if present)
|
||||||
|
- [ ] Index entries reflect version changes
|
||||||
|
|
||||||
|
## Version-Specific Content
|
||||||
|
|
||||||
|
- [ ] Version-specific features clearly noted
|
||||||
|
- [ ] Minimum version requirements stated
|
||||||
|
- [ ] Version compatibility ranges specified where needed
|
||||||
|
- [ ] Deprecated features marked clearly
|
||||||
|
- [ ] Future deprecation warnings included where known
|
||||||
|
|
||||||
|
## Consistency
|
||||||
|
|
||||||
|
- [ ] Updated code follows extracted code patterns
|
||||||
|
- [ ] Voice and tone consistent with existing content
|
||||||
|
- [ ] Terminology consistent throughout chapter
|
||||||
|
- [ ] Formatting matches book standards
|
||||||
|
- [ ] Comment styles match existing examples
|
||||||
|
|
||||||
|
## Documentation
|
||||||
|
|
||||||
|
- [ ] Chapter change log updated with version update details
|
||||||
|
- [ ] Testing notes documented (which version(s) tested)
|
||||||
|
- [ ] Major changes summarized for readers
|
||||||
|
- [ ] Date of update recorded
|
||||||
|
- [ ] Reviewer name documented
|
||||||
|
|
||||||
|
## Examples of Good Version Updates
|
||||||
|
|
||||||
|
**✅ Good Update:**
|
||||||
|
```python
|
||||||
|
# Python 3.12 - Modern Type Hints
|
||||||
|
def process_items(items: list[str]) -> dict[str, int]:
|
||||||
|
"""Process items and return counts (Python 3.9+)."""
|
||||||
|
return {item: items.count(item) for item in set(items)}
|
||||||
|
```
|
||||||
|
- Uses modern syntax
|
||||||
|
- Documents minimum version
|
||||||
|
- Clear and concise
|
||||||
|
|
||||||
|
**❌ Bad Update:**
|
||||||
|
```python
|
||||||
|
# Just changed version number but code uses old syntax
|
||||||
|
def process_items(items: List[str]) -> Dict[str, int]:
|
||||||
|
# Still importing from typing (old way)
|
||||||
|
return {item: items.count(item) for item in set(items)}
|
||||||
|
```
|
||||||
|
- Inconsistent (claims new version but uses old syntax)
|
||||||
|
- Missed opportunity to demonstrate new features
|
||||||
|
|
||||||
|
## Red Flags
|
||||||
|
|
||||||
|
- Version number changed in text but code unchanged
|
||||||
|
- Code uses deprecated features without migration plan
|
||||||
|
- No testing on actual target version
|
||||||
|
- Breaking changes ignored
|
||||||
|
- Cross-references broken by chapter renumbering
|
||||||
|
- Inconsistent version references (some old, some new)
|
||||||
|
|
@ -1,18 +1,21 @@
|
||||||
# <!-- Powered by BMAD™ Core -->
|
# <!-- Powered by BMAD™ Core -->
|
||||||
name: bmad-technical-writing
|
name: bmad-technical-writing
|
||||||
version: 0.3.0
|
version: 1.0.0
|
||||||
short-title: Technical Book Writing Studio
|
short-title: Technical Book Writing Studio
|
||||||
description: >-
|
description: >-
|
||||||
Comprehensive AI-powered technical writing framework for technical book
|
Production-ready AI-powered technical writing framework for technical book
|
||||||
authors, technical trainers, and documentation specialists. Provides 9
|
authors, technical trainers, and documentation specialists. Provides 10
|
||||||
specialized agents, 12 core workflows with section-driven development (BMad story
|
specialized agents (9 greenfield + 1 brownfield), 12 workflows (9 greenfield + 3 brownfield),
|
||||||
analog), and professional quality assurance tools for planning, writing,
|
and professional quality assurance tools for planning, writing, revising,
|
||||||
reviewing, and publishing technical books with code examples, tutorials, and
|
reviewing, and publishing technical books with code examples, tutorials, and
|
||||||
learning objectives. Includes 18 checklists for technical accuracy, security,
|
learning objectives. Includes 21 checklists for technical accuracy, security,
|
||||||
performance, publisher compliance, accessibility, visual quality, and documentation.
|
performance, publisher compliance, accessibility, visual quality, documentation,
|
||||||
15 professional templates cover book planning, chapter development, API reference,
|
and brownfield integration. 15 professional templates cover book planning,
|
||||||
diagrams, and publishing. Section-driven workflows enable incremental chapter
|
chapter development, API reference, diagrams, publishing, book analysis, and
|
||||||
|
revision planning. Section-driven workflows enable incremental chapter
|
||||||
development (2-5 pages per section) with parallel development capabilities.
|
development (2-5 pages per section) with parallel development capabilities.
|
||||||
|
Brownfield support enables 2nd/3rd edition updates, technology version migrations,
|
||||||
|
chapter additions to existing books, and systematic reviewer feedback incorporation.
|
||||||
Supports publishers like PacktPub, O'Reilly, Manning, and self-publishing
|
Supports publishers like PacktPub, O'Reilly, Manning, and self-publishing
|
||||||
platforms (Leanpub/KDP/Gumroad).
|
platforms (Leanpub/KDP/Gumroad).
|
||||||
author: Wes
|
author: Wes
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,212 @@
|
||||||
|
<!-- Powered by BMAD™ Core -->
|
||||||
|
|
||||||
|
# Analyze Existing Book
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
task:
|
||||||
|
id: analyze-existing-book
|
||||||
|
name: Analyze Existing Technical Book
|
||||||
|
description: Deep analysis of existing book state to inform revision planning
|
||||||
|
persona_default: book-analyst
|
||||||
|
inputs:
|
||||||
|
- existing_book_path
|
||||||
|
- revision_motivation (why analyze now?)
|
||||||
|
steps:
|
||||||
|
- Scan all chapters and sections to understand book structure
|
||||||
|
- Extract book metadata (title, version, publisher, audience, publication date)
|
||||||
|
- Analyze structural organization (parts, chapters, sections, learning flow)
|
||||||
|
- Inventory all code examples (count, languages, versions, complexity)
|
||||||
|
- Identify technology versions currently used in book
|
||||||
|
- Extract writing style patterns (voice, tone, heading styles, terminology)
|
||||||
|
- Map cross-references and chapter dependencies
|
||||||
|
- Assess technical currency (what's outdated, deprecated, or broken)
|
||||||
|
- Identify inconsistencies, gaps, or quality issues
|
||||||
|
- Use template book-analysis-report-tmpl.yaml with create-doc.md task
|
||||||
|
- Generate comprehensive analysis report
|
||||||
|
output: docs/analysis/{{book_title}}-analysis-report.md
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Purpose
|
||||||
|
|
||||||
|
This task provides a systematic approach to analyzing an existing technical book before planning revisions. The analysis report becomes the foundation for all brownfield work (2nd editions, version updates, chapter additions, feedback incorporation).
|
||||||
|
|
||||||
|
## Prerequisites
|
||||||
|
|
||||||
|
Before starting this task:
|
||||||
|
|
||||||
|
- Have access to complete current book content (all chapters)
|
||||||
|
- Know why you're analyzing (new edition? version update? publisher request?)
|
||||||
|
- Understand the target audience and original publication goals
|
||||||
|
- Have access to code repository if one exists
|
||||||
|
|
||||||
|
## Workflow Steps
|
||||||
|
|
||||||
|
### 1. Scan Book Structure
|
||||||
|
|
||||||
|
Read through the entire book to understand:
|
||||||
|
|
||||||
|
- Total chapter count
|
||||||
|
- Part/section organization (if applicable)
|
||||||
|
- Front matter (preface, introduction, how to use this book)
|
||||||
|
- Back matter (appendices, glossary, index)
|
||||||
|
- Overall organization pattern (tutorial-based? reference? project-driven?)
|
||||||
|
|
||||||
|
Document the table of contents structure completely.
|
||||||
|
|
||||||
|
### 2. Extract Book Metadata
|
||||||
|
|
||||||
|
Collect core information:
|
||||||
|
|
||||||
|
- Title and subtitle
|
||||||
|
- Author(s)
|
||||||
|
- Current edition/version (1st, 2nd, 3rd)
|
||||||
|
- Publication date (original and current edition if different)
|
||||||
|
- Publisher (PacktPub, O'Reilly, Manning, Self-published)
|
||||||
|
- Target audience (skill level, role, prerequisites)
|
||||||
|
- Current page count
|
||||||
|
- ISBN or product identifiers
|
||||||
|
- Technology stack and versions
|
||||||
|
|
||||||
|
### 3. Analyze Structural Organization
|
||||||
|
|
||||||
|
Evaluate the book's architecture:
|
||||||
|
|
||||||
|
- How are chapters grouped? (By difficulty? By topic? By project?)
|
||||||
|
- Is there a clear learning progression?
|
||||||
|
- Do chapters build on each other sequentially?
|
||||||
|
- Are there standalone chapters that can be read independently?
|
||||||
|
- Is the structure appropriate for the content?
|
||||||
|
- Does the organization match publisher best practices?
|
||||||
|
|
||||||
|
### 4. Inventory Code Examples
|
||||||
|
|
||||||
|
Catalog all code comprehensively:
|
||||||
|
|
||||||
|
- Count total code examples
|
||||||
|
- List programming languages used (Python, JavaScript, Go, etc.)
|
||||||
|
- Document technology versions targeted (Python 3.9, Node 16, React 17)
|
||||||
|
- List frameworks and libraries used
|
||||||
|
- Assess code testing status (Is code tested? CI/CD? Manual only?)
|
||||||
|
- Note code repository location (GitHub, GitLab, book companion site)
|
||||||
|
- Categorize example complexity (simple snippets vs. complete projects)
|
||||||
|
- Identify code dependencies between chapters
|
||||||
|
|
||||||
|
### 5. Identify Technology Versions
|
||||||
|
|
||||||
|
For each technology mentioned in the book:
|
||||||
|
|
||||||
|
- Document current version in book
|
||||||
|
- Find latest stable version available
|
||||||
|
- Identify breaking changes since book publication
|
||||||
|
- Note deprecated features used in book
|
||||||
|
- Flag security vulnerabilities in examples
|
||||||
|
- Assess migration effort (minor updates vs. major rewrites)
|
||||||
|
|
||||||
|
### 6. Extract Writing Style Patterns
|
||||||
|
|
||||||
|
Learn the book's conventions:
|
||||||
|
|
||||||
|
- Voice and tone (conversational vs. formal, friendly vs. academic)
|
||||||
|
- Structural patterns (typical chapter flow: intro→concept→example→exercise?)
|
||||||
|
- Heading hierarchy style (action-based? question-based? topic-based?)
|
||||||
|
- Terminology choices (consistent? any jargon defined?)
|
||||||
|
- Code comment style (inline comments? docstrings? minimal?)
|
||||||
|
- Callout usage (tips, warnings, notes - frequency and style)
|
||||||
|
- Cross-reference patterns ("see Chapter X", "as discussed in Section Y.Z")
|
||||||
|
|
||||||
|
This pattern extraction is critical for maintaining consistency in revisions.
|
||||||
|
|
||||||
|
### 7. Map Cross-References and Dependencies
|
||||||
|
|
||||||
|
Document internal dependencies:
|
||||||
|
|
||||||
|
- Which chapters reference other chapters?
|
||||||
|
- What's the prerequisite flow? (must read Chapter X before Chapter Y)
|
||||||
|
- Which concepts depend on earlier concepts?
|
||||||
|
- Do any code examples build on previous examples?
|
||||||
|
- Are there forward references? ("we'll cover this in Chapter 7")
|
||||||
|
- Are there backward references? ("as we learned in Chapter 4")
|
||||||
|
|
||||||
|
Create a dependency diagram if helpful.
|
||||||
|
|
||||||
|
### 8. Assess Technical Currency
|
||||||
|
|
||||||
|
Evaluate how current the content is:
|
||||||
|
|
||||||
|
- Which sections use outdated technology versions?
|
||||||
|
- What APIs or methods are now deprecated?
|
||||||
|
- Are there breaking changes that make examples fail?
|
||||||
|
- Are security best practices current?
|
||||||
|
- Is terminology up-to-date?
|
||||||
|
- Are there discontinued tools or frameworks?
|
||||||
|
- Do examples follow current best practices?
|
||||||
|
|
||||||
|
Flag specific chapters/sections needing updates.
|
||||||
|
|
||||||
|
### 9. Identify Issues and Gaps
|
||||||
|
|
||||||
|
List problems discovered:
|
||||||
|
|
||||||
|
- Outdated sections (specific locations)
|
||||||
|
- Broken code examples (won't run on current versions)
|
||||||
|
- Inconsistencies (terminology, formatting, style variations)
|
||||||
|
- Coverage gaps (missing important topics)
|
||||||
|
- Missing deprecated warnings
|
||||||
|
- Technical inaccuracies or errors
|
||||||
|
- Unclear explanations
|
||||||
|
- Unstated assumptions or prerequisites
|
||||||
|
|
||||||
|
Be specific: note chapter and section numbers.
|
||||||
|
|
||||||
|
### 10. Generate Analysis Report
|
||||||
|
|
||||||
|
Use the create-doc.md task with book-analysis-report-tmpl.yaml template to create the structured analysis document.
|
||||||
|
|
||||||
|
The report should include all findings from steps 1-9, organized into clear sections.
|
||||||
|
|
||||||
|
### 11. Make Recommendations
|
||||||
|
|
||||||
|
Based on analysis, provide actionable guidance:
|
||||||
|
|
||||||
|
- Priority updates (critical, important, nice-to-have)
|
||||||
|
- Scope suggestions (full 2nd edition? targeted updates? version migration?)
|
||||||
|
- Timeline estimates (weeks/months for different scope levels)
|
||||||
|
- Risk assessment (what could go wrong?)
|
||||||
|
- Testing strategy recommendations
|
||||||
|
- Learning flow impact considerations
|
||||||
|
- Publisher communication needs
|
||||||
|
|
||||||
|
## Success Criteria
|
||||||
|
|
||||||
|
A completed book analysis should have:
|
||||||
|
|
||||||
|
- [ ] Complete structural understanding of existing book
|
||||||
|
- [ ] Metadata fully documented
|
||||||
|
- [ ] Code inventory complete with version information
|
||||||
|
- [ ] Technical currency assessment for all technologies
|
||||||
|
- [ ] Writing style patterns extracted
|
||||||
|
- [ ] Cross-reference map created
|
||||||
|
- [ ] All issues and gaps identified with specific locations
|
||||||
|
- [ ] Recommendations provided with priorities
|
||||||
|
- [ ] Analysis report generated and saved
|
||||||
|
- [ ] Report ready to inform revision planning
|
||||||
|
|
||||||
|
## Common Pitfalls to Avoid
|
||||||
|
|
||||||
|
- **Rushing the analysis**: Take time to read thoroughly, don't skim
|
||||||
|
- **Missing code inventory**: Must catalog ALL examples, not just major ones
|
||||||
|
- **Ignoring style patterns**: Pattern extraction is critical for consistency
|
||||||
|
- **Vague issue identification**: Be specific with chapter/section numbers
|
||||||
|
- **No prioritization**: Not all issues are equal - categorize by severity
|
||||||
|
- **Skipping cross-references**: Dependencies affect revision planning
|
||||||
|
|
||||||
|
## Next Steps
|
||||||
|
|
||||||
|
After completing the book analysis:
|
||||||
|
|
||||||
|
1. Review analysis report with stakeholders (author, publisher)
|
||||||
|
2. Use analysis to plan revision (plan-book-revision.md task)
|
||||||
|
3. Extract code patterns if planning code updates (extract-code-patterns.md)
|
||||||
|
4. Begin revision planning with clear understanding of current state
|
||||||
|
|
@ -0,0 +1,412 @@
|
||||||
|
<!-- Powered by BMAD™ Core -->
|
||||||
|
|
||||||
|
# Extract Code Patterns
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
task:
|
||||||
|
id: extract-code-patterns
|
||||||
|
name: Extract Code Patterns from Existing Book
|
||||||
|
description: Analyze existing code examples to learn style patterns for maintaining consistency in updates
|
||||||
|
persona_default: book-analyst
|
||||||
|
inputs:
|
||||||
|
- existing_book_path
|
||||||
|
- code_repository_path (if exists)
|
||||||
|
steps:
|
||||||
|
- Scan all code examples across entire book
|
||||||
|
- Identify import organization patterns (standard library first? grouped? alphabetical?)
|
||||||
|
- Note naming conventions (snake_case, camelCase, variable prefixes, class names)
|
||||||
|
- Observe comment styles (docstrings? inline? comment density? formatting)
|
||||||
|
- Extract error handling patterns (try/except usage, error messages, logging)
|
||||||
|
- Identify common code structures (class-based? functional? procedural? OOP patterns)
|
||||||
|
- Note formatting choices (indentation, line length, spacing, blank lines)
|
||||||
|
- Document code file organization patterns (imports→constants→classes→main)
|
||||||
|
- Analyze code complexity patterns (simple examples vs. comprehensive demos)
|
||||||
|
- Generate style guide summary document
|
||||||
|
- Run execute-checklist.md with existing-book-integration-checklist.md
|
||||||
|
output: docs/style/{{book_title}}-code-patterns.md
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Purpose
|
||||||
|
|
||||||
|
This task extracts code style patterns from an existing book to ensure new or updated code examples maintain consistency with the established style. Critical for brownfield work where consistency matters.
|
||||||
|
|
||||||
|
## Prerequisites
|
||||||
|
|
||||||
|
Before starting this task:
|
||||||
|
|
||||||
|
- Access to all chapters with code examples
|
||||||
|
- Access to code repository if one exists
|
||||||
|
- Understanding of programming language(s) used in book
|
||||||
|
|
||||||
|
## Workflow Steps
|
||||||
|
|
||||||
|
### 1. Scan All Code Examples
|
||||||
|
|
||||||
|
Read through the entire book systematically to collect all code examples:
|
||||||
|
|
||||||
|
- Chapter-by-chapter scan
|
||||||
|
- Count total code examples
|
||||||
|
- Categorize by type (snippets, full files, project code)
|
||||||
|
- Note which chapters have the most code
|
||||||
|
- Identify any inconsistencies between chapters
|
||||||
|
|
||||||
|
### 2. Identify Import Organization Patterns
|
||||||
|
|
||||||
|
Analyze how imports are organized:
|
||||||
|
|
||||||
|
**Python Import Patterns:**
|
||||||
|
- Order: Standard library → Third-party → Local imports?
|
||||||
|
- Grouping: Alphabetical within groups?
|
||||||
|
- Spacing: Blank lines between groups?
|
||||||
|
- Format: `import os` vs `from os import path`?
|
||||||
|
|
||||||
|
**Example Pattern Found:**
|
||||||
|
```python
|
||||||
|
# Standard library imports (alphabetical)
|
||||||
|
import json
|
||||||
|
import os
|
||||||
|
from pathlib import Path
|
||||||
|
|
||||||
|
# Third-party imports (alphabetical)
|
||||||
|
import numpy as np
|
||||||
|
import pandas as pd
|
||||||
|
from flask import Flask, request
|
||||||
|
|
||||||
|
# Local imports
|
||||||
|
from .models import User
|
||||||
|
from .utils import validate_email
|
||||||
|
```
|
||||||
|
|
||||||
|
**JavaScript Import Patterns:**
|
||||||
|
- CommonJS vs ESM?
|
||||||
|
- Named imports vs default imports?
|
||||||
|
- Import order conventions?
|
||||||
|
|
||||||
|
Document the pattern consistently used throughout the book.
|
||||||
|
|
||||||
|
### 3. Note Naming Conventions
|
||||||
|
|
||||||
|
Extract naming patterns used:
|
||||||
|
|
||||||
|
**Variables:**
|
||||||
|
- snake_case, camelCase, or PascalCase?
|
||||||
|
- Descriptive names or short names?
|
||||||
|
- Any prefixes? (e.g., `str_name`, `is_valid`, `has_permission`)
|
||||||
|
|
||||||
|
**Functions:**
|
||||||
|
- Naming style? (snake_case for Python, camelCase for JavaScript?)
|
||||||
|
- Verb-based names? (get_user, calculate_total, validate_input)
|
||||||
|
- Prefix patterns? (is_valid, has_items, can_delete)
|
||||||
|
|
||||||
|
**Classes:**
|
||||||
|
- PascalCase? (UserAccount, DatabaseConnection)
|
||||||
|
- Singular vs plural? (User vs Users)
|
||||||
|
- Suffix patterns? (UserManager, DataProcessor, HTMLRenderer)
|
||||||
|
|
||||||
|
**Constants:**
|
||||||
|
- UPPER_SNAKE_CASE?
|
||||||
|
- Placement? (top of file? separate config file?)
|
||||||
|
|
||||||
|
**Example Pattern Found:**
|
||||||
|
```python
|
||||||
|
# Constants: UPPER_SNAKE_CASE
|
||||||
|
MAX_RETRIES = 3
|
||||||
|
DEFAULT_TIMEOUT = 30
|
||||||
|
|
||||||
|
# Functions: snake_case, verb-based
|
||||||
|
def calculate_total(items):
|
||||||
|
pass
|
||||||
|
|
||||||
|
def is_valid_email(email):
|
||||||
|
pass
|
||||||
|
|
||||||
|
# Classes: PascalCase, singular nouns
|
||||||
|
class UserAccount:
|
||||||
|
pass
|
||||||
|
|
||||||
|
class DatabaseConnection:
|
||||||
|
pass
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Observe Comment Styles
|
||||||
|
|
||||||
|
Analyze commenting patterns:
|
||||||
|
|
||||||
|
**Docstrings:**
|
||||||
|
- Present? (always, sometimes, rarely?)
|
||||||
|
- Format? (Google style, NumPy style, Sphinx style?)
|
||||||
|
- What's documented? (all functions? only public APIs?)
|
||||||
|
|
||||||
|
**Inline Comments:**
|
||||||
|
- Frequency? (heavy, moderate, minimal?)
|
||||||
|
- Style? (full sentences? fragments? end-of-line? above code?)
|
||||||
|
- Purpose? (explain why? explain what? both?)
|
||||||
|
|
||||||
|
**File Headers:**
|
||||||
|
- Module docstrings?
|
||||||
|
- Author, date, description?
|
||||||
|
- License information?
|
||||||
|
|
||||||
|
**Example Pattern Found:**
|
||||||
|
```python
|
||||||
|
def calculate_discount(price, discount_percent):
|
||||||
|
"""
|
||||||
|
Calculate discounted price.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
price (float): Original price
|
||||||
|
discount_percent (float): Discount percentage (0-100)
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
float: Discounted price
|
||||||
|
"""
|
||||||
|
# Convert percentage to decimal
|
||||||
|
discount_decimal = discount_percent / 100
|
||||||
|
|
||||||
|
# Apply discount
|
||||||
|
return price * (1 - discount_decimal)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5. Extract Error Handling Patterns
|
||||||
|
|
||||||
|
Identify error handling approaches:
|
||||||
|
|
||||||
|
**Exception Handling:**
|
||||||
|
- try/except usage frequency?
|
||||||
|
- Specific exceptions caught or broad Exception?
|
||||||
|
- Error message style?
|
||||||
|
- Logging patterns?
|
||||||
|
- Re-raising exceptions?
|
||||||
|
|
||||||
|
**Validation:**
|
||||||
|
- Input validation at function start?
|
||||||
|
- Assertions used?
|
||||||
|
- Guard clauses?
|
||||||
|
|
||||||
|
**Example Pattern Found:**
|
||||||
|
```python
|
||||||
|
def process_user(user_id):
|
||||||
|
"""Process user with comprehensive error handling."""
|
||||||
|
if not user_id:
|
||||||
|
raise ValueError("user_id is required")
|
||||||
|
|
||||||
|
try:
|
||||||
|
user = User.objects.get(id=user_id)
|
||||||
|
except User.DoesNotExist:
|
||||||
|
logger.error(f"User {user_id} not found")
|
||||||
|
return None
|
||||||
|
except DatabaseError as e:
|
||||||
|
logger.error(f"Database error: {e}")
|
||||||
|
raise
|
||||||
|
|
||||||
|
return user
|
||||||
|
```
|
||||||
|
|
||||||
|
### 6. Identify Code Structure Patterns
|
||||||
|
|
||||||
|
Analyze overall code organization:
|
||||||
|
|
||||||
|
**Programming Paradigm:**
|
||||||
|
- Object-oriented? (classes, inheritance, polymorphism)
|
||||||
|
- Functional? (pure functions, immutability, higher-order functions)
|
||||||
|
- Procedural? (step-by-step scripts)
|
||||||
|
- Mixed? (where and why?)
|
||||||
|
|
||||||
|
**Design Patterns:**
|
||||||
|
- Any common patterns? (Factory, Singleton, Observer, etc.)
|
||||||
|
- Consistent pattern usage across examples?
|
||||||
|
|
||||||
|
**Code Organization:**
|
||||||
|
- File structure patterns?
|
||||||
|
- Class organization patterns (properties→init→public→private)?
|
||||||
|
- Module organization patterns?
|
||||||
|
|
||||||
|
**Example Pattern Found:**
|
||||||
|
```
|
||||||
|
File organization:
|
||||||
|
1. Module docstring
|
||||||
|
2. Imports (stdlib, third-party, local)
|
||||||
|
3. Constants
|
||||||
|
4. Helper functions
|
||||||
|
5. Main classes
|
||||||
|
6. if __name__ == '__main__' block
|
||||||
|
```
|
||||||
|
|
||||||
|
### 7. Note Formatting Choices
|
||||||
|
|
||||||
|
Document formatting standards:
|
||||||
|
|
||||||
|
**Indentation:**
|
||||||
|
- Spaces or tabs? (Python: 4 spaces is PEP 8)
|
||||||
|
- Consistent indentation levels?
|
||||||
|
|
||||||
|
**Line Length:**
|
||||||
|
- Maximum line length? (79, 88, 100, 120 chars?)
|
||||||
|
- Line breaking style?
|
||||||
|
|
||||||
|
**Spacing:**
|
||||||
|
- Blank lines between functions? (2 for top-level, 1 for methods?)
|
||||||
|
- Spacing around operators? (a + b vs a+b)
|
||||||
|
- Spacing in function calls? (func(a, b) vs func( a, b ))
|
||||||
|
|
||||||
|
**Quotes:**
|
||||||
|
- Single or double quotes?
|
||||||
|
- Consistency?
|
||||||
|
|
||||||
|
**Example Pattern Found:**
|
||||||
|
```
|
||||||
|
- Indentation: 4 spaces (never tabs)
|
||||||
|
- Line length: 88 characters maximum
|
||||||
|
- Blank lines: 2 between top-level definitions, 1 between methods
|
||||||
|
- Quotes: Double quotes for strings, single for identifiers
|
||||||
|
- Operators: Spaces around (x = y + 2, not x=y+2)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 8. Document Code File Organization
|
||||||
|
|
||||||
|
Identify file structure patterns:
|
||||||
|
|
||||||
|
**Import Section:**
|
||||||
|
- Always at top?
|
||||||
|
- Grouped and ordered how?
|
||||||
|
|
||||||
|
**Constants Section:**
|
||||||
|
- After imports?
|
||||||
|
- Separate section?
|
||||||
|
|
||||||
|
**Class Definitions:**
|
||||||
|
- Order? (base classes first? main classes first?)
|
||||||
|
- Internal organization? (properties→__init__→public→private?)
|
||||||
|
|
||||||
|
**Main Execution:**
|
||||||
|
- `if __name__ == '__main__'` block?
|
||||||
|
- main() function pattern?
|
||||||
|
|
||||||
|
**Example Pattern Found:**
|
||||||
|
```python
|
||||||
|
# 1. Module docstring
|
||||||
|
"""
|
||||||
|
Module for user authentication.
|
||||||
|
"""
|
||||||
|
|
||||||
|
# 2. Imports
|
||||||
|
import os
|
||||||
|
from typing import Optional
|
||||||
|
|
||||||
|
# 3. Constants
|
||||||
|
DEFAULT_TIMEOUT = 30
|
||||||
|
|
||||||
|
# 4. Helper functions
|
||||||
|
def _internal_helper():
|
||||||
|
pass
|
||||||
|
|
||||||
|
# 5. Main classes
|
||||||
|
class UserAuth:
|
||||||
|
pass
|
||||||
|
|
||||||
|
# 6. Main execution
|
||||||
|
if __name__ == '__main__':
|
||||||
|
main()
|
||||||
|
```
|
||||||
|
|
||||||
|
### 9. Analyze Code Complexity Patterns
|
||||||
|
|
||||||
|
Understand example complexity distribution:
|
||||||
|
|
||||||
|
**Simple Snippets:**
|
||||||
|
- How many? (percentage of total examples)
|
||||||
|
- Purpose? (demonstrate single concept)
|
||||||
|
- Typical length? (5-10 lines)
|
||||||
|
|
||||||
|
**Medium Examples:**
|
||||||
|
- How many?
|
||||||
|
- Purpose? (demonstrate technique in context)
|
||||||
|
- Typical length? (20-50 lines)
|
||||||
|
|
||||||
|
**Complete Projects:**
|
||||||
|
- How many?
|
||||||
|
- Purpose? (demonstrate full application)
|
||||||
|
- Typical length? (100+ lines, multiple files)
|
||||||
|
|
||||||
|
This helps maintain appropriate complexity when adding new examples.
|
||||||
|
|
||||||
|
### 10. Generate Style Guide Summary
|
||||||
|
|
||||||
|
Create comprehensive code-patterns.md document with all findings:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Code Style Patterns for [Book Title]
|
||||||
|
|
||||||
|
## Import Organization
|
||||||
|
[Document pattern]
|
||||||
|
|
||||||
|
## Naming Conventions
|
||||||
|
[Document pattern]
|
||||||
|
|
||||||
|
## Comment Styles
|
||||||
|
[Document pattern]
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
[Document pattern]
|
||||||
|
|
||||||
|
## Code Structure
|
||||||
|
[Document pattern]
|
||||||
|
|
||||||
|
## Formatting
|
||||||
|
[Document pattern]
|
||||||
|
|
||||||
|
## File Organization
|
||||||
|
[Document pattern]
|
||||||
|
|
||||||
|
## Complexity Guidelines
|
||||||
|
[Document pattern]
|
||||||
|
|
||||||
|
## Examples
|
||||||
|
[Provide examples of well-styled code from the book]
|
||||||
|
```
|
||||||
|
|
||||||
|
This document becomes the reference for all new/updated code.
|
||||||
|
|
||||||
|
### 11. Validate with Integration Checklist
|
||||||
|
|
||||||
|
Run execute-checklist.md with existing-book-integration-checklist.md to ensure:
|
||||||
|
|
||||||
|
- Code patterns are comprehensive
|
||||||
|
- Patterns are consistent across book
|
||||||
|
- Examples are clear and representative
|
||||||
|
- New code can match extracted patterns
|
||||||
|
|
||||||
|
## Success Criteria
|
||||||
|
|
||||||
|
A completed code pattern extraction should have:
|
||||||
|
|
||||||
|
- [ ] All code examples analyzed
|
||||||
|
- [ ] Import patterns documented
|
||||||
|
- [ ] Naming conventions extracted
|
||||||
|
- [ ] Comment styles identified
|
||||||
|
- [ ] Error handling patterns noted
|
||||||
|
- [ ] Code structure patterns documented
|
||||||
|
- [ ] Formatting choices specified
|
||||||
|
- [ ] File organization patterns defined
|
||||||
|
- [ ] Complexity patterns understood
|
||||||
|
- [ ] Comprehensive style guide created
|
||||||
|
- [ ] Integration checklist passed
|
||||||
|
|
||||||
|
## Common Pitfalls to Avoid
|
||||||
|
|
||||||
|
- **Inconsistency analysis**: If book has inconsistent patterns, document the *most common* pattern and note variations
|
||||||
|
- **Over-specificity**: Extract patterns, not rigid rules that prevent good code
|
||||||
|
- **Ignoring context**: Some chapters may intentionally use different patterns (e.g., teaching different styles)
|
||||||
|
- **Missing examples**: Include code examples in style guide for clarity
|
||||||
|
|
||||||
|
## Next Steps
|
||||||
|
|
||||||
|
After extracting code patterns:
|
||||||
|
|
||||||
|
1. Use style guide when writing new code examples
|
||||||
|
2. Apply patterns when updating existing code
|
||||||
|
3. Share style guide with technical reviewers
|
||||||
|
4. Reference in existing-book-integration-checklist.md
|
||||||
|
5. Update style guide if patterns evolve
|
||||||
|
|
@ -0,0 +1,317 @@
|
||||||
|
<!-- Powered by BMAD™ Core -->
|
||||||
|
|
||||||
|
# Incorporate Reviewer Feedback
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
task:
|
||||||
|
id: incorporate-reviewer-feedback
|
||||||
|
name: Systematically Incorporate Reviewer Feedback
|
||||||
|
description: Process and address technical reviewer, publisher, and beta reader feedback systematically
|
||||||
|
persona_default: book-analyst
|
||||||
|
inputs:
|
||||||
|
- reviewer_feedback (technical review comments, publisher requests, beta reader notes)
|
||||||
|
- affected_chapters
|
||||||
|
steps:
|
||||||
|
- Collect all reviewer feedback from all sources (technical, publisher, beta readers)
|
||||||
|
- Categorize feedback by severity (critical/must-fix, important/should-fix, optional/nice-to-have)
|
||||||
|
- Create feedback tracking log with status for each item
|
||||||
|
- Address critical issues first (technical errors, broken code, security issues)
|
||||||
|
- Fix important issues (clarity problems, missing examples, structural issues)
|
||||||
|
- Consider optional suggestions (enhancements, additional topics, style preferences)
|
||||||
|
- Test all code changes from feedback
|
||||||
|
- Update text for clarity improvements requested
|
||||||
|
- Track completion status in feedback log
|
||||||
|
- Generate feedback-resolution-log documenting all changes
|
||||||
|
- Run execute-checklist.md with existing-book-integration-checklist.md
|
||||||
|
output: docs/feedback/{{book_title}}-feedback-resolution-log.md
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Purpose
|
||||||
|
|
||||||
|
This task provides a systematic approach to processing reviewer feedback from technical reviewers, publishers, and beta readers. Ensures all feedback is triaged, addressed appropriately, and tracked to completion.
|
||||||
|
|
||||||
|
## Prerequisites
|
||||||
|
|
||||||
|
Before starting this task:
|
||||||
|
|
||||||
|
- Reviewer feedback collected from all sources
|
||||||
|
- Chapters are in reviewable state
|
||||||
|
- Testing environment set up for code changes
|
||||||
|
- Understanding of feedback priorities (which issues are critical)
|
||||||
|
|
||||||
|
## Workflow Steps
|
||||||
|
|
||||||
|
### 1. Collect All Reviewer Feedback
|
||||||
|
|
||||||
|
Gather feedback from all sources:
|
||||||
|
|
||||||
|
**Technical Reviewer Feedback:**
|
||||||
|
- Technical accuracy issues
|
||||||
|
- Code errors or improvements
|
||||||
|
- Misleading explanations
|
||||||
|
- Missing prerequisites
|
||||||
|
- Incorrect terminology
|
||||||
|
|
||||||
|
**Publisher Feedback:**
|
||||||
|
- Format compliance issues
|
||||||
|
- Style guide violations
|
||||||
|
- Length adjustments needed
|
||||||
|
- Market positioning changes
|
||||||
|
- Legal/licensing concerns
|
||||||
|
|
||||||
|
**Beta Reader Feedback:**
|
||||||
|
- Clarity problems
|
||||||
|
- Confusing sections
|
||||||
|
- Missing examples
|
||||||
|
- Difficulty level issues
|
||||||
|
- Typos and errors
|
||||||
|
|
||||||
|
Consolidate into a single master feedback list.
|
||||||
|
|
||||||
|
### 2. Categorize Feedback by Severity
|
||||||
|
|
||||||
|
Triage each feedback item into priority categories:
|
||||||
|
|
||||||
|
**Critical (Must-Fix):**
|
||||||
|
- Technical errors (incorrect information)
|
||||||
|
- Broken code examples (won't run)
|
||||||
|
- Security vulnerabilities
|
||||||
|
- Legal/licensing issues
|
||||||
|
- Publisher blocking issues (won't publish without fix)
|
||||||
|
- Major clarity problems (readers can't follow)
|
||||||
|
|
||||||
|
**Important (Should-Fix):**
|
||||||
|
- Unclear explanations (could be clearer)
|
||||||
|
- Missing examples (would help understanding)
|
||||||
|
- Structural issues (better organization possible)
|
||||||
|
- Incomplete coverage (topic needs expansion)
|
||||||
|
- Style inconsistencies
|
||||||
|
- Minor technical inaccuracies
|
||||||
|
|
||||||
|
**Nice-to-Have (Optional):**
|
||||||
|
- Style preferences (subjective improvements)
|
||||||
|
- Additional topics (scope expansion)
|
||||||
|
- Enhancement suggestions
|
||||||
|
- Alternative explanations
|
||||||
|
- Personal preferences
|
||||||
|
|
||||||
|
### 3. Create Feedback Tracking Log
|
||||||
|
|
||||||
|
Build a structured tracking system:
|
||||||
|
|
||||||
|
| ID | Chapter | Severity | Issue | Requested By | Status | Resolution | Date |
|
||||||
|
|----|---------|----------|-------|--------------|--------|------------|------|
|
||||||
|
| F001 | Ch 3 | Critical | Code won't run Python 3.12 | Tech Review | Done | Fixed import | 2024-01-15 |
|
||||||
|
| F002 | Ch 5 | Important | Unclear JWT explanation | Beta Reader | Done | Added example | 2024-01-16 |
|
||||||
|
| F003 | Ch 7 | Optional | Add async/await example | Tech Review | Deferred | Future edition | 2024-01-16 |
|
||||||
|
|
||||||
|
This provides visibility into progress and ensures nothing is missed.
|
||||||
|
|
||||||
|
### 4. Address Critical Issues First
|
||||||
|
|
||||||
|
Start with must-fix items:
|
||||||
|
|
||||||
|
**For Technical Errors:**
|
||||||
|
- Verify the error (confirm it's incorrect)
|
||||||
|
- Research the correct information
|
||||||
|
- Update text and code
|
||||||
|
- Test updated code
|
||||||
|
- Add verification note to tracking log
|
||||||
|
|
||||||
|
**For Broken Code:**
|
||||||
|
- Reproduce the issue
|
||||||
|
- Fix the code
|
||||||
|
- Test on target version(s)
|
||||||
|
- Verify output is correct
|
||||||
|
- Update text if output changed
|
||||||
|
|
||||||
|
**For Security Issues:**
|
||||||
|
- Assess severity (CVSS score if applicable)
|
||||||
|
- Fix immediately
|
||||||
|
- Add security note if appropriate
|
||||||
|
- Test fix thoroughly
|
||||||
|
- Document in change log
|
||||||
|
|
||||||
|
**For Publisher Blocking Issues:**
|
||||||
|
- Understand exact requirement
|
||||||
|
- Implement change
|
||||||
|
- Verify compliance
|
||||||
|
- Get publisher confirmation
|
||||||
|
- Mark resolved
|
||||||
|
|
||||||
|
Do not proceed to lower-priority items until all critical issues are resolved.
|
||||||
|
|
||||||
|
### 5. Fix Important Issues
|
||||||
|
|
||||||
|
Address should-fix items systematically:
|
||||||
|
|
||||||
|
**For Clarity Problems:**
|
||||||
|
- Identify specific unclear section
|
||||||
|
- Rewrite for clarity
|
||||||
|
- Add examples if needed
|
||||||
|
- Get second opinion (beta reader, colleague)
|
||||||
|
- Update tracking log
|
||||||
|
|
||||||
|
**For Missing Examples:**
|
||||||
|
- Understand what example is needed
|
||||||
|
- Design example that teaches the concept
|
||||||
|
- Write and test code
|
||||||
|
- Integrate into chapter
|
||||||
|
- Verify it improves understanding
|
||||||
|
|
||||||
|
**For Structural Issues:**
|
||||||
|
- Assess reorganization impact
|
||||||
|
- Plan structural change
|
||||||
|
- Reorganize content
|
||||||
|
- Update cross-references
|
||||||
|
- Verify learning flow still works
|
||||||
|
|
||||||
|
**For Incomplete Coverage:**
|
||||||
|
- Determine scope of addition
|
||||||
|
- Write additional content
|
||||||
|
- Test any new code
|
||||||
|
- Integrate smoothly
|
||||||
|
- Ensure doesn't bloat chapter excessively
|
||||||
|
|
||||||
|
### 6. Consider Optional Suggestions
|
||||||
|
|
||||||
|
Evaluate nice-to-have items carefully:
|
||||||
|
|
||||||
|
**Decision Criteria:**
|
||||||
|
- Does it improve reader experience?
|
||||||
|
- Is it within scope of current edition?
|
||||||
|
- Do I have time/space for this?
|
||||||
|
- Does it align with book goals?
|
||||||
|
|
||||||
|
**Actions:**
|
||||||
|
- **Implement**: If valuable and feasible
|
||||||
|
- **Defer**: If good idea but not for this edition (document for next edition)
|
||||||
|
- **Decline**: If not aligned with book goals (document reason)
|
||||||
|
|
||||||
|
Document all decisions in tracking log, even for declined items.
|
||||||
|
|
||||||
|
### 7. Test All Code Changes
|
||||||
|
|
||||||
|
For every code change made from feedback:
|
||||||
|
|
||||||
|
- Test code runs successfully
|
||||||
|
- Test on target version(s)
|
||||||
|
- Verify output matches text
|
||||||
|
- Check for new errors or warnings
|
||||||
|
- Run regression tests (ensure other examples still work)
|
||||||
|
- Update code repository
|
||||||
|
|
||||||
|
No code changes should be marked complete without testing.
|
||||||
|
|
||||||
|
### 8. Update Text for Clarity
|
||||||
|
|
||||||
|
For text improvements from feedback:
|
||||||
|
|
||||||
|
- Rewrite unclear sections
|
||||||
|
- Add clarifying examples
|
||||||
|
- Improve explanations
|
||||||
|
- Fix terminology inconsistencies
|
||||||
|
- Verify technical accuracy
|
||||||
|
- Ensure voice/tone consistency
|
||||||
|
|
||||||
|
Use extracted code patterns and style guide to maintain consistency.
|
||||||
|
|
||||||
|
### 9. Track Completion Status
|
||||||
|
|
||||||
|
Update feedback tracking log continuously:
|
||||||
|
|
||||||
|
- Mark items as "In Progress" when starting
|
||||||
|
- Mark as "Done" when complete and tested
|
||||||
|
- Mark as "Deferred" if postponing to next edition
|
||||||
|
- Mark as "Declined" if not implementing (with reason)
|
||||||
|
- Add completion date
|
||||||
|
- Add resolution notes
|
||||||
|
|
||||||
|
This creates accountability and progress visibility.
|
||||||
|
|
||||||
|
### 10. Generate Feedback Resolution Log
|
||||||
|
|
||||||
|
Create comprehensive document summarizing all feedback processing:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Feedback Resolution Log - [Book Title]
|
||||||
|
|
||||||
|
## Summary
|
||||||
|
- Total feedback items: 47
|
||||||
|
- Critical (resolved): 8/8
|
||||||
|
- Important (resolved): 23/25 (2 deferred)
|
||||||
|
- Optional (resolved): 7/14 (4 deferred, 3 declined)
|
||||||
|
|
||||||
|
## Critical Issues Resolved
|
||||||
|
[List with details]
|
||||||
|
|
||||||
|
## Important Issues Resolved
|
||||||
|
[List with details]
|
||||||
|
|
||||||
|
## Deferred Items
|
||||||
|
[List with rationale and target edition]
|
||||||
|
|
||||||
|
## Declined Items
|
||||||
|
[List with rationale]
|
||||||
|
|
||||||
|
## Code Changes
|
||||||
|
[List all code changes made]
|
||||||
|
|
||||||
|
## Text Changes
|
||||||
|
[List major text revisions]
|
||||||
|
|
||||||
|
## Reviewer Acknowledgments
|
||||||
|
[Thank reviewers]
|
||||||
|
```
|
||||||
|
|
||||||
|
This document provides transparency and completeness.
|
||||||
|
|
||||||
|
### 11. Run Integration Checklist
|
||||||
|
|
||||||
|
Use execute-checklist.md with existing-book-integration-checklist.md to ensure:
|
||||||
|
|
||||||
|
- Changes maintain consistency with existing content
|
||||||
|
- Voice and tone are consistent
|
||||||
|
- Code patterns are followed
|
||||||
|
- Cross-references are accurate
|
||||||
|
- Learning flow is maintained
|
||||||
|
|
||||||
|
## Success Criteria
|
||||||
|
|
||||||
|
A completed feedback incorporation should have:
|
||||||
|
|
||||||
|
- [ ] All feedback collected from all sources
|
||||||
|
- [ ] Feedback categorized by severity
|
||||||
|
- [ ] Tracking log created and maintained
|
||||||
|
- [ ] All critical issues resolved
|
||||||
|
- [ ] All important issues addressed or consciously deferred
|
||||||
|
- [ ] Optional items evaluated (implement, defer, or decline)
|
||||||
|
- [ ] All code changes tested
|
||||||
|
- [ ] Text clarity improvements made
|
||||||
|
- [ ] Completion status tracked for every item
|
||||||
|
- [ ] Feedback resolution log generated
|
||||||
|
- [ ] Integration checklist passed
|
||||||
|
- [ ] No blocking issues remain
|
||||||
|
|
||||||
|
## Common Pitfalls to Avoid
|
||||||
|
|
||||||
|
- **Ignoring low-severity feedback**: Track and evaluate all feedback, even if declining
|
||||||
|
- **No prioritization**: Must address critical items first
|
||||||
|
- **Scope creep**: Optional items can expand scope significantly - be disciplined
|
||||||
|
- **Poor tracking**: Without tracking, items get missed
|
||||||
|
- **Untested changes**: All code changes must be tested
|
||||||
|
- **Inconsistent voice**: Text changes must match existing style
|
||||||
|
- **No documentation**: Document what changed and why
|
||||||
|
|
||||||
|
## Next Steps
|
||||||
|
|
||||||
|
After incorporating feedback:
|
||||||
|
|
||||||
|
1. Send resolution log to reviewers for confirmation
|
||||||
|
2. Request final approval from technical reviewer
|
||||||
|
3. Get publisher sign-off on critical fixes
|
||||||
|
4. Proceed to final editorial review
|
||||||
|
5. Prepare for publication
|
||||||
|
6. Archive deferred items for next edition planning
|
||||||
|
|
@ -0,0 +1,318 @@
|
||||||
|
<!-- Powered by BMAD™ Core -->
|
||||||
|
|
||||||
|
# Plan Book Revision
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
task:
|
||||||
|
id: plan-book-revision
|
||||||
|
name: Plan Book Revision Strategy
|
||||||
|
description: Create strategic plan for updating existing technical book (2nd/3rd edition, version updates, chapter additions)
|
||||||
|
persona_default: book-analyst
|
||||||
|
inputs:
|
||||||
|
- book_analysis_report (from analyze-existing-book.md)
|
||||||
|
- revision_type (new edition, version update, chapter addition, feedback incorporation)
|
||||||
|
- target_versions (if applicable)
|
||||||
|
steps:
|
||||||
|
- Review book analysis report to understand current state
|
||||||
|
- Define revision scope (full edition? specific chapters? code-only? text-only?)
|
||||||
|
- Identify all technology version changes needed
|
||||||
|
- Create chapter revision matrix (complexity, effort, priority for each chapter)
|
||||||
|
- Assess impact on learning progression and flow
|
||||||
|
- Plan code testing strategy across target versions
|
||||||
|
- Define timeline with phases and milestones
|
||||||
|
- Identify chapter dependencies and critical path
|
||||||
|
- Set success criteria and quality gates
|
||||||
|
- Assess risks and create mitigation plans
|
||||||
|
- Use template revision-plan-tmpl.yaml with create-doc.md task
|
||||||
|
- Run execute-checklist.md with revision-completeness-checklist.md
|
||||||
|
- Generate comprehensive revision plan
|
||||||
|
output: docs/planning/{{book_title}}-revision-plan.md
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Purpose
|
||||||
|
|
||||||
|
This task transforms the book analysis into an actionable revision plan. It defines scope, priorities, timeline, and success criteria for updating an existing technical book. The revision plan guides all subsequent brownfield work.
|
||||||
|
|
||||||
|
## Prerequisites
|
||||||
|
|
||||||
|
Before starting this task:
|
||||||
|
|
||||||
|
- Book analysis report completed (from analyze-existing-book.md)
|
||||||
|
- Clear understanding of revision motivation (why update now?)
|
||||||
|
- Target technology versions identified (if version update)
|
||||||
|
- Publisher requirements or deadlines known (if applicable)
|
||||||
|
- Access to stakeholders for scope decisions
|
||||||
|
|
||||||
|
## Workflow Steps
|
||||||
|
|
||||||
|
### 1. Review Book Analysis Report
|
||||||
|
|
||||||
|
Thoroughly review the analysis report to understand:
|
||||||
|
|
||||||
|
- Current book structure and content
|
||||||
|
- Issues and gaps identified
|
||||||
|
- Technical currency assessment
|
||||||
|
- Recommendations provided
|
||||||
|
- Code inventory and version information
|
||||||
|
|
||||||
|
This analysis is your foundation for planning.
|
||||||
|
|
||||||
|
### 2. Define Revision Scope
|
||||||
|
|
||||||
|
Determine the type and extent of revision:
|
||||||
|
|
||||||
|
**Revision Type:**
|
||||||
|
- New edition (2nd, 3rd)? - Full book revision
|
||||||
|
- Technology version update? - Update code and related text
|
||||||
|
- Chapter additions? - New content integration
|
||||||
|
- Reviewer feedback incorporation? - Targeted fixes
|
||||||
|
- Publisher-requested changes? - Specific modifications
|
||||||
|
|
||||||
|
**Scope Level:**
|
||||||
|
- Full book revision (all chapters)
|
||||||
|
- Specific chapters only (which ones?)
|
||||||
|
- Code examples only (no text changes)
|
||||||
|
- Text updates only (no code changes)
|
||||||
|
- Mixed (some chapters full revision, others minor updates)
|
||||||
|
|
||||||
|
**Triggers:** Why now?
|
||||||
|
- New technology version released
|
||||||
|
- Publisher request for new edition
|
||||||
|
- Market demand or competition
|
||||||
|
- Technical debt accumulated
|
||||||
|
- Reviewer or reader feedback
|
||||||
|
|
||||||
|
**Goals:** What does success look like?
|
||||||
|
- Updated to latest technology versions
|
||||||
|
- All broken examples fixed
|
||||||
|
- New features demonstrated
|
||||||
|
- Improved clarity and accuracy
|
||||||
|
- Publisher approval secured
|
||||||
|
|
||||||
|
**Constraints:**
|
||||||
|
- Timeline (publisher deadline, market window)
|
||||||
|
- Budget (author time, technical review costs)
|
||||||
|
- Resources (access to testers, reviewers)
|
||||||
|
|
||||||
|
### 3. Identify Technology Version Changes
|
||||||
|
|
||||||
|
For each technology in the book, document:
|
||||||
|
|
||||||
|
- Current version in book (e.g., Python 3.9)
|
||||||
|
- Target version for revision (e.g., Python 3.12)
|
||||||
|
- Breaking changes between versions
|
||||||
|
- New features to incorporate
|
||||||
|
- Deprecated features to replace
|
||||||
|
- Migration effort estimate (low/medium/high)
|
||||||
|
|
||||||
|
Example:
|
||||||
|
- Python: 3.9 → 3.12 (Medium - add match/case, update deprecated methods)
|
||||||
|
- Django: 3.2 → 4.2 (High - significant async changes, new admin features)
|
||||||
|
- PostgreSQL: 13 → 15 (Low - mostly backward compatible, add new JSON features)
|
||||||
|
|
||||||
|
### 4. Create Chapter Revision Matrix
|
||||||
|
|
||||||
|
For each chapter, define revision needs:
|
||||||
|
|
||||||
|
| Chapter | Title | Complexity | Effort | Priority | Changes Needed |
|
||||||
|
|---------|-------|------------|--------|----------|----------------|
|
||||||
|
| 1 | Introduction | Low | 2h | Important | Update version refs |
|
||||||
|
| 2 | Basic Syntax | High | 8h | Critical | Add match/case (Python 3.10+) |
|
||||||
|
| 3 | Functions | Medium | 5h | Important | Update type hints syntax |
|
||||||
|
| ... | ... | ... | ... | ... | ... |
|
||||||
|
|
||||||
|
**Complexity Levels:**
|
||||||
|
- **Low**: Minor text updates, version number changes, small corrections
|
||||||
|
- **Medium**: Code updates, new examples, moderate text revisions
|
||||||
|
- **High**: Significant rewrites, new sections, major code changes
|
||||||
|
|
||||||
|
**Effort Estimates:** Hours per chapter (be realistic)
|
||||||
|
|
||||||
|
**Priority Levels:**
|
||||||
|
- **Critical**: Must fix (broken code, security issues, major inaccuracies)
|
||||||
|
- **Important**: Should fix (outdated best practices, missing features)
|
||||||
|
- **Nice-to-have**: Optional improvements (polish, minor enhancements)
|
||||||
|
|
||||||
|
### 5. Assess Learning Flow Impact
|
||||||
|
|
||||||
|
Consider how revisions affect pedagogical progression:
|
||||||
|
|
||||||
|
- Does changing Chapter 3 affect Chapters 4-10 that build on it?
|
||||||
|
- If adding new content, where does it fit in the learning sequence?
|
||||||
|
- Will version changes alter the difficulty curve?
|
||||||
|
- Do prerequisite requirements change?
|
||||||
|
- Will the learning objectives still be met?
|
||||||
|
|
||||||
|
Consult learning-frameworks.md for pedagogical best practices.
|
||||||
|
|
||||||
|
### 6. Plan Code Testing Strategy
|
||||||
|
|
||||||
|
Define how you'll validate all code updates:
|
||||||
|
|
||||||
|
**Testing Approach:**
|
||||||
|
- Manual testing (run each example)
|
||||||
|
- Automated testing (unit tests, integration tests)
|
||||||
|
- CI/CD pipeline (automated validation on commits)
|
||||||
|
|
||||||
|
**Version Matrix:**
|
||||||
|
- Which versions to test? (Python 3.10, 3.11, 3.12? or just 3.12?)
|
||||||
|
- Multiple platforms? (Windows, macOS, Linux)
|
||||||
|
- Multiple environments? (development, production)
|
||||||
|
|
||||||
|
**Tool Requirements:**
|
||||||
|
- Testing frameworks (pytest, Jest, etc.)
|
||||||
|
- Linters (pylint, ESLint, etc.)
|
||||||
|
- Code formatters (black, prettier, etc.)
|
||||||
|
|
||||||
|
**Repository Updates:**
|
||||||
|
- Update code repository structure
|
||||||
|
- Add/update tests
|
||||||
|
- Update documentation (README, setup instructions)
|
||||||
|
|
||||||
|
**Regression Testing:**
|
||||||
|
- Test unchanged examples still work
|
||||||
|
- Verify backward compatibility where needed
|
||||||
|
|
||||||
|
### 7. Define Timeline and Milestones
|
||||||
|
|
||||||
|
Break revision into phases with realistic estimates:
|
||||||
|
|
||||||
|
**Example Timeline (14-week revision):**
|
||||||
|
|
||||||
|
**Phase 1: Analysis and Planning (Weeks 1-2)**
|
||||||
|
- Week 1: Complete book analysis
|
||||||
|
- Week 2: Finalize revision plan, set up testing environment
|
||||||
|
|
||||||
|
**Phase 2: Chapter Revisions (Weeks 3-10)**
|
||||||
|
- Weeks 3-4: Chapters 1-5 (Critical priority)
|
||||||
|
- Weeks 5-6: Chapters 6-10 (Critical priority)
|
||||||
|
- Weeks 7-8: Chapters 11-15 (Important priority)
|
||||||
|
- Weeks 9-10: Review, polish, and nice-to-haves
|
||||||
|
|
||||||
|
**Phase 3: Testing and QA (Weeks 11-12)**
|
||||||
|
- Week 11: Code testing across all target versions
|
||||||
|
- Week 12: Technical review and editorial review
|
||||||
|
|
||||||
|
**Phase 4: Finalization (Weeks 13-14)**
|
||||||
|
- Week 13: Incorporate feedback, final revisions
|
||||||
|
- Week 14: Final formatting, publisher submission
|
||||||
|
|
||||||
|
**Critical Path:** Which tasks block others?
|
||||||
|
- Must complete Python version update before testing
|
||||||
|
- Must finish technical review before editorial review
|
||||||
|
- Must have all chapters revised before final formatting
|
||||||
|
|
||||||
|
**Dependencies:** What must complete before next phase?
|
||||||
|
- Analysis must complete before revision starts
|
||||||
|
- Critical chapters must finish before important chapters
|
||||||
|
- All revisions must complete before QA phase
|
||||||
|
|
||||||
|
### 8. Set Success Criteria
|
||||||
|
|
||||||
|
Define what "done" means:
|
||||||
|
|
||||||
|
- [ ] All code examples tested on target versions
|
||||||
|
- [ ] All deprecated APIs replaced with current equivalents
|
||||||
|
- [ ] Technical review approved (no critical issues)
|
||||||
|
- [ ] Editorial review approved (clarity and consistency)
|
||||||
|
- [ ] All checklists passed (version-update-checklist.md, revision-completeness-checklist.md)
|
||||||
|
- [ ] Publisher requirements met
|
||||||
|
- [ ] Learning progression validated (no knowledge gaps)
|
||||||
|
- [ ] Cross-references updated and verified
|
||||||
|
- [ ] No broken examples
|
||||||
|
- [ ] Table of contents reflects changes
|
||||||
|
- [ ] New edition number documented
|
||||||
|
|
||||||
|
### 9. Assess Risks and Create Mitigation Plans
|
||||||
|
|
||||||
|
Identify potential problems and solutions:
|
||||||
|
|
||||||
|
**Technical Risks:**
|
||||||
|
- Risk: Breaking changes too extensive, examples can't be easily migrated
|
||||||
|
- Mitigation: Incremental testing, provide migration examples, consider backward-compatible alternatives
|
||||||
|
- Risk: New version not stable yet
|
||||||
|
- Mitigation: Target only LTS/stable releases, avoid beta versions
|
||||||
|
- Risk: Third-party libraries incompatible with new versions
|
||||||
|
- Mitigation: Research compatibility early, plan alternative examples
|
||||||
|
|
||||||
|
**Scope Risks:**
|
||||||
|
- Risk: Revision scope creeps beyond original plan
|
||||||
|
- Mitigation: Strict scope control, defer enhancements to future edition, track scope changes
|
||||||
|
- Risk: Underestimating effort for "simple" chapters
|
||||||
|
- Mitigation: Add 20% buffer to estimates, track actual time
|
||||||
|
|
||||||
|
**Schedule Risks:**
|
||||||
|
- Risk: Testing takes longer than expected
|
||||||
|
- Mitigation: Start testing early, test incrementally, run tests in parallel
|
||||||
|
- Risk: Publisher deadline pressure
|
||||||
|
- Mitigation: Build buffer time into schedule, prioritize critical updates, communicate early if slipping
|
||||||
|
|
||||||
|
**Quality Risks:**
|
||||||
|
- Risk: Inconsistency between old and new content
|
||||||
|
- Mitigation: Extract style guide early, editorial review, use existing-book-integration-checklist.md
|
||||||
|
- Risk: Breaking learning flow with changes
|
||||||
|
- Mitigation: Review learning progression, test with beta readers, consult instructional designer
|
||||||
|
|
||||||
|
### 10. Generate Revision Plan
|
||||||
|
|
||||||
|
Use the create-doc.md task with revision-plan-tmpl.yaml template to create the structured revision plan document.
|
||||||
|
|
||||||
|
The plan should include all decisions and details from steps 1-9.
|
||||||
|
|
||||||
|
### 11. Validate Revision Plan
|
||||||
|
|
||||||
|
Run execute-checklist.md with revision-completeness-checklist.md to ensure:
|
||||||
|
|
||||||
|
- All aspects of revision are planned
|
||||||
|
- Timeline is realistic
|
||||||
|
- Dependencies are identified
|
||||||
|
- Risks are assessed
|
||||||
|
- Success criteria are clear
|
||||||
|
|
||||||
|
### 12. Review and Approve
|
||||||
|
|
||||||
|
Review the revision plan with stakeholders:
|
||||||
|
|
||||||
|
- Author: Is the timeline realistic? Are priorities correct?
|
||||||
|
- Publisher: Does this meet publication requirements?
|
||||||
|
- Technical reviewer: Are technical estimates accurate?
|
||||||
|
- Instructional designer: Will learning flow be maintained?
|
||||||
|
|
||||||
|
Get formal approval before starting revision work.
|
||||||
|
|
||||||
|
## Success Criteria
|
||||||
|
|
||||||
|
A completed revision plan should have:
|
||||||
|
|
||||||
|
- [ ] Clear revision scope and type defined
|
||||||
|
- [ ] All technology version changes documented
|
||||||
|
- [ ] Chapter revision matrix complete with priorities
|
||||||
|
- [ ] Learning flow impact assessed
|
||||||
|
- [ ] Code testing strategy defined
|
||||||
|
- [ ] Timeline with phases and milestones
|
||||||
|
- [ ] Critical path and dependencies identified
|
||||||
|
- [ ] Success criteria clearly stated
|
||||||
|
- [ ] Risks assessed with mitigation plans
|
||||||
|
- [ ] Revision plan document generated
|
||||||
|
- [ ] Stakeholder approval secured
|
||||||
|
|
||||||
|
## Common Pitfalls to Avoid
|
||||||
|
|
||||||
|
- **Underestimating effort**: Revisions often take longer than expected - add buffer
|
||||||
|
- **Ignoring learning flow**: Changes in early chapters affect later ones
|
||||||
|
- **No testing plan**: Can't verify quality without systematic testing
|
||||||
|
- **Vague success criteria**: Must define "done" explicitly
|
||||||
|
- **Skipping risk assessment**: Surprises derail timelines
|
||||||
|
- **No stakeholder buy-in**: Get approval before starting work
|
||||||
|
|
||||||
|
## Next Steps
|
||||||
|
|
||||||
|
After completing the revision plan:
|
||||||
|
|
||||||
|
1. Set up testing environment and code repository
|
||||||
|
2. Begin chapter revisions following priority order
|
||||||
|
3. Extract code patterns if needed (extract-code-patterns.md)
|
||||||
|
4. Execute book-edition-update-workflow.yaml for full coordination
|
||||||
|
5. Track progress against timeline and adjust as needed
|
||||||
|
|
@ -0,0 +1,279 @@
|
||||||
|
<!-- Powered by BMAD™ Core -->
|
||||||
|
|
||||||
|
# Update Chapter for Version
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
task:
|
||||||
|
id: update-chapter-for-version
|
||||||
|
name: Update Chapter for New Technology Version
|
||||||
|
description: Update a specific chapter for new technology version (e.g., Python 3.9 → 3.12)
|
||||||
|
persona_default: book-analyst
|
||||||
|
inputs:
|
||||||
|
- chapter_path
|
||||||
|
- current_version (e.g., Python 3.9)
|
||||||
|
- target_version (e.g., Python 3.12)
|
||||||
|
- breaking_changes_list
|
||||||
|
steps:
|
||||||
|
- Review chapter current state and code examples
|
||||||
|
- Identify target version (Python 3.12, Node 20, etc.)
|
||||||
|
- Update import statements for new version conventions
|
||||||
|
- Replace deprecated methods/APIs with current equivalents
|
||||||
|
- Adopt new syntax features where applicable (e.g., match/case in Python 3.10+)
|
||||||
|
- Update all code examples and test on exact target version
|
||||||
|
- Revise explanatory text for new best practices
|
||||||
|
- Add migration notes if changes are significant
|
||||||
|
- Update cross-references if chapter numbers or sections changed
|
||||||
|
- Run execute-checklist.md with version-update-checklist.md
|
||||||
|
- Document changes in chapter change log
|
||||||
|
output: Updated chapter file with version-specific changes documented
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Purpose
|
||||||
|
|
||||||
|
This task provides a systematic workflow for updating a single chapter when migrating to a new technology version. It ensures code works, text is accurate, and changes are well-documented.
|
||||||
|
|
||||||
|
## Prerequisites
|
||||||
|
|
||||||
|
Before starting this task:
|
||||||
|
|
||||||
|
- Chapter revision matrix identifies this chapter for version update
|
||||||
|
- Target technology version is clearly defined
|
||||||
|
- Breaking changes between versions are documented
|
||||||
|
- Testing environment with target version is set up
|
||||||
|
- Code patterns extracted (if maintaining consistency is critical)
|
||||||
|
|
||||||
|
## Workflow Steps
|
||||||
|
|
||||||
|
### 1. Review Chapter Current State
|
||||||
|
|
||||||
|
Read the chapter completely to understand:
|
||||||
|
|
||||||
|
- What concepts are taught
|
||||||
|
- What code examples are present
|
||||||
|
- How examples build on each other
|
||||||
|
- What the learning objectives are
|
||||||
|
- Which technology features are demonstrated
|
||||||
|
|
||||||
|
Note the chapter's role in the overall learning progression.
|
||||||
|
|
||||||
|
### 2. Identify Target Version
|
||||||
|
|
||||||
|
Confirm the specific target version:
|
||||||
|
|
||||||
|
- Current version: Python 3.9, Node 16, Django 3.2, etc.
|
||||||
|
- Target version: Python 3.12, Node 20, Django 4.2, etc.
|
||||||
|
- Release date and stability (LTS preferred)
|
||||||
|
- Breaking changes list (consult official migration guides)
|
||||||
|
- New features available in target version
|
||||||
|
|
||||||
|
### 3. Update Import Statements
|
||||||
|
|
||||||
|
Modernize imports for new version:
|
||||||
|
|
||||||
|
**Python Example:**
|
||||||
|
```python
|
||||||
|
# Old (Python 3.9)
|
||||||
|
from typing import List, Dict, Optional
|
||||||
|
|
||||||
|
# New (Python 3.10+)
|
||||||
|
from collections.abc import Sequence
|
||||||
|
# Use built-in list, dict instead of typing.List, typing.Dict
|
||||||
|
```
|
||||||
|
|
||||||
|
**JavaScript Example:**
|
||||||
|
```javascript
|
||||||
|
// Old (Node 16)
|
||||||
|
const fs = require('fs').promises;
|
||||||
|
|
||||||
|
// New (Node 20 with native fetch)
|
||||||
|
// Update examples to use modern ESM imports if appropriate
|
||||||
|
```
|
||||||
|
|
||||||
|
Verify imports work with target version.
|
||||||
|
|
||||||
|
### 4. Replace Deprecated Methods/APIs
|
||||||
|
|
||||||
|
Find and replace deprecated functionality:
|
||||||
|
|
||||||
|
**Python Example:**
|
||||||
|
```python
|
||||||
|
# Old (deprecated in 3.10)
|
||||||
|
collections.Iterable
|
||||||
|
|
||||||
|
# New
|
||||||
|
collections.abc.Iterable
|
||||||
|
```
|
||||||
|
|
||||||
|
**Django Example:**
|
||||||
|
```python
|
||||||
|
# Old (Django 3.x)
|
||||||
|
from django.conf.urls import url
|
||||||
|
|
||||||
|
# New (Django 4.x)
|
||||||
|
from django.urls import re_path
|
||||||
|
```
|
||||||
|
|
||||||
|
Consult official deprecation notices and migration guides.
|
||||||
|
|
||||||
|
### 5. Adopt New Syntax Where Applicable
|
||||||
|
|
||||||
|
Introduce new language features where pedagogically appropriate:
|
||||||
|
|
||||||
|
**Python 3.10+ Match/Case:**
|
||||||
|
```python
|
||||||
|
# Consider updating if/elif chains to match/case
|
||||||
|
# Old
|
||||||
|
if status == 'open':
|
||||||
|
handle_open()
|
||||||
|
elif status == 'closed':
|
||||||
|
handle_closed()
|
||||||
|
else:
|
||||||
|
handle_unknown()
|
||||||
|
|
||||||
|
# New (if teaching Python 3.10+)
|
||||||
|
match status:
|
||||||
|
case 'open':
|
||||||
|
handle_open()
|
||||||
|
case 'closed':
|
||||||
|
handle_closed()
|
||||||
|
case _:
|
||||||
|
handle_unknown()
|
||||||
|
```
|
||||||
|
|
||||||
|
**Python 3.9+ Type Hints:**
|
||||||
|
```python
|
||||||
|
# Old
|
||||||
|
from typing import List
|
||||||
|
def process_items(items: List[str]) -> None:
|
||||||
|
pass
|
||||||
|
|
||||||
|
# New (Python 3.9+)
|
||||||
|
def process_items(items: list[str]) -> None:
|
||||||
|
pass
|
||||||
|
```
|
||||||
|
|
||||||
|
Only add new syntax if:
|
||||||
|
- It improves clarity
|
||||||
|
- It's appropriate for the chapter's teaching level
|
||||||
|
- It doesn't confuse the main concept being taught
|
||||||
|
|
||||||
|
### 6. Update Code Examples and Test
|
||||||
|
|
||||||
|
For each code example in the chapter:
|
||||||
|
|
||||||
|
- Update to target version syntax
|
||||||
|
- Run the code on exact target version
|
||||||
|
- Verify output matches expected results
|
||||||
|
- Fix any errors or warnings
|
||||||
|
- Update output examples in text if output changed
|
||||||
|
- Test edge cases
|
||||||
|
|
||||||
|
**Testing Checklist:**
|
||||||
|
- [ ] Code runs without errors
|
||||||
|
- [ ] Code runs without warnings (or warnings are explained)
|
||||||
|
- [ ] Output matches what's shown in book
|
||||||
|
- [ ] Code follows best practices for target version
|
||||||
|
- [ ] Code is tested on target version specifically
|
||||||
|
|
||||||
|
### 7. Revise Explanatory Text
|
||||||
|
|
||||||
|
Update prose to reflect version changes:
|
||||||
|
|
||||||
|
- Update version references ("Python 3.12 introduced...")
|
||||||
|
- Revise explanations if behavior changed
|
||||||
|
- Add notes about version-specific features
|
||||||
|
- Update best practices if they evolved
|
||||||
|
- Revise performance notes if characteristics changed
|
||||||
|
- Update security guidance if recommendations changed
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```markdown
|
||||||
|
Old: "In Python 3.9, you can use type hints with List from the typing module."
|
||||||
|
New: "In Python 3.12, you can use built-in list directly in type hints without importing from typing."
|
||||||
|
```
|
||||||
|
|
||||||
|
### 8. Add Migration Notes (If Significant)
|
||||||
|
|
||||||
|
If changes are substantial, add migration guidance:
|
||||||
|
|
||||||
|
- Note what changed from previous version
|
||||||
|
- Explain why the new approach is better
|
||||||
|
- Provide migration tips for readers with old code
|
||||||
|
- Link to official migration guides if helpful
|
||||||
|
|
||||||
|
**Example Callout:**
|
||||||
|
```markdown
|
||||||
|
> **Migration Note**: If you're updating code from Python 3.9, you can safely replace
|
||||||
|
> `List[str]` with `list[str]` and `Dict[str, int]` with `dict[str, int]` throughout
|
||||||
|
> your codebase. The functionality is identical, but the new syntax is more concise.
|
||||||
|
```
|
||||||
|
|
||||||
|
### 9. Update Cross-References
|
||||||
|
|
||||||
|
If chapter numbers or section numbers changed:
|
||||||
|
|
||||||
|
- Update all "see Chapter X" references
|
||||||
|
- Update "as discussed in Section Y.Z" references
|
||||||
|
- Verify forward and backward references are accurate
|
||||||
|
- Update index entries if applicable
|
||||||
|
- Update table of contents references
|
||||||
|
|
||||||
|
### 10. Run Version Update Checklist
|
||||||
|
|
||||||
|
Use execute-checklist.md with version-update-checklist.md to verify:
|
||||||
|
|
||||||
|
- [ ] All import statements updated
|
||||||
|
- [ ] All deprecated methods replaced
|
||||||
|
- [ ] New syntax adopted appropriately
|
||||||
|
- [ ] All code tested on target version
|
||||||
|
- [ ] Text revised for accuracy
|
||||||
|
- [ ] Best practices current
|
||||||
|
- [ ] Breaking changes documented
|
||||||
|
- [ ] Cross-references accurate
|
||||||
|
|
||||||
|
### 11. Document Changes
|
||||||
|
|
||||||
|
Add to chapter change log:
|
||||||
|
|
||||||
|
- Version update: Python 3.9 → 3.12
|
||||||
|
- Date of update
|
||||||
|
- Major changes made (deprecated APIs replaced, new syntax added)
|
||||||
|
- Testing completed on Python 3.12.1
|
||||||
|
- Reviewer: [name]
|
||||||
|
|
||||||
|
This creates an audit trail for future updates.
|
||||||
|
|
||||||
|
## Success Criteria
|
||||||
|
|
||||||
|
A successfully updated chapter should have:
|
||||||
|
|
||||||
|
- [ ] All code examples run successfully on target version
|
||||||
|
- [ ] No deprecated methods or APIs used
|
||||||
|
- [ ] Appropriate new syntax features adopted
|
||||||
|
- [ ] All text accurate for target version
|
||||||
|
- [ ] Migration notes added where significant changes occurred
|
||||||
|
- [ ] Cross-references verified and updated
|
||||||
|
- [ ] Version update checklist passed
|
||||||
|
- [ ] Changes documented in change log
|
||||||
|
- [ ] Learning objectives still met with updated content
|
||||||
|
|
||||||
|
## Common Pitfalls to Avoid
|
||||||
|
|
||||||
|
- **Testing on wrong version**: Must test on exact target version, not "close enough"
|
||||||
|
- **Over-modernizing**: Don't add new syntax if it obscures the concept being taught
|
||||||
|
- **Breaking learning flow**: Ensure changes don't confuse the learning progression
|
||||||
|
- **Forgetting text updates**: Code changes must be reflected in explanations
|
||||||
|
- **Ignoring cross-references**: Broken references frustrate readers
|
||||||
|
- **No migration notes**: Readers with old code need guidance
|
||||||
|
|
||||||
|
## Next Steps
|
||||||
|
|
||||||
|
After updating a chapter:
|
||||||
|
|
||||||
|
1. Move to next chapter in revision matrix
|
||||||
|
2. Track progress against revision timeline
|
||||||
|
3. Collect updated chapters for comprehensive testing
|
||||||
|
4. Prepare for technical review phase
|
||||||
|
5. Ensure consistency across all updated chapters
|
||||||
|
|
@ -0,0 +1,105 @@
|
||||||
|
# <!-- Powered by BMAD™ Core -->
|
||||||
|
---
|
||||||
|
template:
|
||||||
|
id: book-analysis-report
|
||||||
|
name: Book Analysis Report
|
||||||
|
version: 1.0
|
||||||
|
description: Comprehensive analysis report of existing technical book for revision planning
|
||||||
|
output:
|
||||||
|
format: markdown
|
||||||
|
filename: "{{book_title}}-analysis-report.md"
|
||||||
|
|
||||||
|
workflow:
|
||||||
|
elicitation: false
|
||||||
|
allow_skip: false
|
||||||
|
sections:
|
||||||
|
- id: metadata
|
||||||
|
title: Book Metadata
|
||||||
|
instruction: |
|
||||||
|
Document core book information:
|
||||||
|
- Title and subtitle
|
||||||
|
- Author(s)
|
||||||
|
- Current edition/version (1st, 2nd, 3rd, etc.)
|
||||||
|
- Publication date (original and current edition)
|
||||||
|
- Publisher (PacktPub, O'Reilly, Manning, Self-published)
|
||||||
|
- Target audience (skill level, role)
|
||||||
|
- Current page count
|
||||||
|
- ISBN/product identifiers
|
||||||
|
- Technology stack and versions currently used
|
||||||
|
- id: structure_analysis
|
||||||
|
title: Structure Analysis
|
||||||
|
instruction: |
|
||||||
|
Analyze book organization:
|
||||||
|
- Total chapter count
|
||||||
|
- Part/section breakdown (if applicable)
|
||||||
|
- Front matter (preface, introduction, how to use)
|
||||||
|
- Back matter (appendices, glossary, index)
|
||||||
|
- Chapter organization pattern (tutorial-based, reference-style, project-driven)
|
||||||
|
- Learning flow assessment (does progression make sense?)
|
||||||
|
- Table of contents structure
|
||||||
|
- id: code_inventory
|
||||||
|
title: Code Inventory
|
||||||
|
instruction: |
|
||||||
|
Catalog all code examples:
|
||||||
|
- Total number of code examples
|
||||||
|
- Programming languages used (Python, JavaScript, etc.)
|
||||||
|
- Technology versions targeted (Python 3.9, Node 16, etc.)
|
||||||
|
- Frameworks/libraries used
|
||||||
|
- Code testing status (tested? CI/CD? manual only?)
|
||||||
|
- Code repository location (if exists)
|
||||||
|
- Example complexity distribution (simple demos vs. complete projects)
|
||||||
|
- id: technical_currency
|
||||||
|
title: Technical Currency Assessment
|
||||||
|
instruction: |
|
||||||
|
Evaluate technical freshness:
|
||||||
|
- Current technology versions in book
|
||||||
|
- Latest stable versions available
|
||||||
|
- Deprecated content identified (APIs, methods, best practices)
|
||||||
|
- Breaking changes since publication
|
||||||
|
- Security vulnerabilities in examples
|
||||||
|
- Outdated terminology or concepts
|
||||||
|
- Technology sunset warnings (discontinued tools/frameworks)
|
||||||
|
- id: writing_style_patterns
|
||||||
|
title: Writing Style Patterns
|
||||||
|
instruction: |
|
||||||
|
Extract writing conventions:
|
||||||
|
- Voice and tone (friendly/formal, conversational/academic)
|
||||||
|
- Structural patterns (intro→concept→example→exercise)
|
||||||
|
- Heading hierarchy style (action-based? question-based? topic-based?)
|
||||||
|
- Terminology choices and consistency
|
||||||
|
- Code comment style (inline? docstrings? none?)
|
||||||
|
- Callout usage (tips, warnings, notes)
|
||||||
|
- Cross-reference patterns (chapter X, section Y.Z)
|
||||||
|
- id: cross_reference_map
|
||||||
|
title: Cross-Reference Map
|
||||||
|
instruction: |
|
||||||
|
Document internal dependencies:
|
||||||
|
- Which chapters reference other chapters
|
||||||
|
- Prerequisite flow (chapter X requires chapter Y)
|
||||||
|
- Concept dependencies (must understand A before B)
|
||||||
|
- Code dependencies (Chapter 5 builds on Chapter 3's code)
|
||||||
|
- Forward references (Chapter 2 mentions "we'll cover this in Chapter 7")
|
||||||
|
- Backward references ("as we learned in Chapter 4")
|
||||||
|
- id: identified_issues
|
||||||
|
title: Identified Issues
|
||||||
|
instruction: |
|
||||||
|
List problems found:
|
||||||
|
- Outdated sections (specific chapters/sections)
|
||||||
|
- Broken code examples (won't run on current versions)
|
||||||
|
- Inconsistencies (terminology, formatting, style)
|
||||||
|
- Coverage gaps (missing important topics)
|
||||||
|
- Deprecated warnings not present
|
||||||
|
- Technical inaccuracies
|
||||||
|
- Unclear explanations or confusing sections
|
||||||
|
- Missing prerequisites or assumptions
|
||||||
|
- id: recommendations
|
||||||
|
title: Recommendations
|
||||||
|
instruction: |
|
||||||
|
Provide actionable guidance:
|
||||||
|
- Priority updates (critical, important, nice-to-have)
|
||||||
|
- Scope suggestions (full 2nd edition? targeted chapter updates? version migration only?)
|
||||||
|
- Timeline estimates (weeks/months for different scope levels)
|
||||||
|
- Risk assessment (what could go wrong during revision)
|
||||||
|
- Testing strategy recommendations
|
||||||
|
- Consider learning flow impact
|
||||||
|
- Publisher communication needs
|
||||||
|
|
@ -0,0 +1,135 @@
|
||||||
|
# <!-- Powered by BMAD™ Core -->
|
||||||
|
---
|
||||||
|
template:
|
||||||
|
id: revision-plan
|
||||||
|
name: Book Revision Plan
|
||||||
|
version: 1.0
|
||||||
|
description: Strategic plan for updating existing technical book (2nd/3rd edition, version updates, chapter additions)
|
||||||
|
output:
|
||||||
|
format: markdown
|
||||||
|
filename: "{{book_title}}-revision-plan.md"
|
||||||
|
|
||||||
|
workflow:
|
||||||
|
elicitation: true
|
||||||
|
allow_skip: false
|
||||||
|
sections:
|
||||||
|
- id: revision_scope
|
||||||
|
title: Revision Scope
|
||||||
|
instruction: |
|
||||||
|
Define the type and extent of revision:
|
||||||
|
- Revision type: New edition (2nd/3rd)? Technology version update? Chapter additions? Reviewer feedback incorporation? Publisher-requested changes?
|
||||||
|
- Scope level: Full book revision? Specific chapters only? Code-only updates? Text-only updates?
|
||||||
|
- Triggers: Why now? (new tech version, publisher request, market demand, technical debt)
|
||||||
|
- Goals: What does success look like?
|
||||||
|
- Constraints: Timeline? Budget? Publisher deadlines?
|
||||||
|
elicit: true
|
||||||
|
- id: technology_version_changes
|
||||||
|
title: Technology Version Changes
|
||||||
|
instruction: |
|
||||||
|
Document all technology updates:
|
||||||
|
For each technology/framework/library:
|
||||||
|
- Current version in book (e.g., Python 3.9)
|
||||||
|
- Target version for revision (e.g., Python 3.12)
|
||||||
|
- Breaking changes between versions
|
||||||
|
- New features to incorporate
|
||||||
|
- Deprecated features to replace
|
||||||
|
- Migration effort estimate (low/medium/high)
|
||||||
|
elicit: true
|
||||||
|
- id: chapter_revision_matrix
|
||||||
|
title: Chapter Revision Matrix
|
||||||
|
instruction: |
|
||||||
|
For each chapter, define revision needs:
|
||||||
|
|
||||||
|
| Chapter | Title | Complexity | Effort | Priority | Changes Needed |
|
||||||
|
|---------|-------|------------|--------|----------|----------------|
|
||||||
|
| 1 | Introduction | Low | 2h | Important | Update Python version references |
|
||||||
|
| 2 | Basic Syntax | High | 8h | Critical | Add match/case syntax (Python 3.10+) |
|
||||||
|
| ... | ... | ... | ... | ... | ... |
|
||||||
|
|
||||||
|
Complexity levels:
|
||||||
|
- Low: Minor text updates, version number changes
|
||||||
|
- Medium: Code updates, new examples, moderate text revisions
|
||||||
|
- High: Significant rewrites, new sections, major code changes
|
||||||
|
|
||||||
|
Effort estimates: hours per chapter
|
||||||
|
|
||||||
|
Priority levels:
|
||||||
|
- Critical: Must fix (broken code, security issues, major inaccuracies)
|
||||||
|
- Important: Should fix (outdated best practices, missing features)
|
||||||
|
- Nice-to-have: Optional improvements (polish, minor enhancements)
|
||||||
|
- id: code_testing_strategy
|
||||||
|
title: Code Testing Strategy
|
||||||
|
instruction: |
|
||||||
|
Plan for validating all code updates:
|
||||||
|
- Testing approach (manual? automated? CI/CD?)
|
||||||
|
- Version matrix (which Python/Node/etc versions to test)
|
||||||
|
- Platform testing (Windows, macOS, Linux)
|
||||||
|
- Tool requirements (testing frameworks, linters)
|
||||||
|
- Code repository updates needed
|
||||||
|
- Regression testing plan (ensure old examples still work if not updated)
|
||||||
|
- Performance testing (if applicable)
|
||||||
|
- id: timeline
|
||||||
|
title: Timeline and Milestones
|
||||||
|
instruction: |
|
||||||
|
Break revision into phases with milestones:
|
||||||
|
|
||||||
|
**Phase 1: Analysis and Planning (Week 1-2)**
|
||||||
|
- Complete book analysis
|
||||||
|
- Finalize revision plan
|
||||||
|
- Set up testing environment
|
||||||
|
|
||||||
|
**Phase 2: Chapter Revisions (Week 3-10)**
|
||||||
|
- Week 3-4: Chapters 1-5
|
||||||
|
- Week 5-6: Chapters 6-10
|
||||||
|
- Week 7-8: Chapters 11-15
|
||||||
|
- Week 9-10: Review and polish
|
||||||
|
|
||||||
|
**Phase 3: Testing and QA (Week 11-12)**
|
||||||
|
- Code testing across versions
|
||||||
|
- Technical review
|
||||||
|
- Editorial review
|
||||||
|
|
||||||
|
**Phase 4: Finalization (Week 13-14)**
|
||||||
|
- Incorporate feedback
|
||||||
|
- Final formatting
|
||||||
|
- Publisher submission
|
||||||
|
|
||||||
|
Critical path: Which tasks block others?
|
||||||
|
Dependencies: What must complete before next phase?
|
||||||
|
- id: success_criteria
|
||||||
|
title: Success Criteria
|
||||||
|
instruction: |
|
||||||
|
Define what "done" means:
|
||||||
|
- All code examples tested on target versions
|
||||||
|
- All deprecated APIs replaced
|
||||||
|
- Technical review approved
|
||||||
|
- Editorial review approved
|
||||||
|
- All checklists passed (version-update, revision-completeness)
|
||||||
|
- Publisher requirements met
|
||||||
|
- Learning progression validated
|
||||||
|
- Cross-references updated
|
||||||
|
- No broken examples
|
||||||
|
- id: risk_assessment
|
||||||
|
title: Risk Assessment and Mitigation
|
||||||
|
instruction: |
|
||||||
|
Identify potential problems and solutions:
|
||||||
|
|
||||||
|
**Technical Risks:**
|
||||||
|
- Risk: Breaking changes too extensive
|
||||||
|
Mitigation: Incremental testing, fallback examples
|
||||||
|
- Risk: New version not stable yet
|
||||||
|
Mitigation: Target LTS/stable releases only
|
||||||
|
|
||||||
|
**Scope Risks:**
|
||||||
|
- Risk: Revision scope creeps beyond plan
|
||||||
|
Mitigation: Strict scope control, defer enhancements to next edition
|
||||||
|
|
||||||
|
**Schedule Risks:**
|
||||||
|
- Risk: Testing takes longer than expected
|
||||||
|
Mitigation: Start testing early, parallel testing
|
||||||
|
- Risk: Publisher deadline pressure
|
||||||
|
Mitigation: Build buffer time, prioritize critical updates
|
||||||
|
|
||||||
|
**Quality Risks:**
|
||||||
|
- Risk: Inconsistency between old and new content
|
||||||
|
Mitigation: Style guide extraction, editorial review
|
||||||
|
|
@ -0,0 +1,232 @@
|
||||||
|
workflow:
|
||||||
|
id: add-chapter-to-existing-book-workflow
|
||||||
|
name: Add New Chapter to Existing Book
|
||||||
|
description: Workflow for adding new chapter while maintaining consistency with existing content. Analyzes existing structure and patterns, plans integration, drafts chapter matching existing style, tests code, reviews consistency, and verifies cross-references.
|
||||||
|
type: chapter-addition
|
||||||
|
project_types:
|
||||||
|
- chapter-addition
|
||||||
|
- content-expansion
|
||||||
|
- brownfield-book-extension
|
||||||
|
sequence:
|
||||||
|
- agent: book-analyst
|
||||||
|
analyzes: existing_structure
|
||||||
|
requires:
|
||||||
|
- existing_book_path
|
||||||
|
- new_chapter_topic
|
||||||
|
- insertion_point
|
||||||
|
notes: "Analyze existing book structure using analyze-existing-book.md task (abbreviated version focusing on structure and patterns). Understand chapter organization, learning progression, where new chapter fits in flow, prerequisites new chapter can assume, how chapter numbers will shift. SAVE OUTPUT: Create chapter-addition-analysis.md"
|
||||||
|
|
||||||
|
- agent: book-analyst
|
||||||
|
extracts: writing_patterns
|
||||||
|
requires: existing book content
|
||||||
|
notes: "Extract writing style patterns using extract-code-patterns.md task (both code and prose patterns). Learn voice/tone, heading hierarchy styles, typical chapter structure (intro→concepts→examples→exercises→summary), terminology conventions, callout usage patterns, code comment styles, cross-reference patterns. Generate style guide. SAVE OUTPUT: Create chapter-addition-style-guide.md"
|
||||||
|
|
||||||
|
- agent: instructional-designer
|
||||||
|
plans: chapter_integration
|
||||||
|
requires:
|
||||||
|
- chapter-addition-analysis.md
|
||||||
|
- new chapter topic
|
||||||
|
notes: "Plan new chapter integration using *design-chapter-outline command (create-chapter-outline.md task). Define learning objectives for new chapter, identify prerequisites (what prior chapters provide), plan how chapter fits learning progression, design chapter structure following existing patterns, plan code examples and exercises, estimate page count to match book style. Use chapter-outline-tmpl.yaml. SAVE OUTPUT: Create new-chapter-outline.md"
|
||||||
|
|
||||||
|
- agent: tutorial-architect
|
||||||
|
drafts: new_chapter
|
||||||
|
requires:
|
||||||
|
- new-chapter-outline.md
|
||||||
|
- chapter-addition-style-guide.md
|
||||||
|
notes: "Draft new chapter using *write-chapter command (write-chapter-draft.md task). Follow outline, match voice/tone from style guide, use extracted heading styles, follow structural patterns, create code examples following code patterns, write exercises matching complexity level, use consistent terminology, match callout styles. Use chapter-draft-tmpl.yaml. SAVE OUTPUT: Create new-chapter-draft.md"
|
||||||
|
|
||||||
|
- agent: code-curator
|
||||||
|
creates: code_examples
|
||||||
|
requires:
|
||||||
|
- new-chapter-draft.md
|
||||||
|
- chapter-addition-style-guide.md (code patterns)
|
||||||
|
notes: "Develop code examples following extracted patterns using *create-code-examples command. Follow import organization patterns, use consistent naming conventions, match comment styles, follow error handling patterns, match code structure patterns, use consistent formatting. Test all code on target versions. SAVE OUTPUT: Code examples integrated into new-chapter-draft.md"
|
||||||
|
|
||||||
|
- agent: technical-reviewer
|
||||||
|
reviews: new_chapter
|
||||||
|
requires: new-chapter-draft.md with code
|
||||||
|
notes: "Technical review of new chapter using *review-accuracy command. Verify technical accuracy, check code correctness, validate prerequisites are appropriate, ensure learning objectives achievable, check difficulty level fits book progression, verify examples teach concepts effectively. Provide feedback. SAVE OUTPUT: Create new-chapter-technical-review.md"
|
||||||
|
|
||||||
|
- agent: technical-editor
|
||||||
|
reviews: consistency
|
||||||
|
requires: new-chapter-draft.md
|
||||||
|
notes: "Editorial review for consistency using *review-consistency command. Verify voice/tone matches existing chapters, check terminology is consistent, validate heading hierarchy matches, ensure callout usage is consistent, check cross-references use book's style, verify formatting matches. Use existing-book-integration-checklist.md. SAVE OUTPUT: Create new-chapter-editorial-review.md"
|
||||||
|
|
||||||
|
- agent: book-analyst
|
||||||
|
validates: cross_references
|
||||||
|
requires: new-chapter-draft.md
|
||||||
|
notes: "Verify all cross-references using *verify-cross-references command. Check new chapter's prerequisites are correctly stated, verify new chapter is referenced from relevant existing chapters if needed, update table of contents with new chapter, adjust chapter numbers in cross-references if chapters shifted, verify index entries added. SAVE OUTPUT: Create cross-reference-updates.md listing all changes needed"
|
||||||
|
|
||||||
|
- agent: tutorial-architect
|
||||||
|
finalizes: new_chapter
|
||||||
|
requires:
|
||||||
|
- technical review feedback
|
||||||
|
- editorial review feedback
|
||||||
|
- cross-reference validation
|
||||||
|
notes: "Finalize new chapter incorporating all feedback. Address technical review comments, fix consistency issues, update cross-references, polish prose, verify code examples, run all checklists (technical-accuracy-checklist.md, code-quality-checklist.md, existing-book-integration-checklist.md). SAVE OUTPUT: Create final new chapter ready for integration"
|
||||||
|
|
||||||
|
flow_diagram: |
|
||||||
|
```mermaid
|
||||||
|
graph TD
|
||||||
|
A[Start: New Chapter Topic + Insertion Point] --> B[book-analyst: Analyze Existing Structure]
|
||||||
|
B --> C[book-analyst: Extract Writing Patterns]
|
||||||
|
C --> D[instructional-designer: Plan Chapter Integration]
|
||||||
|
D --> E{Fits Learning Flow?}
|
||||||
|
E -->|Issues| F[Adjust Topic or Prerequisites]
|
||||||
|
F --> D
|
||||||
|
E -->|Good Fit| G[tutorial-architect: Draft New Chapter]
|
||||||
|
G --> H[code-curator: Create Code Examples]
|
||||||
|
H --> I[code-curator: Test Code Examples]
|
||||||
|
I --> J{Code Tests Pass?}
|
||||||
|
J -->|Failures| K[Fix Code Issues]
|
||||||
|
K --> I
|
||||||
|
J -->|Pass| L[technical-reviewer: Review Chapter]
|
||||||
|
L --> M{Technical Approval?}
|
||||||
|
M -->|Issues| N[Address Technical Feedback]
|
||||||
|
N --> L
|
||||||
|
M -->|Approved| O[technical-editor: Review Consistency]
|
||||||
|
O --> P{Consistency Check?}
|
||||||
|
P -->|Issues| Q[Fix Consistency Problems]
|
||||||
|
Q --> O
|
||||||
|
P -->|Approved| R[book-analyst: Validate Cross-References]
|
||||||
|
R --> S[tutorial-architect: Finalize Chapter]
|
||||||
|
S --> T[New Chapter Complete]
|
||||||
|
T --> U[Integrate into Book]
|
||||||
|
U --> V[Update Table of Contents]
|
||||||
|
|
||||||
|
B -.-> B1[Structure Analysis]
|
||||||
|
C -.-> C1[Style Guide Generated]
|
||||||
|
D -.-> D1[Chapter Outline]
|
||||||
|
G -.-> G1[Initial Draft]
|
||||||
|
L -.-> L1[Technical Review Notes]
|
||||||
|
O -.-> O1[Editorial Review Notes]
|
||||||
|
R -.-> R1[Cross-Reference Updates]
|
||||||
|
|
||||||
|
style V fill:#90EE90
|
||||||
|
style B fill:#FFE4B5
|
||||||
|
style C fill:#FFE4B5
|
||||||
|
style D fill:#DDA0DD
|
||||||
|
style G fill:#FFD700
|
||||||
|
style H fill:#ADD8E6
|
||||||
|
style L fill:#F0E68C
|
||||||
|
style O fill:#F0E68C
|
||||||
|
style R fill:#FFE4B5
|
||||||
|
```
|
||||||
|
|
||||||
|
decision_guidance:
|
||||||
|
when_to_use:
|
||||||
|
- Adding new chapter to existing book
|
||||||
|
- Expanding book coverage with additional content
|
||||||
|
- Publisher requested additional chapter
|
||||||
|
- Responding to reader requests for missing topics
|
||||||
|
- Extending book without full edition update
|
||||||
|
|
||||||
|
when_not_to_use:
|
||||||
|
- Writing entire new book (use book-planning-workflow)
|
||||||
|
- Updating existing chapters (use book-edition-update-workflow)
|
||||||
|
- Addressing feedback only (use incorporate-review-feedback-workflow)
|
||||||
|
- Replacing existing chapter (use chapter revision workflows)
|
||||||
|
|
||||||
|
quality_gates:
|
||||||
|
structure_analyzed:
|
||||||
|
- Chapter organization understood
|
||||||
|
- Learning progression mapped
|
||||||
|
- Insertion point identified
|
||||||
|
- Prerequisites determined
|
||||||
|
- Chapter numbering impact assessed
|
||||||
|
|
||||||
|
patterns_extracted:
|
||||||
|
- Voice/tone patterns documented
|
||||||
|
- Heading styles extracted
|
||||||
|
- Chapter structure pattern identified
|
||||||
|
- Code patterns documented
|
||||||
|
- Terminology conventions noted
|
||||||
|
- Style guide generated
|
||||||
|
|
||||||
|
integration_planned:
|
||||||
|
- Learning objectives defined
|
||||||
|
- Prerequisites explicitly stated
|
||||||
|
- Learning progression validated
|
||||||
|
- Chapter structure planned
|
||||||
|
- Code examples planned
|
||||||
|
- Exercises designed
|
||||||
|
- Checklist: prerequisite-clarity-checklist.md
|
||||||
|
|
||||||
|
chapter_drafted:
|
||||||
|
- Follows chapter outline
|
||||||
|
- Matches voice/tone
|
||||||
|
- Uses extracted heading styles
|
||||||
|
- Follows structural patterns
|
||||||
|
- Includes planned code and exercises
|
||||||
|
- Uses consistent terminology
|
||||||
|
|
||||||
|
code_examples_created:
|
||||||
|
- Follow extracted code patterns
|
||||||
|
- Import organization matches
|
||||||
|
- Naming conventions consistent
|
||||||
|
- Comment styles match
|
||||||
|
- Formatting consistent
|
||||||
|
- All code tested and working
|
||||||
|
- Checklist: code-quality-checklist.md
|
||||||
|
|
||||||
|
technical_review_passed:
|
||||||
|
- Technical accuracy verified
|
||||||
|
- Code correctness confirmed
|
||||||
|
- Prerequisites appropriate
|
||||||
|
- Learning objectives achievable
|
||||||
|
- Difficulty level appropriate
|
||||||
|
- Checklist: technical-accuracy-checklist.md
|
||||||
|
|
||||||
|
consistency_reviewed:
|
||||||
|
- Voice/tone matches existing chapters
|
||||||
|
- Terminology consistent
|
||||||
|
- Heading hierarchy matches
|
||||||
|
- Callouts consistent
|
||||||
|
- Cross-references use book's style
|
||||||
|
- Checklist: existing-book-integration-checklist.md
|
||||||
|
|
||||||
|
cross_references_validated:
|
||||||
|
- New chapter prerequisites correct
|
||||||
|
- Relevant existing chapters updated
|
||||||
|
- Table of contents updated
|
||||||
|
- Chapter numbers adjusted if shifted
|
||||||
|
- Index entries added
|
||||||
|
|
||||||
|
handoff_prompts:
|
||||||
|
start_to_analysis: "Adding new chapter on {{topic}} to {{book_title}} at {{insertion_point}}. Analyzing existing structure."
|
||||||
|
analysis_to_patterns: "Structure analyzed. Book has {{chapter_count}} chapters. New chapter will be Chapter {{new_number}}. Extracting writing patterns."
|
||||||
|
patterns_to_planning: "Patterns extracted. Style guide created. Planning chapter integration to maintain learning flow."
|
||||||
|
planning_to_drafting: "Chapter integration planned. {{prereq_count}} prerequisite chapters identified. Drafting new chapter following existing patterns."
|
||||||
|
drafting_to_code: "Chapter draft complete ({{page_count}} pages estimated). Creating {{example_count}} code examples following extracted patterns."
|
||||||
|
code_to_technical: "Code examples created and tested. {{example_count}}/{{example_count}} passing. Ready for technical review."
|
||||||
|
technical_to_editorial: "Technical review complete and approved. Ready for editorial consistency review."
|
||||||
|
editorial_to_references: "Editorial review approved. Validating all cross-references and chapter number impacts."
|
||||||
|
references_to_final: "Cross-references validated. {{update_count}} references to update. Finalizing chapter."
|
||||||
|
final_to_complete: "New chapter finalized. Ready to integrate into {{book_title}} as Chapter {{new_number}}."
|
||||||
|
|
||||||
|
time_estimates:
|
||||||
|
analyze_structure: "2-4 hours (understand existing book)"
|
||||||
|
extract_patterns: "3-5 hours (comprehensive pattern analysis)"
|
||||||
|
plan_integration: "4-6 hours (learning flow planning)"
|
||||||
|
draft_chapter: "20-40 hours (typical chapter, varies by length)"
|
||||||
|
create_code_examples: "8-16 hours (depends on complexity)"
|
||||||
|
test_code: "2-4 hours (comprehensive testing)"
|
||||||
|
technical_review: "4-6 hours (thorough review)"
|
||||||
|
editorial_review: "2-4 hours (consistency check)"
|
||||||
|
validate_references: "2-3 hours (cross-reference validation)"
|
||||||
|
finalize_chapter: "4-6 hours (incorporate feedback)"
|
||||||
|
total_time: "50-95 hours for typical chapter addition"
|
||||||
|
|
||||||
|
best_practices:
|
||||||
|
- Analyze first - understand existing book before adding
|
||||||
|
- Extract patterns thoroughly - consistency is critical
|
||||||
|
- Plan integration carefully - ensure chapter fits learning flow
|
||||||
|
- Match existing style religiously - new content should be invisible
|
||||||
|
- Test all code comprehensively - no exceptions
|
||||||
|
- Get technical review - new content needs validation
|
||||||
|
- Check consistency obsessively - use existing-book-integration-checklist.md
|
||||||
|
- Validate cross-references - broken references frustrate readers
|
||||||
|
- Update table of contents - don't forget administrative updates
|
||||||
|
- Consider chapter numbering - new chapter may shift existing numbers
|
||||||
|
- Document insertion rationale - why this chapter? why here?
|
||||||
|
- Communicate with publisher - new chapter may affect page count/price
|
||||||
|
|
@ -0,0 +1,215 @@
|
||||||
|
workflow:
|
||||||
|
id: book-edition-update-workflow
|
||||||
|
name: Update Book for New Edition
|
||||||
|
description: Complete workflow for updating existing technical book to 2nd/3rd edition with technology version updates. Coordinates book analysis, revision planning, code pattern extraction, chapter updates, testing, technical review, learning flow validation, and editorial polish for brownfield book authoring.
|
||||||
|
type: book-revision
|
||||||
|
project_types:
|
||||||
|
- book-edition-update
|
||||||
|
- version-migration
|
||||||
|
- brownfield-book-authoring
|
||||||
|
sequence:
|
||||||
|
- agent: book-analyst
|
||||||
|
creates: book-analysis-report.md
|
||||||
|
requires:
|
||||||
|
- existing_book_path
|
||||||
|
- revision_motivation
|
||||||
|
notes: "Analyze existing book completely using *analyze-book command (runs analyze-existing-book.md task). Understand structure, code inventory, technical currency, writing patterns, cross-references, and issues. Output comprehensive analysis report covering metadata, structure, code versions, outdated content, style patterns, and recommendations. SAVE OUTPUT: Copy report to docs/analysis/{{book_title}}-analysis-report.md"
|
||||||
|
|
||||||
|
- agent: book-analyst
|
||||||
|
creates: revision-plan.md
|
||||||
|
requires: book-analysis-report.md
|
||||||
|
notes: "Create strategic revision plan using *plan-revision command (runs plan-book-revision.md task). Define scope (full edition? specific chapters?), document technology version changes (e.g., Python 3.9→3.12), create chapter revision matrix with complexity/effort/priority for each chapter, plan testing strategy, define timeline with milestones, set success criteria, assess risks. Use templates/revision-plan-tmpl.yaml. SAVE OUTPUT: Copy plan to docs/planning/{{book_title}}-revision-plan.md"
|
||||||
|
|
||||||
|
- agent: book-analyst
|
||||||
|
creates: code-patterns.md
|
||||||
|
requires: book-analysis-report.md
|
||||||
|
notes: "Extract code style patterns using *extract-patterns command (runs extract-code-patterns.md task). Learn existing import organization, naming conventions, comment styles, error handling patterns, code structure patterns, formatting choices, file organization. Generate style guide for maintaining consistency in updated code. SAVE OUTPUT: Copy to docs/style/{{book_title}}-code-patterns.md"
|
||||||
|
|
||||||
|
- agent: tutorial-architect
|
||||||
|
updates: chapters (iterative)
|
||||||
|
requires:
|
||||||
|
- revision-plan.md
|
||||||
|
- code-patterns.md
|
||||||
|
notes: "Update chapters according to revision plan using update-chapter-for-version.md task for each chapter marked for revision. Follow priority order (Critical→Important→Nice-to-have). For each chapter: update imports, replace deprecated APIs, adopt new syntax, test code on target versions, revise text for accuracy, add migration notes. Follow code-patterns.md for consistency. Use version-update-checklist.md to verify each chapter. TRACK PROGRESS: Update chapter revision matrix as chapters complete."
|
||||||
|
|
||||||
|
- agent: code-curator
|
||||||
|
tests: all_updated_code
|
||||||
|
requires: updated chapters
|
||||||
|
notes: "Test all updated code examples using *test-code command (runs test-code-examples.md task). Test on exact target versions (e.g., Python 3.12, Node 20), verify all examples run without errors, check outputs match text, run regression tests on unchanged examples, test across platforms (Windows/macOS/Linux if applicable). Document test results. SAVE OUTPUT: Create test-results.md with pass/fail for every example."
|
||||||
|
|
||||||
|
- agent: technical-reviewer
|
||||||
|
reviews: updated chapters
|
||||||
|
requires: tested code
|
||||||
|
notes: "Technical review of all revised chapters using *review-accuracy command. Verify technical accuracy, check code follows current best practices, validate new syntax usage is appropriate, ensure deprecated features are fully replaced, confirm security best practices are current, verify version-specific content is correct. Provide feedback using incorporate-reviewer-feedback.md task format. SAVE OUTPUT: Create technical-review-notes.md"
|
||||||
|
|
||||||
|
- agent: instructional-designer
|
||||||
|
validates: learning_flow
|
||||||
|
requires: updated chapters
|
||||||
|
notes: "Verify learning progression intact after revisions using *validate-learning-path command. Check prerequisite flow still works (chapter dependencies maintained), concepts build logically, difficulty curve is smooth, no knowledge gaps introduced by changes, learning objectives still met, exercises still appropriate. Use learning-objectives-checklist.md and prerequisite-clarity-checklist.md. SAVE OUTPUT: Create learning-flow-validation.md"
|
||||||
|
|
||||||
|
- agent: technical-editor
|
||||||
|
polishes: final_chapters
|
||||||
|
requires:
|
||||||
|
- technical review complete
|
||||||
|
- learning flow validated
|
||||||
|
notes: "Editorial polish for consistency and quality using *review-consistency command. Check voice and tone match original book, terminology is consistent (old and new content), heading styles consistent, cross-references accurate (chapter numbers, section numbers), code patterns followed, formatting consistent throughout. Use existing-book-integration-checklist.md and revision-completeness-checklist.md. SAVE OUTPUT: Create editorial-review-notes.md with final approval or change requests."
|
||||||
|
|
||||||
|
flow_diagram: |
|
||||||
|
```mermaid
|
||||||
|
graph TD
|
||||||
|
A[Start: Existing Book + New Version Target] --> B[book-analyst: Analyze Book]
|
||||||
|
B --> C[book-analyst: Create Revision Plan]
|
||||||
|
C --> D[book-analyst: Extract Code Patterns]
|
||||||
|
D --> E[tutorial-architect: Update Chapters - Critical Priority]
|
||||||
|
E --> F[tutorial-architect: Update Chapters - Important Priority]
|
||||||
|
F --> G[tutorial-architect: Update Chapters - Nice-to-have]
|
||||||
|
G --> H[code-curator: Test All Updated Code]
|
||||||
|
H --> I{All Tests Pass?}
|
||||||
|
I -->|Failures| J[tutorial-architect: Fix Failed Examples]
|
||||||
|
J --> H
|
||||||
|
I -->|Pass| K[technical-reviewer: Technical Review]
|
||||||
|
K --> L{Technical Issues?}
|
||||||
|
L -->|Issues Found| M[tutorial-architect: Address Review Feedback]
|
||||||
|
M --> K
|
||||||
|
L -->|Approved| N[instructional-designer: Validate Learning Flow]
|
||||||
|
N --> O{Flow Intact?}
|
||||||
|
O -->|Issues| P[tutorial-architect: Adjust for Flow]
|
||||||
|
P --> N
|
||||||
|
O -->|Valid| Q[technical-editor: Editorial Polish]
|
||||||
|
Q --> R{Consistency Check?}
|
||||||
|
R -->|Issues| S[tutorial-architect: Final Adjustments]
|
||||||
|
S --> Q
|
||||||
|
R -->|Approved| T[Edition Update Complete]
|
||||||
|
T --> U[Ready for Publisher Submission]
|
||||||
|
|
||||||
|
B -.-> B1[Analysis Report Generated]
|
||||||
|
C -.-> C1[Revision Plan with Timeline]
|
||||||
|
D -.-> D1[Code Style Guide]
|
||||||
|
H -.-> H1[Test Results Report]
|
||||||
|
K -.-> K1[Technical Review Notes]
|
||||||
|
N -.-> N1[Learning Flow Validation]
|
||||||
|
Q -.-> Q1[Editorial Approval]
|
||||||
|
|
||||||
|
style U fill:#90EE90
|
||||||
|
style B fill:#FFE4B5
|
||||||
|
style C fill:#FFE4B5
|
||||||
|
style D fill:#FFE4B5
|
||||||
|
style E fill:#FFD700
|
||||||
|
style F fill:#FFD700
|
||||||
|
style G fill:#FFD700
|
||||||
|
style H fill:#ADD8E6
|
||||||
|
style K fill:#F0E68C
|
||||||
|
style N fill:#DDA0DD
|
||||||
|
style Q fill:#F0E68C
|
||||||
|
```
|
||||||
|
|
||||||
|
decision_guidance:
|
||||||
|
when_to_use:
|
||||||
|
- Updating book for 2nd or 3rd edition
|
||||||
|
- Migrating book to new technology versions (Python 3.9→3.12, Node 16→20, etc.)
|
||||||
|
- Comprehensive book revision with code and text updates
|
||||||
|
- Publisher-requested edition update
|
||||||
|
- Addressing accumulated technical debt in existing book
|
||||||
|
|
||||||
|
when_not_to_use:
|
||||||
|
- Writing new book from scratch (use book-planning-workflow)
|
||||||
|
- Adding single new chapter only (use add-chapter-to-existing-book-workflow)
|
||||||
|
- Addressing reviewer feedback only (use incorporate-review-feedback-workflow)
|
||||||
|
- Minor typo fixes (no workflow needed)
|
||||||
|
|
||||||
|
quality_gates:
|
||||||
|
analysis_complete:
|
||||||
|
- Book structure fully documented
|
||||||
|
- Code inventory complete with versions
|
||||||
|
- Technical currency assessed
|
||||||
|
- Writing patterns extracted
|
||||||
|
- Issues and gaps identified
|
||||||
|
- Recommendations provided
|
||||||
|
|
||||||
|
revision_plan_approved:
|
||||||
|
- Scope clearly defined
|
||||||
|
- Technology versions documented
|
||||||
|
- Chapter revision matrix complete
|
||||||
|
- Timeline with milestones defined
|
||||||
|
- Success criteria set
|
||||||
|
- Risks assessed
|
||||||
|
- Stakeholder approval obtained
|
||||||
|
|
||||||
|
code_patterns_extracted:
|
||||||
|
- Import patterns documented
|
||||||
|
- Naming conventions extracted
|
||||||
|
- Comment styles identified
|
||||||
|
- Error handling patterns noted
|
||||||
|
- Formatting standards defined
|
||||||
|
- Style guide generated
|
||||||
|
|
||||||
|
chapters_updated:
|
||||||
|
- All planned chapters revised
|
||||||
|
- Code follows extracted patterns
|
||||||
|
- Text updated for accuracy
|
||||||
|
- Migration notes added where needed
|
||||||
|
- Cross-references verified
|
||||||
|
- Checklist: version-update-checklist.md for each chapter
|
||||||
|
|
||||||
|
testing_complete:
|
||||||
|
- All code tested on target versions
|
||||||
|
- No broken examples
|
||||||
|
- Outputs verified
|
||||||
|
- Regression tests passed
|
||||||
|
- Test results documented
|
||||||
|
|
||||||
|
technical_review_passed:
|
||||||
|
- Technical accuracy verified
|
||||||
|
- Best practices confirmed
|
||||||
|
- Security reviewed
|
||||||
|
- No blocking issues
|
||||||
|
- Approval documented
|
||||||
|
|
||||||
|
learning_flow_validated:
|
||||||
|
- Prerequisites still flow correctly
|
||||||
|
- Difficulty curve maintained
|
||||||
|
- No knowledge gaps
|
||||||
|
- Learning objectives met
|
||||||
|
- Checklists: learning-objectives-checklist.md, prerequisite-clarity-checklist.md
|
||||||
|
|
||||||
|
editorial_approved:
|
||||||
|
- Consistency maintained
|
||||||
|
- Voice and tone consistent
|
||||||
|
- Terminology consistent
|
||||||
|
- Cross-references accurate
|
||||||
|
- Checklists: existing-book-integration-checklist.md, revision-completeness-checklist.md
|
||||||
|
|
||||||
|
handoff_prompts:
|
||||||
|
start_to_analysis: "Starting edition update for {{book_title}} from {{current_version}} to {{target_version}}. Analyzing existing book to understand current state."
|
||||||
|
analysis_to_planning: "Book analysis complete. Found {{issue_count}} issues. Creating strategic revision plan for {{chapter_count}} chapters."
|
||||||
|
planning_to_patterns: "Revision plan approved. Timeline: {{weeks}} weeks. Extracting code patterns to maintain consistency."
|
||||||
|
patterns_to_updates: "Code patterns extracted. Beginning chapter updates starting with {{critical_count}} critical-priority chapters."
|
||||||
|
updates_to_testing: "All {{chapter_count}} chapters updated. Testing {{example_count}} code examples on {{target_version}}."
|
||||||
|
testing_to_review: "Testing complete. {{pass_count}}/{{example_count}} examples passing. Ready for technical review."
|
||||||
|
review_to_flow: "Technical review approved. Validating learning progression across revised chapters."
|
||||||
|
flow_to_editorial: "Learning flow validated successfully. Ready for editorial consistency review."
|
||||||
|
editorial_to_complete: "Editorial review approved. Edition update complete. Ready for publisher submission."
|
||||||
|
|
||||||
|
time_estimates:
|
||||||
|
book_analysis: "8-12 hours (thorough analysis of existing book)"
|
||||||
|
revision_planning: "8-12 hours (strategic planning and stakeholder alignment)"
|
||||||
|
pattern_extraction: "4-6 hours (code style analysis)"
|
||||||
|
chapter_updates: "Varies by chapter: Low=2-4h, Medium=5-10h, High=12-20h per chapter"
|
||||||
|
code_testing: "1-2 hours per chapter (comprehensive testing)"
|
||||||
|
technical_review: "2-3 hours per chapter"
|
||||||
|
learning_flow_validation: "6-10 hours (full book assessment)"
|
||||||
|
editorial_review: "1-2 hours per chapter"
|
||||||
|
total_time_small_book: "200-300 hours for 10-chapter book with medium complexity"
|
||||||
|
total_time_large_book: "400-600 hours for 20-chapter book with high complexity"
|
||||||
|
|
||||||
|
best_practices:
|
||||||
|
- Thorough analysis first - understand before changing
|
||||||
|
- Extract patterns early - consistency is critical in brownfield
|
||||||
|
- Prioritize critical issues - not all chapters need equal effort
|
||||||
|
- Test incrementally - don't wait until all chapters are done
|
||||||
|
- Maintain learning flow - revisions shouldn't break pedagogy
|
||||||
|
- Document everything - future editions will need this history
|
||||||
|
- Follow extracted patterns - consistency matters more than "better" style
|
||||||
|
- Plan realistic timeline - edition updates take longer than expected
|
||||||
|
- Get stakeholder buy-in - revision plan needs approval
|
||||||
|
- Version everything - use git tags for edition milestones
|
||||||
|
|
@ -0,0 +1,199 @@
|
||||||
|
workflow:
|
||||||
|
id: incorporate-review-feedback-workflow
|
||||||
|
name: Process Technical Review Comments
|
||||||
|
description: Systematic workflow for addressing reviewer feedback from technical reviewers, publishers, and beta readers. Triages feedback by severity, addresses critical/important/optional items systematically, tests changes, and tracks completion.
|
||||||
|
type: feedback-incorporation
|
||||||
|
project_types:
|
||||||
|
- reviewer-feedback
|
||||||
|
- publisher-revisions
|
||||||
|
- beta-reader-feedback
|
||||||
|
- brownfield-improvements
|
||||||
|
sequence:
|
||||||
|
- agent: book-analyst
|
||||||
|
creates: feedback-tracking-log.md
|
||||||
|
requires: reviewer_feedback
|
||||||
|
notes: "Collect and categorize all feedback using incorporate-reviewer-feedback.md task. Gather feedback from technical reviewers, publishers, and beta readers. Triage into Critical (technical errors, broken code, security, blocking issues), Important (clarity, missing examples, structure), and Nice-to-have (enhancements, style preferences). Create structured tracking log with ID, chapter, severity, issue, requester, status, resolution. SAVE OUTPUT: Copy to docs/feedback/feedback-tracking-log.md"
|
||||||
|
|
||||||
|
- agent: code-curator
|
||||||
|
fixes: critical_code_issues
|
||||||
|
requires: feedback-tracking-log.md (critical items)
|
||||||
|
notes: "Address all critical code issues first using *fix-code command. Fix broken code examples, resolve technical errors, patch security vulnerabilities, update deprecated methods. Test every fix on target version(s). Do not proceed to next step until ALL critical code issues are resolved and tested. Update tracking log status to 'Done' for each. SAVE OUTPUT: Document code fixes in critical-fixes-log.md"
|
||||||
|
|
||||||
|
- agent: tutorial-architect
|
||||||
|
fixes: critical_text_issues
|
||||||
|
requires: feedback-tracking-log.md (critical items)
|
||||||
|
notes: "Address all critical text issues using *revise-section command. Fix major clarity problems, correct technical inaccuracies in explanations, add missing prerequisites, resolve misleading statements. Ensure changes maintain voice/tone consistency. Do not proceed until ALL critical text issues resolved. Update tracking log. SAVE OUTPUT: Document text changes in critical-fixes-log.md"
|
||||||
|
|
||||||
|
- agent: code-curator
|
||||||
|
tests: critical_fixes
|
||||||
|
requires: critical fixes complete
|
||||||
|
notes: "Test all critical code fixes comprehensively using *test-code command (test-code-examples.md task). Verify fixed examples now run correctly, check outputs match updated text, run regression tests to ensure other examples unaffected. All tests must pass before proceeding. SAVE OUTPUT: Append test results to critical-fixes-log.md"
|
||||||
|
|
||||||
|
- agent: technical-reviewer
|
||||||
|
validates: critical_fixes
|
||||||
|
requires: tested critical fixes
|
||||||
|
notes: "Verify all critical issues are properly resolved using *verify-fixes command. Review each critical fix, confirm technical accuracy, validate code follows best practices, ensure security issues are fully addressed. Approve before proceeding to important issues. SAVE OUTPUT: Create critical-review-approval.md"
|
||||||
|
|
||||||
|
- agent: tutorial-architect
|
||||||
|
fixes: important_issues
|
||||||
|
requires: critical issues resolved
|
||||||
|
notes: "Address important issues systematically. Improve clarity in identified sections, add missing examples where requested, reorganize content if structure issues identified, expand incomplete coverage areas. Use update-chapter-for-version.md or relevant task. Follow extracted code patterns. Update tracking log as items complete. SAVE OUTPUT: Document changes in important-fixes-log.md"
|
||||||
|
|
||||||
|
- agent: code-curator
|
||||||
|
tests: important_fixes
|
||||||
|
requires: important fixes complete
|
||||||
|
notes: "Test all code changes from important fixes. Verify new examples work correctly, test updated code, run full regression suite. SAVE OUTPUT: Append test results to important-fixes-log.md"
|
||||||
|
|
||||||
|
- agent: book-analyst
|
||||||
|
evaluates: optional_suggestions
|
||||||
|
requires: important issues complete
|
||||||
|
notes: "Evaluate each optional suggestion using *triage-feedback command. Decide: Implement (valuable and feasible), Defer (good but not this edition), or Decline (not aligned with goals). Document decision rationale for each. Update tracking log with decision and rationale. SAVE OUTPUT: Create optional-suggestions-decisions.md"
|
||||||
|
|
||||||
|
- agent: book-analyst
|
||||||
|
creates: feedback-resolution-log.md
|
||||||
|
requires: all feedback processed
|
||||||
|
notes: "Generate comprehensive feedback resolution log using incorporate-reviewer-feedback.md task output section. Summarize: total items (47), critical resolved (8/8), important resolved (23/25), optional resolved/deferred/declined (7/14). List all critical fixes, important fixes, deferred items with rationale, declined items with rationale, code changes, text changes. Acknowledge reviewers. SAVE OUTPUT: Copy to docs/feedback/{{book_title}}-feedback-resolution-log.md"
|
||||||
|
|
||||||
|
flow_diagram: |
|
||||||
|
```mermaid
|
||||||
|
graph TD
|
||||||
|
A[Start: Reviewer Feedback Received] --> B[book-analyst: Collect & Categorize Feedback]
|
||||||
|
B --> C[book-analyst: Create Tracking Log]
|
||||||
|
C --> D{Critical Issues Exist?}
|
||||||
|
D -->|Yes| E[code-curator: Fix Critical Code Issues]
|
||||||
|
E --> F[tutorial-architect: Fix Critical Text Issues]
|
||||||
|
F --> G[code-curator: Test Critical Fixes]
|
||||||
|
G --> H{Tests Pass?}
|
||||||
|
H -->|Failures| I[Re-fix Failed Items]
|
||||||
|
I --> G
|
||||||
|
H -->|Pass| J[technical-reviewer: Validate Critical Fixes]
|
||||||
|
J --> K{Critical Approved?}
|
||||||
|
K -->|Issues| L[Address Review Comments]
|
||||||
|
L --> G
|
||||||
|
K -->|Approved| M[tutorial-architect: Address Important Issues]
|
||||||
|
D -->|No Critical| M
|
||||||
|
M --> N[code-curator: Test Important Fixes]
|
||||||
|
N --> O{Important Tests Pass?}
|
||||||
|
O -->|Failures| P[Fix Failed Items]
|
||||||
|
P --> N
|
||||||
|
O -->|Pass| Q[book-analyst: Evaluate Optional Suggestions]
|
||||||
|
Q --> R{Implement, Defer, or Decline?}
|
||||||
|
R -->|Implement| S[Implement Optional Items]
|
||||||
|
S --> T[Test Optional Changes]
|
||||||
|
T --> U[book-analyst: Generate Resolution Log]
|
||||||
|
R -->|Defer/Decline| U
|
||||||
|
U --> V[Feedback Processing Complete]
|
||||||
|
V --> W[Send Resolution Log to Reviewers]
|
||||||
|
|
||||||
|
B -.-> B1[Feedback Categorized by Severity]
|
||||||
|
C -.-> C1[Tracking Log Created]
|
||||||
|
J -.-> J1[Critical Validation Approval]
|
||||||
|
U -.-> U1[Complete Resolution Documentation]
|
||||||
|
|
||||||
|
style W fill:#90EE90
|
||||||
|
style B fill:#FFE4B5
|
||||||
|
style E fill:#FF6B6B
|
||||||
|
style F fill:#FF6B6B
|
||||||
|
style G fill:#FF6B6B
|
||||||
|
style J fill:#FF6B6B
|
||||||
|
style M fill:#FFD700
|
||||||
|
style N fill:#FFD700
|
||||||
|
style Q fill:#ADD8E6
|
||||||
|
style U fill:#DDA0DD
|
||||||
|
```
|
||||||
|
|
||||||
|
decision_guidance:
|
||||||
|
when_to_use:
|
||||||
|
- Received technical reviewer feedback on draft chapters
|
||||||
|
- Publisher requested specific changes
|
||||||
|
- Beta reader feedback needs systematic processing
|
||||||
|
- Multiple reviewers provided conflicting feedback (need triage)
|
||||||
|
- Addressing accumulated feedback from multiple rounds
|
||||||
|
|
||||||
|
when_not_to_use:
|
||||||
|
- Single minor typo fix (no workflow needed)
|
||||||
|
- Full edition update (use book-edition-update-workflow instead)
|
||||||
|
- New chapter creation (use chapter development workflows)
|
||||||
|
- Self-identified improvements without reviewer feedback
|
||||||
|
|
||||||
|
quality_gates:
|
||||||
|
feedback_collected:
|
||||||
|
- All reviewer sources consulted (technical, publisher, beta)
|
||||||
|
- Feedback consolidated into single list
|
||||||
|
- Each item has clear description and source
|
||||||
|
- Affected chapters identified
|
||||||
|
|
||||||
|
feedback_categorized:
|
||||||
|
- Every item assigned severity (Critical/Important/Optional)
|
||||||
|
- Tracking log created with all items
|
||||||
|
- Severity assignments justified
|
||||||
|
- Critical items clearly identified
|
||||||
|
|
||||||
|
critical_issues_resolved:
|
||||||
|
- All technical errors fixed
|
||||||
|
- All broken code working
|
||||||
|
- Security issues patched
|
||||||
|
- Publisher blocking issues addressed
|
||||||
|
- All critical fixes tested
|
||||||
|
- Technical reviewer approval obtained
|
||||||
|
- No critical items remain unresolved
|
||||||
|
|
||||||
|
important_issues_addressed:
|
||||||
|
- Clarity improvements made
|
||||||
|
- Missing examples added
|
||||||
|
- Structural issues resolved
|
||||||
|
- Incomplete coverage expanded
|
||||||
|
- All important fixes tested
|
||||||
|
- Tracking log updated
|
||||||
|
|
||||||
|
optional_items_evaluated:
|
||||||
|
- Each optional item has decision (implement/defer/decline)
|
||||||
|
- Decision rationale documented
|
||||||
|
- Implemented items tested
|
||||||
|
- Deferred items logged for next edition
|
||||||
|
- Declined items have clear reasoning
|
||||||
|
|
||||||
|
resolution_documented:
|
||||||
|
- Resolution log complete
|
||||||
|
- All changes documented
|
||||||
|
- Deferred items tracked
|
||||||
|
- Reviewers acknowledged
|
||||||
|
- Tracking log shows 100% processed
|
||||||
|
|
||||||
|
handoff_prompts:
|
||||||
|
feedback_to_categorization: "Received feedback from {{reviewer_count}} reviewers. Categorizing {{total_items}} items by severity."
|
||||||
|
categorization_to_critical: "Categorization complete: {{critical_count}} critical, {{important_count}} important, {{optional_count}} optional. Addressing critical issues first."
|
||||||
|
critical_code_to_text: "Critical code issues resolved ({{critical_code_count}} fixes). Now addressing critical text issues."
|
||||||
|
critical_to_testing: "All critical fixes complete ({{critical_total}} items). Testing comprehensively before proceeding."
|
||||||
|
testing_to_validation: "Critical fix testing complete. {{pass_count}}/{{total_count}} passing. Ready for technical reviewer validation."
|
||||||
|
validation_to_important: "Critical fixes approved by reviewer. Proceeding to {{important_count}} important issues."
|
||||||
|
important_to_optional: "Important issues addressed ({{important_resolved}}/{{important_total}}). Evaluating {{optional_count}} optional suggestions."
|
||||||
|
optional_to_resolution: "Optional items evaluated: {{implement_count}} implemented, {{defer_count}} deferred, {{decline_count}} declined. Generating resolution log."
|
||||||
|
resolution_to_complete: "Feedback processing complete. {{total_resolved}}/{{total_items}} items resolved. Sending resolution log to reviewers."
|
||||||
|
|
||||||
|
time_estimates:
|
||||||
|
collect_categorize: "2-4 hours (depends on feedback volume)"
|
||||||
|
critical_code_fixes: "1-2 hours per issue"
|
||||||
|
critical_text_fixes: "1-2 hours per issue"
|
||||||
|
critical_testing: "1-2 hours (comprehensive)"
|
||||||
|
technical_validation: "2-3 hours (reviewer time)"
|
||||||
|
important_fixes: "30min-2 hours per issue"
|
||||||
|
important_testing: "1-2 hours"
|
||||||
|
optional_evaluation: "30min-1 hour (decision making)"
|
||||||
|
resolution_log: "2-3 hours (documentation)"
|
||||||
|
total_time_light: "20-40 hours (10-20 feedback items, mostly important/optional)"
|
||||||
|
total_time_heavy: "60-100 hours (40+ items, many critical, extensive fixes)"
|
||||||
|
|
||||||
|
best_practices:
|
||||||
|
- Categorize ruthlessly - not everything is critical
|
||||||
|
- Critical first always - no exceptions
|
||||||
|
- Test every code change - no untested fixes
|
||||||
|
- Track everything - use tracking log religiously
|
||||||
|
- Document decisions - especially for declined items
|
||||||
|
- Communicate with reviewers - send resolution log
|
||||||
|
- Don't scope creep - optional items can expand significantly
|
||||||
|
- Defer strategically - good ideas for next edition are valuable
|
||||||
|
- Maintain consistency - follow extracted patterns
|
||||||
|
- Get validation - have reviewer approve critical fixes
|
||||||
|
- Be grateful - thank reviewers in resolution log
|
||||||
|
- Archive feedback - helps with next edition planning
|
||||||
Loading…
Reference in New Issue