@schilling.mark.a/software-methodology 1.0.0

package/.github/copilot-instructions.md

@@ -0,0 +1,106 @@
+# Software Methodology Skills for GitHub Copilot
+
+This repository contains a comprehensive software development methodology — from product strategy through production deployment. As GitHub Copilot, you can help developers apply these skills effectively.
+
+## Available Skills
+
+This methodology consists of 11 skills that form a development chain:
+
+1. **product-strategy** — Business Model Canvas and Value Proposition Canvas (foundation — run first)
+2. **ux-research** — Personas, mental models, and user journey maps
+3. **story-mapping** — Organizing user activities and tasks into backbone and releases
+4. **bdd-specification** — Writing Gherkin specifications via example mapping
+5. **ux-design** — Information architecture, interaction patterns, usability evaluation, onboarding
+6. **ui-design-workflow** — Screen flows, component selection, acceptance targets
+7. **ui-design-system** — Design tokens, typography, layout, components, accessibility (reference skill)
+8. **atdd-workflow** — RED-GREEN-REFACTOR implementation driven by acceptance tests
+9. **clean-code** — SOLID principles and design patterns (reference skill)
+10. **cicd-pipeline** — Pipeline stages, environment promotion, deployment and rollback
+11. **continuous-improvement** — Measurement, root cause analysis, process updates (feeds back upstream)
+
+## How to Use These Skills with Copilot
+
+### When suggesting code or architecture:
+
+1. **Check for business context first**: Look for `/docs/business-model-canvas.md` and `/docs/value-proposition-canvas.md`
+2. **Understand user needs**: Reference `/docs/personas/` and `/docs/user-journey-maps/`
+3. **Follow the ubiquitous language**: Check `/docs/ubiquitous-language.md` for domain terms
+4. **Align with test strategy**: Read `/docs/test-strategy.md` before suggesting test code
+5. **Apply clean code principles**: Reference `clean-code/references/` for SOLID principles and design patterns
+
+### When the developer asks about methodology:
+
+Point them to the relevant skill's `SKILL.md` file:
+- Product strategy questions → `product-strategy/SKILL.md`
+- Testing approach → `atdd-workflow/SKILL.md`
+- Design patterns → `clean-code/SKILL.md`
+- CI/CD setup → `cicd-pipeline/SKILL.md`
+
+### When writing code:
+
+1. **Use the test-first approach**: Reference `atdd-workflow/SKILL.md` for the RED-GREEN-REFACTOR cycle
+2. **Follow clean code patterns**: Consult `clean-code/references/solid.md` and pattern files
+3. **Match existing architecture**: Look for project structure in `/docs/architecture.md` or similar
+4. **Respect the test strategy**: Use test commands and patterns from `/docs/test-strategy.md`
+
+### Integration Points
+
+The skills read from and write to specific files:
+
+- **Business context**: `/docs/business-model-canvas.md`, `/docs/value-proposition-canvas.md`
+- **User research**: `/docs/personas/`, `/docs/mental-models/`, `/docs/user-journey-maps/`
+- **Planning**: `/docs/story-map/backbone.md`, `/docs/story-map/releases/*.md`
+- **Specifications**: `/features/*.feature` (Gherkin format)
+- **Tests**: Location defined in `/docs/test-strategy.md`
+- **Design**: `/docs/design-system/`, `/docs/screen-flows/`
+
+## Skill Details
+
+Each skill has:
+- **SKILL.md** — Entry point defining when to use it and what it produces
+- **references/** — Detailed guidance documents loaded on demand
+
+For example:
+- `clean-code/SKILL.md` — Routes to the appropriate design pattern
+- `clean-code/references/solid.md` — Detailed SOLID principles
+- `clean-code/references/structural-patterns.md` — Structural patterns reference
+
+## Suggesting Next Steps
+
+When a developer completes work in one area, suggest the logical next skill:
+
+```
+product-strategy → ux-research → story-mapping → bdd-specification → 
+ux-design → ui-design-workflow → atdd-workflow → cicd-pipeline → 
+continuous-improvement (feeds back to any upstream skill)
+```
+
+**Reference skills** (consulted during other steps):
+- `ui-design-system` — Used during `ui-design-workflow`
+- `clean-code` — Used during `atdd-workflow` GREEN and REFACTOR phases
+
+## Examples
+
+**Developer asks**: "How should I structure this user service?"
+
+**Copilot response**:
+1. Check `/docs/value-proposition-canvas.md` for user-related jobs and pains
+2. Reference `clean-code/references/solid.md` for Single Responsibility Principle
+3. Look at `atdd-workflow/SKILL.md` for the test-driven approach
+4. Suggest a clean architecture with domain, application, and infrastructure layers
+
+**Developer asks**: "What tests should I write?"
+
+**Copilot response**:
+1. Read `/docs/test-strategy.md` for project-specific test commands
+2. Reference `atdd-workflow/SKILL.md` for RED-GREEN-REFACTOR workflow
+3. Check `/features/*.feature` files for related Gherkin scenarios
+4. Suggest acceptance tests first, then unit tests for edge cases
+
+## Important Reminders
+
+- **Always start with business value**: Reference the VPC before suggesting features
+- **Test-first development**: RED phase before GREEN phase (see `atdd-workflow/SKILL.md`)
+- **Use ubiquitous language**: Domain terms from `/docs/ubiquitous-language.md`
+- **Patterns over code**: Suggest patterns from `clean-code/references/` before generating code
+- **Incremental delivery**: Align with release plan in `/docs/story-map/releases/`

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Schilling
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,174 @@
+# software-methodology
+
+A comprehensive software development methodology from product strategy through production deployment. Eleven skills, each with a clear scope and a defined position in the chain. Together they form a closed loop: the last skill (continuous-improvement) feeds findings back into any skill upstream.
+
+**Works with:** Claude Code, GitHub Copilot, VS Code, and other AI coding assistants.
+
+**Quick Start:** See [`docs/QUICKSTART.md`](docs/QUICKSTART.md) | **Skills Index:** [`docs/SKILLS.md`](docs/SKILLS.md) | **Sharing Guide:** [`docs/SHARING.md`](docs/SHARING.md)
+
+## The Chain
+
+Skills execute in this order. Two skills (marked with `*`) are references consulted during other steps rather than executed sequentially.
+
+```
+product-strategy        →  Business Model Canvas and Value Proposition Canvas
+ux-research             →  Personas, mental models, user journey maps
+story-mapping           →  Backbone activities, tasks, release sequencing
+bdd-specification       →  Gherkin feature files via example mapping
+ux-design               →  Information architecture, interaction patterns, usability evaluation, onboarding
+ui-design-workflow      →  Screen flows, component selection, acceptance targets
+ui-design-system     *  →  Design tokens, typography, layout, components, accessibility
+atdd-workflow           →  RED-GREEN-REFACTOR implementation driven by acceptance tests
+clean-code           *  →  SOLID principles and design patterns
+cicd-pipeline           →  Pipeline stages, environment promotion, deployment and rollback
+continuous-improvement  →  Measurement, root cause analysis, process updates (feeds back upstream)
+```
+
+`ui-design-system` is consulted by `ui-design-workflow`. `clean-code` is consulted by `atdd-workflow` during GREEN and REFACTOR phases.
+
+## Repo Structure
+
+```
+software-methodology/
+├── dist/                       ← Packaged .skill files (these are what you deploy)
+│   ├── product-strategy.skill
+│   ├── ux-research.skill
+│   └── ...
+├── product-strategy/           ← Source for each skill
+│   ├── SKILL.md                ← Entry point: triggers, workflow, decision routing
+│   └── references/             ← Detail files, loaded on demand
+│       ├── business-model-canvas.md
+│       └── ...
+├── ux-research/
+├── story-mapping/
+├── ...
+└── project-templates/          ← Starting templates for new projects
+    ├── context.md.template     ← The file Claude Code reads at session start
+    └── test-strategy.md.template
+```
+
+`.skill` files are zip archives with a different extension — that is the format Claude expects. They will appear empty or opaque in most file browsers and editors. If you need to inspect the contents of one, rename it to `.zip` and extract it, or run `unzip -l <file>.skill` to list its contents. The human-readable source for every skill lives in the named directories alongside `dist/` — that is where you read and edit.
+
+Each skill follows the same internal structure. `SKILL.md` is the entry point — it defines when the skill runs, routes to the relevant reference file, and stays under ~75 lines. All detail lives in `references/`. This keeps each skill's cognitive load low: Claude reads `SKILL.md`, then loads only the one reference it needs.
+
+## Usage
+
+The methodology supports multiple AI coding assistants. Choose the approach that fits your workflow:
+
+### Using with Claude Code
+
+**1. Deploy the skills.**
+
+Copy the `.skill` files from `dist/` into your project's skill directory:
+
+```
+/mnt/skills/user/product-strategy.skill
+/mnt/skills/user/ux-research.skill
+/mnt/skills/user/story-mapping.skill
+...
+```
+
+**2. Bootstrap your project.**
+
+Create two files in your project's `/docs/` directory from the templates in `project-templates/`:
+
+- `context.md` — tells Claude Code which skills are available and where to find project documents. Fill in the project-specific sections (name, tech stack, architecture).
+- `test-strategy.md` — defines the testing tools, commands, and coverage thresholds for your project. atdd-workflow and cicd-pipeline both read this.
+
+**3. Start with product-strategy.**
+
+Before any other skill runs, create the Business Model Canvas and Value Proposition Canvas. Every downstream skill reads from these. Nothing else can start without them.
+
+**4. Follow the chain.**
+
+Each skill's `SKILL.md` tells you what to read before starting and what it produces. The chain is the workflow. Run skills in order for a new product. Jump to the relevant skill when iterating on an existing one.
+
+### Using with GitHub Copilot / VS Code
+
+**1. Clone or reference this repository.**
+
+Add this repository as a submodule or reference in your project:
+
+```bash
+# As a submodule
+git submodule add https://github.com/MarkSchilling/software-methodology.git methodology
+
+# Or clone separately
+git clone https://github.com/MarkSchilling/software-methodology.git
+```
+
+**2. GitHub Copilot reads the instructions automatically.**
+
+The `.github/copilot-instructions.md` file tells Copilot how to use the skills. Copilot will:
+- Suggest which skill applies to your current task
+- Reference the appropriate `SKILL.md` and reference files
+- Guide you through the methodology chain
+
+**3. Use the Skills Index for navigation.**
+
+Open [`docs/SKILLS.md`](docs/SKILLS.md) for a complete index with links to all skills and their references. This provides quick navigation to any skill's documentation.
+
+**4. Optional: Open the workspace in VS Code.**
+
+For enhanced navigation with folder organization:
+
+```bash
+code .vscode/software-methodology.code-workspace
+```
+
+This opens a multi-folder workspace with each skill organized and labeled with emojis for easy identification.
+
+**5. Ask Copilot for methodology guidance.**
+
+In VS Code or GitHub, ask Copilot questions like:
+- "Which skill should I use for writing feature specifications?"
+- "How do I implement the RED-GREEN-REFACTOR cycle?"
+- "What design patterns should I consider?"
+
+Copilot will reference the appropriate skill files and guide you through the process.
+
+### General Workflow (All Tools)
+
+1. **Start with product-strategy** — Create Business Model Canvas and Value Proposition Canvas
+2. **Follow the chain** — Each skill's `SKILL.md` defines prerequisites and outputs
+3. **Use reference skills** — `ui-design-system` and `clean-code` are consulted during other steps
+4. **Close the loop** — `continuous-improvement` feeds insights back to upstream skills
+
+## Contributing
+
+**Editing a skill:** Edit the source directory (e.g., `product-strategy/references/business-model-canvas.md`). Never edit `.skill` files in `dist/` directly — they are build outputs.
+
+**Repackaging after an edit:**
+
+```bash
+python3 /mnt/skills/examples/skill-creator/scripts/package_skill.py <skill-dir> dist/
+```
+
+Example:
+
+```bash
+python3 /mnt/skills/examples/skill-creator/scripts/package_skill.py product-strategy/ dist/
+```
+
+The packager validates the skill structure before producing the `.skill` file. If validation fails, it will tell you what is wrong.
+
+**Adding a new skill:** Follow the same pattern as existing skills. Run the init script to scaffold:
+
+```bash
+python3 /mnt/skills/examples/skill-creator/scripts/init_skill.py <skill-name> --path .
+```
+
+Then write `SKILL.md` and populate `references/`. The `SKILL.md` should define: when this skill triggers, what it produces, and how it connects to the rest of the chain. Keep `SKILL.md` under ~75 lines. Put all detail in references.
+
+**Process updates from continuous-improvement:** When continuous-improvement identifies a gap in a skill, the fix is an edit to that skill's source. Commit it the same way as any other change. The validation criterion from the root cause analysis goes in the commit message.
+
+## Sharing and Distribution
+
+Want to share these skills with your team, organization, or community? See the **[Sharing Guide](docs/SHARING.md)** for comprehensive recommendations on:
+
+- **Distribution channels** — GitHub, NPM, PyPI, VS Code extensions, documentation sites, Docker
+- **Target audiences** — Individual developers, teams, enterprises, consultants, students
+- **Use case examples** — Quick starts, team adoption, enterprise standardization, training
+- **Community contribution** — How to report issues, suggest improvements, and submit changes
+
+The methodology is designed to be shared and adapted. Choose the distribution method that fits your needs.

package/atdd-workflow/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: atdd-workflow
+description: ATDD Red-Green-Refactor workflow for implementing features driven by acceptance tests. Use when implementing any feature, when a story map task is referenced, when the user says "implement", "build feature", or "write code for scenario". Requires bdd-specification and story-mapping skills to be available. Reads project context from docs/ and features/ directories. Produces tests and implementation following outside-in acceptance test driven development.
+---
+
+# ATDD Red-Green-Refactor Workflow
+
+## Overview
+
+Implements features outside-in: acceptance test first, then unit tests and production code in tight Red-Green-Refactor cycles until the acceptance test passes. Connects business value all the way through to working, tested code.
+
+## Before Starting — Read Context
+
+Read these files in order before any implementation:
+
+1. `/docs/test-strategy.md` — testing tools and commands (CRITICAL: all test commands come from here)
+2. `/docs/story-map/user-tasks/[task-id].md` — the specific task being implemented
+3. `/features/[domain]/[feature].feature` — the Gherkin scenarios (use bdd-specification skill if these don't exist yet)
+4. `/docs/ubiquitous-language.md` — domain terminology
+5. `/docs/value-proposition-canvas.md` — business context
+6. `/docs/business-model-canvas.md` — broader business context
+
+## Workflow Decision
+
+**Feature file exists with scenarios?** → Follow "Implementation Workflow" below
+**No feature file yet?** → Use story-mapping skill to identify the task, then bdd-specification skill to write scenarios, then return here
+
+## Implementation Workflow
+
+### 🔴 Phase 1: RED
+
+Detailed phase rules and patterns: see `references/red-phase.md`
+
+1. **Acceptance Test (Outer Loop)**
+   - Read Gherkin scenario from `/features/[domain]/[feature].feature`
+   - Identify test framework from `/docs/test-strategy.md`
+   - Create acceptance test in `/tests/acceptance/[domain]/`
+   - Create test helpers in `/tests/helpers/` if needed
+   - Run acceptance test → **MUST FAIL**
+   - Verify failure is for the expected reason
+
+2. **Unit Test (Inner Loop)**
+   - Identify the next smallest behavior needed
+   - Write unit test in `/tests/unit/[domain]/`
+   - Run unit test → **MUST FAIL**
+   - Verify error message is clear and meaningful
+
+### 🟢 Phase 2: GREEN
+
+Detailed phase rules and patterns: see `references/green-phase.md`
+
+1. Write **minimum** code to make the current failing test pass
+2. Hard-code values if that makes the test pass — refactor handles design later
+3. Use ubiquitous language in all naming
+4. Run test → **MUST PASS**
+
+### ♻️ Phase 3: REFACTOR
+
+Detailed phase rules and patterns: see `references/refactor-phase.md`
+
+1. Remove duplication
+2. Improve naming with ubiquitous language
+3. Extract methods/classes for clarity
+4. Apply SOLID principles
+5. Refactor test code too — extract helpers, consolidate fixtures
+6. Run **ALL** tests → **MUST STAY GREEN**
+7. Commit when green
+
+### Cycle
+
+Repeat RED → GREEN → REFACTOR until the acceptance test passes. Then move to next scenario.
+
+## File Structure
+
+```
+tests/
+├── acceptance/[domain]/    ← Outer loop tests (from Gherkin scenarios)
+├── unit/[domain]/          ← Inner loop tests (one per behavior)
+├── fixtures/               ← Shared test data
+└── helpers/                ← Page objects, builders, test utilities
+src/
+└── [architecture per docs/test-strategy.md]
+```
+
+## Commit Convention
+
+```
+🔴 RED: Add failing test for [behavior]
+🟢 GREEN: Make [test name] pass with minimal code
+♻️ REFACTOR: [what improved] — all tests green
+✅ COMPLETE: [Feature name] - [Story Map Task ID]
+```
+
+## Completion Checklist
+
+- [ ] All acceptance tests pass
+- [ ] All unit tests pass
+- [ ] Coverage >90% (verify with coverage command from test-strategy.md)
+- [ ] No duplication
+- [ ] Ubiquitous language consistent throughout
+- [ ] `/docs/story-map/user-tasks/[task-id].md` status updated
+- [ ] `/docs/traceability-matrix.md` updated
+
+## Integration
+
+```
+story-mapping     →  identifies task and acceptance criteria
+    ↓
+bdd-specification →  writes Gherkin feature file
+    ↓
+atdd-workflow (this skill)  →  implements with RED-GREEN-REFACTOR
+    ↓ (during GREEN and REFACTOR)
+clean-code        →  applies design principles and patterns
+```
+
+During GREEN: consult clean-code only if a SOLID violation blocks the next test cycle.
+During REFACTOR: use clean-code's decision tree to identify which principle or pattern applies, then load only the relevant reference.

package/atdd-workflow/references/green-phase.md

@@ -0,0 +1,38 @@
+# GREEN Phase — Make It Pass
+
+## Rules
+
+- Write ONLY enough code to make the current failing test pass
+- Do NOT add functionality that no test requires
+- Hard-coding is acceptable here — that is what REFACTOR fixes
+- Use ubiquitous language in naming even at this stage
+- One test green at a time — do not jump ahead
+
+## Discipline
+
+The temptation in GREEN is to write "proper" code immediately. Resist it. The purpose of GREEN is to establish that the test works correctly and that your implementation path is viable. REFACTOR is where design happens.
+
+**Valid GREEN implementations:**
+
+- Returning a hard-coded value that satisfies the assertion
+- Stubbing a method to return expected output
+- Writing a minimal class with only the method being tested
+- Copying logic from another place if it makes the test pass
+
+**Invalid GREEN behaviors:**
+
+- Adding methods no test calls
+- Implementing edge cases no test covers
+- Optimizing performance
+- Abstracting for future flexibility
+
+## Verification
+
+After writing code:
+1. Run the specific failing test — it must now PASS
+2. Run all other tests — they must still pass
+3. If other tests broke, your GREEN code has a side effect — fix it before proceeding to REFACTOR
+
+## When GREEN Is Harder Than Expected
+
+If writing minimal code to pass is difficult, the unit test is probably too large. Go back to RED and break it into a smaller unit test that targets a single, smaller behavior.

package/atdd-workflow/references/red-phase.md

@@ -0,0 +1,62 @@
+# RED Phase — Write Failing Tests
+
+## Rules
+
+- NEVER write production code before the test fails
+- Test must fail for the **expected** reason — if it fails for the wrong reason, fix the test first
+- One failing test at a time
+- Use ubiquitous language from `/docs/ubiquitous-language.md` in all test descriptions
+
+## Acceptance Test (Outer Loop)
+
+The acceptance test is the target. Everything else exists to make it pass.
+
+**Map Gherkin steps to test actions:**
+
+| Gherkin | Test Pattern |
+|---------|-------------|
+| Given [state] | Arrange — set up preconditions |
+| When [action] | Act — perform the user action |
+| Then [outcome] | Assert — verify observable result |
+| And [additional] | Additional assert or arrange step |
+
+**Test helper patterns to use:**
+
+- **Page Object** — encapsulates all interactions with a single page/screen
+- **Builder** — fluent interface for constructing complex test objects
+- **Factory** — creates valid domain objects with sensible defaults, override as needed
+
+Place helpers in `/tests/helpers/`, fixtures in `/tests/fixtures/`.
+
+**Verifying the failure:**
+- Error message should point clearly to what's missing
+- If test fails during setup rather than assertion, the test is poorly structured — refactor the test before proceeding
+
+## Unit Test (Inner Loop)
+
+Pick the next smallest behavior the acceptance test needs. Write exactly one unit test for it.
+
+**Identify the next behavior by asking:**
+- What does the acceptance test need that doesn't exist?
+- What is the smallest piece of that?
+
+**Example progression for "Create invoice":**
+1. Unit test: Invoice can be instantiated
+2. Unit test: Invoice accepts a line item
+3. Unit test: Invoice calculates total from line items
+4. Unit test: Invoice generates a unique number
+5. (continue until acceptance test passes)
+
+**Arrange-Act-Assert pattern:**
+```
+Arrange: Set up the object/state under test
+Act:     Call the method or trigger the behavior
+Assert:  Verify the expected outcome
+```
+
+## Common Mistakes
+
+- Writing the unit test for behavior that isn't needed yet (YAGNI)
+- Making the test pass by accident — verify it fails first
+- Testing implementation details instead of behavior
+- Writing too many assertions in a single test — one behavior per test

package/atdd-workflow/references/refactor-phase.md

@@ -0,0 +1,75 @@
+# REFACTOR Phase — Improve Design
+
+## Rules
+
+- NEVER change observable behavior — only internal structure
+- Tests must remain GREEN throughout the entire refactor
+- Run tests after every small change
+- Refactor both production code AND test code
+- Commit frequently — each commit must be green
+
+## What to Refactor
+
+### Production Code
+- **Remove duplication** — if the same logic appears twice, extract it
+- **Improve naming** — use terms from `/docs/ubiquitous-language.md`
+- **Extract methods** — a method should do one thing
+- **Extract classes** — group related state and behavior
+- **Apply SOLID:**
+  - Single Responsibility: one reason to change
+  - Open/Closed: extend without modifying
+  - Liskov: subtypes substitute for base types
+  - Interface Segregation: small, focused interfaces
+  - Dependency Inversion: depend on abstractions
+
+### Test Code
+- **Extract common setup** into beforeEach/fixtures
+- **Extract repeated assertions** into helper methods
+- **Consolidate test data** into `/tests/fixtures/`
+- **Improve test names** — should read as a specification
+- **Remove dead test code** — unused helpers or fixtures
+
+## Refactoring Patterns
+
+### Replace Hard-Coded Value
+```
+Before: return 1000
+After:  return this.lineItems.reduce((sum, item) => sum + item.amount, 0)
+```
+
+### Extract Method
+```
+Before: 20 lines of logic inline
+After:  calculateTotal() called from the original location
+```
+
+### Extract Value Object
+```
+Before: amount stored as number (1000)
+After:  amount stored as Money value object with currency and formatting
+```
+
+### Extract Strategy
+```
+Before: if/else chain for tax calculation rules
+After:  TaxCalculator interface, concrete strategy per rule
+```
+
+## When to Stop Refactoring
+
+Stop when:
+- Code is readable without comments
+- No duplication remains
+- Methods are small and focused
+- Names match ubiquitous language
+- Design supports the next likely change without modification
+
+Do NOT refactor speculatively for changes that haven't been required yet.
+
+## Recovery
+
+If refactoring breaks tests and you can't see why:
+1. Revert to last green commit
+2. Make a smaller refactoring step
+3. Run tests
+4. Repeat