gpd-branch-hypothesis

name	gpd-branch-hypothesis
description	Create a hypothesis branch for parallel investigation of an alternative approach
argument-hint	<description>
context_mode	project-required
requires	{"files":[".gpd/ROADMAP.md",".gpd/STATE.md"]}
allowed-tools	["read_file","write_file","shell","grep","glob"]

<codex_runtime_notes> Codex shell compatibility:

• When shell steps call the GPD CLI, use /Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local instead of the ambient gpd on PATH.
• If you intentionally need the repo environment, keep the runtime pin: GPD_ACTIVE_RUNTIME=codex uv run gpd .... </codex_runtime_notes>

Create a git branch for investigating an alternative hypothesis or approach in parallel with the main line of research.

Hypothesis branches allow a researcher to explore "what if?" questions without polluting the main research state. Each branch gets its own STATE.md fork and hypothesis documentation, enabling side-by-side comparison later via $gpd-compare-branches.

Common triggers:

• Two valid approximation schemes and you want to compare both
• A reviewer suggests an alternative derivation pathway
• Numerical instability might be resolved by a different algorithm
• An alternative physical interpretation needs to be tested
• Different gauge choices or regularization schemes to compare

<execution_context>

Create a git branch for parallel investigation of an alternative hypothesis or approach. Sets up isolated research state with hypothesis documentation, enabling side-by-side comparison later via $gpd-compare-branches. Common in physics when multiple approximation schemes, gauge choices, or derivation pathways need to be compared systematically.

<required_reading> Read all files referenced by the invoking prompt's execution_context before starting. </required_reading>

Load project context:

INIT=$(/Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local init phase-op --include state,config "${PHASE_ARG:-}")
if [ $? -ne 0 ]; then
  echo "ERROR: gpd initialization failed: $INIT"
  # STOP — display the error to the user and do not proceed.
fi

Parse JSON for: phase_dir, phase_number, state_exists, roadmap_exists, commit_docs. This command requires project context because it forks hypothesis state from the active roadmap and STATE.md.

Parse the hypothesis description from command arguments.

Example: $gpd-branch-hypothesis Use dimensional regularization instead of hard cutoff -> description = "Use dimensional regularization instead of hard cutoff"

If no arguments provided:

ERROR: Hypothesis description required
Usage: $gpd-branch-hypothesis <description>
Example: $gpd-branch-hypothesis Use dimensional regularization instead of hard cutoff

Exit.

Generate a branch slug from the description:

1. Take the description string
2. Convert to lowercase
3. Replace non-alphanumeric characters with hyphens
4. Collapse multiple hyphens to single
5. Trim leading/trailing hyphens
6. Truncate to 50 characters (at word boundary)

Example: "Use dimensional regularization instead of hard cutoff" -> slug = "use-dimensional-regularization-instead-of-hard"

Verify the repository is in a clean state for branching:

# Check for uncommitted changes
git status --porcelain

If uncommitted changes exist:

Offer to stash instead of hard-failing:

Uncommitted changes detected:
{list of files from git status}

Options:
1. "Stash changes" — Auto-stash and continue
2. "Abort" — I'll handle this manually

If "Stash changes":

git stash push -m "gpd: auto-stash before hypothesis branch ${SLUG}"

Inform user: "Changes stashed. Recover later with git stash pop." Continue to create_branch.

If "Abort": Exit.

Record the current branch name for the hypothesis metadata:

PARENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)

Create the hypothesis branch:

git checkout -b "hypothesis/${SLUG}"

If branch already exists:

ERROR: Branch hypothesis/{slug} already exists.
Either:
1. Switch to it: git checkout hypothesis/{slug}
2. Choose a different description
3. Delete it first: git branch -D hypothesis/{slug}

Exit.

Create the hypothesis documentation directory and file:

mkdir -p .gpd/hypotheses/${SLUG}

Write .gpd/hypotheses/${SLUG}/HYPOTHESIS.md:

# Hypothesis: {description}

## Description

{description}

## Motivation

<!-- Why is this alternative worth investigating? -->
<!-- What limitation of the current approach does it address? -->

[To be filled by researcher]

## Expected Outcome

<!-- What do you expect to find if this hypothesis is correct? -->
<!-- What observable difference should exist vs. the main approach? -->

[To be filled by researcher]

## Success Criteria

<!-- How will you know this approach is better/worse/equivalent? -->

- [ ] [Criterion 1]
- [ ] [Criterion 2]
- [ ] [Criterion 3]

## Metadata

- **Parent branch:** {parent_branch}
- **Created:** {YYYY-MM-DD}
- **Status:** Active
- **Current phase:** [same as parent STATE.md current phase]

Help the researcher populate the HYPOTHESIS.md placeholders by inferring content from the research context.

1. Read project context:

# Get current phase and project state via gpd CLI
INIT=$(/Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local init progress --include roadmap,state)

Parse from INIT JSON: project_exists, state_exists, current_phase (object with number, name, directory), state_content, roadmap_content.

Run centralized context preflight before continuing:

CONTEXT=$(/Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local --raw validate command-context branch-hypothesis "$ARGUMENTS")
if [ $? -ne 0 ]; then
  echo "$CONTEXT"
  exit 1
fi

Then find the current phase directory:

CURRENT_PHASE_NUM="${current_phase.number}"
PHASE_DIR=$(/Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local --raw phase find "$CURRENT_PHASE_NUM")
if [ $? -ne 0 ]; then
  echo "ERROR: Could not find phase directory for phase $CURRENT_PHASE_NUM"
  # STOP — display the error to the user and do not proceed.
fi

Use the read_file tool to read .gpd/STATE.md, .gpd/ROADMAP.md, and any SUMMARY.md files in the phase directory. If state_content and roadmap_content were included via --include, use those directly instead of re-reading.

2. Generate draft content for each placeholder section:

Using the hypothesis description, project state, and latest research results, draft:

• Motivation: Infer from the description what limitation of the current approach this addresses. Reference specific results or methods from STATE.md / SUMMARY that motivate the alternative.
• Expected Outcome: Based on the hypothesis, predict what observable differences should exist. Be specific: "If dimensional regularization preserves gauge invariance better, we expect the Ward identity violation to decrease from O(epsilon) to O(epsilon^2)."
• Success Criteria: Generate 3 concrete, testable criteria derived from the expected outcome. Each criterion should be a checkable statement, not vague: "Energy eigenvalues agree with exact solution to within 1%" not "Results are accurate."

3. Update HYPOTHESIS.md with drafts:

Replace the placeholder sections with the generated content, clearly marked as AI-drafted for researcher review:

## Motivation

<!-- AI-drafted from project context — review and edit -->

{generated motivation referencing current approach limitations}

## Expected Outcome

<!-- AI-drafted — review and edit -->

{generated expected outcome with specific observables}

## Success Criteria

<!-- AI-drafted — review and edit -->

- [ ] {specific testable criterion 1}
- [ ] {specific testable criterion 2}
- [ ] {specific testable criterion 3}

4. Present to researcher:

Drafted motivation, expected outcome, and success criteria from project context.
Review and edit: .gpd/hypotheses/{slug}/HYPOTHESIS.md

The AI-drafted content is marked with <!-- AI-drafted --> comments.
Edit these sections before proceeding to planning.

Fork STATE.md to include hypothesis context:

1. Record the hypothesis branch decision via gpd CLI:

/Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local state add-decision --phase "${CURRENT_PHASE_NUM}" --summary "Created hypothesis branch: ${description}" --rationale "Investigating alternative approach on branch hypothesis/${slug}"

2. Optionally add a short hypothesis note to STATE.md via apply_patch tool. After the ## Current Position section, add:

## Active Hypothesis

**Branch:** hypothesis/{slug}
**Description:** {description}
**Parent:** {parent_branch}

This is a hypothesis branch investigating an alternative approach.
Compare results with parent branch via `$gpd-compare-branches`.

3. Treat that note as markdown-only context. It is not part of the structured state schema, so it will not be mirrored into state.json, and future JSON-driven state rewrites may replace it. The durable record for the hypothesis is the gpd state add-decision entry plus .gpd/hypotheses/${SLUG}/HYPOTHESIS.md.

Commit the hypothesis setup.

The commit CLI command respects commit_docs from .gpd/config.json internally — if commit_docs is false, the commit is automatically skipped.

PRE_CHECK=$(/Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local pre-commit-check --files .gpd/hypotheses/${SLUG}/HYPOTHESIS.md .gpd/STATE.md 2>&1) || true
echo "$PRE_CHECK"

/Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local commit "docs: create hypothesis branch for {slug}" --files .gpd/hypotheses/${SLUG}/HYPOTHESIS.md .gpd/STATE.md

Present completion summary:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 GPD > HYPOTHESIS BRANCH CREATED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

**Branch:** hypothesis/{slug}
**Description:** {description}
**Parent:** {parent_branch}
**Hypothesis doc:** .gpd/hypotheses/{slug}/HYPOTHESIS.md

---

## Next Steps

1. **Fill in HYPOTHESIS.md** — document motivation, expected outcome, and success criteria
2. **Plan the phase** using the alternative approach:

   $gpd-plan-phase {current_phase}

   <sub>/clear first -> fresh context window</sub>

3. **Execute and compare** when ready:

   $gpd-compare-branches

---

**Also available:**
- Switch back to parent: `git checkout {parent_branch}`
- List hypothesis branches: `git branch --list 'hypothesis/*'`

---

<anti_patterns>

• Don't create hypothesis branches for trivial variations (use a parameter sweep instead)
• Don't nest hypothesis branches (hypothesis off hypothesis) — branch from main or the primary research branch
• Don't modify the parent branch's STATE.md — only the copy on this branch
• Don't skip the HYPOTHESIS.md documentation — it's essential for later comparison
• Don't forget to fill in motivation and success criteria before starting work

</anti_patterns>

<success_criteria> Hypothesis branch creation is complete when:

• Description parsed and slug generated
• Git state verified clean
• Branch hypothesis/{slug} created
• .gpd/hypotheses/{slug}/HYPOTHESIS.md created with metadata
• Motivation, Expected Outcome, and Success Criteria populated from project context (AI-drafted)
• Structured hypothesis record created (decision entry + HYPOTHESIS.md)
• Changes committed (if commit_docs enabled)
• User informed of next steps

</success_criteria>

</execution_context>

Arguments: $ARGUMENTS (format: )

@.gpd/STATE.md @.gpd/ROADMAP.md

Execute the branch-hypothesis workflow from @./.codex/get-physics-done/workflows/branch-hypothesis.md end-to-end. Preserve all validation gates (argument parsing, git state checks, branch creation, hypothesis documentation).