@schilling.mark.a/software-methodology 1.0.0

package/continuous-improvement/references/root-cause-analysis.md

@@ -0,0 +1,144 @@
+# Root Cause Analysis
+
+## When to Run
+
+Root cause analysis runs when measurement reveals a 🔴 signal, or when a defect reaches production, or when a feature required rework after screen flows were designed. It does not run for every small issue — only for outcomes that indicate a process failure, not a one-off mistake.
+
+**Triggers:**
+- A critical defect reached production
+- A feature was reworked after implementation began
+- A usability violation was discovered after shipping
+- A measurement signal was 🔴 for two consecutive releases (pattern, not noise)
+
+## The Core Discipline: Find the System Failure
+
+Deming's insight is blunt: in a well-designed system, individual errors are rare. When errors are common, the system is producing them. The investigation must find where the system broke down — not where the individual broke down.
+
+**This means the root cause is never:**
+- "The developer made a mistake"
+- "The designer didn't catch it"
+- "Someone wasn't paying attention"
+
+**The root cause is always one of:**
+- The process did not require a check at the point where this should have been caught
+- The process required a check but did not provide the information needed to perform it
+- The process required a check but the check was not specific enough to catch this class of problem
+- The process produced the right check but too late — after the cost of fixing had already grown
+
+## The 5 Whys — Adapted for Software Process
+
+The 5 Whys technique asks "why?" repeatedly until it reaches a systemic cause. In software process, the technique must be adapted: each "why" must land on a process step, not on a person's judgment.
+
+### How to Apply
+
+Start with the outcome. Ask why. If the answer is about a person ("the developer didn't test it"), reframe: what did the process require at that point, and why did the requirement not prevent this outcome?
+
+### Example
+
+**Outcome:** A bug shipped to production where a form accepted a negative dollar amount.
+
+**Why did it reach production?**
+→ No acceptance test covered negative amounts.
+
+**Why was there no acceptance test for negative amounts?**
+→ The acceptance targets document did not include negative amount validation as a target.
+
+**Why was negative amount validation not in the acceptance targets?**
+→ The screen flow did not specify validation rules for the amount field — it only specified the field exists and accepts numbers.
+
+**Why did the screen flow not specify validation rules?**
+→ The scenario in the feature file did not include an alternative path for invalid amounts. It only covered the happy path.
+
+**Why did the scenario not cover invalid amounts?**
+→ Example mapping did not surface negative amounts as an edge case. The business rule "amounts must be positive" was not listed in the rules discovered during example mapping.
+
+**Root cause:** Example mapping did not surface the "amounts must be positive" business rule. This is a process gap — example mapping needs a prompt or checklist that explicitly asks about numeric field constraints.
+
+**Fix:** Add "For every numeric field: what values are invalid? What is the minimum? Maximum? Can it be zero?" to the example mapping checklist in bdd-specification's example-mapping.md reference.
+
+### The Reframing Rule
+
+At every step, if the answer names a person, reframe:
+
+| Person-focused answer | Reframed as process question |
+|---|---|
+| "Dev didn't write a test" | "What did the process require at that point, and why didn't it prevent this?" |
+| "Designer missed it" | "What check existed to catch this, and why was it insufficient?" |
+| "No one noticed" | "Where in the process should this have been visible, and why wasn't it?" |
+| "It slipped through" | "What gate should have caught this, and what was missing from that gate?" |
+
+## Depth of Investigation
+
+Not every incident needs 5 full rounds of "why." Stop when you reach a cause that is:
+- Systemic (affects the process, not just this instance)
+- Actionable (can be fixed by changing a skill, a checklist, or a process step)
+- Specific (points to exactly where in the methodology the gap exists)
+
+If after 5 rounds you have not reached a systemic cause, the problem may be genuinely novel — something the process could not have been designed to catch. Document it as a new class of risk and add a check for it.
+
+## Distinguishing Common Cause from Special Cause
+
+Deming distinguished two types of variation:
+
+**Common cause:** The system is working as designed, but the design allows this outcome. Fixing it requires changing the system. Example: "Usability violations are consistently found late" across multiple releases — the evaluation process is structurally insufficient.
+
+**Special cause:** Something unusual happened this one time. Fixing it requires addressing the specific unusual event, not redesigning the system. Example: "A typo in a business rule caused a wrong calculation" — the rule was transcribed incorrectly once. A review step at that specific point would catch it.
+
+**Why this matters:** Treating a common cause as a special cause (blaming the individual) changes nothing — the system will produce the same outcome again. Treating a special cause as a common cause (redesigning the system for a one-off event) adds unnecessary complexity.
+
+**How to tell the difference:** Look at measurement history. If the same type of failure appeared in previous releases, it is common cause. If this is the first time, it is likely special cause. Act accordingly.
+
+## Report Format
+
+Create: `/docs/continuous-improvement/root-causes/[incident-name].md`
+
+```markdown
+# Root Cause Analysis: [Incident Name]
+
+**Date discovered:** [When the problem was found]
+**Release:** [Which release]
+**Trigger:** [What caused this investigation — production defect, rework, measurement signal]
+**Cause type:** Common cause / Special cause
+
+## Outcome
+[What happened. Specific, factual. No blame.]
+
+## Investigation
+
+### Why 1
+**Question:** [Why did this outcome occur?]
+**Answer:** [What the process produced at this point]
+
+### Why 2
+**Question:** [Why did the process produce that?]
+**Answer:** [What was missing or insufficient]
+
+### Why 3
+[Continue until root cause is reached]
+
+### Why 4
+[If needed]
+
+### Why 5
+[If needed]
+
+## Root Cause
+[One clear statement of where the system failed. Points to a specific skill and a specific gap in that skill.]
+
+## Fix
+**Skill affected:** [Which skill needs updating]
+**File affected:** [Which SKILL.md or reference file]
+**Change:** [What specifically changes — add a checklist item, add a validation step, add a new signal to measurement, etc.]
+**Applied:** [ ] Yes / [ ] No
+
+## Validation
+[How will we know the fix worked? What signal in the next release confirms this class of problem no longer occurs?]
+```
+
+## Rules
+
+- Every production defect gets a root cause analysis. No exceptions.
+- The investigation stops at a systemic cause, not at a person.
+- The fix is always a change to a skill or a process step — never "be more careful."
+- The validation section is mandatory. If you cannot define how to verify the fix worked, the fix is not specific enough.
+- Root cause analyses are kept permanently. They are the memory of the system. When a new incident occurs, check if a previous root cause analysis covers the same class of failure — if so, the previous fix did not work and needs revisiting.

package/docs/INTEGRATION.md

@@ -0,0 +1,229 @@
+# Integration Architecture
+
+This document explains how the software methodology integrates with different AI coding assistants.
+
+## Multi-Tool Support
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│         Software Methodology Repository                     │
+│                                                              │
+│  ┌────────────────┐              ┌────────────────┐        │
+│  │  Skill Sources │              │  Documentation │        │
+│  │  (Markdown)    │              │                │        │
+│  │                │              │  - SKILLS.md   │        │
+│  │  - SKILL.md    │              │  - QUICKSTART  │        │
+│  │  - references/ │              │                │        │
+│  └───────┬────────┘              └────────────────┘        │
+│          │                                                  │
+│          │ Packaged into                                   │
+│          ▼                                                  │
+│  ┌────────────────┐                                        │
+│  │  .skill files  │                                        │
+│  │  (dist/)       │                                        │
+│  └────────────────┘                                        │
+└──────────┬──────────────────┬──────────────┬───────────────┘
+           │                  │              │
+           │                  │              │
+           ▼                  ▼              ▼
+    ┌─────────────┐   ┌──────────────┐  ┌──────────────┐
+    │ Claude Code │   │    Copilot   │  │   VS Code    │
+    └─────────────┘   └──────────────┘  └──────────────┘
+    Uses .skill       Reads .github/    Uses markdown
+    files from        copilot-          directly +
+    /mnt/skills/      instructions.md   workspace
+    user/                               settings
+```
+
+## File Organization
+
+### For Claude Code
+- **Input**: `.skill` files from `dist/` directory
+- **Location**: `/mnt/skills/user/` on the user's system
+- **Format**: Zipped markdown files with `.skill` extension
+- **Workflow**: Deploy → Use skills via project `context.md`
+
+### For GitHub Copilot
+- **Input**: `.github/copilot-instructions.md`
+- **Location**: Automatically read by Copilot when in the repository
+- **Format**: Markdown with skill descriptions and guidance
+- **Workflow**: Clone repo → Copilot reads instructions → Ask questions
+
+### For VS Code
+- **Input**: Markdown files + workspace configuration
+- **Location**: `.vscode/` directory
+- **Format**: JSON settings + multi-folder workspace
+- **Workflow**: Open workspace → Navigate skills → Reference in code
+
+## Integration Points
+
+### 1. GitHub Copilot Integration
+
+```
+User asks question in VS Code or GitHub
+           ↓
+Copilot reads .github/copilot-instructions.md
+           ↓
+Copilot identifies relevant skill
+           ↓
+Copilot references skill's SKILL.md + references/
+           ↓
+Copilot provides context-aware guidance
+```
+
+**Key Files:**
+- `.github/copilot-instructions.md` — Main instructions for Copilot
+- `docs/SKILLS.md` — Index that Copilot can reference
+- All `*/SKILL.md` files — Skill entry points
+- All `*/references/*.md` — Detailed guidance
+
+### 2. VS Code Integration
+
+```
+User opens workspace
+           ↓
+VS Code loads .vscode/settings.json
+           ↓
+VS Code applies markdown optimizations
+           ↓
+User navigates folders organized by skill
+           ↓
+User reads SKILL.md and references as needed
+```
+
+**Key Files:**
+- `.vscode/settings.json` — VS Code editor settings
+- `.vscode/software-methodology.code-workspace` — Multi-folder layout
+- `docs/SKILLS.md` — Navigation index
+- `docs/QUICKSTART.md` — Getting started guide
+
+### 3. Claude Code Integration (Unchanged)
+
+```
+User deploys .skill files to /mnt/skills/user/
+           ↓
+User creates context.md in project
+           ↓
+Claude Code reads context.md at session start
+           ↓
+Claude Code loads relevant skills on demand
+           ↓
+Skills access their SKILL.md + references/
+```
+
+**Key Files:**
+- `dist/*.skill` — Packaged skill files
+- `project-templates/context.md.template` — Project setup
+- `project-templates/test-strategy.md.template` — Test configuration
+
+## Content Flow
+
+### Source → Multiple Outputs
+
+```
+Skill Source (e.g., clean-code/)
+│
+├── SKILL.md (75 lines, routing logic)
+│   └── When to use, what it does, decision tree
+│
+└── references/
+    ├── solid.md
+    ├── structural-patterns.md
+    ├── behavioral-patterns.md
+    └── ...
+    
+                ↓
+        
+        Packaged into
+        
+                ↓
+        
+┌──────────────────┬──────────────────┬──────────────────┐
+│                  │                  │                  │
+▼                  ▼                  ▼                  ▼
+dist/              .github/           .vscode/          docs/
+clean-code.skill   copilot-           settings.json     SKILLS.md
+(for Claude)       instructions.md    workspace         (index)
+                   (references        (navigation)      
+                   clean-code)
+```
+
+### No Duplication
+
+- **Skill sources** remain the single source of truth
+- **Claude Code** reads from packaged `.skill` files
+- **Copilot** reads instructions that *reference* the sources
+- **VS Code** navigates the markdown sources directly
+- **No content is duplicated** — only packaging differs
+
+## Benefits of This Architecture
+
+### 1. **Single Source of Truth**
+All skill content lives in the skill directories. Updates to SKILL.md or references/ automatically benefit all tools.
+
+### 2. **Tool Flexibility**
+Users can choose:
+- Claude Code for interactive skill execution
+- GitHub Copilot for inline code suggestions and chat
+- VS Code for manual reference and navigation
+- Any combination of the above
+
+### 3. **No Lock-in**
+The methodology is defined in markdown. If a new AI tool emerges, we can add integration without changing the skills.
+
+### 4. **Backward Compatible**
+Existing Claude Code users see no changes. The `.skill` files in `dist/` remain unchanged.
+
+### 5. **Forward Compatible**
+New skills added to the repository automatically work with all tools.
+
+## Usage Patterns
+
+### Pattern 1: Copilot for Coding, Claude for Strategy
+- Use GitHub Copilot in VS Code for day-to-day coding with inline suggestions
+- Use Claude Code for strategic work (creating canvases, story mapping, etc.)
+- Both reference the same methodology
+
+### Pattern 2: Pure Copilot
+- Clone the methodology repository as a submodule
+- Let Copilot guide you through the skills
+- Manually create deliverables (canvases, personas, etc.)
+- Reference skill markdown files as needed
+
+### Pattern 3: Pure Claude Code
+- Deploy `.skill` files to `/mnt/skills/user/`
+- Use Claude Code for the entire workflow
+- Claude executes skills and creates deliverables
+- Ignore the Copilot/VS Code integration files
+
+### Pattern 4: VS Code Reference
+- Open the methodology workspace in VS Code
+- Use it as a reference manual
+- Navigate between skills and patterns
+- Copy templates and patterns into your code
+
+## Maintenance
+
+When updating a skill:
+
+1. **Edit the source** in the skill directory (e.g., `clean-code/SKILL.md`)
+2. **Repackage for Claude** (if needed): 
+   ```bash
+   python3 /mnt/skills/examples/skill-creator/scripts/package_skill.py clean-code/ dist/
+   ```
+3. **Copilot and VS Code automatically see the changes** — no additional steps needed
+
+The integration requires no special maintenance. The documentation files (copilot-instructions.md, SKILLS.md) only need updates when:
+- Adding a new skill to the methodology
+- Changing the methodology flow/chain
+- Adding new integration patterns
+
+## Summary
+
+This architecture provides maximum flexibility:
+- **Write once** in markdown
+- **Package once** for Claude Code
+- **Reference anywhere** with Copilot and VS Code
+- **No duplication** of content
+- **No lock-in** to any single tool
+- **Backward compatible** with existing workflows

package/docs/QUICKSTART.md

@@ -0,0 +1,126 @@
+# Quick Start Guide
+
+Choose your AI coding assistant and get started with the software methodology.
+
+## For GitHub Copilot Users
+
+### In VS Code
+
+1. **Install GitHub Copilot extensions:**
+   - GitHub Copilot
+   - GitHub Copilot Chat
+
+2. **Clone or reference this repository:**
+   ```bash
+   # Add as submodule to your project
+   git submodule add https://github.com/MarkSchilling/software-methodology.git methodology
+   
+   # Or clone separately
+   git clone https://github.com/MarkSchilling/software-methodology.git
+   ```
+
+3. **Open the workspace (optional but recommended):**
+   ```bash
+   code methodology/.vscode/software-methodology.code-workspace
+   ```
+
+4. **Ask Copilot for guidance:**
+   - "Which methodology skill should I use for writing acceptance tests?"
+   - "Show me the ATDD workflow"
+   - "What clean code patterns apply here?"
+
+### In GitHub (Copilot Chat)
+
+Copilot automatically reads `.github/copilot-instructions.md` when you:
+- Ask questions in pull requests
+- Use Copilot Chat in discussions
+- Request code suggestions
+
+Example questions:
+- "How should I structure this feature based on the methodology?"
+- "What's the next step in the chain after BDD specification?"
+- "Which design pattern should I use here?"
+
+## For Claude Code Users
+
+1. **Copy skill files to your project:**
+   ```bash
+   cp dist/*.skill /mnt/skills/user/
+   ```
+
+2. **Create project context files:**
+   ```bash
+   cp project-templates/context.md.template your-project/docs/context.md
+   cp project-templates/test-strategy.md.template your-project/docs/test-strategy.md
+   ```
+
+3. **Fill in project details** in `context.md` and `test-strategy.md`
+
+4. **Start with product-strategy:**
+   Ask Claude to create the Business Model Canvas and Value Proposition Canvas.
+
+5. **Follow the chain:**
+   Each skill's `SKILL.md` tells you the prerequisites and next steps.
+
+## Core Concepts
+
+### The Methodology Chain
+
+```
+product-strategy → ux-research → story-mapping → bdd-specification →
+ux-design → ui-design-workflow → atdd-workflow → cicd-pipeline →
+continuous-improvement (feeds back)
+```
+
+### Reference Skills (Consulted During Other Steps)
+
+- **ui-design-system** — Used during `ui-design-workflow`
+- **clean-code** — Used during `atdd-workflow` GREEN and REFACTOR phases
+
+### Key Deliverables by Skill
+
+| Skill | Creates |
+|-------|---------|
+| product-strategy | Business Model Canvas, Value Proposition Canvas |
+| ux-research | Personas, Mental Models, User Journey Maps |
+| story-mapping | Backbone, Release Plans |
+| bdd-specification | Feature Files (Gherkin) |
+| ux-design | Information Architecture, Interaction Patterns |
+| ui-design-workflow | Screen Flows, Component Selections |
+| atdd-workflow | Implementation (tests + code) |
+| cicd-pipeline | Pipeline Configuration, Deployment Scripts |
+| continuous-improvement | Metrics, Root Cause Analysis, Process Improvements |
+
+## Navigation
+
+- **Full Skills Index**: See [`SKILLS.md`](SKILLS.md) for detailed information about each skill
+- **Sharing Guide**: See [`SHARING.md`](SHARING.md) for how to share with teams and organizations
+- **Project Templates**: Check [`../project-templates/`](../project-templates/) for starter files
+- **Main README**: See [`../README.md`](../README.md) for repository overview
+
+## Common Questions
+
+**Q: Do I need to use all 11 skills?**  
+A: Start with the ones relevant to your current phase. At minimum, create the Business Model Canvas and Value Proposition Canvas first — other skills depend on them.
+
+**Q: Can I use multiple AI assistants?**  
+A: Yes! The skills work with both Claude Code and GitHub Copilot. Use whichever fits your workflow.
+
+**Q: How do I know which skill to use?**  
+A: Ask your AI assistant, or check the [Skills Index](SKILLS.md) for a description of each skill's purpose and when to use it.
+
+**Q: Are the skills mandatory in order?**  
+A: For new products, yes — follow the chain. For existing products, jump to the relevant skill based on what you're working on.
+
+**Q: Can I customize the skills?**  
+A: Yes! Edit the source files in each skill directory, then repackage for Claude Code if needed. See the main README for details.
+
+**Q: How can I share these skills with my team?**  
+A: See the [Sharing Guide](SHARING.md) for multiple distribution options including forking the repo, creating packages, or using direct downloads.
+
+## Getting Help
+
+- **Skills Index**: [`SKILLS.md`](SKILLS.md)
+- **Sharing Guide**: [`SHARING.md`](SHARING.md)
+- **Repository**: [github.com/MarkSchilling/software-methodology](https://github.com/MarkSchilling/software-methodology)
+- **Issues**: Report problems or suggestions via GitHub Issues