convoke-agents 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (244) hide show
  1. package/CHANGELOG.md +920 -0
  2. package/INSTALLATION.md +230 -0
  3. package/LICENSE +21 -0
  4. package/README.md +330 -0
  5. package/UPDATE-GUIDE.md +220 -0
  6. package/_bmad/bme/_vortex/README.md +150 -0
  7. package/_bmad/bme/_vortex/agents/contextualization-expert.md +100 -0
  8. package/_bmad/bme/_vortex/agents/discovery-empathy-expert.md +117 -0
  9. package/_bmad/bme/_vortex/agents/hypothesis-engineer.md +117 -0
  10. package/_bmad/bme/_vortex/agents/lean-experiments-specialist.md +118 -0
  11. package/_bmad/bme/_vortex/agents/learning-decision-expert.md +117 -0
  12. package/_bmad/bme/_vortex/agents/production-intelligence-specialist.md +117 -0
  13. package/_bmad/bme/_vortex/agents/research-convergence-specialist.md +117 -0
  14. package/_bmad/bme/_vortex/compass-routing-reference.md +312 -0
  15. package/_bmad/bme/_vortex/config.yaml +46 -0
  16. package/_bmad/bme/_vortex/contracts/hc1-empathy-artifacts.md +152 -0
  17. package/_bmad/bme/_vortex/contracts/hc2-problem-definition.md +125 -0
  18. package/_bmad/bme/_vortex/contracts/hc3-hypothesis-contract.md +112 -0
  19. package/_bmad/bme/_vortex/contracts/hc4-experiment-context.md +140 -0
  20. package/_bmad/bme/_vortex/contracts/hc5-signal-report.md +130 -0
  21. package/_bmad/bme/_vortex/examples/hc2-example-problem-definition.md +85 -0
  22. package/_bmad/bme/_vortex/examples/hc3-example-hypothesis-contract.md +103 -0
  23. package/_bmad/bme/_vortex/examples/hc5-example-signal-report.md +76 -0
  24. package/_bmad/bme/_vortex/guides/EMMA-USER-GUIDE.md +232 -0
  25. package/_bmad/bme/_vortex/guides/ISLA-USER-GUIDE.md +208 -0
  26. package/_bmad/bme/_vortex/guides/LIAM-USER-GUIDE.md +255 -0
  27. package/_bmad/bme/_vortex/guides/MAX-USER-GUIDE.md +213 -0
  28. package/_bmad/bme/_vortex/guides/MILA-USER-GUIDE.md +235 -0
  29. package/_bmad/bme/_vortex/guides/NOAH-USER-GUIDE.md +258 -0
  30. package/_bmad/bme/_vortex/guides/WADE-USER-GUIDE.md +245 -0
  31. package/_bmad/bme/_vortex/workflows/_deprecated/empathy-map/empathy-map.template.md +143 -0
  32. package/_bmad/bme/_vortex/workflows/_deprecated/empathy-map/steps/step-01-define-user.md +60 -0
  33. package/_bmad/bme/_vortex/workflows/_deprecated/empathy-map/steps/step-02-says-thinks.md +67 -0
  34. package/_bmad/bme/_vortex/workflows/_deprecated/empathy-map/steps/step-03-does-feels.md +79 -0
  35. package/_bmad/bme/_vortex/workflows/_deprecated/empathy-map/steps/step-04-pain-points.md +87 -0
  36. package/_bmad/bme/_vortex/workflows/_deprecated/empathy-map/steps/step-05-gains.md +103 -0
  37. package/_bmad/bme/_vortex/workflows/_deprecated/empathy-map/steps/step-06-synthesize.md +104 -0
  38. package/_bmad/bme/_vortex/workflows/_deprecated/empathy-map/validate.md +117 -0
  39. package/_bmad/bme/_vortex/workflows/_deprecated/empathy-map/workflow.md +44 -0
  40. package/_bmad/bme/_vortex/workflows/_deprecated/wireframe/steps/step-01-define-requirements.md +85 -0
  41. package/_bmad/bme/_vortex/workflows/_deprecated/wireframe/steps/step-02-user-flows.md +59 -0
  42. package/_bmad/bme/_vortex/workflows/_deprecated/wireframe/steps/step-03-information-architecture.md +68 -0
  43. package/_bmad/bme/_vortex/workflows/_deprecated/wireframe/steps/step-04-wireframe-sketch.md +97 -0
  44. package/_bmad/bme/_vortex/workflows/_deprecated/wireframe/steps/step-05-components.md +128 -0
  45. package/_bmad/bme/_vortex/workflows/_deprecated/wireframe/steps/step-06-synthesize.md +83 -0
  46. package/_bmad/bme/_vortex/workflows/_deprecated/wireframe/wireframe.template.md +287 -0
  47. package/_bmad/bme/_vortex/workflows/_deprecated/wireframe/workflow.md +44 -0
  48. package/_bmad/bme/_vortex/workflows/assumption-mapping/steps/step-01-setup.md +66 -0
  49. package/_bmad/bme/_vortex/workflows/assumption-mapping/steps/step-02-context.md +93 -0
  50. package/_bmad/bme/_vortex/workflows/assumption-mapping/steps/step-03-risk-mapping.md +103 -0
  51. package/_bmad/bme/_vortex/workflows/assumption-mapping/steps/step-04-synthesize.md +101 -0
  52. package/_bmad/bme/_vortex/workflows/assumption-mapping/workflow.md +49 -0
  53. package/_bmad/bme/_vortex/workflows/behavior-analysis/steps/step-01-setup.md +81 -0
  54. package/_bmad/bme/_vortex/workflows/behavior-analysis/steps/step-02-context.md +67 -0
  55. package/_bmad/bme/_vortex/workflows/behavior-analysis/steps/step-03-classification.md +98 -0
  56. package/_bmad/bme/_vortex/workflows/behavior-analysis/steps/step-04-evidence.md +100 -0
  57. package/_bmad/bme/_vortex/workflows/behavior-analysis/steps/step-05-synthesize.md +174 -0
  58. package/_bmad/bme/_vortex/workflows/behavior-analysis/workflow.md +52 -0
  59. package/_bmad/bme/_vortex/workflows/contextualize-scope/contextualize-scope.template.md +67 -0
  60. package/_bmad/bme/_vortex/workflows/contextualize-scope/steps/step-01-list-opportunities.md +47 -0
  61. package/_bmad/bme/_vortex/workflows/contextualize-scope/steps/step-02-define-criteria.md +36 -0
  62. package/_bmad/bme/_vortex/workflows/contextualize-scope/steps/step-03-evaluate-opportunities.md +30 -0
  63. package/_bmad/bme/_vortex/workflows/contextualize-scope/steps/step-04-define-boundaries.md +32 -0
  64. package/_bmad/bme/_vortex/workflows/contextualize-scope/steps/step-05-validate-fit.md +28 -0
  65. package/_bmad/bme/_vortex/workflows/contextualize-scope/steps/step-06-synthesize.md +36 -0
  66. package/_bmad/bme/_vortex/workflows/contextualize-scope/validate.md +30 -0
  67. package/_bmad/bme/_vortex/workflows/contextualize-scope/workflow.md +59 -0
  68. package/_bmad/bme/_vortex/workflows/empathy-map/empathy-map.template.md +143 -0
  69. package/_bmad/bme/_vortex/workflows/empathy-map/steps/step-01-define-user.md +60 -0
  70. package/_bmad/bme/_vortex/workflows/empathy-map/steps/step-02-says-thinks.md +67 -0
  71. package/_bmad/bme/_vortex/workflows/empathy-map/steps/step-03-does-feels.md +79 -0
  72. package/_bmad/bme/_vortex/workflows/empathy-map/steps/step-04-pain-points.md +87 -0
  73. package/_bmad/bme/_vortex/workflows/empathy-map/steps/step-05-gains.md +103 -0
  74. package/_bmad/bme/_vortex/workflows/empathy-map/steps/step-06-synthesize.md +107 -0
  75. package/_bmad/bme/_vortex/workflows/empathy-map/validate.md +117 -0
  76. package/_bmad/bme/_vortex/workflows/empathy-map/workflow.md +45 -0
  77. package/_bmad/bme/_vortex/workflows/experiment-design/steps/step-01-setup.md +66 -0
  78. package/_bmad/bme/_vortex/workflows/experiment-design/steps/step-02-context.md +77 -0
  79. package/_bmad/bme/_vortex/workflows/experiment-design/steps/step-03-design.md +114 -0
  80. package/_bmad/bme/_vortex/workflows/experiment-design/steps/step-04-synthesize.md +128 -0
  81. package/_bmad/bme/_vortex/workflows/experiment-design/workflow.md +51 -0
  82. package/_bmad/bme/_vortex/workflows/hypothesis-engineering/steps/step-01-setup.md +66 -0
  83. package/_bmad/bme/_vortex/workflows/hypothesis-engineering/steps/step-02-context.md +80 -0
  84. package/_bmad/bme/_vortex/workflows/hypothesis-engineering/steps/step-03-brainwriting.md +79 -0
  85. package/_bmad/bme/_vortex/workflows/hypothesis-engineering/steps/step-04-assumption-mapping.md +102 -0
  86. package/_bmad/bme/_vortex/workflows/hypothesis-engineering/steps/step-05-synthesize.md +130 -0
  87. package/_bmad/bme/_vortex/workflows/hypothesis-engineering/workflow.md +52 -0
  88. package/_bmad/bme/_vortex/workflows/lean-experiment/lean-experiment.template.md +29 -0
  89. package/_bmad/bme/_vortex/workflows/lean-experiment/steps/step-01-hypothesis.md +58 -0
  90. package/_bmad/bme/_vortex/workflows/lean-experiment/steps/step-02-design.md +68 -0
  91. package/_bmad/bme/_vortex/workflows/lean-experiment/steps/step-03-metrics.md +73 -0
  92. package/_bmad/bme/_vortex/workflows/lean-experiment/steps/step-04-run.md +75 -0
  93. package/_bmad/bme/_vortex/workflows/lean-experiment/steps/step-05-analyze.md +84 -0
  94. package/_bmad/bme/_vortex/workflows/lean-experiment/steps/step-06-decide.md +111 -0
  95. package/_bmad/bme/_vortex/workflows/lean-experiment/validate.md +30 -0
  96. package/_bmad/bme/_vortex/workflows/lean-experiment/workflow.md +26 -0
  97. package/_bmad/bme/_vortex/workflows/lean-persona/lean-persona.template.md +163 -0
  98. package/_bmad/bme/_vortex/workflows/lean-persona/steps/step-01-define-job.md +72 -0
  99. package/_bmad/bme/_vortex/workflows/lean-persona/steps/step-02-current-solution.md +83 -0
  100. package/_bmad/bme/_vortex/workflows/lean-persona/steps/step-03-problem-contexts.md +90 -0
  101. package/_bmad/bme/_vortex/workflows/lean-persona/steps/step-04-forces-anxieties.md +98 -0
  102. package/_bmad/bme/_vortex/workflows/lean-persona/steps/step-05-success-criteria.md +103 -0
  103. package/_bmad/bme/_vortex/workflows/lean-persona/steps/step-06-synthesize.md +129 -0
  104. package/_bmad/bme/_vortex/workflows/lean-persona/validate.md +30 -0
  105. package/_bmad/bme/_vortex/workflows/lean-persona/workflow.md +50 -0
  106. package/_bmad/bme/_vortex/workflows/learning-card/learning-card.template.md +179 -0
  107. package/_bmad/bme/_vortex/workflows/learning-card/steps/step-01-experiment-context.md +100 -0
  108. package/_bmad/bme/_vortex/workflows/learning-card/steps/step-02-raw-results.md +125 -0
  109. package/_bmad/bme/_vortex/workflows/learning-card/steps/step-03-analysis.md +125 -0
  110. package/_bmad/bme/_vortex/workflows/learning-card/steps/step-04-validated-learning.md +139 -0
  111. package/_bmad/bme/_vortex/workflows/learning-card/steps/step-05-implications.md +134 -0
  112. package/_bmad/bme/_vortex/workflows/learning-card/steps/step-06-synthesize.md +121 -0
  113. package/_bmad/bme/_vortex/workflows/learning-card/validate.md +134 -0
  114. package/_bmad/bme/_vortex/workflows/learning-card/workflow.md +51 -0
  115. package/_bmad/bme/_vortex/workflows/mvp/mvp.template.md +40 -0
  116. package/_bmad/bme/_vortex/workflows/mvp/steps/step-01-riskiest-assumption.md +17 -0
  117. package/_bmad/bme/_vortex/workflows/mvp/steps/step-02-success-criteria.md +13 -0
  118. package/_bmad/bme/_vortex/workflows/mvp/steps/step-03-smallest-test.md +13 -0
  119. package/_bmad/bme/_vortex/workflows/mvp/steps/step-04-scope-features.md +13 -0
  120. package/_bmad/bme/_vortex/workflows/mvp/steps/step-05-build-measure-learn.md +13 -0
  121. package/_bmad/bme/_vortex/workflows/mvp/steps/step-06-synthesize.md +28 -0
  122. package/_bmad/bme/_vortex/workflows/mvp/validate.md +30 -0
  123. package/_bmad/bme/_vortex/workflows/mvp/workflow.md +36 -0
  124. package/_bmad/bme/_vortex/workflows/pattern-mapping/steps/step-01-setup.md +102 -0
  125. package/_bmad/bme/_vortex/workflows/pattern-mapping/steps/step-02-context.md +81 -0
  126. package/_bmad/bme/_vortex/workflows/pattern-mapping/steps/step-03-pattern-identification.md +88 -0
  127. package/_bmad/bme/_vortex/workflows/pattern-mapping/steps/step-04-theme-clustering.md +100 -0
  128. package/_bmad/bme/_vortex/workflows/pattern-mapping/steps/step-05-synthesize.md +135 -0
  129. package/_bmad/bme/_vortex/workflows/pattern-mapping/workflow.md +58 -0
  130. package/_bmad/bme/_vortex/workflows/pivot-patch-persevere/pivot-patch-persevere.template.md +201 -0
  131. package/_bmad/bme/_vortex/workflows/pivot-patch-persevere/steps/step-01-evidence-review.md +125 -0
  132. package/_bmad/bme/_vortex/workflows/pivot-patch-persevere/steps/step-02-hypothesis-assessment.md +132 -0
  133. package/_bmad/bme/_vortex/workflows/pivot-patch-persevere/steps/step-03-option-analysis.md +167 -0
  134. package/_bmad/bme/_vortex/workflows/pivot-patch-persevere/steps/step-04-stakeholder-input.md +141 -0
  135. package/_bmad/bme/_vortex/workflows/pivot-patch-persevere/steps/step-05-decision.md +161 -0
  136. package/_bmad/bme/_vortex/workflows/pivot-patch-persevere/steps/step-06-action-plan.md +188 -0
  137. package/_bmad/bme/_vortex/workflows/pivot-patch-persevere/validate.md +159 -0
  138. package/_bmad/bme/_vortex/workflows/pivot-patch-persevere/workflow.md +51 -0
  139. package/_bmad/bme/_vortex/workflows/pivot-resynthesis/steps/step-01-setup.md +97 -0
  140. package/_bmad/bme/_vortex/workflows/pivot-resynthesis/steps/step-02-context.md +86 -0
  141. package/_bmad/bme/_vortex/workflows/pivot-resynthesis/steps/step-03-jtbd-reframing.md +88 -0
  142. package/_bmad/bme/_vortex/workflows/pivot-resynthesis/steps/step-04-pains-gains-revision.md +76 -0
  143. package/_bmad/bme/_vortex/workflows/pivot-resynthesis/steps/step-05-synthesize.md +158 -0
  144. package/_bmad/bme/_vortex/workflows/pivot-resynthesis/workflow.md +52 -0
  145. package/_bmad/bme/_vortex/workflows/product-vision/product-vision.template.md +147 -0
  146. package/_bmad/bme/_vortex/workflows/product-vision/steps/step-01-define-problem.md +89 -0
  147. package/_bmad/bme/_vortex/workflows/product-vision/steps/step-02-target-market.md +91 -0
  148. package/_bmad/bme/_vortex/workflows/product-vision/steps/step-03-unique-approach.md +87 -0
  149. package/_bmad/bme/_vortex/workflows/product-vision/steps/step-04-future-state.md +100 -0
  150. package/_bmad/bme/_vortex/workflows/product-vision/steps/step-05-principles.md +92 -0
  151. package/_bmad/bme/_vortex/workflows/product-vision/steps/step-06-synthesize.md +170 -0
  152. package/_bmad/bme/_vortex/workflows/product-vision/validate.md +30 -0
  153. package/_bmad/bme/_vortex/workflows/product-vision/workflow.md +55 -0
  154. package/_bmad/bme/_vortex/workflows/production-monitoring/steps/step-01-setup.md +84 -0
  155. package/_bmad/bme/_vortex/workflows/production-monitoring/steps/step-02-context.md +66 -0
  156. package/_bmad/bme/_vortex/workflows/production-monitoring/steps/step-03-monitoring.md +74 -0
  157. package/_bmad/bme/_vortex/workflows/production-monitoring/steps/step-04-prioritization.md +97 -0
  158. package/_bmad/bme/_vortex/workflows/production-monitoring/steps/step-05-synthesize.md +183 -0
  159. package/_bmad/bme/_vortex/workflows/production-monitoring/workflow.md +52 -0
  160. package/_bmad/bme/_vortex/workflows/proof-of-concept/proof-of-concept.template.md +25 -0
  161. package/_bmad/bme/_vortex/workflows/proof-of-concept/steps/step-01-risk.md +79 -0
  162. package/_bmad/bme/_vortex/workflows/proof-of-concept/steps/step-02-scope.md +105 -0
  163. package/_bmad/bme/_vortex/workflows/proof-of-concept/steps/step-03-build.md +92 -0
  164. package/_bmad/bme/_vortex/workflows/proof-of-concept/steps/step-04-test.md +103 -0
  165. package/_bmad/bme/_vortex/workflows/proof-of-concept/steps/step-05-evaluate.md +114 -0
  166. package/_bmad/bme/_vortex/workflows/proof-of-concept/steps/step-06-document.md +125 -0
  167. package/_bmad/bme/_vortex/workflows/proof-of-concept/validate.md +30 -0
  168. package/_bmad/bme/_vortex/workflows/proof-of-concept/workflow.md +26 -0
  169. package/_bmad/bme/_vortex/workflows/proof-of-value/proof-of-value.template.md +29 -0
  170. package/_bmad/bme/_vortex/workflows/proof-of-value/steps/step-01-value-hypothesis.md +75 -0
  171. package/_bmad/bme/_vortex/workflows/proof-of-value/steps/step-02-validation-design.md +94 -0
  172. package/_bmad/bme/_vortex/workflows/proof-of-value/steps/step-03-willingness.md +96 -0
  173. package/_bmad/bme/_vortex/workflows/proof-of-value/steps/step-04-test.md +107 -0
  174. package/_bmad/bme/_vortex/workflows/proof-of-value/steps/step-05-analyze.md +116 -0
  175. package/_bmad/bme/_vortex/workflows/proof-of-value/steps/step-06-document.md +147 -0
  176. package/_bmad/bme/_vortex/workflows/proof-of-value/validate.md +30 -0
  177. package/_bmad/bme/_vortex/workflows/proof-of-value/workflow.md +26 -0
  178. package/_bmad/bme/_vortex/workflows/research-convergence/steps/step-01-setup.md +69 -0
  179. package/_bmad/bme/_vortex/workflows/research-convergence/steps/step-02-context.md +70 -0
  180. package/_bmad/bme/_vortex/workflows/research-convergence/steps/step-03-jtbd-framing.md +81 -0
  181. package/_bmad/bme/_vortex/workflows/research-convergence/steps/step-04-pains-gains.md +77 -0
  182. package/_bmad/bme/_vortex/workflows/research-convergence/steps/step-05-synthesize.md +147 -0
  183. package/_bmad/bme/_vortex/workflows/research-convergence/workflow.md +50 -0
  184. package/_bmad/bme/_vortex/workflows/signal-interpretation/steps/step-01-setup.md +68 -0
  185. package/_bmad/bme/_vortex/workflows/signal-interpretation/steps/step-02-context.md +67 -0
  186. package/_bmad/bme/_vortex/workflows/signal-interpretation/steps/step-03-signal-analysis.md +85 -0
  187. package/_bmad/bme/_vortex/workflows/signal-interpretation/steps/step-04-anomaly-detection.md +93 -0
  188. package/_bmad/bme/_vortex/workflows/signal-interpretation/steps/step-05-synthesize.md +163 -0
  189. package/_bmad/bme/_vortex/workflows/signal-interpretation/workflow.md +52 -0
  190. package/_bmad/bme/_vortex/workflows/user-discovery/steps/step-01-discovery-scope.md +77 -0
  191. package/_bmad/bme/_vortex/workflows/user-discovery/steps/step-02-research-methods.md +152 -0
  192. package/_bmad/bme/_vortex/workflows/user-discovery/steps/step-03-research-plan.md +159 -0
  193. package/_bmad/bme/_vortex/workflows/user-discovery/steps/step-04-execute.md +169 -0
  194. package/_bmad/bme/_vortex/workflows/user-discovery/steps/step-05-organize-data.md +149 -0
  195. package/_bmad/bme/_vortex/workflows/user-discovery/steps/step-06-synthesize.md +159 -0
  196. package/_bmad/bme/_vortex/workflows/user-discovery/user-discovery.template.md +231 -0
  197. package/_bmad/bme/_vortex/workflows/user-discovery/validate.md +153 -0
  198. package/_bmad/bme/_vortex/workflows/user-discovery/workflow.md +45 -0
  199. package/_bmad/bme/_vortex/workflows/user-interview/steps/step-01-research-goals.md +100 -0
  200. package/_bmad/bme/_vortex/workflows/user-interview/steps/step-02-interview-script.md +123 -0
  201. package/_bmad/bme/_vortex/workflows/user-interview/steps/step-03-recruitment.md +144 -0
  202. package/_bmad/bme/_vortex/workflows/user-interview/steps/step-04-conduct.md +154 -0
  203. package/_bmad/bme/_vortex/workflows/user-interview/steps/step-05-findings.md +163 -0
  204. package/_bmad/bme/_vortex/workflows/user-interview/steps/step-06-synthesize.md +171 -0
  205. package/_bmad/bme/_vortex/workflows/user-interview/user-interview.template.md +250 -0
  206. package/_bmad/bme/_vortex/workflows/user-interview/validate.md +142 -0
  207. package/_bmad/bme/_vortex/workflows/user-interview/workflow.md +51 -0
  208. package/_bmad/bme/_vortex/workflows/vortex-navigation/steps/step-01-current-state.md +56 -0
  209. package/_bmad/bme/_vortex/workflows/vortex-navigation/steps/step-02-evidence-inventory.md +70 -0
  210. package/_bmad/bme/_vortex/workflows/vortex-navigation/steps/step-03-gap-analysis.md +76 -0
  211. package/_bmad/bme/_vortex/workflows/vortex-navigation/steps/step-04-stream-evaluation.md +57 -0
  212. package/_bmad/bme/_vortex/workflows/vortex-navigation/steps/step-05-recommendation.md +65 -0
  213. package/_bmad/bme/_vortex/workflows/vortex-navigation/steps/step-06-navigation-plan.md +72 -0
  214. package/_bmad/bme/_vortex/workflows/vortex-navigation/validate.md +75 -0
  215. package/_bmad/bme/_vortex/workflows/vortex-navigation/vortex-navigation.template.md +105 -0
  216. package/_bmad/bme/_vortex/workflows/vortex-navigation/workflow.md +54 -0
  217. package/index.js +56 -0
  218. package/package.json +77 -0
  219. package/scripts/README.md +226 -0
  220. package/scripts/convoke-doctor.js +322 -0
  221. package/scripts/docs-audit.js +584 -0
  222. package/scripts/install-all-agents.js +9 -0
  223. package/scripts/install-vortex-agents.js +208 -0
  224. package/scripts/postinstall.js +104 -0
  225. package/scripts/update/convoke-migrate.js +169 -0
  226. package/scripts/update/convoke-update.js +272 -0
  227. package/scripts/update/convoke-version.js +134 -0
  228. package/scripts/update/lib/agent-registry.js +144 -0
  229. package/scripts/update/lib/backup-manager.js +243 -0
  230. package/scripts/update/lib/config-merger.js +242 -0
  231. package/scripts/update/lib/migration-runner.js +367 -0
  232. package/scripts/update/lib/refresh-installation.js +171 -0
  233. package/scripts/update/lib/utils.js +96 -0
  234. package/scripts/update/lib/validator.js +360 -0
  235. package/scripts/update/lib/version-detector.js +241 -0
  236. package/scripts/update/migrations/1.0.x-to-1.3.0.js +128 -0
  237. package/scripts/update/migrations/1.1.x-to-1.3.0.js +29 -0
  238. package/scripts/update/migrations/1.2.x-to-1.3.0.js +29 -0
  239. package/scripts/update/migrations/1.3.x-to-1.5.0.js +29 -0
  240. package/scripts/update/migrations/1.4.x-to-1.5.0.js +29 -0
  241. package/scripts/update/migrations/1.5.x-to-1.6.0.js +95 -0
  242. package/scripts/update/migrations/1.6.x-to-1.7.0.js +29 -0
  243. package/scripts/update/migrations/1.7.x-to-2.0.0.js +31 -0
  244. package/scripts/update/migrations/registry.js +194 -0
@@ -0,0 +1,163 @@
1
+ ---
2
+ step: 5
3
+ workflow: signal-interpretation
4
+ title: Synthesize & Route
5
+ ---
6
+
7
+ # Step 5: Synthesize & Route
8
+
9
+ Time to bring everything together. We've validated the experiment context, connected it to the production signal, described and analyzed the signal, and assessed anomalies and data quality. Now we produce the HC5 Signal Report artifact and route to the next step in the Vortex.
10
+
11
+ ## Why This Matters
12
+
13
+ Production data is the most honest user feedback — it can't lie. But raw data isn't intelligence. Intelligence is data interpreted through context, connected to its experiment lineage, and packaged for the decision-maker. The HC5 artifact gives Max everything needed to make evidence-based decisions: what the signal is, where it came from, where it's heading, and what doesn't fit the expected model. No recommendations. No strategy. Just contextualized intelligence.
14
+
15
+ ## Your Task
16
+
17
+ ### 1. Review Your Signal Report
18
+
19
+ Before we package everything, let's do a final quality pass on each section:
20
+
21
+ **Signal Description:**
22
+
23
+ | Field | Check |
24
+ |-------|-------|
25
+ | **Signal Summary** | Is it factual and one sentence? Could someone unfamiliar with the experiment understand what happened? |
26
+ | **Signal Type** | Is the classification accurate? Does it match what was actually observed? |
27
+ | **Severity** | Is the severity justified by the signal's deviation from experiment expectations? |
28
+ | **Detection Method** | Is it clear how this signal came to attention? |
29
+ | **Time Window** | Is the observation period precisely defined? |
30
+ | **Affected Scope** | Are the affected users/segments/features clearly identified? |
31
+
32
+ **Context (Experiment Lineage + Vortex History):**
33
+
34
+ | Field | Check |
35
+ |-------|-------|
36
+ | **Experiment Lineage** | Can the signal be traced back to its originating experiment? Is the actual-vs-expected comparison clear? |
37
+ | **Vortex History** | Are available upstream references (HC2, HC3, previous HC5) documented? |
38
+
39
+ **Trend Analysis:**
40
+
41
+ | Field | Check |
42
+ |-------|-------|
43
+ | **Trend Direction** | Does the classification reflect the data trajectory accurately? |
44
+ | **Rate of Change** | Is it quantified with specific metrics, not vague descriptions? |
45
+ | **Baseline Comparison** | Is the pre-experiment baseline explicitly stated? |
46
+ | **Confidence** | Does the confidence level accurately reflect data quality? |
47
+
48
+ **Anomaly Detection (if applicable):**
49
+
50
+ | Field | Check |
51
+ |-------|-------|
52
+ | **Anomaly Description** | Is the unexpected behavior described factually, without speculative strategy? |
53
+ | **Discovery Needed** | Is the HC10 routing decision documented with rationale? |
54
+
55
+ **Data Quality:**
56
+
57
+ | Field | Check |
58
+ |-------|-------|
59
+ | **Sample Size** | Is it sufficient for the conclusions drawn? |
60
+ | **Confidence Level** | Does it honestly reflect data reliability? |
61
+
62
+ ### 2. Generate the HC5 Artifact
63
+
64
+ I'll produce the HC5 Signal Report artifact with this structure:
65
+
66
+ ```yaml
67
+ ---
68
+ contract: HC5
69
+ type: artifact
70
+ source_agent: noah
71
+ source_workflow: signal-interpretation
72
+ target_agents: [max]
73
+ input_artifacts:
74
+ - path: "_bmad-output/vortex-artifacts/{your-hc4-artifact}"
75
+ contract: HC4
76
+ created: YYYY-MM-DD
77
+ ---
78
+ ```
79
+
80
+ **HC5 Required Body Sections:**
81
+ 1. **Signal Description** — Signal Summary, Signal Type, Severity, Detection Method, Time Window, Affected Scope
82
+ 2. **Context** — Experiment Lineage (Originating Experiment, Original Hypothesis, Experiment Outcome, Expected Production Behavior, Actual vs Expected) + Vortex History (Problem Definition, Hypothesis Origin, Previous Signals, Related Experiments)
83
+ 3. **Trend Analysis** — Trend Direction, Trend Duration, Rate of Change, Baseline Comparison, Confidence
84
+ 4. **Anomaly Detection** (when unexpected patterns detected) — Anomaly Description, Deviation from Expected, Potential Explanations, Discovery Needed, Discovery Focus
85
+ 5. **Data Quality** — Sample Size, Data Completeness, Known Biases, Confidence Level
86
+
87
+ **This artifact explicitly does NOT include:**
88
+ - Strategic recommendations (that is Max's domain)
89
+ - Pivot/patch/persevere decisions (that is Max's domain)
90
+ - Experiment design suggestions (that is Liam/Wade's domain)
91
+ - Resource allocation recommendations (that is Max's domain)
92
+
93
+ Noah produces intelligence — contextual, evidence-based signal interpretation. Max produces decisions.
94
+
95
+ **Save to:** `{output_folder}/vortex-artifacts/hc5-signal-report-{date}.md`
96
+
97
+ I'll create this file with all the sections above once you confirm the content is ready.
98
+
99
+ ### 3. Validation Questions
100
+
101
+ Before we finalize, let's validate:
102
+
103
+ **Evidence Check:**
104
+ - [ ] Is every signal description grounded in observed data, not assumptions?
105
+ - [ ] Can we trace the signal back to its originating experiment through the Experiment Lineage section?
106
+ - [ ] Is the trend analysis based on actual metrics with quantified rates of change?
107
+
108
+ **Completeness Check:**
109
+ - [ ] Does the Signal Description include all 6 required fields?
110
+ - [ ] Does the Context section include Experiment Lineage with all 5 required fields?
111
+ - [ ] Does the Trend Analysis include all 5 required fields?
112
+ - [ ] Does the Data Quality section include all required fields?
113
+ - [ ] If anomalies were detected, does Anomaly Detection include all required fields?
114
+
115
+ **Intelligence-Not-Strategy Check:**
116
+ - [ ] Does the report contain zero strategic recommendations?
117
+ - [ ] Does it avoid prescribing what to do about the signal?
118
+ - [ ] Does it present findings in signal + context + trend format, leaving decisions to Max?
119
+ - [ ] Would Max have everything needed to make an informed decision from this report?
120
+
121
+ ---
122
+
123
+ ## Your Turn
124
+
125
+ Review the signal report sections. Confirm when you're ready for me to generate the final HC5 artifact.
126
+
127
+ ---
128
+
129
+ **[a]** Advanced Elicitation — Deep dive into HC5 refinement with guided questioning
130
+ **[p]** Party Mode — Bring in other Vortex agents for collaborative artifact critique
131
+ **[c]** Continue — Generate the HC5 artifact and proceed to routing
132
+
133
+ ---
134
+
135
+ ## Vortex Compass
136
+
137
+ Based on what you just completed, here are your evidence-driven options:
138
+
139
+ | If you learned... | Consider next... | Agent | Why |
140
+ |---|---|---|---|
141
+ | Signal report complete with contextualized intelligence | learning-card | Max 🧭 | Signal report ready for decision (HC5) |
142
+ | ⚡ Anomalous behavior detected not covered by original hypothesis | user-discovery | Isla 🔍 | Unexpected behavior warrants discovery research (HC10) |
143
+
144
+ > **Note:** These are evidence-based recommendations. You can navigate to any Vortex agent
145
+ > at any time based on your judgment.
146
+
147
+ **Or run Max's [VN] Vortex Navigation** for a full gap analysis across all streams.
148
+
149
+ ### ⚠️ Insufficient Evidence for Routing
150
+
151
+ If the evidence gathered so far doesn't clearly point to a single next step:
152
+
153
+ | To route to... | You need... |
154
+ |----------------|-------------|
155
+ | Max 🧭 | Complete HC5 signal report with all required sections and sufficient data quality confidence |
156
+ | Isla 🔍 | Specific anomalous behavior identified with clear deviation from experiment expectations |
157
+
158
+ **Workflow-specific signals:**
159
+ - Signal description too vague → consider revisiting **step-03** for sharper analysis
160
+ - Cannot connect signal to experiment context → consider revisiting **step-02** for deeper context loading
161
+ - Data quality insufficient for any conclusion → gather more production data before proceeding
162
+
163
+ **Recommended:** Revisit earlier steps to strengthen your signal report, or run **Max's [VN] Vortex Navigation** for a full gap analysis.
@@ -0,0 +1,52 @@
1
+ ---
2
+ workflow: signal-interpretation
3
+ type: step-file
4
+ description: Interpret production signals through experiment lineage and Vortex history to produce contextualized intelligence reports
5
+ author: Noah (production-intelligence-specialist)
6
+ version: 1.6.0
7
+ ---
8
+
9
+ # Signal Interpretation Workflow
10
+
11
+ This workflow guides you through interpreting a production signal by connecting it to its originating experiment context, analyzing trends, detecting anomalies, and producing an HC5 signal report for Max.
12
+
13
+ ## What is Signal Interpretation?
14
+
15
+ Signal interpretation is the practice of reading production data through contextual lenses — not as isolated numbers on a dashboard, but as signals connected to the experiments that shaped them.
16
+
17
+ Raw metrics mean nothing without interpretation frames. A 15% drop in engagement could be catastrophic or expected, depending on what experiment produced the current state, what hypothesis was tested, and what production behavior was predicted. The signal indicates one thing when viewed in isolation and something entirely different when viewed through experiment lineage.
18
+
19
+ This workflow connects each production signal to its originating experiment, analyzes the trend in context, surfaces anomalies that dashboards hide, and packages everything as intelligence for the decision-maker — without prescribing what to do about it. Here's what we're seeing in context: that's the deliverable. Not strategy. Not recommendations. Contextualized intelligence.
20
+
21
+ ## Workflow Structure
22
+
23
+ **Step-file architecture:**
24
+ - Just-in-time loading (each step loads only when needed)
25
+ - Sequential enforcement (must complete step N before step N+1)
26
+ - State tracking in frontmatter (progress preserved)
27
+
28
+ ## Steps Overview
29
+
30
+ 1. **Setup & Input Validation** - Validate experiment context input (HC4 artifact or equivalent)
31
+ 2. **Experiment Context & Signal Connection** - Load experiment lineage and connect it to the production signal
32
+ 3. **Signal Description & Trend Analysis** - Describe the signal factually and analyze its trajectory against baselines
33
+ 4. **Anomaly Detection & Data Quality** - Surface unexpected behavior patterns and assess data reliability
34
+ 5. **Synthesize & Route** - Produce HC5 signal report artifact and route via Compass
35
+
36
+ ## Output
37
+
38
+ **Artifact:** HC5 Signal Report markdown file in `{output_folder}/vortex-artifacts/hc5-signal-report-{date}.md`
39
+
40
+ **Template:** None (HC5 artifact is generated inline during Step 5)
41
+
42
+ **Schema:** Conforms to HC5 contract (`_bmad/bme/_vortex/contracts/hc5-signal-report.md`)
43
+
44
+ **Consumer:** Max (learning-card) uses this to make evidence-based decisions grounded in production reality.
45
+
46
+ ---
47
+
48
+ ## INITIALIZATION
49
+
50
+ Load config from {project-root}/_bmad/bme/_vortex/config.yaml
51
+
52
+ Load step: {project-root}/_bmad/bme/_vortex/workflows/signal-interpretation/steps/step-01-setup.md
@@ -0,0 +1,77 @@
1
+ ---
2
+ step: 1
3
+ workflow: user-discovery
4
+ title: Define Discovery Scope
5
+ ---
6
+
7
+ # Step 1: Define Discovery Scope
8
+
9
+ Before any research begins, you need to be explicit about what you are trying to learn and why it matters. A well-scoped discovery prevents the two most common research failures: learning everything about nothing, and learning nothing about everything.
10
+
11
+ ## Why This Matters
12
+
13
+ Discovery research is expensive in time, attention, and participant goodwill. A clear scope ensures every research activity produces knowledge that moves your product forward. Without it, teams collect volumes of data and still cannot answer the questions that matter.
14
+
15
+ ## Your Task
16
+
17
+ ### 1. State the Discovery Goal
18
+
19
+ What decision or direction will this research inform? Be specific about the business or product context that makes this discovery necessary right now.
20
+
21
+ **Strong examples:**
22
+ - "We're entering the small-business accounting market and need to understand how owners currently manage their finances before we design our onboarding flow."
23
+ - "Churn increased 15% last quarter among enterprise accounts. We need to discover what changed in their workflows or expectations."
24
+ - "We have three feature directions for Q3. We need to understand which user problems are most urgent to decide where to invest."
25
+
26
+ **Weak examples:**
27
+ - "We want to understand our users better." (Too vague -- what would change if you did?)
28
+ - "We need to do some research." (Not a goal, it's an activity.)
29
+
30
+ ### 2. Formulate Research Questions (3-7)
31
+
32
+ Research questions are NOT interview questions. They are the knowledge gaps you need to close. Good research questions share three traits: they are specific, answerable through observation or conversation, and relevant to a decision you face.
33
+
34
+ **Example research questions:**
35
+ - "What does a typical day look like for a small-business owner managing finances? What tools, workarounds, and people are involved?"
36
+ - "At what point in the workflow do enterprise users become frustrated enough to consider alternatives?"
37
+ - "What criteria do users actually use when choosing between competing tools, versus what they say they use?"
38
+ - "How do environmental factors (noise, interruptions, device switching) affect how users interact with our product?"
39
+
40
+ **Tip:** If a question can be answered with a simple yes/no, it is not a research question -- it is a hypothesis. Save those for experiments (Wade can help with that).
41
+
42
+ ### 3. Define the User Population
43
+
44
+ Who do you need to learn about? Be specific enough to recruit effectively, but broad enough that you do not accidentally study only your happiest customers.
45
+
46
+ **Consider:**
47
+ - Current users vs. non-users vs. former users
48
+ - Power users vs. casual users vs. struggling users
49
+ - Different roles, contexts, or segments
50
+ - People who might use your product but currently solve the problem differently
51
+
52
+ ### 4. Set Success Criteria for Discovery
53
+
54
+ How will you know when discovery is "done enough"? Perfect knowledge is impossible, but you should define a threshold.
55
+
56
+ **Examples:**
57
+ - "We can confidently describe 3 distinct user segments and their primary workflows."
58
+ - "We have evidence-backed answers to all 5 research questions from at least 3 independent sources each."
59
+ - "We've identified the top 3 unmet needs and can rank them by severity with supporting evidence."
60
+
61
+ ---
62
+
63
+ ## Your Turn
64
+
65
+ Please provide:
66
+ 1. Your discovery goal (what decision will this research inform?)
67
+ 2. 3-7 research questions you need to answer
68
+ 3. The user population you plan to study
69
+ 4. Your success criteria for completing discovery
70
+
71
+ I'll review your scope for clarity, specificity, and feasibility before we proceed.
72
+
73
+ ## Next Step
74
+
75
+ When your discovery scope is defined and confirmed, I'll load:
76
+
77
+ {project-root}/_bmad/bme/_vortex/workflows/user-discovery/steps/step-02-research-methods.md
@@ -0,0 +1,152 @@
1
+ ---
2
+ step: 2
3
+ workflow: user-discovery
4
+ title: Choose Research Methods
5
+ ---
6
+
7
+ # Step 2: Choose Research Methods
8
+
9
+ Now that you know what you need to learn, let's choose the right methods to learn it. Different questions call for different approaches, and combining methods produces richer, more trustworthy findings.
10
+
11
+ ## Why This Matters
12
+
13
+ Relying on a single research method creates blind spots. Interviews reveal what people say but not always what they do. Analytics show behavior but not motivation. Observation captures context but is hard to scale. The best discovery plans triangulate -- using multiple methods to validate findings from different angles.
14
+
15
+ ## Method Menu
16
+
17
+ ### Contextual Inquiry
18
+
19
+ **What it is:** Observing and interviewing users in their actual environment while they perform real tasks.
20
+
21
+ **Best for answering:**
22
+ - "What does their actual workflow look like?" (not the idealized version)
23
+ - "What environmental factors affect their experience?"
24
+ - "What workarounds and tools do they combine to get things done?"
25
+
26
+ **Practical guidance:**
27
+ - Visit users where they work (office, home, field)
28
+ - Ask them to perform their normal tasks while you observe
29
+ - Use the "master-apprentice" model: they are the expert, you are learning
30
+ - Capture the physical environment (desk setup, sticky notes, multiple monitors)
31
+ - Session length: 60-90 minutes per participant
32
+ - Recommended sample: 5-8 participants per segment
33
+
34
+ **Watch out for:** The Hawthorne effect -- people change behavior when observed. Schedule enough time that participants forget you're there.
35
+
36
+ ### Diary Studies
37
+
38
+ **What it is:** Participants log their experiences over time (days or weeks) in a structured format you provide.
39
+
40
+ **Best for answering:**
41
+ - "How does this experience unfold over time?"
42
+ - "What triggers engagement or frustration?"
43
+ - "How frequently do specific problems actually occur?"
44
+
45
+ **Practical guidance:**
46
+ - Provide a simple logging template (time, activity, emotion, notes)
47
+ - Use tools participants already have (text messages, photos, simple forms)
48
+ - Keep the burden low: 2-3 entries per day, 5 minutes each
49
+ - Duration: 1-4 weeks depending on the cycle you're studying
50
+ - Send daily reminders and respond to entries to maintain engagement
51
+ - Recommended sample: 8-15 participants
52
+
53
+ **Watch out for:** Participant fatigue. Front-load the most critical days and keep the logging format minimal.
54
+
55
+ ### Ethnographic Observation
56
+
57
+ **What it is:** Immersive observation of users in their natural context without direct interaction or task direction.
58
+
59
+ **Best for answering:**
60
+ - "What do users actually do versus what they report doing?"
61
+ - "What social and environmental dynamics influence behavior?"
62
+ - "What implicit norms or habits exist that users cannot articulate?"
63
+
64
+ **Practical guidance:**
65
+ - Observe without intervening or asking questions during the session
66
+ - Take detailed field notes: what you see, hear, and the environment
67
+ - Note timestamps so you can reconstruct sequences later
68
+ - Photograph or sketch the physical environment (with permission)
69
+ - Debrief with participants afterward to clarify what you observed
70
+ - Session length: 2-4 hours per observation
71
+ - Recommended sample: 4-6 sessions per context
72
+
73
+ **Watch out for:** Observer bias -- you will see what you expect to see. Bring a second observer when possible and compare notes independently before discussing.
74
+
75
+ ### Surveys
76
+
77
+ **What it is:** Structured questionnaires distributed to a larger sample for quantitative and qualitative data.
78
+
79
+ **Best for answering:**
80
+ - "How prevalent is this behavior or attitude across our user base?"
81
+ - "What are the relative priorities among known needs?"
82
+ - "How do different segments compare on key dimensions?"
83
+
84
+ **Practical guidance:**
85
+ - Use surveys to validate and quantify patterns found in qualitative research, not to discover new patterns
86
+ - Keep surveys under 15 questions and under 5 minutes completion time
87
+ - Mix closed-ended (scales, multiple choice) with 1-2 open-ended questions
88
+ - Pilot test with 3-5 people before full distribution
89
+ - Target a minimum of 30 responses per segment for meaningful patterns
90
+ - Recommended sample: 50-200+ depending on segment count
91
+
92
+ **Watch out for:** Leading questions, double-barreled questions, and social desirability bias. Have someone outside the team review the survey before distribution.
93
+
94
+ ### Analytics Review
95
+
96
+ **What it is:** Analyzing existing behavioral data from your product, website, or other systems.
97
+
98
+ **Best for answering:**
99
+ - "What do users actually do in our product?"
100
+ - "Where do they drop off, get stuck, or abandon?"
101
+ - "Which features are used most and least?"
102
+ - "How do behavioral patterns differ across segments?"
103
+
104
+ **Practical guidance:**
105
+ - Start with the user journey and map data to each stage
106
+ - Look for anomalies: unexpected drop-offs, surprising usage patterns, features with high engagement but low satisfaction
107
+ - Combine quantitative metrics with qualitative context (why is this number what it is?)
108
+ - Create cohort analyses to compare segments
109
+ - Time investment: 4-8 hours for a thorough review
110
+
111
+ **Watch out for:** Analytics show what happened but not why. Never draw motivational conclusions from behavioral data alone.
112
+
113
+ ## Choosing Your Methods
114
+
115
+ ### Method Selection Matrix
116
+
117
+ | Research Question | Contextual Inquiry | Diary Study | Observation | Survey | Analytics |
118
+ |---|---|---|---|---|---|
119
+ | Understand workflows | Strong | Medium | Strong | Weak | Medium |
120
+ | Discover motivations | Strong | Strong | Weak | Medium | Weak |
121
+ | Measure prevalence | Weak | Weak | Weak | Strong | Strong |
122
+ | Track over time | Weak | Strong | Weak | Medium | Strong |
123
+ | Uncover environment | Strong | Medium | Strong | Weak | Weak |
124
+ | Validate patterns | Medium | Medium | Medium | Strong | Strong |
125
+
126
+ ### Recommended Combinations
127
+
128
+ **Deep understanding of a new domain:** Contextual Inquiry + Diary Studies
129
+ **Validating known problems at scale:** Analytics Review + Survey
130
+ **Comprehensive discovery:** Contextual Inquiry + Analytics Review + Survey (confirmation)
131
+ **Longitudinal insight:** Diary Study + Analytics Review
132
+
133
+ ## Your Task
134
+
135
+ For each of your research questions from Step 1:
136
+ 1. Select 1-2 methods that best answer that question
137
+ 2. Explain why you chose those methods
138
+ 3. Note any constraints (budget, time, access to users) that limit your options
139
+
140
+ Aim for at least 2 different methods total across all questions to enable triangulation.
141
+
142
+ ---
143
+
144
+ ## Your Turn
145
+
146
+ Please share your method selections for each research question. I'll review them for appropriateness and suggest adjustments if needed.
147
+
148
+ ## Next Step
149
+
150
+ When your methods are selected and confirmed, I'll load:
151
+
152
+ {project-root}/_bmad/bme/_vortex/workflows/user-discovery/steps/step-03-research-plan.md
@@ -0,0 +1,159 @@
1
+ ---
2
+ step: 3
3
+ workflow: user-discovery
4
+ title: Plan Research Activities
5
+ ---
6
+
7
+ # Step 3: Plan Research Activities
8
+
9
+ You know what to learn and which methods to use. Now let's build a concrete plan: who participates, when things happen, what materials you need, and how you handle ethics.
10
+
11
+ ## Why This Matters
12
+
13
+ Research without a plan produces scattered, unreliable data. A clear plan ensures you recruit the right participants, prepare the right materials, and respect the people who give you their time and trust. It also gives stakeholders confidence that the investment will pay off.
14
+
15
+ ## Your Task
16
+
17
+ ### 1. Participant Recruitment
18
+
19
+ **How many participants do you need?**
20
+
21
+ Use these guidelines based on your chosen methods:
22
+ - Contextual inquiry: 5-8 per segment
23
+ - Diary studies: 8-15 total (expect 20-30% dropout)
24
+ - Ethnographic observation: 4-6 sessions
25
+ - Surveys: 50+ per segment (30 minimum for any pattern)
26
+ - Analytics review: N/A (uses existing data)
27
+
28
+ **Where will you find participants?**
29
+
30
+ | Source | Pros | Cons |
31
+ |--------|------|------|
32
+ | Existing users | Easy access, real context | Survivorship bias |
33
+ | Former users | Understand churn | Harder to reach, may be negative |
34
+ | Non-users | Fresh perspective | May not understand domain |
35
+ | Recruiting panels | Fast, screened | May not match real users |
36
+ | Community forums | Self-selected, passionate | Skewed toward vocal minority |
37
+ | Partner referrals | Trusted introduction | Small sample, filtered |
38
+
39
+ **Screening criteria:**
40
+ - What characteristics MUST participants have? (Include criteria)
41
+ - What characteristics DISQUALIFY someone? (Exclude criteria)
42
+ - How will you ensure diversity within your target population?
43
+
44
+ **Example screening questions:**
45
+ - "How often do you [relevant activity]?" (filters for frequency)
46
+ - "What tools do you currently use for [task]?" (filters for context)
47
+ - "How would you describe your experience level with [domain]?" (filters for expertise)
48
+
49
+ ### 2. Timeline
50
+
51
+ Build a realistic timeline that accounts for the reality that recruitment always takes longer than expected.
52
+
53
+ **Template timeline:**
54
+
55
+ | Week | Activity | Deliverable |
56
+ |------|----------|-------------|
57
+ | 1 | Finalize plan, create materials, begin recruitment | Screener, guides, consent forms |
58
+ | 2 | Recruitment and pilot sessions (1-2) | Refined guides based on pilot |
59
+ | 3-4 | Core research sessions | Raw notes, recordings, artifacts |
60
+ | 5 | Data organization and initial synthesis | Organized data set, initial themes |
61
+ | 6 | Final synthesis and report | Discovery report artifact |
62
+
63
+ Adjust based on your methods. Diary studies extend the core research phase. Analytics reviews can compress the timeline significantly.
64
+
65
+ ### 3. Research Materials
66
+
67
+ **For each method, prepare:**
68
+
69
+ **Contextual Inquiry:**
70
+ - Discussion guide (topics, not rigid questions)
71
+ - Observation checklist (what to look for in the environment)
72
+ - Note-taking template (timestamp, observation, interpretation columns)
73
+ - Recording equipment and backup plan
74
+
75
+ **Diary Studies:**
76
+ - Participant briefing document (what to log, how often, for how long)
77
+ - Logging template or tool setup
78
+ - Reminder schedule
79
+ - Incentive structure (when and how participants are compensated)
80
+
81
+ **Ethnographic Observation:**
82
+ - Observation protocol (where to position, what to record)
83
+ - Field notes template
84
+ - Camera/sketch supplies for environment capture
85
+ - Post-observation debrief questions
86
+
87
+ **Surveys:**
88
+ - Draft questionnaire with all questions
89
+ - Pilot test plan (3-5 people review before launch)
90
+ - Distribution channel and timeline
91
+ - Response target and follow-up plan
92
+
93
+ **Analytics Review:**
94
+ - Data sources and access confirmed
95
+ - Key metrics and events to analyze
96
+ - Cohort definitions
97
+ - Analysis framework (what comparisons to make)
98
+
99
+ ### 4. Ethical Considerations
100
+
101
+ Research involves real people. Handle their trust with care.
102
+
103
+ **Informed Consent:**
104
+ - Explain the purpose of the research in plain language
105
+ - Describe what participation involves (time, activities, recording)
106
+ - State that participation is voluntary and can be stopped at any time
107
+ - Explain how data will be stored, used, and eventually deleted
108
+ - Get written consent before any session begins
109
+
110
+ **Privacy and Data Protection:**
111
+ - Anonymize data as early as possible (use participant codes, not names)
112
+ - Store recordings and notes securely (encrypted, access-limited)
113
+ - Define a data retention period and stick to it
114
+ - Never share raw data outside the research team without consent
115
+ - Be especially careful with screenshots, photos, and screen recordings
116
+
117
+ **Compensation:**
118
+ - Compensate participants fairly for their time
119
+ - Pay regardless of whether they complete the full session
120
+ - Common rates: $50-150/hour for professionals, gift cards for consumers
121
+ - For diary studies: milestone payments to maintain engagement
122
+
123
+ **Vulnerability:**
124
+ - Be aware that research can surface sensitive topics
125
+ - Have a plan for if a participant becomes distressed
126
+ - Never pressure someone to continue if they seem uncomfortable
127
+ - Researchers are not therapists -- know your boundaries
128
+
129
+ ### 5. Logistics Checklist
130
+
131
+ - [ ] Recruitment screener created and distributed
132
+ - [ ] Consent forms prepared
133
+ - [ ] Discussion guides / observation protocols drafted
134
+ - [ ] Recording equipment tested
135
+ - [ ] Note-taking templates ready
136
+ - [ ] Incentives budgeted and procured
137
+ - [ ] Calendar invites sent with clear instructions
138
+ - [ ] Backup plan for no-shows (over-recruit by 20%)
139
+ - [ ] Data storage location set up and access confirmed
140
+ - [ ] Pilot session scheduled (at least 1 before core research)
141
+
142
+ ---
143
+
144
+ ## Your Turn
145
+
146
+ Please provide:
147
+ 1. Your recruitment plan (how many, from where, screening criteria)
148
+ 2. Your timeline (adapt the template above to your reality)
149
+ 3. Which materials you need to prepare for your chosen methods
150
+ 4. Your approach to consent, privacy, and compensation
151
+ 5. Any logistical concerns or constraints
152
+
153
+ I'll review your plan for feasibility and completeness.
154
+
155
+ ## Next Step
156
+
157
+ When your research plan is confirmed, I'll load:
158
+
159
+ {project-root}/_bmad/bme/_vortex/workflows/user-discovery/steps/step-04-execute.md