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