Initial extract: templates + methodology guide from Ideation
Public, version-controlled source of truth for TeamIDE's project templates, coding conventions, and the build-plan → PM scaffolding rules. Mounted read-only by TeamIDE's planner agent at runtime. Extracted from the personal Ideation repo as a precondition for workspace-projects-agent-spec.md §9.4. Personal Ideation stays private; this repo holds only the publishable methodology.
This commit is contained in:
@@ -0,0 +1,64 @@
|
||||
# Data files (large, not committed)
|
||||
data/
|
||||
|
||||
# Environment files
|
||||
.env
|
||||
.env.*
|
||||
!.env.example
|
||||
|
||||
# Python
|
||||
__pycache__/
|
||||
*.py[cod]
|
||||
*$py.class
|
||||
*.egg-info/
|
||||
*.egg
|
||||
dist/
|
||||
build/
|
||||
.eggs/
|
||||
*.whl
|
||||
venv/
|
||||
.venv/
|
||||
|
||||
# Rust
|
||||
target/
|
||||
|
||||
# Node
|
||||
node_modules/
|
||||
npm-debug.log*
|
||||
yarn-error.log*
|
||||
|
||||
# Model weights & checkpoints
|
||||
*.pt
|
||||
*.pth
|
||||
*.ckpt
|
||||
*.safetensors
|
||||
*.bin
|
||||
*.onnx
|
||||
*.h5
|
||||
checkpoints/
|
||||
weights/
|
||||
|
||||
# Jupyter
|
||||
.ipynb_checkpoints/
|
||||
*.ipynb_metadata/
|
||||
|
||||
# IDE
|
||||
.idea/
|
||||
.vscode/
|
||||
*.swp
|
||||
*.swo
|
||||
|
||||
# OS
|
||||
.DS_Store
|
||||
Thumbs.db
|
||||
|
||||
# Logs
|
||||
*.log
|
||||
logs/
|
||||
|
||||
# Build artifacts
|
||||
*.o
|
||||
*.so
|
||||
*.dylib
|
||||
*.a
|
||||
*.out
|
||||
@@ -0,0 +1,387 @@
|
||||
# Research Project Guidelines
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
ProjectName/
|
||||
├── README.md # Project overview (public-facing)
|
||||
├── LICENSE # MIT Transparency License
|
||||
├── CLAUDE.md # AI assistant guidelines + project config
|
||||
├── goals.md # Success criteria (what does "done" look like?)
|
||||
├── spec.md # Technical specification (optional)
|
||||
├── conclusions.md # Living findings document
|
||||
├── open_questions.md # Unresolved questions tracker
|
||||
├── .gitignore
|
||||
├── experiments/ # Experiment code (numbered runs)
|
||||
│ ├── run1-baseline.ext
|
||||
│ ├── run2-variable-change.ext
|
||||
│ └── ...
|
||||
├── results/ # Experiment results documentation
|
||||
│ ├── TEMPLATE-results.md # Template for new results docs
|
||||
│ └── experiment_N_results.md # One per experiment group
|
||||
├── data/ # Datasets (gitignored — large files)
|
||||
├── literature/ # Paper notes & prior art
|
||||
│ ├── TEMPLATE-paper.md # Template for paper reviews
|
||||
│ └── paper-name.md
|
||||
├── src/ # Implementation code (when research produces software)
|
||||
├── tests/ # Test suite
|
||||
├── docs/ # Technical documentation
|
||||
│ ├── README.md # Docs index
|
||||
│ ├── TEMPLATE-experiment-plan.md
|
||||
│ ├── TEMPLATE-milestone.md
|
||||
│ ├── getting-started.md
|
||||
│ └── architecture.md
|
||||
└── screenshots/ # Visuals for README / portfolio
|
||||
```
|
||||
|
||||
## TeamIDE Project Management
|
||||
|
||||
If this project was scaffolded from Ideation, `.teamide/` PM files (plans, tasks, project.yml) should already exist — generated from milestone definitions during scaffolding. See the Ideation workspace's `claude.md` for the PM generation workflow and format details.
|
||||
|
||||
## Terminology
|
||||
|
||||
| Term | Meaning |
|
||||
|------|---------|
|
||||
| **goals.md** | What success looks like — pass/fail criteria, anti-goals, kill gates |
|
||||
| **spec.md** | Technical specification for the system being built or studied (optional) |
|
||||
| **conclusions.md** | Living findings — updated after each experiment phase |
|
||||
| **open_questions.md** | Unresolved questions with context and leads |
|
||||
| **experiment** | A numbered run in `experiments/` with a hypothesis |
|
||||
| **results doc** | Structured write-up in `results/` documenting what happened |
|
||||
| **milestone** | A dependency-tracked unit of work with success criteria |
|
||||
|
||||
## The Research Pipeline
|
||||
|
||||
```
|
||||
Vision doc --> Math/tradeoff analysis --> Milestone plan --> Implementation --> Tests pass
|
||||
(speculative) (constrained) (prescriptive) (code) (done)
|
||||
```
|
||||
|
||||
Each stage has a different document type and level of commitment. Ideas flow left to right and can be killed at any stage.
|
||||
|
||||
## Document Layers
|
||||
|
||||
### Layer 1: Vision Documents
|
||||
|
||||
Thinking documents. Speculative, conversational, organized around questions and hypotheses. These live at the repo root or in topic-specific folders.
|
||||
|
||||
**Purpose:** Capture the frontier of thinking. These are allowed to be wrong.
|
||||
|
||||
**Examples:** Mathematical explorations, system architecture visions, training/data blueprints, goal documents.
|
||||
|
||||
### Layer 2: Specs & Plans
|
||||
|
||||
Prescriptive. Designed to be turned directly into implementation tasks. Live in `docs/` or as top-level files (`spec.md`).
|
||||
|
||||
**Purpose:** Bridge between "what if" and "what to build." Every spec includes tasks, API surface, success criteria, and test cases.
|
||||
|
||||
### Layer 3: Research Subprojects
|
||||
|
||||
Active investigations with clear experiment plans and validation gates. Each gets its own directory or subfolder within `experiments/` with a README explaining the hypothesis, experiment design, and expected outcomes.
|
||||
|
||||
### Layer 4: Architecture Docs
|
||||
|
||||
Written after implementation. Describe how things actually work, not how they were planned. Live in `docs/architecture.md`.
|
||||
|
||||
**Purpose:** Let a new developer understand the system without reading source code.
|
||||
|
||||
## Key Patterns
|
||||
|
||||
### 1. Hypothesis First (Non-Negotiable)
|
||||
|
||||
**Every experiment requires a written hypothesis before any code runs.** No hypothesis, no experiment.
|
||||
|
||||
The hypothesis states what you expect to happen and why — it forces you to think before you compute.
|
||||
|
||||
```markdown
|
||||
## Hypothesis
|
||||
Increasing batch size from 1 to 32 will reduce gradient noise enough for
|
||||
convergence, because individual gradient samples have high variance but
|
||||
batch-averaged gradients should be stable.
|
||||
|
||||
## Expected Outcome
|
||||
Loss should decrease monotonically with batch=32, vs oscillating with batch=1.
|
||||
If loss still oscillates with batch=32, the variance problem is fundamental,
|
||||
not just a sample-size issue.
|
||||
```
|
||||
|
||||
Without a hypothesis, you don't know what the experiment is testing. You'll see a number and not know if it's good or bad.
|
||||
|
||||
**The scientific method, applied:**
|
||||
1. **Observe** — notice something in your data, results, or literature
|
||||
2. **Question** — formulate a specific question about what you observed
|
||||
3. **Hypothesize** — predict an answer and state WHY you expect it
|
||||
4. **Experiment** — design a run that can confirm or reject the hypothesis
|
||||
5. **Analyze** — compare results to the prediction
|
||||
6. **Conclude** — state what was learned, update your mental model
|
||||
7. **Repeat** — the conclusion feeds the next observation
|
||||
|
||||
### 2. Kill Gates
|
||||
|
||||
Research questions get structured investigation with kill gates:
|
||||
|
||||
```
|
||||
Phase 1: Literature review (what exists?)
|
||||
Phase 2: Build minimal viable module
|
||||
Phase 3: Integration experiments (defined matrix of configs)
|
||||
Phase 4: Investigate properties (hypothesis-based, only if Phase 3 passes)
|
||||
Phase 5: Optimization (only if Phase 4 is promising)
|
||||
```
|
||||
|
||||
Each phase is a gate. If Phase 3 fails, Phase 4 doesn't happen. This prevents sunk-cost fallacy on dead-end research.
|
||||
|
||||
### 3. Constraint-Driven Design
|
||||
|
||||
Start with hard limits. Let them drive architecture.
|
||||
|
||||
```markdown
|
||||
## Constraints
|
||||
- [Your hardware/budget/time limit here]
|
||||
- [Your performance requirement here]
|
||||
- [Your compatibility requirement here]
|
||||
|
||||
## Design (driven by above)
|
||||
- [Architecture decision that follows from constraints]
|
||||
```
|
||||
|
||||
Don't design the ideal system then optimize. Design around your actual constraints from day one.
|
||||
|
||||
### 4. Explicit Deferral
|
||||
|
||||
Every milestone says what it's NOT doing and why:
|
||||
|
||||
```markdown
|
||||
**Deferred:** [Feature/capability].
|
||||
**Reason:** [Why it's not worth doing now].
|
||||
```
|
||||
|
||||
Three categories for all work items:
|
||||
- **Active/Concrete** — being built now, with tests
|
||||
- **Outlined** — architectural sketch, no code yet
|
||||
- **Deferred** — recognized need, explicitly postponed with rationale
|
||||
|
||||
This prevents scope creep while preserving ideas for later.
|
||||
|
||||
### 5. Tradeoff Tables
|
||||
|
||||
Every complex decision gets a table showing the option space:
|
||||
|
||||
```markdown
|
||||
| Option | Pros | Cons | When to pick |
|
||||
|-----------|------------------|-----------------------|----------------|
|
||||
| Option A | Simple, fast | Doesn't scale past N | Prototyping |
|
||||
| Option B | Scales well | Complex to implement | Production |
|
||||
| Option C | Best performance | Vendor lock-in | If budget > $X |
|
||||
```
|
||||
|
||||
No "we chose X because it's better." Instead: "here's the tradeoff space, here's what we picked and why."
|
||||
|
||||
### 6. Testable Success Criteria
|
||||
|
||||
Every milestone ends with a concrete, falsifiable statement:
|
||||
|
||||
```markdown
|
||||
**Success Criteria:**
|
||||
- [System] does [specific thing] in [specific time/resource bound]
|
||||
- [N] tests pass with zero warnings
|
||||
- [Specific scenario] produces [specific measurable result]
|
||||
```
|
||||
|
||||
Not "it should work" — specific numbers, specific scenarios.
|
||||
|
||||
### 7. Math First, Code Second
|
||||
|
||||
Abstract ideas get mathematical or formal framing before any code is written:
|
||||
|
||||
```
|
||||
Idea (what if we tried X?)
|
||||
--> Formalization (what does X actually mean mathematically?)
|
||||
--> Existing work (has anyone done this? what libraries exist?)
|
||||
--> Experiment plan (how would we test this?)
|
||||
--> Validation gate (what result would make us continue vs abandon?)
|
||||
```
|
||||
|
||||
This filters out ideas that sound good but don't survive formalization.
|
||||
|
||||
### 8. Documentation as Specification
|
||||
|
||||
Write implementation-ready docs before coding:
|
||||
|
||||
1. Write detailed spec in markdown (API signatures, wire formats, data structures)
|
||||
2. Implement against the spec
|
||||
3. Test against the spec's success criteria
|
||||
4. Update the spec if reality diverges
|
||||
|
||||
The spec IS the source of truth. Code follows docs, not the other way around.
|
||||
|
||||
## Experiment Tracking
|
||||
|
||||
All experiments live in the `experiments/` folder and follow strict naming and documentation conventions.
|
||||
|
||||
### Naming Convention
|
||||
|
||||
Experiments are numbered sequentially with a descriptive kebab-case suffix:
|
||||
|
||||
```
|
||||
experiments/
|
||||
├── run1-batch-gradient-baseline.c
|
||||
├── run2-per-sample-online.c
|
||||
├── run3-leaky-relu-activation.c
|
||||
├── run4-temperature-annealing.c
|
||||
└── ...
|
||||
```
|
||||
|
||||
Rules:
|
||||
- Prefix: `run<N>-` where N is sequential (run1, run2, run3...)
|
||||
- Suffix: short kebab-case description of what this run changes vs the previous
|
||||
- One variable changed per run when possible (isolation)
|
||||
- If a run is a variant of another, use sub-numbering: `run9b-normalization-lower-temp`
|
||||
- Run numbering stays globally sequential across the whole project — don't restart at run1 inside subfolders
|
||||
|
||||
When a single experiment direction spawns many runs, group them in a subfolder inside `experiments/`:
|
||||
|
||||
```
|
||||
experiments/
|
||||
├── run1-baseline.ext
|
||||
├── run2-different-approach.ext
|
||||
├── scaling-study/ # Subfolder for related runs
|
||||
│ ├── run3-small-scale.ext
|
||||
│ ├── run4-medium-scale.ext
|
||||
│ └── run5-large-scale.ext
|
||||
└── ...
|
||||
```
|
||||
|
||||
### Results Documentation
|
||||
|
||||
Every experiment's results are documented in `results/`. One results file per experiment or per logical group:
|
||||
|
||||
```
|
||||
results/
|
||||
├── experiment_1_results.md
|
||||
├── experiment_2_results.md
|
||||
└── ...
|
||||
```
|
||||
|
||||
Use `results/TEMPLATE-results.md` as the starting point for each results file.
|
||||
|
||||
### Key Rules for Results
|
||||
|
||||
1. **Every run gets a row in the summary table** — even failed runs. Especially failed runs.
|
||||
2. **Link to source files** — reference experiment files as `experiments/run1-descriptive-name.ext`
|
||||
3. **Include raw output** — paste actual terminal output. Don't just summarize.
|
||||
4. **One finding per discovery** — each finding gets its own subsection with a bold **Verdict** line
|
||||
5. **Comparison tables for pivots** — when switching approaches, add a side-by-side comparison table
|
||||
6. **Strikethrough completed next steps** — mark done items with `~~strikethrough~~` and add **DONE**
|
||||
7. **Decision points with kill gates** — define upfront what results would make you continue, pivot, or abandon
|
||||
8. **Literature context** — compare your results to published work
|
||||
|
||||
### Running Experiments
|
||||
|
||||
**All experiments MUST be run in the background** so the user can continue chatting while they execute. Never run a build or training run in the foreground — it blocks the conversation. Use background execution and check on results later.
|
||||
|
||||
## Milestone Format
|
||||
|
||||
Every implementation milestone follows this structure:
|
||||
|
||||
```markdown
|
||||
### Milestone X.Y: Title — [STATUS]
|
||||
|
||||
**What:** One-sentence summary of the deliverable.
|
||||
|
||||
**Tasks:**
|
||||
- [ ] Task with enough detail that someone else could do it
|
||||
- [ ] Another task
|
||||
|
||||
**Completed.** [Summary paragraph when done.]
|
||||
|
||||
**Deferred:** [What was intentionally left out and why.]
|
||||
|
||||
**New Files:**
|
||||
|
||||
| File | What |
|
||||
|------|------|
|
||||
| path/to/file | One-line description |
|
||||
|
||||
**API Surface:**
|
||||
[Function signatures or interface definitions]
|
||||
|
||||
**Depends on:** Milestone X.Y-1
|
||||
|
||||
**Success Criteria:** [Falsifiable statement with numbers]
|
||||
|
||||
**Test Cases:**
|
||||
1. [Specific scenario] — [expected result]
|
||||
2. [Specific scenario] — [expected result]
|
||||
```
|
||||
|
||||
### Dependency Graphs
|
||||
|
||||
Milestones form a dependency chain. Visualize it:
|
||||
|
||||
```
|
||||
Phase 1: 1.1 --> 1.2 --> 1.3 --> 1.4 --> 1.5
|
||||
| |
|
||||
Phase 2: v v
|
||||
2.1 --> 2.2 --> 2.3 --> 2.4
|
||||
```
|
||||
|
||||
This makes it obvious what can be parallelized and what blocks what.
|
||||
|
||||
## Principles
|
||||
|
||||
1. **Hypothesis before experiment** — no code runs without a written prediction of what will happen and why. This is the most important rule.
|
||||
2. **Speculation is welcome but quarantined** — vision docs are clearly marked as exploratory
|
||||
3. **Implementation follows specs** — not the reverse
|
||||
4. **Deferral is first-class** — saying "not now" with a reason is as important as saying "yes"
|
||||
5. **Constraints are features** — limits drive creative solutions rather than being obstacles
|
||||
6. **Tests are the definition of done** — not "it compiles" but "N tests pass with zero warnings"
|
||||
7. **Tradeoffs are documented** — future-you can understand why decisions were made
|
||||
8. **Kill gates protect your time** — research that fails a gate gets abandoned, not propped up
|
||||
9. **Every experiment is tracked** — numbered, named, with raw output in results files. Failed runs are documented just as thoroughly as successes.
|
||||
10. **One variable per run** — isolate changes so you know what caused the result. Sub-number variants (run9b) when testing minor tweaks.
|
||||
11. **Experiments run in the background** — never block the user's ability to chat. All builds, training runs, and long-running processes execute in the background.
|
||||
|
||||
## Commit Rules
|
||||
|
||||
- Never mention Claude, AI, or generated code in commits
|
||||
- Write as the developer, first person
|
||||
- Concise and descriptive
|
||||
|
||||
## Customization Checklist
|
||||
|
||||
When creating a new project from this template:
|
||||
|
||||
- [ ] Update `README.md` with project name, problem, idea, approaches
|
||||
- [ ] Fill in `goals.md` with success criteria from the project plan
|
||||
- [ ] Fill in `spec.md` if the project has a technical specification (otherwise delete it)
|
||||
- [ ] Set up `open_questions.md` with initial research questions
|
||||
- [ ] Create initial experiment plans in `docs/` using `TEMPLATE-experiment-plan.md`
|
||||
- [ ] Add project-specific entries to `.gitignore` (language-specific, data formats, etc.)
|
||||
- [ ] Update the "Project-Specific Configuration" section below
|
||||
- [ ] Initialize git and create GitHub repo
|
||||
|
||||
---
|
||||
|
||||
# Project-Specific Configuration
|
||||
|
||||
<!-- Everything below this line is customized per project -->
|
||||
|
||||
## Project Name
|
||||
|
||||
[PROJECT_NAME]
|
||||
|
||||
## Description
|
||||
|
||||
[Brief description of the research project]
|
||||
|
||||
## Research Question
|
||||
|
||||
[The core question this project investigates]
|
||||
|
||||
## Tech Stack
|
||||
|
||||
[Languages, frameworks, libraries being used]
|
||||
|
||||
## TeamIDE Workspace ID
|
||||
|
||||
[Workspace ID if deployed via TeamIDE]
|
||||
@@ -0,0 +1,27 @@
|
||||
MIT Transparency License
|
||||
|
||||
Copyright (c) Corey Herrera
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software without any modification,
|
||||
exemption or additional provision. All operational distributions, including
|
||||
executables, embedded installations, package repositories, container images,
|
||||
and network deployments must preserve their users' access to original source,
|
||||
documentation, build scripts, configuration, and modifications necessary to
|
||||
reproduce the intended implementation, in order to promote operational
|
||||
transparency for the betterment of humanity.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
@@ -0,0 +1,67 @@
|
||||
# [Project Name]
|
||||
|
||||
> One-line description of what this research investigates.
|
||||
|
||||
## The Problem
|
||||
|
||||
[What problem exists. Why current solutions are insufficient. 2-3 paragraphs max.]
|
||||
|
||||
## The Idea
|
||||
|
||||
[Your proposed approach. What makes it different. Include a diagram or table if helpful.]
|
||||
|
||||
## Current Status
|
||||
|
||||
[What works, what doesn't, what's next. Update this as the project progresses.]
|
||||
|
||||
| Component | Status | Key Metric |
|
||||
|-----------|--------|------------|
|
||||
| ... | ... | ... |
|
||||
|
||||
## Research Approaches
|
||||
|
||||
[List each approach being investigated with pros/cons.]
|
||||
|
||||
### Approach 1: [Name]
|
||||
- **Pro:** ...
|
||||
- **Con:** ...
|
||||
- **Open question:** ...
|
||||
|
||||
## Experiment Plan
|
||||
|
||||
[Numbered list of planned experiments with goals.]
|
||||
|
||||
### Experiment 1: [Name]
|
||||
**Goal:** [One sentence.]
|
||||
- [Details]
|
||||
- [Key question this answers]
|
||||
|
||||
## Success Criteria
|
||||
|
||||
[What results would make this research succeed vs fail.]
|
||||
|
||||
1. [Criterion with specific number]
|
||||
2. [Criterion with specific number]
|
||||
|
||||
If no approach meets these criteria: [fallback plan].
|
||||
|
||||
## Folder Structure
|
||||
|
||||
```
|
||||
ProjectName/
|
||||
├── experiments/ # Numbered experiment runs
|
||||
├── results/ # Experiment results documentation
|
||||
├── data/ # Datasets (gitignored)
|
||||
├── literature/ # Paper notes & prior art
|
||||
├── src/ # Implementation code
|
||||
├── tests/ # Test suite
|
||||
└── docs/ # Technical documentation
|
||||
```
|
||||
|
||||
## References
|
||||
|
||||
- [Paper/resource](URL) — one-line note
|
||||
|
||||
## License
|
||||
|
||||
[MIT Transparency License](LICENSE)
|
||||
@@ -0,0 +1,27 @@
|
||||
# Conclusions: [Project Name]
|
||||
|
||||
## Status: In Progress
|
||||
|
||||
## Key Findings
|
||||
|
||||
### Finding 1: [Title]
|
||||
**Discovered in:** [Experiment N, Phase X]
|
||||
**Summary:** [One paragraph]
|
||||
**Evidence:** See `results/experiment_N_results.md`
|
||||
**Impact:** [How this changes our approach]
|
||||
|
||||
## What Worked
|
||||
|
||||
1. [Approach/technique that succeeded and why]
|
||||
|
||||
## What Didn't Work
|
||||
|
||||
1. [Approach/technique that failed and why — this is equally valuable]
|
||||
|
||||
## Final Recommendation
|
||||
|
||||
[What to do with these findings. Ship it? Pivot? Integrate into another project?]
|
||||
|
||||
## Open Questions Remaining
|
||||
|
||||
1. [Question that this research didn't answer]
|
||||
@@ -0,0 +1,42 @@
|
||||
# Documentation
|
||||
|
||||
> Technical documentation for [Project Name]
|
||||
|
||||
## Table of Contents
|
||||
|
||||
### Getting Started
|
||||
- [Setup Guide](./getting-started.md)
|
||||
|
||||
### Research
|
||||
<!-- Add experiment plans and milestone docs as the project progresses -->
|
||||
<!-- Example: [Experiment 1 Plan](./experiment-1-plan.md) -->
|
||||
|
||||
### Architecture
|
||||
- [Architecture](./architecture.md) — Post-implementation technical design
|
||||
|
||||
### Templates
|
||||
- [Experiment Plan Template](./TEMPLATE-experiment-plan.md) — For planning new experiments
|
||||
- [Milestone Template](./TEMPLATE-milestone.md) — For milestone-based planning
|
||||
|
||||
---
|
||||
|
||||
## Documentation Guidelines
|
||||
|
||||
### Adding New Documentation
|
||||
|
||||
After completing an experiment phase or milestone:
|
||||
|
||||
1. Create a new `.md` file in this folder
|
||||
2. Add a link to the Table of Contents above
|
||||
3. Use the appropriate template:
|
||||
- [Experiment plan template](./TEMPLATE-experiment-plan.md) — For planning experiments
|
||||
- [Milestone template](./TEMPLATE-milestone.md) — For implementation milestones
|
||||
|
||||
### Naming Convention
|
||||
|
||||
| Type | Pattern | Example |
|
||||
|------|---------|---------|
|
||||
| Experiment plans | `experiment-N-plan.md` | `experiment-1-plan.md` |
|
||||
| Milestone docs | `milestone-N-name.md` | `milestone-1-foundation.md` |
|
||||
| Topic research | `research-[topic].md` | `research-gradient-methods.md` |
|
||||
| Guide docs | `guide-[topic].md` | `guide-data-preparation.md` |
|
||||
@@ -0,0 +1,21 @@
|
||||
# Run N: [Descriptive Name]
|
||||
|
||||
## Hypothesis
|
||||
|
||||
[What we expect to happen and why.]
|
||||
|
||||
## Setup
|
||||
|
||||
- **Architecture:** [Model/system description]
|
||||
- **Key change vs previous run:** [What's different]
|
||||
- **Config:** [Hyperparameters, settings]
|
||||
|
||||
## Expected Outcome
|
||||
|
||||
[What result would confirm or reject the hypothesis.]
|
||||
|
||||
## Run Command
|
||||
|
||||
```bash
|
||||
[How to build and run this experiment]
|
||||
```
|
||||
@@ -0,0 +1,66 @@
|
||||
# Milestone Plan: [Project Name]
|
||||
|
||||
## Dependency Graph
|
||||
|
||||
```
|
||||
Phase 1: 1.1 --> 1.2 --> 1.3
|
||||
|
|
||||
Phase 2: v
|
||||
2.1 --> 2.2 --> 2.3
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: [Phase Name]
|
||||
|
||||
### Milestone 1.1: [Title] — PENDING
|
||||
|
||||
**What:** [One-sentence summary of the deliverable.]
|
||||
|
||||
**Tasks:**
|
||||
- [ ] Task with enough detail that someone else could do it
|
||||
- [ ] Another task
|
||||
|
||||
**Deferred:** [What was intentionally left out and why.]
|
||||
|
||||
**New Files:**
|
||||
|
||||
| File | What |
|
||||
|------|------|
|
||||
| path/to/file | One-line description |
|
||||
|
||||
**API Surface:**
|
||||
[Function signatures or interface definitions, if applicable]
|
||||
|
||||
**Depends on:** None
|
||||
|
||||
**Success Criteria:** [Falsifiable statement with numbers]
|
||||
|
||||
**Test Cases:**
|
||||
1. [Specific scenario] — [expected result]
|
||||
2. [Specific scenario] — [expected result]
|
||||
|
||||
### Milestone 1.2: [Title] — PENDING
|
||||
|
||||
**What:** ...
|
||||
|
||||
**Depends on:** Milestone 1.1
|
||||
|
||||
...
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: [Phase Name]
|
||||
|
||||
### Milestone 2.1: [Title] — PENDING
|
||||
|
||||
**Depends on:** Milestone 1.2
|
||||
|
||||
...
|
||||
|
||||
---
|
||||
|
||||
## Kill Gates
|
||||
|
||||
- **After Phase 1:** If [condition], abandon [approach] and [fallback action]
|
||||
- **After Phase 2:** If [condition], pivot to [alternative]
|
||||
@@ -0,0 +1,35 @@
|
||||
# Architecture
|
||||
|
||||
> Technical architecture for [Project Name]
|
||||
|
||||
**Note:** This document is written after implementation. It describes how things actually work, not how they were planned. For the original design, see [spec.md](../spec.md).
|
||||
|
||||
## Tech Stack
|
||||
|
||||
| Layer | Technology | Purpose |
|
||||
|-------|------------|---------|
|
||||
| [Layer] | [Technology] | [Purpose] |
|
||||
|
||||
## System Design
|
||||
|
||||
[Diagrams, data flow, component interactions.]
|
||||
|
||||
## Key Design Decisions
|
||||
|
||||
### [Decision 1]
|
||||
|
||||
**Context:** [Why this decision was needed]
|
||||
|
||||
**Decision:** [What was decided]
|
||||
|
||||
**Consequences:** [Trade-offs and implications]
|
||||
|
||||
## Data Model
|
||||
|
||||
[Describe main entities, formats, and relationships]
|
||||
|
||||
## External Dependencies
|
||||
|
||||
| Dependency | Purpose | Documentation |
|
||||
|------------|---------|---------------|
|
||||
| [Library] | [Purpose] | [Link] |
|
||||
@@ -0,0 +1,47 @@
|
||||
# Getting Started
|
||||
|
||||
> Setup guide for [Project Name]
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- [Language runtime / compiler]
|
||||
- [Package manager]
|
||||
- [Additional prerequisites]
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/dcherrera/[ProjectName].git
|
||||
cd [ProjectName]
|
||||
|
||||
# Install dependencies
|
||||
[install command]
|
||||
```
|
||||
|
||||
## Running Experiments
|
||||
|
||||
```bash
|
||||
# Run a specific experiment
|
||||
[command to run experiment]
|
||||
|
||||
# View results
|
||||
[command to view output]
|
||||
```
|
||||
|
||||
## Project Layout
|
||||
|
||||
| Folder | Purpose |
|
||||
|--------|---------|
|
||||
| `experiments/` | Experiment code (numbered runs) |
|
||||
| `results/` | Experiment results documentation |
|
||||
| `data/` | Datasets (gitignored) |
|
||||
| `literature/` | Paper notes & prior art |
|
||||
| `src/` | Implementation code |
|
||||
| `tests/` | Test suite |
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Read [goals.md](../goals.md) to understand success criteria
|
||||
- Check [open_questions.md](../open_questions.md) for current research questions
|
||||
- Review [Architecture](./architecture.md) for technical design
|
||||
@@ -0,0 +1,36 @@
|
||||
# Goals: [Project Name]
|
||||
|
||||
## Primary Goal
|
||||
|
||||
[One sentence: what does this research need to achieve to be worth the time?]
|
||||
|
||||
## Success Criteria
|
||||
|
||||
These are pass/fail — either you hit them or you don't.
|
||||
|
||||
1. [Specific measurable criterion]
|
||||
2. [Specific measurable criterion]
|
||||
3. [Specific measurable criterion]
|
||||
|
||||
## Stretch Goals
|
||||
|
||||
Nice to have, not required for success.
|
||||
|
||||
1. [Stretch criterion]
|
||||
|
||||
## Anti-Goals
|
||||
|
||||
What this project is NOT trying to do. Prevents scope creep.
|
||||
|
||||
1. [Explicit non-goal]
|
||||
2. [Explicit non-goal]
|
||||
|
||||
## Fallback Plan
|
||||
|
||||
If no approach meets the success criteria:
|
||||
- [What you'll do instead]
|
||||
|
||||
## Timeline
|
||||
|
||||
- **Phase 1 deadline:** [Date or "N weeks from start"]
|
||||
- **Kill gate:** If Phase 1 doesn't pass by [deadline], [action]
|
||||
@@ -0,0 +1,11 @@
|
||||
# [Paper Title] ([Author Year])
|
||||
|
||||
**Link:** [URL]
|
||||
|
||||
**Key idea:** [One sentence]
|
||||
|
||||
**Relevance:** [How it relates to our research]
|
||||
|
||||
**What they got:** [Their results]
|
||||
|
||||
**What we can use:** [Actionable takeaway]
|
||||
@@ -0,0 +1,17 @@
|
||||
# Open Questions: [Project Name]
|
||||
|
||||
## Active Questions
|
||||
|
||||
### Q1: [Question]
|
||||
**Context:** [Why this matters]
|
||||
**Blocking:** [What can't proceed until this is answered, if anything]
|
||||
**Leads:** [Any partial answers or places to look]
|
||||
|
||||
## Answered Questions
|
||||
|
||||
<!-- Move questions here as they're resolved -->
|
||||
<!--
|
||||
### ~~Q0: [Question]~~
|
||||
**Answer:** [What we found]
|
||||
**Discovered in:** [Experiment N / Phase X / literature review]
|
||||
-->
|
||||
@@ -0,0 +1,81 @@
|
||||
# Experiment N Results: [Short Title]
|
||||
|
||||
## Phase [A/B/C...] — [Phase Name]
|
||||
|
||||
### Setup
|
||||
|
||||
- **Architecture:** [Model/system description]
|
||||
- **Source:** `experiments/run1-descriptive-name.ext`
|
||||
- **Config:** [Key hyperparameters or settings]
|
||||
|
||||
---
|
||||
|
||||
## Summary of All Runs
|
||||
|
||||
| Run | Key Variable | Config | Best Metric | Key Finding |
|
||||
|-----|-------------|--------|-------------|-------------|
|
||||
| 1 | baseline | ... | ... | [One-line takeaway] |
|
||||
| 2 | changed X | ... | ... | [One-line takeaway] |
|
||||
| 3 | changed Y | ... | ... | [One-line takeaway] |
|
||||
|
||||
---
|
||||
|
||||
## Detailed Findings
|
||||
|
||||
### Finding 1: [Descriptive Title]
|
||||
|
||||
**Runs [N-M]** ([what was varied])
|
||||
|
||||
[Explanation of what happened and why. Include raw output.]
|
||||
|
||||
```
|
||||
[Raw output from the run — config, per-epoch metrics, final results]
|
||||
```
|
||||
|
||||
**Verdict:** [One-line conclusion. Bold the action item.]
|
||||
|
||||
### Finding 2: [Next Discovery]
|
||||
|
||||
...
|
||||
|
||||
---
|
||||
|
||||
## Current Best Result
|
||||
|
||||
**Run N: [Short description of the winning config]**
|
||||
|
||||
```
|
||||
[Full output of the best run]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Conclusions
|
||||
|
||||
[What the phase proved or disproved. Structural insights, not just numbers.]
|
||||
|
||||
1. **[Finding]:** [Explanation]
|
||||
2. **[Finding]:** [Explanation]
|
||||
3. **[Finding]:** [Explanation]
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
Priority order:
|
||||
|
||||
1. ~~**Run N: [Description]**~~ — **DONE.** [Result summary.]
|
||||
2. **Run N+1: [Description]** — *Next up.* [Why this is the next thing to try.]
|
||||
3. **Run N+2: [Description]** — [Brief rationale.]
|
||||
|
||||
**Decision points:**
|
||||
- **>[Target] achieved:** Proceed to [next phase]
|
||||
- **Stuck at [range]:** [What that means and what to try]
|
||||
- **Below [floor] after remaining runs:** [Kill gate — abandon or pivot]
|
||||
|
||||
### Literature Context
|
||||
|
||||
| Method | Result | Notes |
|
||||
|--------|--------|-------|
|
||||
| [Existing work] | [Their result] | [How it compares] |
|
||||
| **Us (Run N)** | **[Our result]** | **[Where we stand]** |
|
||||
@@ -0,0 +1,37 @@
|
||||
# Spec: [System/Component Name]
|
||||
|
||||
## Overview
|
||||
|
||||
[What this system does. One paragraph.]
|
||||
|
||||
## Constraints
|
||||
|
||||
- [Hard limit 1]
|
||||
- [Hard limit 2]
|
||||
- [Hard limit 3]
|
||||
|
||||
## Architecture
|
||||
|
||||
[System design. Diagrams, data flow, component interactions.]
|
||||
|
||||
## API Surface
|
||||
|
||||
[Function signatures, data formats, wire protocols — whatever the system exposes.]
|
||||
|
||||
```
|
||||
// Example
|
||||
void system_do_thing(input_t *in, output_t *out);
|
||||
```
|
||||
|
||||
## Data Formats
|
||||
|
||||
[File formats, serialization, storage layout.]
|
||||
|
||||
## Integration Points
|
||||
|
||||
[How this system connects to other projects or systems.]
|
||||
|
||||
## Open Design Questions
|
||||
|
||||
- [Question that needs resolution before implementation]
|
||||
- [Question]
|
||||
Reference in New Issue
Block a user