docs/README.md

ClarifyRL — Documentation Index

Project: ClarifyRL — Train LLMs to ask clarifying questions instead of hallucinating. Hackathon: Meta OpenEnv Hackathon Grand Finale, Apr 25-26, 2026, Bangalore. Team: Bhole Chature (Anurag Agarwal + Kanan Agarwal).

New agent / new chat? Read in this order:

1. AGENT_ONBOARDING.md — paste-this-first for non-Windsurf agents
2. STATUS.md — what's true right now
3. SESSION_LOG.md — last 3 entries, what prior agents did
4. Then the design docs below.

Read in this order

#	Doc	What it covers
00	overview.md	Pitch, problem statement, why this idea wins
01	requirements.md	Functional, non-functional, hackathon validator requirements
02	architecture.md	System architecture, components, data flow
03	environment-spec.md	OpenEnv env design: state, actions, observations, MCP tools
04	rubric-design.md	5-component composable rubric, weights, anti-hacking
05	scenario-design.md	Profile schema, task types, user simulator
06	training-plan.md	GRPO + Unsloth config, baseline, eval methodology
07	deployment.md	HF Space, Colab, README, submission checklist
08	timeline.md	Hour-by-hour 48h sprint plan + team split
09	risks.md	Risk register + mitigations + fallback plans

Lock-status

• ✅ Idea LOCKED: ClarifyRL (AskBeforeYouAct) — train epistemic humility via RL
• ✅ Theme LOCKED: #5 Wild Card (primary) + 3.2 Personalized + 2 Long-Horizon (secondary)
• ✅ Task families LOCKED: 3 high-stakes (coding, medical-intake, support) + 2 personal (meeting, event)
• ✅ Stack LOCKED: OpenEnv 0.2.2 + MCPEnvironment + FastMCP + Unsloth + TRL GRPO + Qwen2.5-1.5B
• ✅ Compute LOCKED: Colab free T4 + $30 HF inference credits + M3 Pro 18GB
• ✅ Docs LOCKED: Positioning sharpened with AI-safety framing
• ⏳ Code: Scaffolding done, env + rubric pending

Headline metric

Hallucination rate: ~90% baseline → ~3% trained (on 100 held-out scenarios across 5 task families).

Secondary metrics: plan satisfaction 27% → 85%, field-match F1 0.20 → 0.92, avg clarifying questions 0.4 → 2.7.