# HDD Skill Cheat Sheet

## What It Does

The `hypothesis-driven-development` skill helps turn a story into a small, outcome-focused execution path. It keeps the work grounded in:

- clear user outcome
- measurable proof
- small vertical slice
- execution-ready plan
- resumable shared context

## Links

[Closing the Feedback Loop with Claude and Codex - YouTube](https://youtu.be/GE48aDZwfPQ)  
[imdone-cli on npm](https://www.npmjs.com/package/imdone-cli)

## How To Start

Run `claude` or `codex` from the backlog repo directory:

Codex:

```text
$hypothesis-driven-development SCRUM-267
```

Claude:

```text
/hypothesis-driven-development SCRUM-267
```

Use a story key when you know it. The skill resolves the story, checks the HDD template, loads relevant attachments, and continues from the next honest unchecked step.

## Custom HDD Template

The skill will prefer a project-local HDD template when one exists:

- `.imdone/templates/hypothesis_driven_development.md`
- fallback: `stock_hypothesis_driven_development`

Safe customizations:

- project-specific helper copy and examples
- default attachment links or attachment scaffolding
- extra guidance that does not change the HDD phase model

Do not rely on overriding these skill expectations:

- the `#HDD-template` marker
- the core story sections: `## Hypothesis`, `## Vertical Slice`, `## Acceptance Criteria`, `## Validate Assumptions`
- the `## Define the Outcome` checklist being used to track completion
- `attachments/success-metrics.md`, `attachments/demo.md`, `attachments/design.md`, `attachments/diagram.md`, `attachments/plan.md`, and `attachments/dod.md` as the standard artifact locations

If a custom template drifts too far from those expectations, the skill may repair the story structure before continuing.

## Core imdone Commands

```text
imdone pull
imdone push
imdone merge
```

- `imdone pull`: get the latest issue content, comments, and attachments from Jira before continuing local refinement or implementation.
- `imdone push`: sync accepted story and attachment changes back to Jira.
- `imdone merge`: use this after resolving a sync conflict locally so imdone can finish the merge state cleanly.

## The 3 Phases

### 1. Define the Outcome

Goal: make sure the story is worth building and narrow enough to prove.

Artifacts:

- `## Hypothesis` in the issue
- `## Vertical Slice` in the issue
- `## Acceptance Criteria` in the issue
- `## Validate Assumptions` in the issue
- `attachments/success-metrics.md`
- `attachments/demo.md`

Order:

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

### 2. Prove the Outcome

Goal: define the smallest clean implementation path.

Artifacts:

- `attachments/design.md`
- `attachments/diagram.md`
- `attachments/plan.md`

Order:

1. Design
2. Plan
3. Implement

Plan rule: always use explicit `red / green / refactor`.

### 3. Confirm the Outcome

Goal: capture what happened and whether the outcome was actually achieved.

Artifacts:

- `attachments/dod.md`
- `## Results` in `attachments/success-metrics.md`
- `## Retrospect` in `attachments/success-metrics.md`

Order:

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

## Core Working Rules

- Work only the current unchecked item.
- Skip what is already done.
- Update artifacts, not just chat.
- Keep the issue file linked to all important attachments.
- Prefer small slices over broad plans.
- Do not invent outcome evidence.
- If blocked by something outside the repo, record the evidence gate honestly.

## Interaction Pattern

The skill should work in short cycles:

1. Read current context
2. Draft the smallest useful update
3. Ask a pointed question when alignment is weak
4. Write the accepted change to the real artifact
5. Show the diff

## Best Uses

Use HDD when you need to:

- refine a vague story
- make acceptance criteria binary
- create a clean implementation plan
- recover context after interruption
- preserve handoff context for another person or agent

## Important Files

- issue file: source of truth for phase status
- `attachments/plan.md`: live execution plan and progress notes
- `attachments/demo.md`: proof script for showing the slice
- `attachments/success-metrics.md`: what success means and what happened
- `.imdone/hdd-skill.yml`: project-local HDD skill settings

## Quick Reminders

- hypothesis first, implementation second
- outcome over output
- slice by workflow, not by layer
- use red/green/refactor in the plan
- keep `plan.md` current when reality changes
- update demo steps if built behavior changes
