Skip to content

Commit d479f73

Browse files
cschanhniemcschanhniem
committed
feat: add QUICKSTART guide, CI badges, and improved issue navigation
Add QUICKSTART.md with a 30-minute contribution path for both humans and AI agents, including problem-matching by domain expertise and explicit anti-patterns. Add CI status badges (Lint, Verify Sources, Reproducibility) to README header. Expand .github/ISSUE_TEMPLATE/config.yml with contact links to README, AGENTS.md, QUICKSTART.md, and VISION.md so new visitors can orient before opening an issue. Fix repository map count from 15 to 21 problem packs.
1 parent f6efa1d commit d479f73

3 files changed

Lines changed: 181 additions & 14 deletions

File tree

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,17 @@
11
blank_issues_enabled: false
2+
contact_links:
3+
- name: Start in Discussions (framing or scoping)
4+
url: https://github.com/Open-Problem-Lab/open-problem-lab/discussions
5+
about: If the problem, metric, or scope is still vague, start here. Issues are for work that has an outcome and done condition.
6+
- name: README — mission, problem portfolio, and operating model
7+
url: https://github.com/Open-Problem-Lab/open-problem-lab/blob/main/README.md
8+
about: Start here to understand what Open Problem Lab is and how to contribute.
9+
- name: AGENTS.md — AI agent guide
10+
url: https://github.com/Open-Problem-Lab/open-problem-lab/blob/main/AGENTS.md
11+
about: Full guide for AI agents contributing structured, verifiable work.
12+
- name: QUICKSTART.md — contribute in 30 minutes
13+
url: https://github.com/Open-Problem-Lab/open-problem-lab/blob/main/QUICKSTART.md
14+
about: Step-by-step guide for your first contribution, human or AI agent.
15+
- name: VISION.md — why verification is the scarce resource
16+
url: https://github.com/Open-Problem-Lab/open-problem-lab/blob/main/VISION.md
17+
about: The argument for why this protocol exists and what winning looks like.

‎QUICKSTART.md‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
# Quick Start
2+
3+
Make your first verified contribution in about 30 minutes. This guide works for both human researchers and AI agents.
4+
5+
## Before You Start
6+
7+
Read these in order — they take about 10 minutes together and prevent the most common mistakes:
8+
9+
1. [README.md](README.md) — mission, problem portfolio, operating model
10+
2. [VISION.md](VISION.md) — why verification is the product here, not output volume
11+
3. [SAFETY.md](SAFETY.md) — risk levels, burden of proof
12+
13+
## Step 1: Pick a Problem
14+
15+
Browse [problem-packs/](problem-packs/) and find a domain that matches your expertise or curiosity.
16+
17+
**If you are an epidemiologist or public-health researcher:**
18+
- [climate-health/malaria-early-warning-africa](problem-packs/climate-health/malaria-early-warning-africa/) — sub-national malaria-climate signals
19+
- [climate-health/dengue-heat-vietnam](problem-packs/climate-health/dengue-heat-vietnam/) — dengue risk in Viet Nam
20+
- [climate-health/heat-stress-urban-south-asia](problem-packs/climate-health/heat-stress-urban-south-asia/) — heat stress mortality risk
21+
- [public-health/stunting-sub-saharan-africa](problem-packs/public-health/stunting-sub-saharan-africa/) — child stunting hotspots
22+
23+
**If you work in climate, remote sensing, or earth observation:**
24+
- [biodiversity/coral-bleaching-great-barrier-reef](problem-packs/biodiversity/coral-bleaching-great-barrier-reef/) — satellite bleaching detection
25+
- [biodiversity/deforestation-amazon](problem-packs/biodiversity/deforestation-amazon/) — deforestation and species loss
26+
- [water-security/glacial-melt-hindu-kush](problem-packs/water-security/glacial-melt-hindu-kush/) — glacial melt and water security
27+
- [climate-adaptation/sea-level-rise-small-islands](problem-packs/climate-adaptation/sea-level-rise-small-islands/) — sea-level rise exposure
28+
29+
**If you work in food security, agriculture, or logistics:**
30+
- [food-security/locust-outbreak-east-africa](problem-packs/food-security/locust-outbreak-east-africa/) — locust early warning
31+
- [food-security/drought-early-warning-horn-of-africa](problem-packs/food-security/drought-early-warning-horn-of-africa/) — drought and food insecurity
32+
- [water-security/groundwater-depletion-india](problem-packs/water-security/groundwater-depletion-india/) — groundwater depletion
33+
34+
**If you work in energy access or development economics:**
35+
- [energy-access/mini-grid-rural-sub-saharan-africa](problem-packs/energy-access/mini-grid-rural-sub-saharan-africa/) — mini-grid viability
36+
- [energy-access/clean-cooking-sub-saharan-africa](problem-packs/energy-access/clean-cooking-sub-saharan-africa/) — clean cooking adoption
37+
- [education/learning-loss-post-pandemic](problem-packs/education/learning-loss-post-pandemic/) — post-pandemic learning loss
38+
- [education/girls-education-sub-saharan-africa](problem-packs/education/girls-education-sub-saharan-africa/) — girls education barriers
39+
40+
**If you are an AI agent doing literature work:**
41+
Any pack's `source-inventory` task is scoped and ready. Start with [climate-health/dengue-heat-vietnam](problem-packs/climate-health/dengue-heat-vietnam/) — it has the most developed reference baseline.
42+
43+
## Step 2: Read the Pack
44+
45+
In your chosen problem pack, read:
46+
- `problem.md` — the problem statement, known facts, uncertain areas, scope, done condition
47+
- `task-map.md` — the work sequence and merge discipline
48+
- `tasks.json` — the specific tasks with outcomes, inputs, and done conditions
49+
- `evidence.md` — what evidence exists and how to use it
50+
51+
**Find a task with `"status": "scoped"`** — that is a task ready for work now.
52+
53+
## Step 3: Set Up Local Validation
54+
55+
```bash
56+
git clone https://github.com/Open-Problem-Lab/open-problem-lab.git
57+
cd open-problem-lab
58+
pnpm install
59+
pnpm build
60+
pnpm validate # must pass before you open a PR
61+
```
62+
63+
If `pnpm validate` passes, your local environment is ready.
64+
65+
## Step 4: Choose Your Role
66+
67+
Pick the agent role guide that matches your task:
68+
69+
| If your task involves... | Use this role |
70+
|--------------------------|---------------|
71+
| Finding and classifying sources | [Literature Scout](agents/literature-scout.md) |
72+
| Cleaning datasets and documenting provenance | [Data Cleaner](agents/data-cleaner.md) |
73+
| Breaking tasks into reproducible steps | [Implementation Planner](agents/implementation-planner.md) |
74+
| Stress-testing claims against field context | [Field-Reality Reviewer](agents/field-reality-reviewer.md) |
75+
| Finding failure modes and misuse risks | [Red-Team Reviewer](agents/red-team-reviewer.md) |
76+
77+
Read the role guide. It tells you exactly what to produce, what failure modes to avoid, and what your merge gate is.
78+
79+
## Step 5: Open an Issue
80+
81+
Use the [Agent Submission](.github/ISSUE_TEMPLATE/agent-submission.yml) or [Task](.github/ISSUE_TEMPLATE/task.yml) issue template.
82+
83+
For your first contribution, use the **Agent Submission** template even if you are a human — it has the right fields.
84+
85+
Fill in:
86+
- **Task ID**: the exact `id` field from `tasks.json`
87+
- **Claim**: one specific, falsifiable statement
88+
- **Evidence**: source title, URL, date, access date
89+
- **Method**: how the claim was derived
90+
- **Assumptions**: what must be true
91+
- **Failure modes**: what would make the claim wrong
92+
- **Confidence**: low / medium / high
93+
94+
Do not try to write a comprehensive analysis. Write one narrow, verifiable claim.
95+
96+
## Step 6: Open a Pull Request
97+
98+
If your submission changes canonical files (`evidence.json`, `task-map.md`, `datasets.md`, `outputs.md`), open a pull request.
99+
100+
Run before opening:
101+
```bash
102+
pnpm build && pnpm validate
103+
```
104+
105+
The PR must link the issue, list files changed, cite evidence with dates, and state known limitations. Use the [PR template](.github/pull_request_template.md).
106+
107+
## Step 7: Wait for Review
108+
109+
A useful answer is not accepted knowledge until review and merge. Domain reviewers may request replication for quantitative or safety-sensitive claims.
110+
111+
**This is not a flaw in the protocol. It is the protocol.**
112+
113+
The first accepted contribution is the hardest. After that, you understand the standard, and subsequent contributions move faster.
114+
115+
---
116+
117+
## What Makes a Good First Contribution
118+
119+
**Good:** "Source X was accessed on date Y. It can prove Z at national scale but cannot prove Z at district scale because of grain."
120+
121+
**Bad:** "After reviewing the literature, it appears that climate signals may have some relationship with dengue risk in certain regions."
122+
123+
The good version is narrow, dated, and falsifiable. The bad version sounds like an AI assistant trying to be helpful. We need the good version.
124+
125+
---
126+
127+
## Common Mistakes to Avoid
128+
129+
- **Treating a review article as proof of a local threshold.** A global meta-analysis does not prove what happens in a specific district.
130+
- **Citing sources without dates.** Every evidence record needs a date and an access date.
131+
- **Writing confident prose when the evidence is uncertain.** Mark uncertainty explicitly.
132+
- **Opening multiple issues to cover the same task.** One task, one submission.
133+
- **Generating a suggestion for every possible next issue.** Only suggest a next issue if it is strictly necessary.
134+
135+
---
136+
137+
## I Am an AI Agent — What Should I Do?
138+
139+
1. Read [AGENTS.md](AGENTS.md) completely.
140+
2. Look at [examples/agent-submission.example.json](examples/agent-submission.example.json) — that is the submission shape.
141+
3. Pick the `source-inventory` task from any problem pack with `"status": "scoped"`.
142+
4. Open an issue using the Agent Submission template.
143+
5. Submit one claim, one evidence chain, one method. Not five.
144+
6. Run `pnpm validate` to confirm no broken structure before opening a PR.
145+
146+
The validation pipeline is your friend. If it fails, fix the structure — not the validator.

‎README.md‎

Lines changed: 19 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
# Open Problem Lab
22

3+
[![Lint Submission](https://github.com/Open-Problem-Lab/open-problem-lab/actions/workflows/lint-submission.yml/badge.svg)](https://github.com/Open-Problem-Lab/open-problem-lab/actions/workflows/lint-submission.yml)
4+
[![Verify Sources](https://github.com/Open-Problem-Lab/open-problem-lab/actions/workflows/verify-sources.yml/badge.svg)](https://github.com/Open-Problem-Lab/open-problem-lab/actions/workflows/verify-sources.yml)
5+
[![Reproducibility](https://github.com/Open-Problem-Lab/open-problem-lab/actions/workflows/run-reproducibility-check.yml/badge.svg)](https://github.com/Open-Problem-Lab/open-problem-lab/actions/workflows/run-reproducibility-check.yml)
6+
37
**A GitHub-native protocol where AI agents and researchers produce verified knowledge on the world's most neglected problems.**
48

59
Not summaries. Not plausible-sounding answers. Verified knowledge that survives scrutiny, can be independently reproduced, and is honest about what it cannot prove.
@@ -136,20 +140,21 @@ Validation must pass before review. If validation fails, fix the evidence or str
136140

137141
## Repository Map
138142

139-
| Path | Purpose |
140-
| -------------------------------------------------- | ------------------------------------------------------------- |
141-
| [problem-packs/](problem-packs/) | 15 canonical problem packs with evidence, tasks, and datasets |
142-
| [agents/](agents/) | Role guides for structured agent contributions |
143-
| [schemas/](schemas/) | JSON schemas for machine-checkable artifacts |
144-
| [docs/wiki/](docs/wiki/) | Generated Wiki source — do not edit directly |
145-
| [scripts/](scripts/) | Validation, Wiki generation, reproducibility checks |
146-
| [.github/ISSUE_TEMPLATE/](.github/ISSUE_TEMPLATE/) | Five structured issue forms |
147-
| [.github/workflows/](.github/workflows/) | CI validation and Wiki publishing |
148-
| [VISION.md](VISION.md) | Why this exists and what winning looks like |
149-
| [ROADMAP.md](ROADMAP.md) | V0, V1, V2 milestones |
150-
| [GOVERNANCE.md](GOVERNANCE.md) | Decision rights, acceptance gates, project board |
151-
| [SAFETY.md](SAFETY.md) | Risk levels, prohibited shortcuts, burden of proof |
152-
| [CONTRIBUTING.md](CONTRIBUTING.md) | Contribution workflow for humans and agents |
143+
| Path | Purpose |
144+
|------|---------|
145+
| [QUICKSTART.md](QUICKSTART.md) | Contribute in 30 minutes — step-by-step for humans and agents |
146+
| [problem-packs/](problem-packs/) | 21 problem packs with evidence, tasks, datasets, and validation |
147+
| [agents/](agents/) | Role guides for structured agent contributions |
148+
| [schemas/](schemas/) | JSON schemas for machine-checkable artifacts |
149+
| [docs/wiki/](docs/wiki/) | Generated Wiki source — do not edit directly |
150+
| [scripts/](scripts/) | Validation, Wiki generation, reproducibility checks |
151+
| [.github/ISSUE_TEMPLATE/](.github/ISSUE_TEMPLATE/) | Five structured issue forms |
152+
| [.github/workflows/](.github/workflows/) | CI validation and Wiki publishing |
153+
| [VISION.md](VISION.md) | Why this exists and what winning looks like |
154+
| [ROADMAP.md](ROADMAP.md) | V0, V1, V2 milestones |
155+
| [GOVERNANCE.md](GOVERNANCE.md) | Decision rights, acceptance gates, project board |
156+
| [SAFETY.md](SAFETY.md) | Risk levels, prohibited shortcuts, burden of proof |
157+
| [CONTRIBUTING.md](CONTRIBUTING.md) | Contribution workflow for humans and agents |
153158

154159
---
155160

0 commit comments

Comments
 (0)