get-research-done 1.1.0

package/get-research-done/templates/data-report.md

@@ -0,0 +1,173 @@
+# Data Report: {dataset_name}
+
+**Generated:** {timestamp}
+**Source:** {file_path_or_paths}
+**Sampling:** {sampling_note_if_applicable}
+
+## Data Overview
+
+| Metric | Value |
+|--------|-------|
+| Total Rows | {count} |
+| Total Columns | {count} |
+| Memory Usage | {size} |
+| File Format | {format} |
+
+### Column Summary
+
+| Column | Type | Non-Null | Unique | Sample Values |
+|--------|------|----------|--------|---------------|
+| {col} | {dtype} | {count} | {count} | {values} |
+
+## Distributions & Statistics
+
+### Numerical Columns
+
+| Column | Mean | Std | Min | 25% | 50% | 75% | Max |
+|--------|------|-----|-----|-----|-----|-----|-----|
+| {col} | {val} | {val} | {val} | {val} | {val} | {val} | {val} |
+
+### Categorical Columns
+
+| Column | Unique | Top Value | Frequency |
+|--------|--------|-----------|-----------|
+| {col} | {count} | {value} | {count} |
+
+## Missing Data Analysis
+
+| Column | Missing Count | Missing % | Pattern | Confidence |
+|--------|---------------|-----------|---------|------------|
+| {col} | {count} | {pct} | {MCAR/MAR/MNAR} | {HIGH/MEDIUM/LOW} |
+
+**Pattern definitions:**
+- **MCAR** (Missing Completely At Random): Missing values are randomly distributed, no correlation with other features
+- **MAR** (Missing At Random): Missingness depends on observed data (other features)
+- **MNAR** (Missing Not At Random): Missingness depends on the unobserved value itself
+
+## Outlier Detection
+
+### Statistical Outliers
+
+| Column | Method | Outlier Count | % of Total | Severity |
+|--------|--------|---------------|------------|----------|
+| {col} | Z-score (>3) | {count} | {pct} | {severity} |
+| {col} | IQR (1.5x) | {count} | {pct} | {severity} |
+
+**Severity levels:**
+- **LOW**: <1% outliers
+- **MEDIUM**: 1-5% outliers
+- **HIGH**: >5% outliers
+
+### Top Anomalous Values
+
+| Column | Value | Z-score | Reason |
+|--------|-------|---------|--------|
+| {col} | {val} | {z} | {explanation} |
+
+## Class Balance (if target specified)
+
+**Target Variable:** {target_column}
+
+| Class | Count | Percentage |
+|-------|-------|------------|
+| {class} | {count} | {pct} |
+
+**Imbalance Ratio:** {ratio}
+**Severity:** {LOW/MEDIUM/HIGH}
+**Recommendation:** {recommendation}
+
+**Severity thresholds:**
+- **LOW**: Ratio <2:1 (acceptable imbalance)
+- **MEDIUM**: Ratio 2-10:1 (consider resampling or class weighting)
+- **HIGH**: Ratio >10:1 (resampling or specialized techniques required)
+
+## Data Leakage Analysis
+
+### Feature-Target Correlation
+
+| Feature | Correlation | Risk Level | Confidence | Notes |
+|---------|-------------|------------|------------|-------|
+| {feature} | {corr} | {HIGH/MEDIUM/LOW} | {confidence} | {explanation} |
+
+**Risk thresholds:**
+- **HIGH**: Correlation >0.9 (likely leakage)
+- **MEDIUM**: Correlation 0.7-0.9 (investigate further)
+- **LOW**: Correlation <0.7 (normal relationship)
+
+### High Feature-Feature Correlations
+
+| Feature 1 | Feature 2 | Correlation | Risk |
+|-----------|-----------|-------------|------|
+| {f1} | {f2} | {corr} | {risk_note} |
+
+**Note:** Correlations >0.95 may indicate redundancy, derived features, or leakage.
+
+### Train-Test Overlap (if multiple files)
+
+| Metric | Value |
+|--------|-------|
+| Overlapping Rows | {count} |
+| Overlap % (Train) | {pct} |
+| Overlap % (Test) | {pct} |
+| Severity | {severity} |
+
+**Severity thresholds:**
+- **LOW**: <1% overlap (minor contamination)
+- **MEDIUM**: 1-5% overlap (significant issue)
+- **HIGH**: >5% overlap (critical—invalidates evaluation)
+
+### Temporal Leakage Indicators
+
+| Issue | Detected | Confidence | Details |
+|-------|----------|------------|---------|
+| Future timestamps in features | {yes/no} | {confidence} | {details} |
+| Train dates after test dates | {yes/no} | {confidence} | {details} |
+| Rolling features computed globally | {unknown} | {confidence} | {details} |
+
+**Common temporal leakage sources:**
+- Features computed using future data (e.g., global mean instead of train-only mean)
+- Target leakage through time-lagged features
+- Features derived from test set statistics
+
+## Recommendations
+
+### Must Address (Blocking)
+
+These issues will cause model failure or produce invalid results:
+
+- [ ] {critical_issue_1}
+- [ ] {critical_issue_2}
+
+**Examples of blocking issues:**
+- High-confidence data leakage (feature correlates >0.95 with target)
+- Train-test overlap >5%
+- Target variable has missing values
+- Features with 100% missing values
+
+### Should Address (Non-blocking)
+
+These issues will reduce model quality but won't break training:
+
+- [ ] {recommended_issue_1}
+- [ ] {recommended_issue_2}
+
+**Examples of non-blocking issues:**
+- Missing data <30% (imputation recommended)
+- High number of outliers (investigate or clip)
+- Class imbalance >5:1 (resampling recommended)
+- Low-variance features (consider removal)
+
+### Notes
+
+{additional_observations}
+
+**Common observations:**
+- High-cardinality categorical features (may need encoding strategy)
+- Skewed distributions (may benefit from transformation)
+- Correlated feature groups (consider dimensionality reduction)
+- Data quality issues (duplicate rows, inconsistent formatting)
+
+---
+
+*Report generated by GRD Explorer Agent*
+*Template: get-research-done/templates/data-report.md*

package/get-research-done/templates/debug-subagent-prompt.md

@@ -0,0 +1,91 @@
+# Debug Subagent Prompt Template
+
+Template for spawning grd-debugger agent. The agent contains all debugging expertise - this template provides problem context only.
+
+---
+
+## Template
+
+```markdown
+<objective>
+Investigate issue: {issue_id}
+
+**Summary:** {issue_summary}
+</objective>
+
+<symptoms>
+expected: {expected}
+actual: {actual}
+errors: {errors}
+reproduction: {reproduction}
+timeline: {timeline}
+</symptoms>
+
+<mode>
+symptoms_prefilled: {true_or_false}
+goal: {find_root_cause_only | find_and_fix}
+</mode>
+
+<debug_file>
+Create: .planning/debug/{slug}.md
+</debug_file>
+```
+
+---
+
+## Placeholders
+
+| Placeholder | Source | Example |
+|-------------|--------|---------|
+| `{issue_id}` | Orchestrator-assigned | `auth-screen-dark` |
+| `{issue_summary}` | User description | `Auth screen is too dark` |
+| `{expected}` | From symptoms | `See logo clearly` |
+| `{actual}` | From symptoms | `Screen is dark` |
+| `{errors}` | From symptoms | `None in console` |
+| `{reproduction}` | From symptoms | `Open /auth page` |
+| `{timeline}` | From symptoms | `After recent deploy` |
+| `{goal}` | Orchestrator sets | `find_and_fix` |
+| `{slug}` | Generated | `auth-screen-dark` |
+
+---
+
+## Usage
+
+**From /grd:debug:**
+```python
+Task(
+  prompt=filled_template,
+  subagent_type="grd-debugger",
+  description="Debug {slug}"
+)
+```
+
+**From diagnose-issues (UAT):**
+```python
+Task(prompt=template, subagent_type="grd-debugger", description="Debug UAT-001")
+```
+
+---
+
+## Continuation
+
+For checkpoints, spawn fresh agent with:
+
+```markdown
+<objective>
+Continue debugging {slug}. Evidence is in the debug file.
+</objective>
+
+<prior_state>
+Debug file: @.planning/debug/{slug}.md
+</prior_state>
+
+<checkpoint_response>
+**Type:** {checkpoint_type}
+**Response:** {user_response}
+</checkpoint_response>
+
+<mode>
+goal: {goal}
+</mode>
+```

package/get-research-done/templates/decision-log.md

@@ -0,0 +1,58 @@
+# Decision Log Template
+
+Template for `human_eval/decision_log.md` — central chronological record of all human evaluation decisions.
+
+---
+
+## File Template
+
+```markdown
+# Human Evaluation Decision Log
+
+This log tracks all human evaluation decisions for this research project.
+
+| Timestamp | Run | Decision | Key Metric | Reference |
+|-----------|-----|----------|------------|-----------|
+```
+
+---
+
+## Usage Notes
+
+- **Append-only:** New entries always added at the bottom (chronological order)
+- **Timestamp:** YYYY-MM-DD HH:MM format (local time)
+- **Run:** Run directory name (e.g., run_003_tuned)
+- **Decision:** One of Seal, Iterate, Archive
+- **Key Metric:** Primary metric with value (e.g., F1=0.85)
+- **Reference:** Relative path to run directory
+
+## Example Entries
+
+| Timestamp | Run | Decision | Key Metric | Reference |
+|-----------|-----|----------|------------|-----------|
+| 2026-01-30 14:23 | run_003_tuned | Seal | F1=0.85 | experiments/run_003_tuned/ |
+| 2026-01-29 10:15 | run_002_baseline | Iterate | F1=0.76 | experiments/run_002_baseline/ |
+| 2026-01-28 16:45 | run_001_initial | Archive | F1=0.65 | experiments/archive/2026-01-28_hypothesis_v1/ |
+
+## Navigation
+
+- For full decision context, see DECISION.md in each run directory
+- For archived runs, see ARCHIVE_REASON.md in archive directory
+- Log created automatically on first /grd:evaluate decision
+
+---
+
+## Integration
+
+This template is used by `/grd:evaluate` command in Phase 4 (Decision Logging).
+
+**Creation:**
+- Created automatically when first decision is logged
+- Initialized with header and table structure
+
+**Updates:**
+- Each human decision appends one row
+- Order: chronological (newest at bottom)
+- No deletion or modification of existing entries
+
+**Log references run only, no bidirectional links** — per 05-CONTEXT.md decision

package/get-research-done/templates/decision.md

@@ -0,0 +1,138 @@
+# Human Decision Template
+
+Template for per-run decision records in `experiments/run_NNN/DECISION.md`.
+
+---
+
+## File Template
+
+```markdown
+# Human Decision: {{run_name}}
+
+**Timestamp:** {{ISO_8601_timestamp}}
+**Hypothesis:** {{brief_hypothesis_from_objective}}
+**Decision:** {{Seal|Iterate|Archive}}
+**Rationale:** {{user_reasoning_if_provided}}
+
+## Evidence Summary
+
+**Critic Verdict:** {{PROCEED}} (Confidence: {{HIGH|MEDIUM|LOW}})
+**Composite Score:** {{score}} (threshold: {{threshold}})
+**Key Metric:** {{metric_name}}={{value}} (target: {{comparison}}{{threshold}})
+
+## Metrics Detail
+
+| Metric | Value | Threshold | Status |
+|--------|-------|-----------|--------|
+| {{metric_1}} | {{value}} | {{threshold}} | {{PASS|FAIL}} |
+| {{metric_2}} | {{value}} | {{threshold}} | {{PASS|FAIL}} |
+
+## Decision Context
+
+### For Seal
+- Hypothesis validated
+- Ready for production/publication
+- All success criteria met
+
+### For Iterate
+- Continuing experimentation
+- Direction: {{REVISE_METHOD|REVISE_DATA}} (from Critic recommendation)
+- Next focus: {{specific_area}}
+
+### For Archive
+- Hypothesis abandoned
+- Reason: {{user_rationale_required}}
+- Preserved as negative result
+
+---
+
+*Decision recorded: {{ISO_8601_timestamp}}*
+*Run directory: experiments/{{run_name}}/*
+```
+
+---
+
+## Usage Notes
+
+**Field descriptions:**
+
+- **run_name:** Directory name (e.g., run_003_tuned) extracted from experiments/ path
+- **ISO_8601_timestamp:** Format YYYY-MM-DDTHH:MM:SSZ (UTC time)
+- **brief_hypothesis_from_objective:** Extract "what" statement from OBJECTIVE.md (1-2 sentences max)
+- **Decision:** One of: Seal, Iterate, Archive
+- **Rationale:** REQUIRED for Archive, optional for Seal/Iterate
+
+**Evidence Summary fields:**
+
+- **Critic Verdict:** Always "PROCEED" (required to reach human eval)
+- **Confidence:** Extract from CRITIC_LOG.md (HIGH/MEDIUM/LOW)
+- **Composite Score:** Weighted average from SCORECARD.json
+- **threshold:** Overall threshold from OBJECTIVE.md
+- **Key Metric:** Primary metric (highest weight or first in list)
+- **comparison:** Operator (>, <, >=, <=, ==)
+
+**Metrics Detail table:**
+
+- Pull all metrics from SCORECARD.json
+- Include: name, achieved value, threshold, PASS/FAIL status
+- Order by weight (descending) or as defined in OBJECTIVE.md
+
+**Decision Context sections:**
+
+- Only populate the section matching the decision type
+- For Iterate: include Critic's recommendation if available
+- For Archive: user_rationale is REQUIRED
+
+**Example populated template:**
+
+```markdown
+# Human Decision: run_003_tuned
+
+**Timestamp:** 2026-01-30T14:35:00Z
+**Hypothesis:** Ensemble methods will improve F1 score over single models
+**Decision:** Seal
+**Rationale:** Results demonstrate clear improvement with robust validation
+
+## Evidence Summary
+
+**Critic Verdict:** PROCEED (Confidence: HIGH)
+**Composite Score:** 0.89 (threshold: 0.80)
+**Key Metric:** f1_score=0.91 (target: >=0.85)
+
+## Metrics Detail
+
+| Metric | Value | Threshold | Status |
+|--------|-------|-----------|--------|
+| f1_score | 0.91 | 0.85 | PASS |
+| precision | 0.88 | 0.80 | PASS |
+| recall | 0.94 | 0.80 | PASS |
+
+## Decision Context
+
+### For Seal
+- Hypothesis validated
+- Ready for production/publication
+- All success criteria met
+
+---
+
+*Decision recorded: 2026-01-30T14:35:00Z*
+*Run directory: experiments/run_003_tuned/*
+```
+
+---
+
+## Integration
+
+This template is used by `/grd:evaluate` command in Phase 4 (Decision Logging).
+
+**Inputs:**
+- OBJECTIVE.md (hypothesis, metrics, thresholds)
+- SCORECARD.json (metrics values, composite score)
+- CRITIC_LOG.md (verdict, confidence)
+- User decision (Seal/Iterate/Archive)
+- User rationale (if Archive or provided)
+
+**Output:**
+- experiments/run_NNN/DECISION.md (this template populated)
+- Appended to human_eval/decision_log.md (summary entry)

package/get-research-done/templates/discovery.md

@@ -0,0 +1,146 @@
+# Discovery Template
+
+Template for `.planning/phases/XX-name/DISCOVERY.md` - shallow research for library/option decisions.
+
+**Purpose:** Answer "which library/option should we use" questions during mandatory discovery in plan-phase.
+
+For deep ecosystem research ("how do experts build this"), use `/grd:research-phase` which produces RESEARCH.md.
+
+---
+
+## File Template
+
+```markdown
+---
+phase: XX-name
+type: discovery
+topic: [discovery-topic]
+---
+
+<session_initialization>
+Before beginning discovery, verify today's date:
+!`date +%Y-%m-%d`
+
+Use this date when searching for "current" or "latest" information.
+Example: If today is 2025-11-22, search for "2025" not "2024".
+</session_initialization>
+
+<discovery_objective>
+Discover [topic] to inform [phase name] implementation.
+
+Purpose: [What decision/implementation this enables]
+Scope: [Boundaries]
+Output: DISCOVERY.md with recommendation
+</discovery_objective>
+
+<discovery_scope>
+<include>
+- [Question to answer]
+- [Area to investigate]
+- [Specific comparison if needed]
+</include>
+
+<exclude>
+- [Out of scope for this discovery]
+- [Defer to implementation phase]
+</exclude>
+</discovery_scope>
+
+<discovery_protocol>
+
+**Source Priority:**
+1. **Context7 MCP** - For library/framework documentation (current, authoritative)
+2. **Official Docs** - For platform-specific or non-indexed libraries
+3. **WebSearch** - For comparisons, trends, community patterns (verify all findings)
+
+**Quality Checklist:**
+Before completing discovery, verify:
+- [ ] All claims have authoritative sources (Context7 or official docs)
+- [ ] Negative claims ("X is not possible") verified with official documentation
+- [ ] API syntax/configuration from Context7 or official docs (never WebSearch alone)
+- [ ] WebSearch findings cross-checked with authoritative sources
+- [ ] Recent updates/changelogs checked for breaking changes
+- [ ] Alternative approaches considered (not just first solution found)
+
+**Confidence Levels:**
+- HIGH: Context7 or official docs confirm
+- MEDIUM: WebSearch + Context7/official docs confirm
+- LOW: WebSearch only or training knowledge only (mark for validation)
+
+</discovery_protocol>
+
+
+<output_structure>
+Create `.planning/phases/XX-name/DISCOVERY.md`:
+
+```markdown
+# [Topic] Discovery
+
+## Summary
+[2-3 paragraph executive summary - what was researched, what was found, what's recommended]
+
+## Primary Recommendation
+[What to do and why - be specific and actionable]
+
+## Alternatives Considered
+[What else was evaluated and why not chosen]
+
+## Key Findings
+
+### [Category 1]
+- [Finding with source URL and relevance to our case]
+
+### [Category 2]
+- [Finding with source URL and relevance]
+
+## Code Examples
+[Relevant implementation patterns, if applicable]
+
+## Metadata
+
+<metadata>
+<confidence level="high|medium|low">
+[Why this confidence level - based on source quality and verification]
+</confidence>
+
+<sources>
+- [Primary authoritative sources used]
+</sources>
+
+<open_questions>
+[What couldn't be determined or needs validation during implementation]
+</open_questions>
+
+<validation_checkpoints>
+[If confidence is LOW or MEDIUM, list specific things to verify during implementation]
+</validation_checkpoints>
+</metadata>
+```
+</output_structure>
+
+<success_criteria>
+- All scope questions answered with authoritative sources
+- Quality checklist items completed
+- Clear primary recommendation
+- Low-confidence findings marked with validation checkpoints
+- Ready to inform PLAN.md creation
+</success_criteria>
+
+<guidelines>
+**When to use discovery:**
+- Technology choice unclear (library A vs B)
+- Best practices needed for unfamiliar integration
+- API/library investigation required
+- Single decision pending
+
+**When NOT to use:**
+- Established patterns (CRUD, auth with known library)
+- Implementation details (defer to execution)
+- Questions answerable from existing project context
+
+**When to use RESEARCH.md instead:**
+- Niche/complex domains (3D, games, audio, shaders)
+- Need ecosystem knowledge, not just library choice
+- "How do experts build this" questions
+- Use `/grd:research-phase` for these
+</guidelines>

package/get-research-done/templates/experiment-readme.md

@@ -0,0 +1,104 @@
+# {{run_name}}
+
+**Created:** {{timestamp}}
+**Iteration:** {{iteration_number}}
+**Status:** {{status}}
+**Experiment Type:** {{experiment_type}} (script | notebook)
+**Hypothesis:** {{brief_hypothesis_from_objective}}
+
+## Summary
+
+{{one_paragraph_explaining_what_why_how}}
+
+## Notebook Execution
+
+> Note: This section only appears for notebook experiments (experiment_type == 'notebook')
+
+- **Source Notebook:** {{source_notebook}}
+- **Input Notebook:** code/input.ipynb (copy of source)
+- **Executed Notebook:** output.ipynb (with outputs)
+- **Metrics Extracted:** metrics.json (via scrapbook)
+
+### Parameters Injected
+
+The following parameters were injected via papermill:
+
+| Parameter | Value |
+|-----------|-------|
+| random_seed | {{random_seed}} |
+| data_path | {{data_path}} |
+| {{parameter_name}} | {{parameter_value}} |
+
+### Execution Details
+
+- **Kernel:** {{kernel_name}} (auto-detected)
+- **Cell Timeout:** {{cell_timeout}} seconds
+- **Execution Time:** {{execution_time_seconds}} seconds
+- **Retry Attempted:** {{retry_attempted}} (true/false)
+
+## Reproduce
+
+### For Script Experiments
+
+```bash
+cd experiments/{{run_name}}
+python code/train.py --config config.yaml
+```
+
+### For Notebook Experiments
+
+```bash
+cd experiments/{{run_name}}
+# Re-execute notebook with papermill
+papermill code/input.ipynb output.ipynb -f config.yaml
+# Or view executed notebook
+jupyter notebook output.ipynb
+```
+
+## Configuration
+
+See: `config.yaml`
+
+Key parameters:
+{{key_hyperparameters_list}}
+
+## Files
+
+### For Notebook Experiments
+
+- `code/input.ipynb` - Original notebook (source copy)
+- `output.ipynb` - Executed notebook with outputs
+- `metrics.json` - Extracted metrics (via scrapbook)
+- `config.yaml` - Experiment configuration
+- `data/` - Data references (symlinks + hashes)
+- `logs/` - Execution logs
+- `outputs/` - Model artifacts
+- `metrics/SCORECARD.json` - Evaluation results (if generated)
+- `CRITIC_LOG.md` - Critic verdict
+
+### For Script Experiments
+
+- `code/train.py` - Training script
+- `config.yaml` - Experiment configuration
+- `data/` - Data references (symlinks + hashes)
+- `logs/` - Execution logs
+- `outputs/` - Model artifacts
+- `metrics/SCORECARD.json` - Evaluation results
+- `CRITIC_LOG.md` - Critic verdict
+
+## Data
+
+- **Source:** {{data_path}}
+- **Hash:** {{data_hash}}
+- **Version:** {{data_version_if_available}}
+
+## Results
+
+{{metrics_summary_or_pending}}
+
+## Critic Verdict
+
+{{verdict_if_available_or_pending}}
+
+---
+*Generated by grd-researcher*