Hep Idea

HEP Idea Generator

Generate concrete, publishable research proposals for particle physics phenomenology. The goal is not to produce vague directions, but specific, well-scoped problems that can realistically lead to a paper.

Step 1: Determine the idea source strategy

Before generating ideas, ask the user which approach they want for this session. Present these three strategies and let them pick:

Strategy A - Experiment-driven: Start from a recent experimental anomaly or new data release (e.g., a tension in B-meson measurements, a new LHC search limit, updated neutrino oscillation data). The idea addresses the anomaly with a concrete model or reinterprets new bounds in an existing framework.

Strategy B - Theory-driven: Start from a theoretical model or mechanism and explore its phenomenological consequences in a region that hasn't been fully studied (e.g., extending a known Z' model to the lepton sector, combining a seesaw mechanism with a particular dark matter candidate).

Strategy C - Gap-driven: Start from an open question or gap identified in existing literature (e.g., "nobody has computed the one-loop correction to this process", "the interplay between constraints X and Y in this model class hasn't been mapped out").

If the user has already indicated a preference in their message (e.g., "there's a new anomaly in muon g-2, let's build a model for it"), skip the strategy question and proceed directly.

Step 2: Gather context

Based on the chosen strategy, collect the necessary inputs:

• Strategy A: Ask what anomaly or dataset. If the user doesn't have one in mind, consult references/research-directions.md for current hot topics and suggest 2-5 recent experimental results worth investigating.

• Strategy B: Ask what model or mechanism to start from. If vague, consult references/research-directions.md and suggest 2-5 model frameworks with unexplored phenomenological territory.

• Strategy C: Ask what area to look for gaps. If the user has a previous project (check workspace/projects/ for completed projects), offer to read its conclusions and derive follow-up questions from there.

When consulting references/research-directions.md:

• If the file is missing or unreadable, inform the user that the reference file was not found at the expected path and suggest they check the skill installation. Then fall back to web search (arXiv, INSPIRE) to gather current hot topics instead. Do not halt the workflow; proceed with web-sourced information.
• If the file is present, use it as the primary source but still supplement with web search when available, since the file may not reflect the very latest developments.
• The reference file is a starting point, not a boundary. It captures a snapshot of known directions and is inevitably incomplete. Interesting ideas often lie outside any pre-curated list, at the intersection of sub-fields, in very recent developments, or in directions nobody has catalogued yet. Actively consider directions not covered in the file, especially when the user's input or web search results point somewhere new. At least one of the three candidate ideas in Step 3 should come from outside the reference file whenever possible.

Also ask about scope preferences:

• Preferred number of observables to include in the project, for example 1-3, 3-5, or more than 5
• Any models, experiments, processes, observables, or methods the user particularly wants to avoid discussing

Hard workflow constraint:

• Because the current Package-X workflow supports only tree-level and one-loop calculations, the core observables in candidate ideas must be executable at tree level or one loop. Do not center an idea on two-loop or higher-order calculations. If a topic is otherwise interesting but its main novelty depends on 2-loop or higher-order work, reformulate it around a tree-level or one-loop observable, or discard it.

Step 3: Generate candidate ideas

Produce exactly 3 candidate ideas. For each idea, provide:

1. Title - a working paper title, specific enough to be informative
2. One-paragraph pitch - what the paper would do and why it matters
3. Model sketch - particle content and key interactions in 2-3 sentences
4. Key observables - the observables you would actually compute,

with the count chosen to match the user's preferred scope. For each observable, specify:

• Calculation type (tree / 1-loop only)
• External particles
• Loop particles (if loop diagram)
• Target physical quantity (form factor, cross section, decay width, etc.)
• Priority (high / medium / low)

These details must be concrete enough to directly populate calc-tasks.json entries in Step 5b.

1. Feasibility note - estimated difficulty and timeline

The ideas should be meaningfully different from each other, not three variations on the same theme. Aim for one safer/incremental idea, one moderately ambitious idea, and one higher-risk/higher-reward idea.

Quality criteria for a good idea:

• It should be specific enough that you can immediately start writing a Lagrangian (not "study new physics effects in neutrino oscillations" but "constrain a U(1){Lmu - L_tau} model using the latest NOvA and T2K disappearance data combined with IceCube DeepCore")
• The observables should be computable with standard tools (FeynCalc, MadGraph, Package-X, etc.) within a reasonable timeframe, with Package-X tasks restricted to tree-level or one-loop calculations in the current workflow
• There should be a clear "punchline": what new thing the reader learns
• If the proposal would only become publishable after a two-loop or higher-order analytic calculation, it is out of scope for this workflow

When generating ideas, draw on knowledge of:

• Current experimental status (LHC Run 3 results, neutrino oscillation global fits, dark matter direct detection limits, flavor anomalies, etc.)
• Standard BSM frameworks (Z' models, two-Higgs-doublet models,

leptoquarks, scotogenic models, seesaw variants, ALPs, etc.)

• Methodological gaps (missing tree-level or one-loop calculations, unexplored parameter regions, combinations of constraints not yet studied together, etc.)

If web search is available, perform a lightweight but explicit novelty check before finalizing any candidate idea.

Minimum requirements:

• Search for related work from roughly the last three years using relevant keywords on arXiv and INSPIRE.
• Identify at least 3 closely related recent papers or results for each serious candidate idea.
• Briefly summarize how the proposed idea differs from the closest existing work.

If an idea appears too close to existing literature, downgrade or discard it and replace it with a more differentiated alternative.

Step 4: User selects and refines

Present the 3 ideas and let the user choose one (or ask to modify/combine). Once selected, ask if they want to adjust anything before generating the full proposal.

Step 5: Generate full proposal, model formalization, constraints, and benchmarks

This step has multiple phases executed in sequence:

• 5a: determine the project name, initialize the project skeleton, and write the research proposal
• 5b: formalize the model into machine-readable definitions
• 5c: collect and structure experimental constraints
• 5d: search for benchmark formulas for calculation verification
• 5e: write manifest.json

Each phase owns only its own outputs. Use scripts/init_project_skeleton.py to create the directory skeleton once. That script creates directories only: it does not create manifest.json or any placeholder output files. After the skeleton exists, Steps 5a-5e may assume their target directories already exist and should each write only the files assigned to that phase.

Step 5a - Initialize the project skeleton and write the research proposal

Write the proposal to the project workspace. Follow these steps:

1. Determine the project name from the idea (short, kebab-case, e.g.,

u1-lmu-ltau-nova-t2k or scotogenic-2loop-leptogenesis)

1. Run the skeleton initializer located in this skill's own

scripts/ directory. Resolve the path relative to the current skill directory rather than hardcoding a platform-specific repository path. For example, if you are operating inside the skill directory itself: `` python scripts/init_project_skeleton.py {project-name} ` If the current working directory is the repository root, invoke the same script via the current skill's path, for example: ` python .agents/skills/hep-idea/scripts/init_project_skeleton.py {project-name} ` in Codex-style layouts, or the corresponding .claude/... path in Claude-style layouts. The important rule is to resolve scripts/` relative to the current skill installation, not to assume one fixed top-level platform directory.

• In the standard .agents/... or .claude/... skill layout, the script infers the repository root from its own installation path and writes under workspace/projects/{project-name}/ by default. Users normally should not need to pass any extra root argument.
• This script creates only the directory skeleton under

workspace/projects/{project-name}/

• It must not create manifest.json or any placeholder output files
• The resulting skeleton is:

`` workspace/projects/{project-name}/ |-- idea/ |-- model/ |-- calculations/ |-- constraints/ |-- numerics/ | |-- scan-results/ | -- figures/ -- paper/ ``

1. Create idea/proposal.md from templates/proposal.md.tmpl

• Fill every placeholder with project-specific content
• Write in English, academic style
• Use LaTeX notation for equations ($...$, $$...$$) where appropriate

proposal.md template

Use templates/proposal.md.tmpl. Do not reorder sections.

Step 5b - Model formalization and calculation task decomposition

Formalize the model into machine-readable definitions. Read the Model Framework and Key Observables and Calculations sections of the proposal you just wrote, and generate the following two files.

For every JSON artifact below, treat the template as the shape example and the matching references/*-contract.md file as the authoritative artifact contract. Do not change field names, nesting, or semantics relative to those contracts. If a contract and a template example ever appear inconsistent, follow the contract.

File 1: model/model-spec.json

Machine-readable model definition. This is the single source of truth for all downstream modules.

Use templates/model-spec.example.json as the local canonical shape reference for this skill. For the authoritative artifact contract - required top-level keys, entry shapes, conditional parameter fields, and cross-file invariants - read references/model-spec-json-contract.md.

Write this file first. It is the machine-readable source of truth for downstream modules.

Hard rules for model-spec.json:

• For initial hep-idea output, set version to "v1".
• All parameter names use canonical name convention: ASCII letters, digits, underscores only. No LaTeX commands, Unicode, prime symbols, or curly braces.
• Each canonical name is unique and immutable within the project.

calc-tasks.json, and all future downstream files (result-meta.json, result-python.py, constraints-data.json) must use the exact same canonical names.

File 2: model/calc-tasks.json

Structured calculation task list. Decompose the Key Observables from the proposal into concrete tasks that package-scribe can execute directly.

Use templates/calc-tasks.example.json as the local canonical shape reference for this skill. For the authoritative artifact contract - top-level shape, required task fields, external_particles encoding, and tree/loop invariants - read references/calc-tasks-json-contract.md.

Decomposition logic:

• Since a single observable may correspond to multiple Feynman diagrams, it may be more appropriate to define one task per observable, depending on the capabilities of package-scribe
• Each task must contain all input information package-scribe needs: Lagrangian terms, structured external legs with momentum labels, loop particles (for loop diagrams), on-shell conditions, and target quantity
• Every task in calc-tasks.json must be executable at tree level or one loop only. Use type: "tree" with loop_order: 0 for tree-level tasks, and type: "loop" with loop_order: 1 for one-loop tasks. Do not emit tasks with loop_order > 1.
• Conventions are NOT repeated in tasks; they live in model-spec.json. Only add "convention_overrides": {...} if a specific task genuinely needs different conventions (rare)
• All parameter names in calc-tasks.json must match model-spec.json exactly. For particle names, every model-specific or new particle must match a fields[].name entry in model-spec.json exactly, while standard SM particle labels may be used directly as long as they follow one consistent shared naming convention. Put momentum labels in sibling fields such as momentum, not inside the particle name itself.

Post-write review

After generating both model files, write them to the workspace immediately.

Then present a summary of model-spec.json and calc-tasks.json to the user. Highlight:

• The model definition (fields, interactions, conventions)
• The task list coverage (which observables are included)
• Parameter names and ranges

Pause here for user confirmation before proceeding to constraints and benchmarks, unless the user has explicitly asked for a fully end-to-end run without intermediate review. If the user requests changes at this stage, revise the model and task decomposition in place before continuing.

Step 5c - Experimental constraints collection

Immediately after Step 5b, collect and structure the experimental constraints relevant to this model.

Write the constraint outputs in this order:

1. First write constraints/constraints-data.json as the structured source of truth for downstream automation.
2. Then write constraints/constraints-summary.md as the human-readable view derived from constraints-data.json.

The summary must not overstate automation readiness. It should reflect the actual implementation_status and computed_by values written to constraints-data.json.

Information sources:

1. Proposal's Experimental Constraints section: The proposal already lists relevant bounds in narrative form. Use this as the starting point.

1. Web search for latest data: For each constraint identified in the proposal, search arXiv, INSPIRE, and PDG for the latest experimental values. Specifically look for:

• PDG latest world averages for relevant quantities
• LHC search results from the last 1-2 years (may be stronger than those cited in the proposal)
• Latest global fit results (e.g., neutrino oscillation global fits)

1. Gap check: Based on model-spec.json's fields, interactions, and tags, consider whether the proposal missed any important constraints. Common categories to check: electroweak precision (S, T, U parameters), collider direct searches, flavor-changing processes, dark matter bounds (if applicable), cosmological constraints.

Output files:

constraints/constraints-data.json

Structured constraint data. Use templates/constraints-data.example.json as the local canonical shape reference for this skill. For the authoritative artifact contract - top-level shape, required per-constraint fields, computed_by, implementation_status, and interpolation rules - read references/constraints-data-json-contract.md.

Write this file before constraints/constraints-summary.md. It is the machine-readable source of truth for downstream modules and for the scan-usability labels shown in the summary.

Treat computed_by and implementation_status as two independent labels:

• first decide where the theory quantity comes from
• then

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: huangzhonglv
• Source: huangzhonglv/hep-workflow
• License: MIT

Install and usage instructions live in the source repository linked above.