research-hypothesis
Create, update, and manage hypothesis cards within an research project. Maintains the hypothesis graph (Mermaid diagram) and the catalog table. Handles parent-child relationships, status transitions, and result recording. Use when formulating a new hypothesis, recording experimen
Install
npx skills add https://github.com/v0lka/skills/tree/main/engineering/research-hypothesis
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install v0lka-skills@llmmart
git clone https://github.com/v0lka/skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole v0lka/skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Hypothesis Management
Create, update, and manage hypothesis cards and the hypothesis graph for an research project.
Context
The hypothesis is the atomic unit of work in the methodology. Hypotheses are organized as a directed acyclic graph (DAG) where edges represent the relationship "result of X led to formulation of Y." The graph grows as the research progresses — only initial hypotheses are known at the start.
Each hypothesis has a card (a dedicated .md file) and an entry in the
graph page (hypotheses/graph.md).
Hypothesis Card Fields
Every hypothesis card contains these fields:
| Field | Description |
|---|---|
| Identifier | Unique ID within the research, e.g., H-001 |
| Short title | Concise label for graph nodes and catalog entries |
| Statement | What is being tested, phrased as a falsifiable assertion |
| Verification criterion | Specific condition for confirmation (working PoC, metric threshold, counterexample) |
| Timebox | Maximum time allocated for verification (ISO 8601 duration or calendar dates) |
| Parents | Links to hypothesis cards whose results led to this one (empty for root hypotheses) |
| Status | open / in-progress / confirmed / refuted / cancelled |
| Created | Date the hypothesis was formulated (ISO 8601) |
| Completed | Date the experiment concluded (filled upon completion) |
| Decision | The iteration decision applied after the result: continue / pivot / kill / fork (filled by research-decision) |
| Experiment notes | Free-form observations, intermediate findings, and methodology notes recorded during the experiment |
| Result | Filled upon completion: findings, link to prototype or proof, list of artifacts |
Operations
Create a New Hypothesis
Step 1 — Gather information
Collect from the researcher:
- Statement — a clear, falsifiable assertion. Good: "Static analysis of webpack bundles can extract >= 90% of API endpoints." Bad: "Look at webpack bundles."
- Verification criterion — what constitutes confirmation. Must be specific and measurable.
- Timebox — maximum time for this hypothesis. Push back if the timebox seems too generous (encourages scope creep) or too tight (guarantees inconclusive results).
- Parents — which existing hypothesis results motivated this one. For root hypotheses (formulated during Exploration), parents are empty.
If the statement is vague, help the researcher sharpen it. A hypothesis must be an assertion that can be confirmed or refuted, not a topic or direction.
Step 2 — Assign identifier
Read hypotheses/graph.md to find the highest existing H-NNN. Assign
H-(N+1), zero-padded to three digits.
Step 3 — Create the card file
Create hypotheses/H-NNN.md using the template at
assets/hypothesis-card-template.md.
Fill in all collected fields. Set status to open.
Step 4 — Update the graph
Update hypotheses/graph.md in two places:
Mermaid diagram: Add a new node with the appropriate CSS class (
openfor new hypotheses). If the hypothesis has parents, add edges from each parent node to the new node.Catalog table: Add a row with ID (linked to the card file), statement summary, status, decision (empty for new), and parent IDs.
Update Hypothesis Status
When a hypothesis transitions between statuses, update:
- The card file (
H-NNN.md): change the Status field. - The graph diagram: change the CSS class of the node.
- The catalog table: update the Status column.
- The research log (
log.md): append astatus_changeentry (see "Research Log" below).
Valid transitions:
open → in-progress → confirmed
→ refuted
→ cancelled
open → cancelled
A hypothesis cannot transition backwards. If rework is needed, create a new hypothesis with the original as parent.
Record Results
When an experiment completes (see research-experiment skill), update
the hypothesis card:
- Set Status to
confirmed,refuted, or leave asin-progressif the result is inconclusive. - Fill the Result section with:
- What was discovered.
- Link to the prototype, proof, or experiment artifacts.
- If inconclusive: why, and what would be needed for a definitive result.
- Update the graph diagram and catalog table accordingly.
Fork Hypotheses
When a fork decision is made (see research-decision skill), create
multiple child hypotheses from the same parent. Each competing approach
becomes its own hypothesis with its own timebox and verification criteria.
Document in each card that it is part of a fork and which hypotheses are
its siblings.
Mermaid Diagram Conventions
Use this node styling:
classDef confirmed fill:#4CAF50,color:#fff classDef refuted fill:#F44336,color:#fff classDef in_progress fill:#FF9800,color:#fff classDef open fill:#2196F3,color:#fff classDef cancelled fill:#9E9E9E,color:#fff
Node IDs use the pattern H001, H002, etc. (no hyphen, for Mermaid
compatibility). Display labels include the hyphen: H-001: Short title.
Edges represent "result led to formulation":
H001 --> H003 H002 --> H003
Important Notes
- One hypothesis at a time is the default. Fork (parallel hypotheses) is the exception, used only when competing approaches are discovered and resources allow parallel investigation.
- Timebox is a hard ceiling: if the timebox expires without a result,
that is itself a result (hypothesis not confirmed in allocated time) and
a signal for
killorpivot. - Keep hypothesis statements atomic. If a statement contains "and," consider splitting into two hypotheses.
- The graph is the primary navigation tool for the research. Keep it accurate and up to date at all times.
Research Log
Maintain a research-history log at log.md in the research project directory
(R-NNN/log.md). Whenever this skill mutates hypothesis state, append one
best-effort, timestamped entry so the timeline fills in automatically.
Each entry is a level-2 heading plus a one-line message body:
## <kind> <created_at> <hypothesis-id>
<message>
<kind>—status_changefor status transitions (this skill's entries).<created_at>— current UTC time in ISO 8601 (YYYY-MM-DDTHH:MM:SSZ, e.g.date -u +%Y-%m-%dT%H:%M:%SZ).<hypothesis-id>— the canonicalH-NNNidentifier of the hypothesis whose status changed.<message>— a single line summarizing the change, e.g.Moved H-003 from open to in-progress.
If log.md does not exist, create it with a # Research Log heading first.
Always append — never rewrite existing entries. If the log cannot be written,
continue anyway; the log is best-effort and must not block the operation.
Relation to Other Skills
- Invoked by
research-initto create the first hypothesis. - Works closely with
research-experiment(records results) andresearch-decision(determines next hypotheses after a result). research-statusreads the graph to generate overviews.research-synthesisuses the graph to produce the final report.
Files (skills)
-
assets
-
hypothesis-card-template.md 736 B
Loading…
-
-
SKILL.md 7.6 KB
--- name: research-hypothesis description: >- Create, update, and manage hypothesis cards within an research project. Maintains the hypothesis graph (Mermaid diagram) and the catalog table. Handles parent-child relationships, status transitions, and result recording. Use when formulating a new hypothesis, recording experiment results, updating hypothesis status, or managing the hypothesis graph. metadata: domain: engineering methodology: iterative-engineering-research --- # Hypothesis Management Create, update, and manage hypothesis cards and the hypothesis graph for an research project. ## Context The hypothesis is the atomic unit of work in the methodology. Hypotheses are organized as a directed acyclic graph (DAG) where edges represent the relationship "result of X led to formulation of Y." The graph grows as the research progresses — only initial hypotheses are known at the start. Each hypothesis has a card (a dedicated `.md` file) and an entry in the graph page (`hypotheses/graph.md`). ## Hypothesis Card Fields Every hypothesis card contains these fields: | Field | Description | |---|---| | **Identifier** | Unique ID within the research, e.g., `H-001` | | **Short title** | Concise label for graph nodes and catalog entries | | **Statement** | What is being tested, phrased as a falsifiable assertion | | **Verification criterion** | Specific condition for confirmation (working PoC, metric threshold, counterexample) | | **Timebox** | Maximum time allocated for verification (ISO 8601 duration or calendar dates) | | **Parents** | Links to hypothesis cards whose results led to this one (empty for root hypotheses) | | **Status** | `open` / `in-progress` / `confirmed` / `refuted` / `cancelled` | | **Created** | Date the hypothesis was formulated (ISO 8601) | | **Completed** | Date the experiment concluded (filled upon completion) | | **Decision** | The iteration decision applied after the result: `continue` / `pivot` / `kill` / `fork` (filled by `research-decision`) | | **Experiment notes** | Free-form observations, intermediate findings, and methodology notes recorded during the experiment | | **Result** | Filled upon completion: findings, link to prototype or proof, list of artifacts | ## Operations ### Create a New Hypothesis #### Step 1 — Gather information Collect from the researcher: 1. **Statement** — a clear, falsifiable assertion. Good: "Static analysis of webpack bundles can extract >= 90% of API endpoints." Bad: "Look at webpack bundles." 2. **Verification criterion** — what constitutes confirmation. Must be specific and measurable. 3. **Timebox** — maximum time for this hypothesis. Push back if the timebox seems too generous (encourages scope creep) or too tight (guarantees inconclusive results). 4. **Parents** — which existing hypothesis results motivated this one. For root hypotheses (formulated during Exploration), parents are empty. If the statement is vague, help the researcher sharpen it. A hypothesis must be an assertion that can be confirmed or refuted, not a topic or direction. #### Step 2 — Assign identifier Read `hypotheses/graph.md` to find the highest existing `H-NNN`. Assign `H-(N+1)`, zero-padded to three digits. #### Step 3 — Create the card file Create `hypotheses/H-NNN.md` using the template at [assets/hypothesis-card-template.md](assets/hypothesis-card-template.md). Fill in all collected fields. Set status to `open`. #### Step 4 — Update the graph Update `hypotheses/graph.md` in two places: 1. **Mermaid diagram**: Add a new node with the appropriate CSS class (`open` for new hypotheses). If the hypothesis has parents, add edges from each parent node to the new node. 2. **Catalog table**: Add a row with ID (linked to the card file), statement summary, status, decision (empty for new), and parent IDs. ### Update Hypothesis Status When a hypothesis transitions between statuses, update: 1. **The card file** (`H-NNN.md`): change the Status field. 2. **The graph diagram**: change the CSS class of the node. 3. **The catalog table**: update the Status column. 4. **The research log** (`log.md`): append a `status_change` entry (see "Research Log" below). Valid transitions: ``` open → in-progress → confirmed → refuted → cancelled open → cancelled ``` A hypothesis cannot transition backwards. If rework is needed, create a new hypothesis with the original as parent. ### Record Results When an experiment completes (see `research-experiment` skill), update the hypothesis card: 1. Set **Status** to `confirmed`, `refuted`, or leave as `in-progress` if the result is inconclusive. 2. Fill the **Result** section with: - What was discovered. - Link to the prototype, proof, or experiment artifacts. - If inconclusive: why, and what would be needed for a definitive result. 3. Update the graph diagram and catalog table accordingly. ### Fork Hypotheses When a `fork` decision is made (see `research-decision` skill), create multiple child hypotheses from the same parent. Each competing approach becomes its own hypothesis with its own timebox and verification criteria. Document in each card that it is part of a fork and which hypotheses are its siblings. ## Mermaid Diagram Conventions Use this node styling: ```mermaid classDef confirmed fill:#4CAF50,color:#fff classDef refuted fill:#F44336,color:#fff classDef in_progress fill:#FF9800,color:#fff classDef open fill:#2196F3,color:#fff classDef cancelled fill:#9E9E9E,color:#fff ``` Node IDs use the pattern `H001`, `H002`, etc. (no hyphen, for Mermaid compatibility). Display labels include the hyphen: `H-001: Short title`. Edges represent "result led to formulation": ```mermaid H001 --> H003 H002 --> H003 ``` ## Important Notes - **One hypothesis at a time** is the default. Fork (parallel hypotheses) is the exception, used only when competing approaches are discovered and resources allow parallel investigation. - **Timebox is a hard ceiling**: if the timebox expires without a result, that is itself a result (hypothesis not confirmed in allocated time) and a signal for `kill` or `pivot`. - Keep hypothesis statements atomic. If a statement contains "and," consider splitting into two hypotheses. - The graph is the primary navigation tool for the research. Keep it accurate and up to date at all times. ## Research Log Maintain a research-history log at `log.md` in the research project directory (`R-NNN/log.md`). Whenever this skill mutates hypothesis state, append one best-effort, timestamped entry so the timeline fills in automatically. Each entry is a level-2 heading plus a one-line message body: ``` ## <kind> <created_at> <hypothesis-id> <message> ``` - `<kind>` — `status_change` for status transitions (this skill's entries). - `<created_at>` — current UTC time in ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`, e.g. `date -u +%Y-%m-%dT%H:%M:%SZ`). - `<hypothesis-id>` — the canonical `H-NNN` identifier of the hypothesis whose status changed. - `<message>` — a single line summarizing the change, e.g. `Moved H-003 from open to in-progress.` If `log.md` does not exist, create it with a `# Research Log` heading first. Always append — never rewrite existing entries. If the log cannot be written, continue anyway; the log is best-effort and must not block the operation. ## Relation to Other Skills - Invoked by `research-init` to create the first hypothesis. - Works closely with `research-experiment` (records results) and `research-decision` (determines next hypotheses after a result). - `research-status` reads the graph to generate overviews. - `research-synthesis` uses the graph to produce the final report.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.