ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity
BMAD-METHOD/expansion-packs/bmad-technical-writing/tasks/write-summary.md

12 KiB
Raw Blame History

Write Chapter Summary

task: id: write-summary name: Write Chapter Summary description: Create concise chapter summary recapping key concepts and previewing next steps persona_default: tutorial-architect inputs: - completed chapter content - learning-objectives (from introduction) - next-chapter topic steps: - Review chapter content thoroughly - Identify key concepts covered (3-5 main points) - Summarize main learning points in bullet format - Recap what readers accomplished - Reinforce learning objectives were met - Preview next chapter topic - Suggest further reading or practice - Keep concise (1-2 pages maximum) - Review for completeness - Ensure alignment with introduction output: Chapter summary section (final 1-2 pages)

Purpose

This task guides you through creating an effective chapter summary that reinforces learning, validates progress, and motivates continued reading. The result is a concise recap that helps readers consolidate knowledge.

Prerequisites

Before starting this task:

  • Have complete chapter content
  • Know learning objectives from introduction
  • Understand next chapter's topic
  • Access to book-structures.md knowledge base

Workflow Steps

1. Review Chapter Content

Re-read the chapter with summary in mind:

Identify:

  • Key concepts introduced
  • Main skills practiced
  • Important patterns or principles
  • Common pitfalls covered
  • Hands-on projects completed

Questions to ask:

  • What are the 3-5 most important takeaways?
  • What would readers need to remember in 6 months?
  • What enables them to build their own projects?
  • What concepts appear in later chapters?

2. Identify Key Concepts

List 3-5 main concepts (no more than 5):

Selection criteria:

  • Essential to understanding this topic
  • Referenced in later chapters
  • Applicable to real-world projects
  • Aligned with learning objectives
  • Not trivial details

Example: From a chapter on Docker:

  1. Container isolation enables consistent environments
  2. Dockerfiles define reproducible image builds
  3. Multi-stage builds optimize image size
  4. Docker Compose orchestrates multi-container apps
  5. Health checks enable automatic container restart

Avoid:

  • Too many points (overwhelming)
  • Trivial details ("We installed Docker")
  • Concepts not actually covered
  • Vague statements ("Containers are useful")

3. Summarize Main Learning Points

Create a bullet list of key takeaways:

Format:

"## Summary

In this chapter, you learned:

  • Container fundamentals: Containers provide lightweight, isolated environments that bundle applications with their dependencies, ensuring consistent behavior across development, testing, and production.

  • Dockerfile best practices: Multi-stage builds, layer caching, and minimal base images reduce image size and build time. The order of COPY and RUN commands matters for cache efficiency.

  • Docker Compose orchestration: YAML configuration files define multi-container applications, networks, and volumes, enabling one-command deployment of complex systems.

  • Production deployment patterns: Health checks, restart policies, and proper logging ensure containerized applications run reliably in production.

  • Debugging techniques: Interactive shells (docker exec), logs (docker logs), and network inspection (docker network) help diagnose container issues."

Guidelines:

  • One concept per bullet
  • 1-2 sentences each
  • Bold the concept name
  • Include the "why" or "so what"
  • Use concrete language, not abstract
  • Match terminology from chapter

Good vs. Bad:

  • ✅ "Health checks detect and restart failed containers automatically"
  • ❌ "Health checks are important" (why? how?)
  • ✅ "Multi-stage builds separate build tools from runtime images, reducing final image size by 70%"
  • ❌ "You can optimize Docker images" (how? what's the benefit?)

4. Recap What Readers Accomplished

Highlight concrete achievements:

Format:

"You built several practical projects in this chapter:

  • Containerized Python API: You created a Dockerfile for a Flask application, including dependencies, environment configuration, and entry point.

  • Multi-container application: Your Docker Compose configuration connected a web app, PostgreSQL database, and Redis cache with defined networks and persistent volumes.

  • Production deployment: You deployed containers with health checks, restart policies, and centralized logging.

You can now containerize your own applications and deploy them consistently across any Docker-enabled environment."

Include:

  • Specific projects or exercises completed
  • Skills demonstrated
  • How these apply beyond the chapter
  • What readers can build independently now

Tone:

  • Celebratory ("You built...")
  • Specific ("containerized Python API" not "learned Docker")
  • Empowering ("You can now...")

5. Reinforce Learning Objectives Were Met

Explicitly connect back to stated objectives:

Format:

"Returning to our learning objectives from the beginning of the chapter:

✅ Create Dockerfiles to containerize Python applications – You wrote Dockerfiles with multi-stage builds and optimized layer caching.

✅ Configure multi-container applications using Docker Compose – Your docker-compose.yml defined services, networks, and volumes for a complete application stack.

✅ Debug containers using logs and interactive shells – You used docker logs, docker exec, and docker network inspect to diagnose issues.

✅ Deploy containerized applications to production – You configured health checks, restart policies, and persistent storage for production deployment.

✅ Implement health checks and restart policies – Your production containers automatically restart on failure and report health status."

Guidelines:

  • Use checkmarks (✅) to show completion
  • Repeat objectives verbatim from introduction
  • Add brief evidence of achievement
  • If any objective wasn't fully met, acknowledge it
  • Reinforce that stated goals were achieved

Why this matters:

  • Validates reader's progress
  • Builds confidence
  • Shows chapter delivered on promises
  • Provides sense of accomplishment

6. Preview Next Chapter

Connect to what's coming:

Format:

"## What's Next

Now that you can containerize and deploy applications with Docker, you're ready to scale beyond a single host.

In Chapter 8: Kubernetes Orchestration, you'll learn to:

  • Manage hundreds of containers across multiple servers
  • Implement automatic scaling based on load
  • Achieve zero-downtime deployments with rolling updates
  • Configure service discovery and load balancing
  • Monitor cluster health and resource usage

You'll use your Docker expertise as the foundation, with Kubernetes adding orchestration, scaling, and resilience for production-grade deployments.

The containers you built in this chapter will run on Kubernetes with minimal changes, but you'll gain powerful new capabilities for managing them at scale."

Include:

  • Next chapter number and title
  • How it builds on this chapter
  • Preview of key topics (3-5 bullet points)
  • Why readers should be excited
  • Connection between chapters

Avoid:

  • Detailed explanations (save for next chapter)
  • Spoiling surprises or major reveals
  • Making next chapter sound harder than it is
  • Disconnected topics

7. Suggest Further Reading and Practice

Provide optional resources:

Format:

"## Further Reading and Practice

Recommended practice:

  • Containerize one of your own applications using the patterns from this chapter
  • Experiment with different base images (alpine, slim, distroless) and compare sizes
  • Add health checks to an existing application and test failure scenarios
  • Set up Docker Compose for a multi-tier application you're familiar with

Additional resources:

Community:

Include:

  • Practice exercises (apply to own projects)
  • Official documentation
  • Related articles or books
  • Community resources
  • Code repositories or examples

Guidelines:

  • Keep it optional (not required)
  • Prioritize quality over quantity (3-5 resources max)
  • Include brief description of each
  • Indicate difficulty level if relevant
  • Prefer official/authoritative sources

8. Keep It Concise

Summaries should be brief:

Length guidelines:

  • 1-2 pages maximum
  • 300-500 words typical
  • If longer, you're re-teaching, not summarizing

Structure:

  1. Summary (key concepts) - 1/2 page
  2. What you accomplished - 1/4 page
  3. Learning objectives recap - 1/4 page
  4. What's next - 1/4 page
  5. Further reading (optional) - 1/4 page

Avoid:

  • Repeating chapter content verbatim
  • Introducing new concepts
  • Detailed explanations
  • Code examples (reference them, don't repeat)

9. Review for Completeness

Validate the summary:

  • Are key concepts identified (3-5)?
  • Are learning points clearly summarized?
  • Are accomplishments celebrated?
  • Are stated objectives validated?
  • Is next chapter previewed?
  • Are further resources provided?
  • Is it concise (1-2 pages)?
  • Does it match introduction tone?

Alignment check:

  • Introduction stated objectives → Summary validates them
  • Introduction promised content → Summary confirms delivery
  • Introduction set expectations → Summary meets them

10. Ensure Alignment with Introduction

Cross-reference introduction and summary:

Introduction said: "By the end of this chapter, you will be able to create Dockerfiles to containerize Python applications."

Summary must confirm: "✅ Create Dockerfiles to containerize Python applications – You wrote Dockerfiles with multi-stage builds and optimized layer caching."

Check:

  • Every objective has a checkmark in summary
  • Projects mentioned in introduction were completed
  • Tone and voice are consistent
  • Prerequisites mentioned were actually prerequisites
  • Time estimate was reasonable (note if not)

Success Criteria

A completed chapter summary should have:

  • 3-5 key concepts clearly summarized
  • Bullet list of main learning points
  • Recap of reader accomplishments
  • Validation of all stated learning objectives
  • Preview of next chapter with connection
  • Optional further reading suggestions
  • Concise length (1-2 pages maximum)
  • Consistent tone with introduction
  • No new concepts introduced
  • Celebratory and empowering tone

Common Pitfalls to Avoid

  • Too long: Summaries shouldn't exceed 2 pages
  • Too detailed: Don't re-teach, just recap
  • Vague: "You learned about Docker" instead of specific accomplishments
  • Missing objectives: Every stated objective needs validation
  • Disconnected: Next chapter preview seems unrelated
  • No celebration: Acknowledge reader's hard work
  • New content: Summary introduces concepts not in chapter
  • Boring: Just listing topics instead of emphasizing achievements

Notes and Warnings

  • Summaries aid retention: Well-written summaries improve learning outcomes
  • Validation matters: Readers need confirmation they achieved objectives
  • Preview motivates: Good preview encourages continued reading
  • Be specific: "You built X" is better than "We covered X"
  • Match introduction: Summary and introduction should bookend the chapter
  • Celebrate progress: Readers accomplished something, acknowledge it

Next Steps

After writing summary:

  1. Ensure introduction and summary form coherent bookends
  2. Verify all learning objectives were actually met
  3. Update introduction if chapter deviated from plan
  4. Add summary to chapter outline/structure
  5. Review entire chapter for coherent flow
  6. Begin planning next chapter based on preview