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
imdone-cli on npm

How To Start

Run claude or codex from the backlog repo directory:

Codex:

$hypothesis-driven-development SCRUM-267

Claude:

/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.

Core imdone Commands

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