@schilling.mark.a/software-methodology 1.0.0

package/clean-code/references/structural-patterns.md

@@ -0,0 +1,238 @@
+# Structural Patterns
+
+Patterns for composing objects and classes into larger structures.
+
+---
+
+## Adapter
+
+**When to use:**
+- You need to use an existing class but its interface doesn't match what your code expects
+- You want to wrap an external or legacy system behind your own interface
+- You want to isolate your domain from third-party APIs
+
+**Smell that triggers it:**
+- Direct calls to an external API scattered through business logic
+- Changing the external provider would require changes across the codebase
+- Unit tests fail because they can't mock the external system
+
+**Solution:**
+```
+// External system you don't control
+class StripePaymentGateway:
+  chargeCard(cardNumber, amount, currency, metadata): StripeResponse
+
+// Your domain's contract — defined by YOUR needs, not Stripe's
+interface PaymentProcessor:
+  process(payment: Payment): PaymentResult
+
+// Adapter — translates between your world and theirs
+class StripeAdapter implements PaymentProcessor:
+  constructor(stripe: StripePaymentGateway)
+
+  process(payment: Payment): PaymentResult
+    stripeResponse = this.stripe.chargeCard(
+      payment.cardNumber,
+      payment.amount.value,
+      payment.amount.currency,
+      { invoiceId: payment.invoiceId }
+    )
+    return new PaymentResult(stripeResponse.id, stripeResponse.status)
+
+// Business logic knows nothing about Stripe
+class InvoicePaymentService:
+  constructor(processor: PaymentProcessor)   ← depends on YOUR interface
+
+  pay(invoice, payment):
+    result = this.processor.process(payment)
+    invoice.markPaid(result.transactionId)
+```
+
+**Key insight:** Switching from Stripe to PayPal means writing a new adapter. `InvoicePaymentService` never changes. Tests inject a mock `PaymentProcessor` — no real payment gateway needed.
+
+---
+
+## Facade
+
+**When to use:**
+- A subsystem has many classes with complex interdependencies
+- You want to provide a simple entry point to a complex system
+- You want to decouple clients from the internal structure of a subsystem
+
+**Smell that triggers it:**
+- Calling code needs to orchestrate 5+ steps across multiple classes to accomplish one logical action
+- Internal details of a subsystem leak into the calling code
+
+**Solution:**
+```
+// Complex subsystem internals
+class TaxEngine: ...
+class DiscountCalculator: ...
+class InvoiceFormatter: ...
+class InvoiceValidator: ...
+class InvoiceRepository: ...
+
+// Facade — single entry point, hides orchestration
+class InvoiceService:
+  constructor(taxEngine, discountCalc, formatter, validator, repo)
+
+  createAndSave(invoiceData): Invoice
+    invoice = new Invoice(invoiceData)
+    invoice.applyDiscount(this.discountCalc.calculate(invoice))
+    invoice.applyTax(this.taxEngine.calculate(invoice))
+    this.validator.validate(invoice)
+    formatted = this.formatter.format(invoice)
+    this.repo.save(formatted)
+    return invoice
+
+// Caller sees only one method
+service.createAndSave(data)
+```
+
+**Key insight:** The facade doesn't prevent direct access to subsystem classes if needed, but it provides the simple path for the common case. Internal classes can change without affecting callers that go through the facade.
+
+---
+
+## Composite
+
+**When to use:**
+- You have a tree structure where individual objects and compositions of objects are treated uniformly
+- Clients should be able to interact with individual objects and compositions through the same interface
+
+**Smell that triggers it:**
+- Code that checks "is this a leaf or a container?" before acting
+- Recursive structures (categories containing subcategories, directories containing files or subdirectories)
+
+**Solution:**
+```
+interface PriceComponent:
+  getPrice(): Money
+  getDescription(): string
+
+class LineItem implements PriceComponent:          ← leaf
+  constructor(description, price)
+  getPrice(): return this.price
+  getDescription(): return this.description
+
+class InvoiceSection implements PriceComponent:    ← composite
+  private items: PriceComponent[] = []
+
+  add(item: PriceComponent): this.items.push(item)
+
+  getPrice(): Money
+    return this.items.reduce((sum, item) => sum.add(item.getPrice()), Money.zero())
+
+  getDescription(): string
+    return this.items.map(i => i.getDescription()).join(", ")
+
+// Usage — sections can contain items OR other sections
+consulting = new InvoiceSection("Consulting")
+consulting.add(new LineItem("Architecture Review", 2000))
+consulting.add(new LineItem("Code Review", 500))
+
+development = new InvoiceSection("Development")
+development.add(new LineItem("Feature X", 5000))
+
+invoice = new InvoiceSection("Invoice Total")
+invoice.add(consulting)      ← section inside section
+invoice.add(development)
+
+invoice.getPrice()           ← recursively sums everything: 7500
+```
+
+**Key insight:** The caller never checks types. Every `PriceComponent` responds to `getPrice()` the same way, whether it's a single item or a tree of sections.
+
+---
+
+## Decorator
+
+**When to use:**
+- You need to add behavior to an object dynamically, without modifying its class
+- You want to stack multiple behaviors independently
+- Subclassing would create a combinatorial explosion of classes
+
+**Smell that triggers it:**
+- A growing list of subclasses, each adding one behavior variant
+- A class accumulating flags/booleans that conditionally activate features
+- "I want Invoice to optionally have tax, optionally have discount, optionally have header"
+
+**Solution:**
+```
+interface InvoiceRenderer:
+  render(invoice): string
+
+class BasicInvoiceRenderer implements InvoiceRenderer:  ← base
+  render(invoice): return formatBasicInvoice(invoice)
+
+class WithHeaderDecorator implements InvoiceRenderer:   ← adds header
+  constructor(wrapped: InvoiceRenderer)
+  render(invoice):
+    return renderHeader() + this.wrapped.render(invoice)
+
+class WithFooterDecorator implements InvoiceRenderer:   ← adds footer
+  constructor(wrapped: InvoiceRenderer)
+  render(invoice):
+    return this.wrapped.render(invoice) + renderFooter()
+
+class WithPageNumbersDecorator implements InvoiceRenderer:
+  constructor(wrapped: InvoiceRenderer)
+  render(invoice):
+    return addPageNumbers(this.wrapped.render(invoice))
+
+// Compose at runtime — any combination, any order
+renderer = new WithPageNumbersDecorator(
+  new WithHeaderDecorator(
+    new WithFooterDecorator(
+      new BasicInvoiceRenderer()
+    )
+  )
+)
+
+output = renderer.render(invoice)
+```
+
+**Key insight:** Each decorator is independent. Adding a new rendering behavior means one new class. No modification to existing decorators or the base renderer. The wrapping order determines execution order.
+
+---
+
+## Bridge
+
+**When to use:**
+- You have two dimensions of variation (e.g., shape × color, platform × UI control)
+- You want to avoid a combinatorial explosion of subclasses
+- You want to vary implementation and abstraction independently
+
+**Smell that triggers it:**
+- Class hierarchy growing as every combination of two independent concepts creates a new subclass
+- `RedCircle`, `BlueCircle`, `RedSquare`, `BlueSquare`... and new colors or shapes keep appearing
+
+**Solution:**
+```
+// Implementation dimension
+interface Renderer:
+  renderCircle(radius)
+  renderRectangle(width, height)
+
+class CanvasRenderer implements Renderer: ...
+class SVGRenderer implements Renderer: ...
+class PDFRenderer implements Renderer: ...
+
+// Abstraction dimension — holds a reference to implementation
+abstract class Shape:
+  constructor(renderer: Renderer)
+
+class Circle extends Shape:
+  constructor(renderer, radius)
+  draw(): this.renderer.renderCircle(this.radius)
+
+class Rectangle extends Shape:
+  constructor(renderer, width, height)
+  draw(): this.renderer.renderRectangle(this.width, this.height)
+
+// New renderer = one new class. New shape = one new class.
+// No combinatorial explosion.
+circle = new Circle(new SVGRenderer(), 50)
+circle.draw()
+```
+
+**Key insight:** Two independent hierarchies connected by composition, not inheritance. Adding a new renderer or a new shape is one class each, never a product of both.

package/continuous-improvement/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: continuous-improvement
+description: Post-release quality and process improvement skill grounded in Deming's system thinking. Use after a release ships, when the team wants to run a retrospective, when defects or rework surfaced during a release cycle, when the user says "retrospective", "what went wrong", "improve our process", or "why did that happen". Reads release plans, usability evaluations, and commit history. Produces measurement reports, root cause analyses, and process updates that feed back into the other skills. This is the closing loop — without it the methodology cannot learn from itself.
+---
+
+# Continuous Improvement
+
+## Core Principle: The System, Not the Individual
+
+Most defects are produced by the system — the process, the tools, the structure — not by the people in it. A bug that slips to production is not evidence that a developer made a mistake. It is evidence that the process allowed it through. A design that required rework is not evidence that a designer failed. It is evidence that the evaluation caught it too late or not at all.
+
+This skill investigates the system. It asks "why did the process produce this outcome?" not "who made this mistake?" Root cause analysis that ends with blaming an individual has found a symptom, not a cause. The cause is always upstream in the process.
+
+## When to Run This Skill
+
+- **After every release ships** — run measurement (Step 1) as a lightweight check
+- **When a defect reaches production** — run full root cause analysis (Step 2)
+- **When a feature required significant rework** — run root cause analysis to find where the process failed to catch it earlier
+- **After 3+ releases** — run process update (Step 3) to see if patterns have emerged
+
+## Workflow
+
+### Step 1: Measure
+
+Collect the data the release naturally produced. This is not a separate instrumentation effort — every artifact in the methodology already contains the signals. The job here is to read them and record the numbers.
+
+See `references/measurement.md` for what to measure, where each signal comes from, and the measurement report format.
+
+Create: `/docs/continuous-improvement/measurements/r[N]-[name].md`
+
+### Step 2: Root Cause Analysis
+
+When a defect reached production, or a feature required rework that should have been caught earlier, investigate why. The goal is to find the earliest point in the process where the outcome was already determined — not the point where it was discovered.
+
+See `references/root-cause-analysis.md` for the investigation method, the "5 Whys" technique adapted for software process, and the report format.
+
+Create: `/docs/continuous-improvement/root-causes/[incident-name].md`
+
+### Step 3: Process Update
+
+Findings from measurement and root cause analysis feed back into the methodology. A pattern in the data means a skill needs updating. A single root cause points to a specific gap.
+
+See `references/process-update.md` for how to decide what changes, how to apply changes to the skills, and how to validate that the change worked.
+
+Update: the relevant skill's SKILL.md or references as identified.
+
+## File Structure
+
+```
+docs/continuous-improvement/
+├── measurements/
+│   ├── r1-[name].md          ← measurement report per release
+│   └── r2-[name].md
+└── root-causes/
+    └── [incident-name].md    ← root cause analysis per incident
+```
+
+## Integration
+
+```
+ux-research → story-mapping → bdd-specification → ux-design →
+ui-design-workflow → atdd-workflow → [RELEASE SHIPS]
+                                          ↓
+                              continuous-improvement (this skill)
+                                          ↓
+                              feeds back into any skill above
+```
+
+This is the only skill that writes back into other skills. Every other skill in the methodology is a consumer. This one is the loop that closes.

package/continuous-improvement/references/measurement.md

@@ -0,0 +1,133 @@
+# Measurement
+
+## Why Measure?
+
+You cannot improve what you do not measure. But measurement is only useful if it measures the right things — signals that reveal whether the process is healthy, not vanity numbers that feel productive but change nothing.
+
+The methodology already produces every signal needed. No new instrumentation. No dashboards. No tracking tools. The data lives in the artifacts each skill already creates. This skill reads them after a release and records the numbers.
+
+## What to Measure
+
+Nine signals. Each one maps to a specific artifact that already exists.
+
+### Signal 1: Scenarios Written vs Scenarios Passing
+
+**What it measures:** How well the acceptance criteria matched what was actually built. A large gap means scenarios were ambiguous or the implementation drifted from intent.
+
+**Where to find it:**
+- Written: count the Scenario blocks in `/features/[domain]/*.feature`
+- Passing: count the passing acceptance tests in the test run report
+
+**Healthy range:** 95–100% passing on first release. Below 90% indicates scenarios need refinement before implementation begins.
+
+### Signal 2: Usability Violations Found vs Violations Found Late
+
+**What it measures:** Whether the usability evaluation is catching problems at the right time. Violations found during evaluation (before screen design) cost nothing. Violations found during implementation or after shipping cost a full rework cycle.
+
+**Where to find it:**
+- Planned violations: `/docs/ux-design/usability-evaluation/[feature].md` — the Violations Found section
+- Late violations: any design change that occurred after ui-design-workflow produced screen flows, or any bug report that maps to a usability heuristic
+
+**Healthy range:** >80% of violations found during evaluation. Any violation discovered after shipping is a process failure worth investigating.
+
+### Signal 3: Acceptance Targets Defined vs Acceptance Targets Tested
+
+**What it measures:** Whether every design decision that matters has a test behind it. Untested design decisions drift.
+
+**Where to find it:**
+- Defined: count the checkboxes in the Acceptance Targets section of `/docs/ui-design/screen-flows/[feature].md`
+- Tested: count the acceptance test assertions that map to those targets
+
+**Healthy range:** 100%. Every defined target has a test. Any gap means a design decision is unverified.
+
+### Signal 4: Red-Green-Refactor Cycles Per Feature
+
+**What it measures:** How tight the implementation loop is. A large number of cycles per feature is healthy — it means the developer is working in small, verified increments. A small number means either the feature was trivially simple or the developer wrote large chunks without verification.
+
+**Where to find it:** Count the commits tagged with `feat:`, `test:`, and `refactor:` per feature in git history. Each RED-GREEN-REFACTOR sequence is one cycle.
+
+**Healthy range:** 3+ cycles per feature. Fewer than 3 on a non-trivial feature means the ATDD loop is not being followed tightly enough.
+
+### Signal 5: Defects Reaching Production
+
+**What it measures:** How many bugs escaped the entire methodology and reached users. This is the most expensive signal — every production defect represents a failure somewhere upstream in the process.
+
+**Where to find it:** Bug reports or production incident logs. Each defect is tagged with which feature it belongs to.
+
+**Healthy range:** 0 per release for critical defects. Any critical defect in production triggers a root cause analysis (see root-cause-analysis.md).
+
+### Signal 6: Rework After Screen Flows Were Designed
+
+**What it measures:** Whether the design process produced stable specifications. Rework after screen flows means something was missed during ux-design or ui-design-workflow.
+
+**Where to find it:** Compare the original screen flow document date to any subsequent revisions. Any revision after atdd-workflow began implementation is rework.
+
+**Healthy range:** 0 revisions after implementation begins. Any rework after that point triggers root cause analysis.
+
+### Signal 7: Story Map Accuracy
+
+**What it measures:** How well the story map predicted what actually shipped. Tasks that were Must Have but didn't ship, or tasks that shipped but weren't planned, indicate the estimation and prioritization process needs calibration.
+
+**Where to find it:**
+- Planned: `/docs/story-map/releases/r[N]-[name].md` — the Tasks section with MoSCoW priorities
+- Actual: what actually shipped in the release
+
+**Healthy range:** All Must Have tasks shipped. Should Have tasks shipped or explicitly deferred with documented reason. No unplanned work shipped without a documented decision to include it.
+
+### Signal 8: Time From Scenario to Shipped
+
+**What it measures:** The total flow time for a feature — from when the scenario was written to when it shipped. This reveals whether bottlenecks exist in the process. A long gap between scenario and shipped means something stalled.
+
+**Where to find it:** Compare the feature file creation date (or first commit to the .feature file) to the release ship date.
+
+**Healthy range:** Consistent across features in the same release. Large variance between features indicates a bottleneck on specific types of work.
+
+### Signal 9: Mental Model Conflicts Found
+
+**What it measures:** Whether the product is drifting away from user mental models. Conflicts found during ux-design are cheap to fix. Conflicts discovered by users after shipping are expensive and erode trust.
+
+**Where to find it:**
+- Planned conflicts: `/docs/ux-research/mental-models/*.md` — the "Where the System Model Differs" section
+- User-discovered conflicts: support tickets, user feedback, or usability testing results that indicate confusion about how the product works
+
+**Healthy range:** All known conflicts addressed before shipping. Any user-discovered conflict not predicted by the mental model documents indicates the research phase missed something.
+
+## Measurement Report Format
+
+Create: `/docs/continuous-improvement/measurements/r[N]-[name].md`
+
+```markdown
+# Measurement Report: Release [N] — [Name]
+
+**Release date:** [Date]
+**Features shipped:** [List]
+
+## Signals
+
+| Signal | Target | Actual | Status |
+|---|---|---|---|
+| Scenarios written vs passing | ≥95% | [N]% | ✅ / ⚠️ / 🔴 |
+| Usability violations: found early vs late | ≥80% early | [N]% early | ✅ / ⚠️ / 🔴 |
+| Acceptance targets: defined vs tested | 100% | [N]% | ✅ / ⚠️ / 🔴 |
+| Red-Green-Refactor cycles per feature | ≥3 | [N] avg | ✅ / ⚠️ / 🔴 |
+| Defects reaching production | 0 critical | [N] | ✅ / ⚠️ / 🔴 |
+| Rework after screen flows designed | 0 | [N] | ✅ / ⚠️ / 🔴 |
+| Story map accuracy | All Must Have shipped | [summary] | ✅ / ⚠️ / 🔴 |
+| Time from scenario to shipped | Consistent | [range] | ✅ / ⚠️ / 🔴 |
+| Mental model conflicts | 0 user-discovered | [N] | ✅ / ⚠️ / 🔴 |
+
+**Status key:** ✅ Within healthy range. ⚠️ Borderline — monitor next release. 🔴 Outside healthy range — investigate.
+
+## Summary
+[1–2 sentences: overall process health this release. Which signals are healthy, which need attention.]
+
+## Signals Requiring Investigation
+[List any 🔴 signals. Each becomes a root cause analysis if the cause is not immediately obvious.]
+```
+
+## Rules
+
+- Run measurement after every release. It takes 30 minutes if the artifacts are well-maintained.
+- Record actuals even when they are healthy. Trends over multiple releases reveal drift that a single measurement cannot.
+- A 🔴 signal does not mean the team failed. It means the system produced an outcome worth investigating. See root-cause-analysis.md.
+- Do not skip signals because they are inconvenient. Every signal exists for a reason. Skipping one creates a blind spot.

package/continuous-improvement/references/process-update.md

@@ -0,0 +1,118 @@
+# Process Update
+
+## What Is a Process Update?
+
+A process update is a change to one of the other skills in the methodology, made in response to findings from measurement or root cause analysis. It is the mechanism by which the methodology learns.
+
+Without process updates, the methodology is static. It will produce the same outcomes forever — including the same failures. Process updates close the loop.
+
+## When to Make a Process Update
+
+Not every finding warrants a change. Changes add complexity. Unnecessary complexity degrades the process just as surely as missing checks do.
+
+### Change if:
+
+- A root cause analysis identified a specific gap in a skill — a missing check, a missing signal, an insufficient prompt
+- A measurement signal was 🔴 for two consecutive releases (common cause — the system is producing this outcome consistently)
+- A root cause analysis identified a new class of risk the methodology has no check for
+
+### Do NOT change if:
+
+- A measurement signal was 🔴 once but recovered the next release (likely special cause — addressed by the specific root cause fix, not a systemic change)
+- The finding is about team behavior, not process structure ("the team should be more careful" is not a process update)
+- The proposed change would add a step that every feature must go through, but the problem only affects rare edge cases (the cost of the check exceeds the cost of the occasional failure)
+
+## How to Decide What Changes
+
+### Step 1: Locate the Gap
+
+The root cause analysis already points to a specific skill and a specific gap. Confirm by reading the relevant skill file. The gap will be one of these types:
+
+**Missing check:** The skill does not require verification at a point where a problem can be caught. Fix: add the check.
+
+**Insufficient prompt:** The skill requires a check but does not ask the right questions. Fix: add specificity to the prompt or checklist.
+
+**Missing signal:** The measurement report does not track something that would have revealed this problem earlier. Fix: add the signal to measurement.md.
+
+**Wrong ordering:** The skill requires a check but at a point too late in the process to prevent the cost. Fix: move the check earlier.
+
+### Step 2: Scope the Change
+
+Before changing anything, state precisely:
+- What file changes
+- What line or section changes
+- What is added, removed, or modified
+- What the change prevents that was not previously prevented
+
+A process update should be surgical. If the change requires rewriting an entire reference file, the scope is wrong — narrow it.
+
+### Step 3: Apply the Change
+
+Edit the skill directly. The skills live in the repository alongside the product code. A process update is a commit just like any other.
+
+**Commit convention for process updates:**
+```
+chore(continuous-improvement): [brief description of what changed and why]
+
+Example:
+chore(continuous-improvement): add numeric field constraint check to example mapping
+
+Root cause: RCA-2024-03 found that example mapping does not surface
+numeric validation rules. Added explicit prompt for min/max/zero
+constraints on all numeric fields.
+```
+
+### Step 4: Validate the Change Worked
+
+This is the most important step and the most commonly skipped. A change that is never validated is just a guess that was written down.
+
+**How to validate:**
+- Define the validation criterion before making the change: "In the next release, if a numeric field exists, the example mapping will have documented its constraints."
+- After the next release, check whether the criterion was met.
+- If met: the fix worked. Close the loop.
+- If not met: the fix was insufficient. Re-investigate. This is not failure — it is the loop working as designed.
+
+**Record validation in the root cause analysis document.** Update the "Applied" checkbox and add a note under Validation with the result.
+
+## Types of Process Updates
+
+### Adding a Checklist Item
+
+The most common update. A check that should exist does not.
+
+**Example:** Root cause analysis found that example mapping does not ask about numeric field constraints. The fix is to add an item to the example mapping checklist in `bdd-specification/references/example-mapping.md`.
+
+**How to apply:** Find the checklist or prompt section in the relevant reference. Add the item. Keep it specific — "What values are invalid for this field?" not "Check for edge cases."
+
+### Adding a Measurement Signal
+
+A problem was not visible in measurement because nothing was tracking it.
+
+**Example:** Root cause analysis found that design rework after implementation began was not being tracked. The fix is to add Signal 6 (Rework after screen flows designed) to `continuous-improvement/references/measurement.md`.
+
+**How to apply:** Add the signal to measurement.md with: what it measures, where to find it, and what the healthy range is.
+
+### Strengthening an Evaluation
+
+An evaluation exists but is not catching a class of problem it should catch.
+
+**Example:** Usability evaluation consistently misses state transition issues. The fix is to add a specific check for state visibility and transition feedback to the heuristic H1 section in `ux-design/references/usability-evaluation.md`.
+
+**How to apply:** Find the relevant heuristic. Add a specific check question that would have caught the missed problem.
+
+### Moving a Check Earlier
+
+A check exists but fires too late — after the cost of the problem has already grown.
+
+**Example:** Mental model conflicts are being discovered during implementation rather than during ux-design. The fix is to add a mental model consistency check to the scenario validation step in `bdd-specification/SKILL.md` — scenarios are checked against mental models before they reach ux-design.
+
+**How to apply:** Add the check to the earlier skill's workflow. Update the later skill's input assumptions to reflect that this check has already been performed.
+
+## Rules
+
+- Every process update traces back to a specific root cause analysis or a specific measurement pattern. No speculative changes.
+- Changes are small and surgical. One fix per commit.
+- Every change has a defined validation criterion. Without it, the change is not applied.
+- Process updates are reviewed by reading the changed skill end-to-end after the change. Ensure the change does not conflict with or duplicate anything else in the skill.
+- If a process update would affect how two or more skills interact, update both skills and document the dependency in both.
+- The methodology is the team's shared tool. A process update that makes the methodology better for one person but harder for others is not a good update. Discuss before applying.