Skip to content

Repurposing GitHub for Mathematical Research

courtesy: Claude

Marin project triggers my interest to repurpose github as a tool for open and reproducible mathematical research. Below is an example of how this can work, mostly one-shot generated by Claude.

Basic Repository Structure

conjecture-name/
├── README.md         # Overview, current status, and roadmap
├── conjecture.md     # Formal statement and background
├── proofs/           # Your proof attempts and progress
├── simulations/      # Code for experimental verification
└── notes/            # Working thoughts and observations

Simple Workflow

1. Setup & Problem Definition

  • Create the repository with a clear README explaining your goal
  • Write conjecture.md with the formal statement, notation, and known related results
  • Set up an initial project board with basic columns: "Ideas", "In Progress", "Needs Review", "Completed"

2. Working Process Using Issues

  • Create issues for specific approaches: "Approach via induction", "Probabilistic method attempt"
  • Create issues for subproblems: "Prove special case when n=2", "Find counterexample for condition X"
  • Use issue descriptions to outline your thinking process
  • Reference mathematical literature with links or DOIs
  • Close issues when an approach proves unsuccessful (with notes on why)

3. Exploration via Branches

  • Create a new branch for each significant approach (inductive-approach, computational-verification)
  • Commit frequently with descriptive messages that explain your mathematical thinking
  • Use commit messages to document insights: "Realized lemma fails when x approaches infinity"

4. Documentation Using Pull Requests

When you make meaningful progress: - Open a PR from your working branch to main - Write a detailed description of your findings - Self-review your work by reading through changes with fresh eyes - Merge when you're confident in the correctness

5. Simulation & Verification

  • Place code in the simulations/ directory
  • Document computational experiments in PR descriptions
  • Link simulation results to theoretical approaches

6. Progress Tracking

  • Use GitHub milestones to mark significant achievements ("Special case proven", "Main lemma established")
  • Update the README regularly with current status
  • Pin important issues that represent active lines of inquiry

Key GitHub Features to Leverage

Issues - Use as mathematical questions, approaches, or subproblems

  • Add labels like "promising", "stuck", "counterexample"
  • Reference equations with LaTeX in Markdown: $E = mc^2$

Project Board - Visual organization of your research flow

  • Track which approaches are active
  • See what needs verification

PR Process - Even as a solo researcher, use PRs as checkpoints

  • Force yourself to clearly articulate progress
  • Create a record of major developments
  • Serve as a self-review mechanism

Discussions - For longer-form mathematical exploration

  • Work through complex ideas
  • Record insights that don't fit elsewhere