good-citizens-corporation/hypothesis-driven-design-kit/docs

Copilot Skill: Hypothesis-Driven Design

This repo includes a .skill file that teaches GitHub Copilot the HDD methodology. When installed, Copilot can analyze artifacts, generate hypotheses, create test plans, and produce GitHub-ready outputs — all following the HDD discipline.

Installation

Option 1: Skill Import (Recommended)

1. Open VS Code with Copilot Chat enabled
2. Open the Copilot Chat panel
3. Type: @workspace /installSkill
4. Select hypothesis-driven-design.skill from this repo
5. The skill activates immediately

Option 2: Manual Install

1. Unzip the skill file:

``bash unzip hypothesis-driven-design.skill -d .github/copilot-skills/ ``

1. Copilot detects the skill automatically on next chat

When the Skill Activates

The skill triggers automatically when you share:

Rule of thumb: If the artifact makes claims about users, value, or outcomes — the skill applies.

What It Does

The skill runs a 5-phase analysis on any artifact:

1. NARRATIVE CHALLENGE    → Surface unsupported assertions
2. ASSUMPTION EXTRACTION  → Extract hidden assumptions
3. CONFIDENCE RANKING     → Rank by consequence of being wrong
4. HYPOTHESIS GENERATION  → Convert to canonical hypothesis format
5. ARTIFACT ROUTING       → Generate the output you need

Canonical Hypothesis Format

Every output traces back to this atomic unit:

We believe [outcome] is achievable if people doing/being [situation] can get [motivation].

If you can't write this sentence for what you're building, you're not doing product work.

Available Outputs

Example Prompts

Analyze an artifact

Here's our PRD. Apply HDD analysis.
[paste PRD]

Generate a test plan

Create a test plan for this hypothesis:
We believe increased retention is achievable if users reviewing dashboards 
can get inline annotations.

Create GitHub issues

Turn this hypothesis into GitHub issues with vertical slices.

Pre-register a hypothesis

Pre-register this hypothesis for V&V tracing:
We believe faster onboarding is achievable if new users doing initial setup 
can get contextual progress indicators.

Analyze a strategy deck

Analyze this deck for narrative risk.
[attach PPTX or paste extracted text]

The Fidelity Ladder (Test Plans)

When you request a test plan, the skill generates a progressive validation roadmap:

The rule: Never escalate to fidelity N+1 until fidelity N produces signal above your confidence threshold.

Key Concepts

Narrative vs. Evidence

A narrative is a claim presented as a finding with no source, no measurement, and no way to prove it wrong. Narratives feel like evidence but aren't. The skill identifies and flags them.

Stopping Conditions

Every hypothesis needs a stopping condition — what would cause you to abandon it. Without one, you're not testing. You're fishing.

INVEST Compliance

Slices generated by the skill follow INVEST:

• Independent — can be validated without other hypotheses
• Negotiable — implementation is flexible; outcome being tested is not
• Valuable — advances validation of parent hypothesis
• Estimable — assumption is specific enough to scope
• Small — tests one assumption, not a cluster
• Testable — has observable acceptance criteria

Skill Contents

The .skill file is a ZIP archive containing:

hypothesis-driven-design/
├── SKILL.md                         # Main skill definition
└── references/
    ├── deck-intake.md               # Strategy deck analysis
    ├── prd-rewrite.md               # PRD transformation
    ├── github-output.md             # Issue/EPIC generation
    ├── vv-preregistration.md        # V&V pre-registration
    ├── agile-output.md              # EPIC + vertical slices
    ├── test-plan.md                 # Progressive validation
    ├── invest-slicing.md            # Slice splitting patterns
    ├── artifact-risk.md             # Danger levels by artifact type
    └── consulting-package.md        # Engagement packaging

To inspect or modify the skill:

unzip hypothesis-driven-design.skill -d skill-working/
# edit files
zip -r hypothesis-driven-design.skill skill-working/hypothesis-driven-design/

Troubleshooting

Skill not triggering?

• Ensure the skill is installed (check Copilot Chat settings)
• Try an explicit prompt: "Using the hypothesis-driven-design skill, analyze this PRD"

Output missing stopping conditions?

The skill enforces output contracts. If your input doesn't contain enough information to generate a stopping condition, it will ask for clarification rather than guess.

Input is too thin?

If you provide a single sentence or brief claim instead of a full artifact, the skill will:

1. Flag that Phase 1 cannot decompose it (the input IS the narrative)
2. Either ask for the source document, or synthesize the likely artifact and proceed

This is intentional — a single assertion has nothing to analyze. Either provide the full document or let the skill reconstruct what the document probably says.

PPTX files?

Extract text first:

python -m markitdown presentation.pptx

Then paste the output into chat.

Integration with Kit Workflows

The skill outputs integrate with the repo's issue templates and evidence tracking:

The skill generates; the kit tracks.