---
name: hypothesis-driven-development
description: Guide a story through hypothesis-driven development from hypothesis through design, plan, implementation order, and outcome review. Use when the user wants to refine a story, define or repair binary acceptance criteria, create or revise an AI-executable plan, add success metrics or demo steps, validate dependency direction, or check progress against the workflow artifacts.
user-invocable: true
argument-hint: "[issueKey]"
---

# Hypothesis-Driven Development

## Operating Model

Guide a story through three outcome-focused phases:
- Define the Outcome
- Prove the Outcome
- Confirm the Outcome

Purpose:
- leave the story with a small, current, execution-ready plan for an AI coding agent
- train outcome-first product-engineering behavior, not just artifact production
- reduce handoff risk with explicit assumptions, measurable evidence, and direct user-feedback paths
- keep touched implementation paths maintainable by preferring small DRY refactors and code-as-documentation during planning and implementation
- make implementation plans explicitly use red/green/refactor so test-first intent, smallest green change, and cleanup are visible in the plan itself
- capture implementation feedback in story artifacts so humans and AI can regain context after interruptions
- make `attachments/plan.md` the default place to record pivots and corrections, using `Progress notes` to capture both what changed and why
- treat `attachments/demo.md` as a single evolving proof artifact: define it early, then revise it during implementation when the real behavior, commands, or visible outcomes change

Non-goals:
- do not produce free-floating advice when the story artifacts should be updated instead
- do not advance phases or mark progress beyond the current honest step
- do not invent evidence when the next step depends on external validation or an unblock from outside the tool boundary

## Session Contract

Before doing workflow work:

1. Read `references/session-setup.md`.
2. Resolve the story and load only the current story plus its relevant attachments.
3. Read HDD skill state through `scripts/hdd_skill_state.mjs get-config`. If `push.status` is `missing`, prompt the user for push reminder preferences using the short setup in `references/configuration.md`, then persist the answer with `scripts/hdd_skill_state.mjs set-push-config` before continuing. After push config exists, call `scripts/hdd_skill_state.mjs begin-session` so interval timing starts from the current HDD session. For prompt-reminder config, push timing state, and `active_story` reads and writes, use `scripts/hdd_skill_state.mjs` instead of handling YAML directly in the workflow.
4. If the story is not already using the HDD template, use the `imdone-template` skill first.
5. Make sure the issue file links to every issue attachment that exists so artifacts are easy to find from the story. If the template already includes a link, leave it where it is. Duplicate links are acceptable.
6. Read `references/interaction-contract.md` and follow it throughout the session.

Provider detection rule:
- detect the backing provider from the issue markdown HTML comment metadata
- if the metadata contains `jira:<KEY>`, treat the story as Jira-backed
- if the metadata contains `github:<NUMBER>` or another GitHub issue identifier, treat the story as GitHub-backed
- if neither marker is present, use provider-neutral wording and avoid inventing provider-specific behavior

`references/interaction-contract.md` owns:
- the draft -> confirm -> write loop
- question style and pacing
- when to ask comprehension or critical questions
- push and pull behavior
- external-evidence gates
- plan freshness and shared-context checks
- how to handle blocked stories

## Phase Execution

Run only the current phase and current unchecked item. Skip anything already checked.

### Phase 1: Define the Outcome

Order:
1. Hypothesis
2. Vertical Slice
3. Acceptance Criteria
4. Validate Assumptions
5. Demo Plan

Write locations:
- Hypothesis: inline in `## Hypothesis` above `## Define the Outcome`
- Related Work: inline in `## Related Work` above `## Define the Outcome`
- Vertical Slice: inline in `## Vertical Slice` above `## Define the Outcome`
- Acceptance Criteria: inline in `## Acceptance Criteria` above `## Define the Outcome`
- Success Metrics: `attachments/success-metrics.md`
- Validate Assumptions: inline in `## Validate Assumptions` above `## Define the Outcome`
- Demo Plan: `attachments/demo.md`

Load `references/define-the-outcome.md` only when working this phase.
During Vertical Slice, first inspect related past stories or experiments in the current backlog plus the configured archive, then link the useful ones under `## Related Work` so the slice benefits from prior decisions and evidence.

### Phase 2: Prove the Outcome

Order:
1. Design
2. Plan
3. Implement

Write locations:
- Design: `attachments/design.md` and at least one Mermaid diagram in `attachments/diagram.md`
- Plan: `attachments/plan.md` using explicit red/green/refactor sequencing
- Progress notes from feedback, pivots, and discovered constraints: `attachments/plan.md`, plus additional attachments when warranted for clarity

Load `references/prove-the-outcome.md` only when working this phase.
Use it for implementation hygiene guidance, including DRY cleanup in touched flows and code-as-documentation defaults.
During Design, Plan, and Implement, always load the relevant expert reference before drafting or building, and inspect related past stories or hypotheses in the current backlog plus the configured archive so the work benefits from prior decisions and evidence.

### Phase 3: Confirm the Outcome

Order:
1. Definition of Done
2. Measure Results
3. Retrospect

Write locations:
- Definition of Done: `attachments/dod.md`
- Measure Results: `## Results` in `attachments/success-metrics.md`
- Retrospect: `## Retrospect` in `attachments/success-metrics.md`

Load `references/confirm-the-outcome.md` only when working this phase.

## Focused References

Load only the reference file needed for the current decision:
- setup and attachment rules: `references/session-setup.md`
- skill config and smart defaults: `references/configuration.md`
- Define Outcome workflow: `references/define-the-outcome.md`
- Prove Outcome workflow: `references/prove-the-outcome.md`
- Confirm Outcome workflow: `references/confirm-the-outcome.md`
- review prompt shape and product-owner flow: `references/interactive-review-pattern.md`
- acceptance-criteria rewrite help: `references/acceptance-criteria.md`
- slicing and demo questions: `references/vertical-slicing-experts.md`
- hypothesis, metrics, and results questions: `references/product-builder-experts.md`
- design, plan, and architecture questions: `references/lean-architecture-experts.md`
- dependency direction or inversion questions: `references/dependency-direction-rule.md`
- comprehension checks or facilitation help: `references/interactive-facilitation.md`
- implementation collaboration or done framing: `references/pair-mob-programming-experts.md`
- skill feedback artifact rules: `references/skill-feedback.md`
- shared-context framing only when needed: `references/solving-the-shared-context-problem.md`

## Persistent Rules

- Safe to re-run after interruption.
- Prefer updating current story artifacts over free-floating advice.
- Keep the issue file current as an attachment index. When an issue attachment exists or is created, make sure the issue file links to it. Leave existing template links in place, and accept duplicates when adding missing links is simpler than normalizing them.
- Use `scripts/hdd_skill_state.mjs` as the boundary for HDD config reads and writes, including push reminder settings, push timing state, `active_story`, and saved-key path resolution. Do not parse or rewrite those parts of `.imdone/hdd-skill.yml` inline in the HDD workflow.
- Before any push reminder, check `scripts/hdd_skill_state.mjs get-config` and only ask whether to run `imdone push` when `push.imdoneStatus.hasPendingChanges` is true.
- In `interval_prompt` mode, check push timing through `scripts/hdd_skill_state.mjs get-config` before starting any substantial read, edit, verification, or implementation cycle, not only at phase boundaries. Treat `push.promptDue` as already gated by elapsed interval and pending `imdone status` changes.
- When using this skill, end each user-facing message with a visible indicator showing the active story key, a short story summary, and the HDD skill version from `imdone --version`. Example: `🧭 HDD v0.58.2 | SCRUM-260 — Share changelog section on prompt upgrade`
- When `Progress notes:` are updated in `attachments/plan.md`, explicitly say so in the user-facing message after the story footer, using a visible indicator such as: `📝 Progress notes updated in attachments/plan.md`
- Rely on the tool's built-in edit diff. In chat, list changed file paths and summarize the change instead of replaying diffs.
- Default recording pattern for pivots and corrections:
  - update the affected phase steps in `attachments/plan.md`
  - add a short `Progress notes:` block for what changed, why it changed, and what must be remembered
  - when adding a `Progress notes:` entry, prefix it with a full ISO date-time timestamp such as `2026-05-15T14:32:10-04:00`, not a date-only stamp
  - add a new attachment only when the plan is no longer enough to recover the reasoning or boundary cleanly
- No supported skill alias field was found in the current local skill format, so keep the canonical skill name `hypothesis-driven-development` unless alias support is added to the skill loader.
- If the next honest step is outside the tool boundary, record the unblock note or evidence gate instead of pretending the story can advance locally.
- In `phase_prompt` push mode, prompt for `imdone push` after the first real write to `attachments/plan.md` and again after any `Progress notes:` update, not only at the end of a phase.
- If a follow-on step involves creating issues with `imdone add` or the `imdone-add` skill, treat creation as a serialized repo operation. Do not run multiple `imdone add` commands in parallel in the same repo unless a later implementation explicitly proves that concurrent create flows are safe for git state, attachment upload, and local issue refresh.
- During Phase 2, do not draft Design, Plan, or Implement artifacts from only the active story. First load the relevant expert reference, then search current backlog stories and the configured archive for similar hypotheses, acceptance criteria, plans, or outcomes. Summarize only the useful prior context; do not bulk-load unrelated archived work.
