diff --git a/.agents/skills/grilling-autoresearch/.senpai-developer-only b/.agents/skills/grilling-autoresearch/.senpai-developer-only new file mode 100644 index 000000000..e69de29bb diff --git a/.agents/skills/grilling-autoresearch/SKILL.md b/.agents/skills/grilling-autoresearch/SKILL.md new file mode 100644 index 000000000..ce96a5172 --- /dev/null +++ b/.agents/skills/grilling-autoresearch/SKILL.md @@ -0,0 +1,71 @@ +--- +name: grilling-autoresearch +description: Coach the user through a rigorous, repository-grounded interview to create or improve program.md. Use when a target repository lacks program.md, its goals, metrics, data, or guardrails are unclear, or the user asks to be grilled about an autoresearch setup. +--- + +# Grilling autoresearch + +Interview the user relentlessly until you reach a shared understanding. Map +this as a **design tree**: every decision branches into the decisions that hang +off it. + +Before asking questions, inspect the repository's documentation, data loaders, +training and evaluation code, configuration, and any existing `program.md`. +Finding facts is your job, never the user's. Ask the user only for decisions +and intent. + +Work the tree in **rounds**. The **frontier** is every decision whose +prerequisites are already settled: the questions you can ask now without +guessing at answers you have not heard yet. Ask the whole frontier in one +round. Number each question, give your recommended answer, and then wait for +the user's answers before the next round. + +Format each question like this: + +```text +❓ **Q1** - ****: + +➡️ +``` + +Each round reshapes the tree. Settled decisions push the frontier outward and +unblock dependent questions. Recompute the frontier and ask the next round. A +question whose answer depends on another question still open in this round +belongs to a later round. + +When a frontier question needs a fact from the environment, dispatch a +subagent to find it. Do not ask the user for anything you could look up +yourself, and do not block the independent questions: a running investigation +is only an unsettled prerequisite for its downstream branch. The decisions are +the user's; put each to them and wait. + +For `program.md`, keep the design tree centered on: + +- the objective, exact primary metric names and definitions, optimization + direction, evaluation split, and any secondary gates; +- data paths, shapes, sizes, splits, exclusions, leakage risks, and footguns; +- commands, budgets, result artifacts, editable boundaries, and benchmark + integrity constraints; and +- useful research avenues, papers, models, or libraries without unnecessarily + narrowing the search space. Narrow it only when that is the user's explicit + intent. + +The session is done when the frontier is empty: every branch of the design +tree has been visited and nothing material remains silently assumed. Do not +act on it until the user confirms that you have reached a shared understanding. + +Then draft a `program.md` that is concise, plain-language, and high-signal +because Senpai appends it to every model's system prompt. Make it specific +enough to run and evaluate the research correctly, while leaving implementation +choices and exploration to the research agents. Prefer high-level goals and +guardrails over step-by-step micromanagement, and verify every repository path, +command, data claim, and metric definition against the repository. + +Useful examples: + +- [TandemFoilSet-Balanced](https://github.com/morganmcg1/TandemFoilSet-Balanced/blob/main/program.md) +- [DrivAerML](https://github.com/morganmcg1/DrivAerML/blob/main/program.md) +- [MLXFast challenge](https://github.com/morganmcg1/mlxfast-challenge_senpai/blob/main/senpai/program.md) +- [autoresearch](https://github.com/karpathy/autoresearch/blob/master/program.md) + +Adapted from [Matt Pocock's grilling skill](https://github.com/mattpocock/skills/blob/main/skills/productivity/grilling/SKILL.md), used under the MIT License. diff --git a/.agents/skills/grilling-autoresearch/agents/openai.yaml b/.agents/skills/grilling-autoresearch/agents/openai.yaml new file mode 100644 index 000000000..576b4e663 --- /dev/null +++ b/.agents/skills/grilling-autoresearch/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Grilling Autoresearch" + short_description: "Clarify a high-signal program.md with the user" + default_prompt: "Use $grilling-autoresearch to help me define a clear program.md for this research repository." diff --git a/AGENTS.md b/AGENTS.md index ad828d7cb..2057f4a7d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,7 +10,7 @@ SPDX-PackageName: senpai ### Creating a target program.md -When helping a user onboard a target repository, inspect an explicitly configured `program_path` first. When it is blank, look for `program.md` at the root and exactly one directory below it. If there is no usable file, coach the user through creating one. Inspect the repository before interviewing them, establish facts yourself, ask the user to decide the remaining intent and tradeoffs, and wait for shared understanding before drafting the file. Multiple auto-discovered files are ambiguous; do not choose one silently. +When helping a user onboard a target repository, inspect an explicitly configured `program_path` first. When it is blank, look for `program.md` at the root and exactly one directory below it. If there is no usable file, coach the user through creating one by following the [`grilling-autoresearch`](.agents/skills/grilling-autoresearch/SKILL.md) skill (`$grilling-autoresearch`). Inspect the repository before interviewing them, establish facts yourself, ask the user to decide the remaining intent and tradeoffs, and wait for shared understanding before drafting the file. Multiple auto-discovered files are ambiguous; do not choose one silently. `program.md` is appended to every Senpai model's system prompt, so keep it concise, plain-language, and high-signal. It should clearly define: diff --git a/tests/test_openhands_tools_and_agents.py b/tests/test_openhands_tools_and_agents.py index d3691be64..1cfb8a140 100644 --- a/tests/test_openhands_tools_and_agents.py +++ b/tests/test_openhands_tools_and_agents.py @@ -560,6 +560,34 @@ def test_program_md_onboarding_context_is_shared_across_agent_clients(): assert all(url in agents_context for url in example_urls) +def test_grilling_autoresearch_skill_guides_human_program_design(): + agents_context = (REPO_ROOT / "AGENTS.md").read_text(encoding="utf-8") + skill_dir = REPO_ROOT / ".agents" / "skills" / "grilling-autoresearch" + skill = (skill_dir / "SKILL.md").read_text(encoding="utf-8") + normalized_skill = " ".join(skill.split()) + example_urls = { + "https://github.com/morganmcg1/TandemFoilSet-Balanced/blob/main/program.md", + "https://github.com/morganmcg1/DrivAerML/blob/main/program.md", + "https://github.com/morganmcg1/mlxfast-challenge_senpai/blob/main/senpai/program.md", + "https://github.com/karpathy/autoresearch/blob/master/program.md", + } + + assert (skill_dir / ".senpai-developer-only").exists() + assert "name: grilling-autoresearch" in skill + assert "$grilling-autoresearch" in agents_context + for requirement in ( + "Finding facts is your job, never the user's", + "Ask the whole frontier in one round", + "The decisions are the user's", + "Do not act on it until the user confirms", + "exact primary metric names and definitions", + "shapes, sizes, splits, exclusions", + "without unnecessarily narrowing the search space", + ): + assert requirement in normalized_skill + assert all(url in skill for url in example_urls) + + def test_delegation_guidance_lives_in_the_plugin_skill(): harness = ( REPO_ROOT / "system_instructions" / "SENPAI-HARNESS.md"