Chapter 6: Planning Epics, Chores, and Bugs

Epics are large initiatives that span multiple pieces of work. You can't build an epic directly. You have to break it down first.

When you identify an epic, the first job is brainstorming what it contains. "Build an authentication system" might contain: login feature, signup feature, password reset feature, session management chore, and security hardening chore. "Add a reporting dashboard" might contain: dashboard layout feature, chart components feature, data export feature, and performance optimization chore.

Some epics are technical rather than user-facing. "Migrate from JavaScript to TypeScript" or "Refactor the database layer" don't produce features because there's no UX to explore. These technical epics produce chores directly.

Epics may also involve architectural decisions that apply across all their children. If you're building real-time collaboration, you might decide upfront to use WebSockets rather than polling. This decision affects every feature in the epic. Document it at the epic level so individual features respect it.

Epic planning is lightweight:

Brainstorm the features and chores the epic contains

Identify any architectural decisions that span the epic

Pick a feature to start with and begin feature planning

The epic is a container. The real work happens in its children.

Chores are technical tasks where the implementation is obvious. There's no UX to explore because users never see this work directly.

Chores come in four types:

Refactors restructure code without changing behavior. Moving a function to a different file. Renaming variables for clarity. Extracting a reusable component. The key constraint: all existing tests must pass without modification. If tests fail, you changed behavior, not just structure.

Dependency updates upgrade packages your code relies on. The key constraint: check changelogs for breaking changes. Update your code if APIs changed. Run the full test suite to catch regressions.

Cleanup removes unused code. Dead functions, obsolete files, commented-out blocks. The key constraint: verify the code is actually unused before deleting. Search for references. Check for dynamic usage patterns that static analysis might miss.

Tooling improves your development or build process. Configuring linters, setting up CI, improving test infrastructure. The key constraint: document what you're changing and why so future you understands the setup.

Chore planning is minimal. Identify what type of chore it is, understand the constraints for that type, and do the work carefully. Chores don't need scenarios or UX exploration. They need verification that you didn't break anything.

Bugs require investigation before implementation. The temptation is to jump straight to fixing. Resist it.

When you fix a symptom without understanding the cause, the bug often resurfaces. Or your fix breaks something else. Or you spend hours on a fix that doesn't work because you misunderstood the problem.

Bug planning follows an investigation process:

Symptom capture. What's happening? What should happen instead? How do you reproduce it? What error messages appear? Be specific. "The login doesn't work" is vague. "Clicking the login button on mobile Safari does nothing, no error in console" is useful.

Hypothesis formation. Based on symptoms, what might be causing this? Form two or three theories. Maybe the click handler isn't attached on mobile. Maybe there's a CSS issue making the button unclickable. Maybe the API call fails silently.

Evidence gathering. Test your hypotheses one at a time. Add logging. Check network requests. Inspect the DOM. Each hypothesis should be confirmable or eliminable with evidence.

Root cause confirmation. When you find the cause, verify it. Can you explain exactly why the bug occurs? Can you predict when it will and won't happen? If you can't articulate the root cause clearly, keep investigating.

Only after confirming the root cause do you write the fix. The fix should address the cause, not the symptom. And you should write a regression test: a scenario that fails before your fix and passes after. This prevents the bug from returning.

Bug planning takes more time than jumping straight to a fix. But it produces fixes that actually work and stay working.

That's the three variations on feature planning. Epics break down into features. Chores execute carefully with type-specific constraints. Bugs investigate before fixing. Each has its place, and routing (from Chapter 4) puts you on the right path.