@schilling.mark.a/software-methodology 1.0.0 → 1.0.1

package/docs/story-map/user-tasks/ACT-005-task-003.md

@@ -0,0 +1,48 @@
+# ACT-005-task-003: Select UI Components
+
+## Activity
+ACT-005: Design User Experience
+
+## User Task
+As a UI designer or developer
+I want to choose appropriate UI components for each interaction pattern
+So that the interface is consistent and uses familiar patterns
+
+## Value Proposition Link
+- Pain relieved: Inconsistent UI patterns confuse users; Developers build custom components unnecessarily
+- Gain created: Faster implementation; Consistent user experience; Accessible by default
+
+## Acceptance Criteria
+- Component selection documented for key screens
+- Components chosen from design system (reference: ui-design-system)
+- Each component mapped to interaction pattern it supports
+- Accessibility considerations documented per component
+- Components support scenarios from Gherkin feature files
+- Selection documented in `/docs/component-selection.md`
+- Follows approach from `ui-design-workflow/references/component-selection.md`
+
+## Priority
+- **MoSCoW:** Should Have
+- **Business Value:** Medium
+- **Complexity:** Low
+
+## Release
+Release 3 - UI/UX Design
+
+## Dependencies
+- ACT-005-task-002: Create screen flows (need screens to select components for)
+- ui-design-system skill (reference for available components)
+
+## Feature File
+`/features/ui-design-workflow/component-selection.feature`
+
+## Status
+- [x] Acceptance criteria defined
+- [ ] Example mapping complete
+- [ ] Scenarios written
+- [ ] Acceptance tests created
+- [ ] Implementation complete
+- [ ] Deployed
+
+## Notes
+Component selection bridges design intent and implementation. Using design system components ensures consistency and accessibility.

package/docs/story-map/user-tasks/ACT-005-task-004.md

@@ -0,0 +1,48 @@
+# ACT-005-task-004: Define Acceptance Targets
+
+## Activity
+ACT-005: Design User Experience
+
+## User Task
+As a UX designer or product owner
+I want to define measurable usability targets for key interactions
+So that we can verify the design meets usability standards
+
+## Value Proposition Link
+- Pain relieved: Features ship but are hard to use; No objective measure of design quality
+- Gain created: Users can accomplish tasks efficiently; Design decisions based on data
+
+## Acceptance Criteria
+- Acceptance targets defined for 3-5 key user tasks
+- Each target includes: task, success metric, target value, measurement method
+- Targets are specific and measurable (not vague like "easy to use")
+- Examples: "Create invoice in under 2 minutes", "Find payment status in 3 clicks or less"
+- Targets trace to VPC gains (desired outcomes)
+- Targets documented in `/docs/acceptance-targets.md`
+- Follows format from `ui-design-workflow/references/acceptance-targets.md`
+
+## Priority
+- **MoSCoW:** Could Have
+- **Business Value:** Medium
+- **Complexity:** Medium
+
+## Release
+Release 3 - UI/UX Design
+
+## Dependencies
+- ACT-005-task-002: Create screen flows (need flows to measure)
+- ACT-001-task-002: Create Value Proposition Canvas (source for desired gains)
+
+## Feature File
+`/features/ui-design-workflow/acceptance-targets.feature`
+
+## Status
+- [x] Acceptance criteria defined
+- [ ] Example mapping complete
+- [ ] Scenarios written
+- [ ] Acceptance tests created
+- [ ] Implementation complete
+- [ ] Deployed
+
+## Notes
+Acceptance targets make usability measurable. They define "good enough" before implementation and can be tested post-launch.

package/docs/story-map/user-tasks/ACT-006-task-001.md

@@ -0,0 +1,47 @@
+# ACT-006-task-001: Write Failing Acceptance Test (RED)
+
+## Activity
+ACT-006: Implement Features
+
+## User Task
+As a developer
+I want to write an automated test that verifies a Gherkin scenario before implementing the feature
+So that I have clear success criteria and catch regressions early
+
+## Value Proposition Link
+- Pain relieved: Writing tests after code feels like extra work and is often skipped
+- Gain created: Have clear criteria for "done"; Spend less time debugging
+
+## Acceptance Criteria
+- Test written that automates one Gherkin scenario
+- Test fails with clear error message (RED phase)
+- Test uses Given-When-Then structure matching scenario
+- Test setup includes necessary test data
+- Test assertion checks observable behavior, not implementation
+- Test follows project test strategy format
+- Test can be run with a single command
+
+## Priority
+- **MoSCoW:** Must Have
+- **Business Value:** High
+- **Complexity:** Medium
+
+## Release
+Release 1 - Walking Skeleton
+
+## Dependencies
+- ACT-004-task-002: Write Gherkin scenarios (source for test specification)
+
+## Feature File
+`/features/atdd-workflow/red-phase.feature`
+
+## Status
+- [x] Acceptance criteria defined
+- [ ] Example mapping complete
+- [ ] Scenarios written
+- [ ] Acceptance tests created
+- [ ] Implementation complete
+- [ ] Deployed
+
+## Notes
+RED phase is critical. Test must fail for the right reason (feature not implemented) not wrong reason (bad test setup). Walking skeleton version focuses on one happy path scenario.

package/docs/story-map/user-tasks/ACT-006-task-002.md

@@ -0,0 +1,46 @@
+# ACT-006-task-002: Make Test Pass with Minimum Code (GREEN)
+
+## Activity
+ACT-006: Implement Features
+
+## User Task
+As a developer
+I want to write the simplest implementation that makes the failing test pass
+So that I deliver working functionality quickly before optimizing
+
+## Value Proposition Link
+- Pain relieved: Code becomes messy over time without clear patterns
+- Gain created: Ship smaller increments more frequently; Feel confident refactoring
+
+## Acceptance Criteria
+- Previously failing test now passes
+- Implementation includes only code necessary to pass the test
+- No premature optimization or "future-proofing"
+- Code follows basic language idioms and conventions
+- Test runs green with no errors or warnings
+- Implementation addresses the scenario's "So that" business value
+
+## Priority
+- **MoSCoW:** Must Have
+- **Business Value:** High
+- **Complexity:** Medium
+
+## Release
+Release 1 - Walking Skeleton
+
+## Dependencies
+- ACT-006-task-001: Write failing acceptance test (must have RED before GREEN)
+
+## Feature File
+`/features/atdd-workflow/green-phase.feature`
+
+## Status
+- [x] Acceptance criteria defined
+- [ ] Example mapping complete
+- [ ] Scenarios written
+- [ ] Acceptance tests created
+- [ ] Implementation complete
+- [ ] Deployed
+
+## Notes
+GREEN phase focuses on making it work, not making it beautiful. Resist urge to refactor here. That's the next step (REFACTOR phase). Walking skeleton version implements simplest path only.

package/docs/story-map/user-tasks/ACT-006-task-003.md

@@ -0,0 +1,47 @@
+# ACT-006-task-003: Refactor for Maintainability
+
+## Activity
+ACT-006: Implement Features
+
+## User Task
+As a developer
+I want to improve code structure while keeping tests green
+So that the code is maintainable and follows clean code principles
+
+## Value Proposition Link
+- Pain relieved: Code becomes messy over time without clear patterns
+- Gain created: Feel confident refactoring and extending code; Build transferable skills
+
+## Acceptance Criteria
+- All tests remain green throughout refactoring
+- At least one SOLID principle explicitly applied
+- Code duplications extracted to shared functions/methods
+- Variable and function names use ubiquitous language from domain
+- Code structure improves (measured by reduced complexity or improved readability)
+- No new functionality added (behavior unchanged)
+- Refactoring documented in commit message or code comments
+
+## Priority
+- **MoSCoW:** Must Have
+- **Business Value:** High
+- **Complexity:** Medium
+
+## Release
+Release 1 - Walking Skeleton
+
+## Dependencies
+- ACT-006-task-002: Make test pass with minimum code (must have GREEN before REFACTOR)
+
+## Feature File
+`/features/atdd-workflow/refactor-phase.feature`
+
+## Status
+- [x] Acceptance criteria defined
+- [ ] Example mapping complete
+- [ ] Scenarios written
+- [ ] Acceptance tests created
+- [ ] Implementation complete
+- [ ] Deployed
+
+## Notes
+REFACTOR phase is where clean code principles apply. Reference `clean-code/references/solid.md` for guidance. Walking skeleton version applies one principle explicitly. Full version reviews all SOLID principles.

package/docs/story-map/user-tasks/ACT-006-task-004.md

@@ -0,0 +1,46 @@
+# ACT-006-task-004: Review Code Against SOLID Principles
+
+## Activity
+ACT-006: Implement Features
+
+## User Task
+As a developer or code reviewer
+I want to evaluate code against SOLID principles systematically
+So that we maintain code quality and identify improvement opportunities
+
+## Value Proposition Link
+- Pain relieved: Code becomes messy over time without clear patterns
+- Gain created: Build transferable skills; Feel confident refactoring; Code reviews focus on meaningful issues
+
+## Acceptance Criteria
+- Code reviewed against all 5 SOLID principles: Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion
+- Each principle evaluated with concrete evidence (not subjective opinion)
+- Violations identified with specific line references
+- Refactoring opportunities documented (not all violations require immediate fix)
+- Review documented in PR comments or code review notes
+- References `clean-code/references/solid.md` for principle definitions
+
+## Priority
+- **MoSCoW:** Should Have
+- **Business Value:** Medium
+- **Complexity:** Medium
+
+## Release
+Release 2 - Enhanced Implementation
+
+## Dependencies
+- ACT-006-task-003: Refactor for maintainability (review happens after GREEN+REFACTOR)
+
+## Feature File
+`/features/atdd-workflow/code-review.feature`
+
+## Status
+- [x] Acceptance criteria defined
+- [ ] Example mapping complete
+- [ ] Scenarios written
+- [ ] Acceptance tests created
+- [ ] Implementation complete
+- [ ] Deployed
+
+## Notes
+Systematic SOLID review prevents "code review is just opinion" problem. Walking skeleton version applies one principle during REFACTOR; full version reviews all five.

package/docs/story-map/user-tasks/ACT-007-task-001.md

@@ -0,0 +1,48 @@
+# ACT-007-task-001: Set Up Pipeline Stages
+
+## Activity
+ACT-007: Deploy Safely
+
+## User Task
+As a developer
+I want an automated pipeline that builds, tests, and deploys code
+So that I can ship to production with confidence and without manual steps
+
+## Value Proposition Link
+- Pain relieved: Fear of breaking existing functionality; Manual deployment errors
+- Gain created: Make confident changes without breaking existing functionality; Deploy smaller increments more frequently
+
+## Acceptance Criteria
+- Pipeline configuration file created
+- Build stage: compiles/bundles code, fails on build errors
+- Test stage: runs automated tests, fails if any test fails
+- Deploy stage: deploys to target environment on successful test
+- Pipeline runs automatically on code push
+- Pipeline status visible (pass/fail) in version control system
+- Failed pipeline prevents deployment
+- Pipeline completes in under 10 minutes
+
+## Priority
+- **MoSCoW:** Must Have
+- **Business Value:** High
+- **Complexity:** High
+
+## Release
+Release 1 - Walking Skeleton
+
+## Dependencies
+- ACT-006-task-003: Refactor for maintainability (need working code with tests to deploy)
+
+## Feature File
+`/features/cicd-pipeline/pipeline-stages.feature`
+
+## Status
+- [x] Acceptance criteria defined
+- [ ] Example mapping complete
+- [ ] Scenarios written
+- [ ] Acceptance tests created
+- [ ] Implementation complete
+- [ ] Deployed
+
+## Notes
+Pipeline is the delivery mechanism. Walking skeleton version: single environment, linear stages. Full version adds: multiple environments, blue-green deployment, automated rollback, performance testing.

package/docs/story-map/user-tasks/ACT-007-task-002.md

@@ -0,0 +1,47 @@
+# ACT-007-task-002: Configure Environment Promotion
+
+## Activity
+ACT-007: Deploy Safely
+
+## User Task
+As a DevOps engineer or tech lead
+I want to define how code progresses through environments (dev → staging → production)
+So that we test changes thoroughly before production deployment
+
+## Value Proposition Link
+- Pain relieved: Fear of breaking existing functionality; Production issues that weren't caught in testing
+- Gain created: Make confident changes; Catch issues before users see them
+
+## Acceptance Criteria
+- At least 2 environments defined (e.g., staging and production)
+- Promotion criteria defined for each environment (e.g., "all tests pass" to reach staging, "manual approval" to reach production)
+- Environment differences documented (data, integrations, config)
+- Promotion process automated (no manual file copying)
+- Failed promotion blocks further progression
+- Environment configuration saved in `/docs/environment-promotion.md`
+- Follows guidance from `cicd-pipeline/references/environment-promotion.md`
+
+## Priority
+- **MoSCoW:** Should Have
+- **Business Value:** High
+- **Complexity:** High
+
+## Release
+Release 2 - Enhanced CI/CD
+
+## Dependencies
+- ACT-007-task-001: Set up pipeline stages (need basic pipeline before adding environments)
+
+## Feature File
+`/features/cicd-pipeline/environment-promotion.feature`
+
+## Status
+- [x] Acceptance criteria defined
+- [ ] Example mapping complete
+- [ ] Scenarios written
+- [ ] Acceptance tests created
+- [ ] Implementation complete
+- [ ] Deployed
+
+## Notes
+Environment promotion adds safety gates. Walking skeleton deploys to single environment; full version progresses through multiple environments with gates.

package/docs/story-map/user-tasks/ACT-007-task-003.md

@@ -0,0 +1,47 @@
+# ACT-007-task-003: Implement Deployment Strategy
+
+## Activity
+ACT-007: Deploy Safely
+
+## User Task
+As a DevOps engineer or tech lead
+I want to deploy using a strategy that minimizes downtime and risk
+So that we can release frequently without disrupting users
+
+## Value Proposition Link
+- Pain relieved: Fear of breaking existing functionality; Deployments require downtime
+- Gain created: Deploy smaller increments more frequently; Zero-downtime releases
+
+## Acceptance Criteria
+- Deployment strategy selected (blue-green, canary, rolling, feature flags)
+- Strategy implemented and documented
+- Deployment can complete without user-facing downtime
+- Ability to serve traffic from old and new versions simultaneously (if applicable)
+- Deployment monitored for errors during rollout
+- Strategy documented in `/docs/deployment-strategy.md`
+- Follows patterns from `cicd-pipeline/references/deployment-rollback.md`
+
+## Priority
+- **MoSCoW:** Should Have
+- **Business Value:** High
+- **Complexity:** High
+
+## Release
+Release 2 - Enhanced CI/CD
+
+## Dependencies
+- ACT-007-task-002: Configure environment promotion (need environments to deploy to)
+
+## Feature File
+`/features/cicd-pipeline/deployment-strategy.feature`
+
+## Status
+- [x] Acceptance criteria defined
+- [ ] Example mapping complete
+- [ ] Scenarios written
+- [ ] Acceptance tests created
+- [ ] Implementation complete
+- [ ] Deployed
+
+## Notes
+Deployment strategy enables frequent, low-risk releases. Blue-green and canary strategies provide instant rollback capability.

package/docs/story-map/user-tasks/ACT-007-task-004.md

@@ -0,0 +1,48 @@
+# ACT-007-task-004: Test Rollback Procedure
+
+## Activity
+ACT-007: Deploy Safely
+
+## User Task
+As a DevOps engineer or developer
+I want to verify we can rollback a deployment quickly and safely
+So that we can recover from bad deployments without extended outages
+
+## Value Proposition Link
+- Pain relieved: Fear of breaking existing functionality; Bad deployments cause extended downtime
+- Gain created: Make confident changes; Deploy more frequently knowing we can undo
+
+## Acceptance Criteria
+- Rollback procedure documented step-by-step
+- Rollback tested in non-production environment
+- Rollback completes in under 5 minutes (target)
+- Rollback verified to restore previous working state
+- Data migrations considered (can they be rolled back?)
+- Rollback can be triggered with single command or button
+- Procedure documented in `/docs/rollback-procedure.md`
+- Follows guidance from `cicd-pipeline/references/deployment-rollback.md`
+
+## Priority
+- **MoSCoW:** Should Have
+- **Business Value:** High
+- **Complexity:** Medium
+
+## Release
+Release 2 - Enhanced CI/CD
+
+## Dependencies
+- ACT-007-task-003: Implement deployment strategy (need deployment before testing rollback)
+
+## Feature File
+`/features/cicd-pipeline/rollback.feature`
+
+## Status
+- [x] Acceptance criteria defined
+- [ ] Example mapping complete
+- [ ] Scenarios written
+- [ ] Acceptance tests created
+- [ ] Implementation complete
+- [ ] Deployed
+
+## Notes
+Rollback is safety net for deployments. Teams that can rollback quickly deploy more frequently and with less fear.

package/docs/story-map/user-tasks/ACT-008-task-001.md

@@ -0,0 +1,48 @@
+# ACT-008-task-001: Define Success Metrics
+
+## Activity
+ACT-008: Measure and Improve
+
+## User Task
+As a product owner or engineering leader
+I want to define measurable outcomes that indicate success
+So that we can objectively evaluate if delivered features create value
+
+## Value Proposition Link
+- Pain relieved: Hard to prove ROI of quality practices; Disconnect between built vs needed
+- Gain created: Demonstrate quality practices increase speed; Connect engineering to business outcomes
+
+## Acceptance Criteria
+- 3-5 key metrics defined per release or feature
+- Mix of business metrics (adoption, usage) and quality metrics (defect rate, cycle time)
+- Each metric has: definition, target value, measurement method, collection frequency
+- Metrics trace to VPC gains (measure if gains were actually created)
+- Baseline values captured before release
+- Metrics documented in `/docs/metrics.md` or in release plan
+- Follows guidance from `continuous-improvement/references/measurement.md`
+
+## Priority
+- **MoSCoW:** Should Have
+- **Business Value:** High
+- **Complexity:** Medium
+
+## Release
+Release 3 - Continuous Improvement
+
+## Dependencies
+- ACT-003-task-003: Plan release 1 (need release to define metrics for)
+- ACT-007-task-001: Set up pipeline stages (delivery capability must exist before measuring it)
+
+## Feature File
+`/features/continuous-improvement/metrics.feature`
+
+## Status
+- [x] Acceptance criteria defined
+- [ ] Example mapping complete
+- [ ] Scenarios written
+- [ ] Acceptance tests created
+- [ ] Implementation complete
+- [ ] Deployed
+
+## Notes
+Metrics are how we validate VPC assumptions. They close the feedback loop from deployment back to product strategy.

package/docs/story-map/user-tasks/ACT-008-task-002.md

@@ -0,0 +1,48 @@
+# ACT-008-task-002: Collect Measurement Data
+
+## Activity
+ACT-008: Measure and Improve
+
+## User Task
+As a developer or data analyst
+I want to automatically collect metrics defined in success criteria
+So that we have objective data about outcomes without manual reporting overhead
+
+## Value Proposition Link
+- Pain relieved: Hard to prove ROI of quality practices; Manual reporting is time-consuming and error-prone
+- Gain created: Data-driven decisions; Continuous visibility into key metrics
+
+## Acceptance Criteria
+- Data collection automated (not manual spreadsheets)
+- Data collected at defined frequency (daily, per-deployment, etc.)
+- Data stored in queryable format (database, analytics platform, logs)
+- Collection infrastructure documented
+- Data quality validated (no missing or obviously incorrect values)
+- Dashboards or reports created for key stakeholders
+- Collection method documented in `/docs/data-collection.md`
+
+## Priority
+- **MoSCoW:** Should Have
+- **Business Value:** Medium
+- **Complexity:** High
+
+## Release
+Release 3 - Continuous Improvement
+
+## Dependencies
+- ACT-008-task-001: Define success metrics (need to know what to collect)
+- ACT-007-task-001: Set up pipeline stages (pipeline can trigger collection)
+
+## Feature File
+`/features/continuous-improvement/data-collection.feature`
+
+## Status
+- [x] Acceptance criteria defined
+- [ ] Example mapping complete
+- [ ] Scenarios written
+- [ ] Acceptance tests created
+- [ ] Implementation complete
+- [ ] Deployed
+
+## Notes
+Automated collection is critical. Manual metrics gathering doesn't scale and is often abandoned under pressure.

package/docs/story-map/user-tasks/ACT-008-task-003.md

@@ -0,0 +1,47 @@
+# ACT-008-task-003: Perform Root Cause Analysis
+
+## Activity
+ACT-008: Measure and Improve
+
+## User Task
+As an engineering leader or team facilitator
+I want to investigate when metrics show problems or unexpected results
+So that we identify systemic issues rather than treating symptoms
+
+## Value Proposition Link
+- Pain relieved: Same problems recur repeatedly; Firefighting without fixing root causes
+- Gain created: Process improvements that prevent future issues; Team learning and growth
+
+## Acceptance Criteria
+- Root cause analysis (5 Whys, Fishbone, etc.) performed for significant issues
+- Analysis involves multiple team members, not just one person
+- Root causes distinguished from symptoms
+- Systemic issues identified (not just individual mistakes)
+- Findings documented with evidence
+- Analysis saved in `/docs/root-cause-analysis/[issue-date].md`
+- Follows method from `continuous-improvement/references/root-cause-analysis.md`
+
+## Priority
+- **MoSCoW:** Should Have
+- **Business Value:** High
+- **Complexity:** Medium
+
+## Release
+Release 3 - Continuous Improvement
+
+## Dependencies
+- ACT-008-task-002: Collect measurement data (need data to analyze)
+
+## Feature File
+`/features/continuous-improvement/root-cause-analysis.feature`
+
+## Status
+- [x] Acceptance criteria defined
+- [ ] Example mapping complete
+- [ ] Scenarios written
+- [ ] Acceptance tests created
+- [ ] Implementation complete
+- [ ] Deployed
+
+## Notes
+RCA is critical for learning. Without it, teams repeatedly treat symptoms without fixing underlying problems.

package/docs/story-map/user-tasks/ACT-008-task-004.md

@@ -0,0 +1,48 @@
+# ACT-008-task-004: Update Upstream Artifacts
+
+## Activity
+ACT-008: Measure and Improve
+
+## User Task
+As a product owner or process facilitator
+I want to update VPC, personas, story maps, or other artifacts based on learnings
+So that future work builds on validated knowledge rather than original assumptions
+
+## Value Proposition Link
+- Pain relieved: Disconnect between what we built and what users needed; Same mistakes repeated
+- Gain created: Deliver features users actually want; Continuous learning and improvement
+
+## Acceptance Criteria
+- Findings from metrics and RCA reviewed against existing artifacts
+- Artifacts updated where learnings invalidate assumptions (e.g., VPC pains were wrong, persona goals incomplete)
+- Updates documented with rationale and evidence
+- Affected teams notified of significant artifact changes
+- Update history tracked (when changed, why, based on what evidence)
+- Process documented in `/docs/artifact-updates.md`
+- Follows guidance from `continuous-improvement/references/process-update.md`
+
+## Priority
+- **MoSCoW:** Should Have
+- **Business Value:** High
+- **Complexity:** Medium
+
+## Release
+Release 3 - Continuous Improvement
+
+## Dependencies
+- ACT-008-task-003: Perform root cause analysis (need findings to feed back)
+- All upstream artifacts (VPC, personas, story maps, etc.) - these get updated
+
+## Feature File
+`/features/continuous-improvement/process-update.feature`
+
+## Status
+- [x] Acceptance criteria defined
+- [ ] Example mapping complete
+- [ ] Scenarios written
+- [ ] Acceptance tests created
+- [ ] Implementation complete
+- [ ] Deployed
+
+## Notes
+Artifact updates close the learning loop. This is where continuous improvement feeds back to product strategy, completing the methodology cycle.